Documentation · hardware

Connect a device without losing the meaning of its data.

The transport is only one part of the job. Identity, timestamp behaviour, units, buffering and credential ownership determine whether the data remains useful after the pilot.

Before writing device code

Write down five decisions before opening the firmware project:

Stable device identifier

Signal names and engineering units

Sampling and publish intervals

Offline buffer depth

Credential provisioning and rotation

Firmware update and rollback behaviour

Payload and timestamp model

A reading needs a value and a reliable relationship to time. Add context only when it changes the interpretation, such as location, operating mode or quality state.

{
  "temperature": {
    "value": 27.4,
    "timestamp": 1721456400000,
    "context": { "unit": "degC", "quality": "good" }
  }
}

Use device time only when the device clock is maintained. If the network or platform assigns time, document that choice so delayed packets are not mistaken for current measurements.

Authentication

The legacy device API uses a token supplied with the request. The current token and base URL come from the authenticated portal or project onboarding record. Do not embed example credentials from documentation in firmware.

X-Auth-Token: {PROJECT_TOKEN}
Content-Type: application/json

Use separate credentials for development and production. Record which product batch or gateway owns each credential.

HTTPS transport

HTTPS suits devices that wake, send a bounded payload and disconnect. It is also the simplest commissioning path because requests and responses can be inspected directly.

POST {BASE_URL}/api/v1.0/update-Device
X-Auth-Token: {PROJECT_TOKEN}
Content-Type: application/json

{"temperature": 27.4, "pressure": 5.2}

The exact production endpoint must be confirmed against the project environment before firmware release. The legacy documentation contains multiple historical URL forms and should not be treated as a release specification.

MQTT transport

MQTT suits long-lived sessions, constrained links and publish/subscribe workflows. Choose the quality-of-service level from the consequence of duplication or loss, not from a preference for the highest number.

QoS 0

Use when the next reading makes an occasional lost packet irrelevant.

QoS 1

Use when delivery matters and the consumer can tolerate or remove duplicates.

QoS 2

Use only when exactly-once handling justifies the extra protocol work.

Commissioning checklist

Send a known value and verify its unit and timestamp.
Disconnect the network long enough to fill part of the offline buffer.
Reconnect and verify packet order, duplicates and gaps.
Expire or replace a credential and observe the device response.
Reboot during a write and during an update.
Record the firmware, hardware and configuration versions accepted for production.