← Back to the chapter

Technical detail · IoT Project Planning: Discovery and Scope

Version the interface contracts

Use planning artifacts to expose interface contracts. A payload schema is the agreed description of message fields, their meaning, units, and format. The device contract covers sensor range, sample interval, calibration, firmware version, power source, and local fault state. The transport contract covers MQTT topic names, QoS, retained-message policy, TLS identity, retry behavior, and this schema. The service contract covers validation rules, storage retention, alert latency, dashboard freshness, user permissions, and incident ownership.

Those contracts should have version and ownership fields. The schema can move from temperature_c and battery_mv to temperature_c, battery_mv, door_open, and fault_code only when the backend, dashboard, tests, and support runbook know how to handle both versions during rollout. A device shadow or twin is a record of a device’s desired settings and its reported current state. A device-shadow or twin record in AWS IoT Core, Azure IoT Hub, LwM2M, or a custom fleet table should distinguish desired configuration, reported configuration, firmware version, last heartbeat, and update state. Without that split, planning documents may say “update firmware” while the system cannot tell which devices actually accepted the update.

JSON (JavaScript Object Notation) stores data as readable text with named fields; CBOR (Concise Binary Object Representation) stores similar structured data in a compact binary form. These are two formats a device can use for its message payload.

An IP rating states how well an enclosure resists dust and water entry. An application programming interface (API) contract defines the requests, responses, fields, and error behavior that software components agree to use.

← Back to the chapter