← Back to the chapter · Next detail →

Technical detail · Implement and Iterate

Device state and update contracts

A contract is an agreed description of the fields a device sends and what each field means. A schema is the field-by-field layout of one message, including names, types, and required values. A versioned contract labels changes to that layout so old and new firmware can be handled safely during rollout. For example, firmware version 1.4 might send a temperature reading, battery voltage, sequence number, and fault code; the schema version tells the cloud which message layout to expect. Device state also has two views: desired state is what an operator asks the device to become, while reported state is what the device says it is now. A device shadow or twin stores and compares these views so a mismatch, such as a requested firmware update that has not yet completed, is visible. The implementation layer should record hardware revision, firmware version, configuration version, schema version, boot reason, battery state, network type, last heartbeat, and update status. AWS IoT Device Shadow, Azure IoT Hub device twin, and LwM2M objects are examples of fleet records that can carry this state.

OTA safety is a state machine, not a button. Queued, downloading, verifying signature, installing, rebooting, healthy, failed, rolled back, and support-needed are separate states. Systems such as Mender, RAUC, SWUpdate, AWS IoT Jobs, Azure Device Update, or a custom bootloader can support this pattern, but only if rollback, power-loss behavior, storage limits, and compatibility checks are tested.

The message contract needs the same discipline. For example, firmware version 1.4 publishes temperature_c, battery_mv, sequence_number, and fault_code; the cloud rule should tolerate the previous schema during rollout and reject malformed values without hiding them. A gateway that bridges BLE sensors to MQTT should attach gateway firmware, sensor address, receive signal strength, timestamp source, and queue depth so an operations engineer can distinguish a failed sensor from a failed bridge. Schema registries, JSON Schema, Protocol Buffers, Avro, or typed TypeScript contracts can all help, but the release record must say which versions remain supported.

← Back to the chapter · Next detail →