What interface documentation does an IoT integration actually need?
An interface is documented well enough to integrate when you can answer, before writing code: which hardware and firmware revision the document describes, what each value means, which operations only observe and which change equipment state, what a command requires and what its acknowledgement proves, how errors, timeouts and retries behave, who may access it — and whether the contract exists in a machine-readable form your tools can check. Whatever you cannot answer from the documentation belongs on an explicit gap list for the technical owner, not in a code editor.
A protocol specification is not device documentation
The protocol layer and the device layer are two different documents. The Modbus application protocol specification fixes byte order for its 16-bit values and defines four data tables with access types — read-only discrete inputs and input registers, read-write coils and holding registers. Yet the same specification states that "each device can have its own organization of the data", so the protocol tells you how bytes move, not what a register means. For a Modbus-class device, request the device-specific register map in addition to a protocol-compliance claim.
Value semantics, not just field names
A register or field name is not a meaning. For every value you plan to consume, documentation must state units, scaling (raw counts and scale factors), validity range and what a timestamp means — sample, transmission or processing time. Semantic models are a separate artefact: the OPC Foundation publishes UA companion specifications to provide per-industry and per-device information models on top of the transport protocol, so interoperability extends to the semantic level. Check whether such a model exists for your device class; if not, value semantics must come from the vendor document. That review is practical integration method, not a property any protocol guarantees.
Reading versus commanding
Distinguish operations that observe from operations that change state. Modbus encodes the split in its table structure: read-only versus read-write. Web APIs carry the same distinction in method semantics — HTTP methods are documented as safe, idempotent or neither, and POST can cause state changes or side effects on the server. Read access also does not imply authority to change a value; authorisation must be documented separately. When you do command, the documentation must define what an acknowledgement proves: that a request was accepted, that it was executed, or that a physical result was confirmed. Treating "accepted" as "done" can present an incomplete action to an operator — engineering method, not a protocol property.
The failure path is part of the contract
Before coding, establish allowed command values and preconditions, timeout behaviour, whether repeating a command repeats its effect, and how to read current state back to verify. MDN defines an HTTP method as idempotent when the intended effect of one request equals that of several identical requests — the same question every actuator integration must answer before its first retry. Missing preconditions or retry semantics are integration gaps, not implementation details to discover during commissioning.
Identity, revision and machine-readable contracts
Record which exact hardware and software revision the document describes, and keep the versioned document reference with the implementation. For HTTP-style APIs, prefer a machine-readable description: an OpenAPI Description documents the possible calls, their parameters, return values and required data formats in a form tooling can consume, which makes the contract checkable instead of prose-only.
Turn gaps into a list, not assumptions
Practical method: walk through the items above per interface, record what is documented and what is missing, and send that gap list to the technical owner before development starts, so gaps are resolved before coding rather than discovered during commissioning.
If you are still selecting hardware, our hardware selection checklist explains why to require documentation before purchase, and the sensor measurement brief covers defining what to measure.
That evidence packet is also where Manna starts. Our component-integration workflow begins with the component documentation (analysed from a PDF or URL), produces a driver validated on actual hardware, and keeps versioned evidence with the implementation. Support stays conditional case by case: an accessible interface, documentation and actual-hardware verification are required, so a thinly documented device is exactly the situation to scope before committing.
If you have a device or interface document in front of you, bring it to a project discussion with Manna.
Prepared with AI assistance for Manna Insect Oy.