Skip to main content
Version: 1.7

Device APIs at a Glance

Every way a device can reach DeviceChain, each with one command you can paste into a shell. This page is a map, not a specification: each row links to the page that explains the transport, and the Device Protocol Reference lists every field and every refusal. What each transport can and cannot do is in the Transport Capability Matrix.

Examples use the local kind install (tenant acme, instance devicechain). Replace the host, tenant and credentials with your own.

TransportDirectionAuthenticates withGo to
MQTTtelemetry in, commands outcredential id and secret, per connectionConnecting a device
HTTPtelemetry in, opt-in command pullbody credential for events; bearer access token for command pullConnecting a device
LwM2Mtelemetry in, writes outDTLS pre-shared keyLwM2M
Sparkplug Btelemetry in, commands outthe source's broker credentialSparkplug B
X.509 certificateas MQTTclient certificateCertificate devices
Self-registrationobtain a device and credentialprovision key and secretSelf-registration

MQTT​

Publish a device event to the device's events topic on the platform broker. The username is {tenant}:{credentialId}, and the event body carries no credential.

mosquitto_pub --cafile instance-ca.crt -h <mqtt-host> -p 1883 \
-i 'devicechain:acme:sensor-001' -u 'acme:<credentialId>' -P '<credentialSecret>' \
-t 'devicechain/acme/devices/sensor-001/events' \
-m '{"device":"sensor-001","eventType":"Measurement","payload":{"entries":[{"measurements":{"temperature":"21.5"}}]}}'

Commands arrive on a topic the device subscribes to:

mosquitto_sub --cafile instance-ca.crt -h <mqtt-host> -p 1883 \
-i 'devicechain:acme:sensor-001' -u 'acme:<credentialId>' -P '<credentialSecret>' \
-t 'devicechain/acme/device-commands/sensor-001'

HTTP​

POST the same event body to the event-sources service. Over HTTP the credential travels in the body, and the answer is 202 when the event was accepted. A 429 or a 503 with Retry-After means send it again later.

curl -i -X POST http://localhost:8081/devicechain/acme/events \
-H 'Content-Type: application/json' \
-d '{"device":"sensor-001","eventType":"Measurement","credentialType":"ACCESS_TOKEN","credentialId":"<token>","payload":{"entries":[{"measurements":{"temperature":"21.5"}}]}}'

For HTTP command pull, set the device type's commandChannel to HTTP_PULL. The device polls for commands, acknowledges receipt and submits responses using Authorization: Bearer <access-token> with its own device access token. The default PUBLISH channel is not pollable. HTTP command pull does not carry configuration or managed update assignments. Keep port 8081 behind network controls.

LwM2M​

An LwM2M client registers over CoAP on DTLS, UDP 5684, presenting a pre-shared-key identity that the platform resolves to a tenant and a device. Use any LwM2M client that supports PSK; with the Leshan demo client, for instance:

./leshan-client-demo -u coaps://<lwm2m-host>:5684 -n sensor-001 -i <pskIdentity> -p <pskKeyHex>

The platform then observes the device's sensor objects and stores each notification as a measurement. See LwM2M for presence, writes and what is not supported.

Sparkplug B​

The platform is a Sparkplug host: it subscribes to your own broker and does not accept a connection from the edge node. Point a configured source at the broker, then publish a node birth followed by data as usual. The topic names are the Sparkplug ones; the payloads are Protobuf, so a Sparkplug library builds them. With a plain MQTT client you can confirm the topic is reachable:

mosquitto_sub -h <your-broker> -p 1883 -u <user> -P <password> -t 'spBv1.0/plant-a/#' -v

Each {group}/{node} becomes the external id of a device in the source's tenant.

X.509 certificate​

A device holding a certificate issued by a trusted CA connects with the username {tenant}:@x509 and no password.

mosquitto_pub --cafile instance-ca.crt --cert device.crt --key device.key \
-h <mqtt-host> -p 1883 -i 'devicechain:acme:<deviceToken>' -u 'acme:@x509' \
-t 'devicechain/acme/devices/<deviceToken>/events' \
-m '{"device":"<deviceToken>","eventType":"Measurement","payload":{"entries":[{"measurements":{"temperature":"21.5"}}]}}'

Self-registration​

A device with a provision key and secret creates itself and its credential. Generate and save the credential before sending, then register:

curl -sS https://<instance-host>/api/device-management/provisioning/acme/register \
-H 'Content-Type: application/json' \
-d '{"provisionKey":"acme-sensors-2026","provisionSecret":"<secret>","externalId":"SN-000123","credentialSecret":"<credential you saved>"}'

The answer names the device token and the MQTT client id to connect with. Repeating the same request is safe and answers REPLAYED. See the retry contract.