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.
| Transport | Direction | Authenticates with | Go to |
|---|---|---|---|
| MQTT | telemetry in, commands out | credential id and secret, per connection | Connecting a device |
| HTTP | telemetry in, opt-in command pull | body credential for events; bearer access token for command pull | Connecting a device |
| LwM2M | telemetry in, writes out | DTLS pre-shared key | LwM2M |
| Sparkplug B | telemetry in, commands out | the source's broker credential | Sparkplug B |
| X.509 certificate | as MQTT | client certificate | Certificate devices |
| Self-registration | obtain a device and credential | provision key and secret | Self-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.