Most schedule slips on a connected product are not caused by hardware being late or software being slow. They are caused by the seam between them. The firmware team believed the sensor value was reported in tenths of a degree Celsius; the app team assumed whole degrees Fahrenheit. Both sides tested their own half successfully. The bug surfaced three weeks before a pilot, in a customer's hands, as "the temperature is wrong sometimes."
The cure is unglamorous and enormously effective: write the interface down as a formal contract, assign it a single owner, version it, and build the tools that let each side develop against the contract instead of against the other team's availability. On projects that combine hardware, firmware, and software, this document does more for the schedule than any process change.
What the interface contract actually contains
It is not a diagram and it is not a wiki page someone updates when they remember. It is a specification, kept in version control alongside the code, with these parts:
- Transport definition. Which physical and logical link carries the traffic — a bus such as I2C, SPI, or UART between chips, BLE GATT between device and phone, MQTT or HTTP between device and cloud — with speeds, addresses, and framing.
- Data model. Every value the device exposes: name, type, width, units, valid range, resolution, update rate, and whether it is readable, writable, or both.
- Command set. Every operation the software can request, with parameters, preconditions, expected duration, and what happens if it is issued in the wrong state.
- Event and notification model. What the device sends unprompted, when, and how it is acknowledged.
- Error model. A closed list of error codes with defined meanings and defined caller behavior.
- State machine. Which commands are legal in which device state, and which transitions the software can trigger. If the firmware runs an explicit state machine, publish it — half of all integration confusion comes from software not knowing what mode the device is in.
- Version and capability negotiation. How each side discovers what the other supports.
Register maps and command protocols
Two structural styles dominate, and mixing them carelessly is a source of trouble.
A register map treats the device as addressable memory: each item has an address, a width, an access mode, and a reset value. It is simple, easy to generate code from, and easy to debug with a bus analyzer. Its weakness is that a multi-byte value read across two transactions can tear, so any map with wide values needs a latching rule or an explicit atomic-read command.
A command protocol treats the device as a service: framed messages containing an opcode, a payload, and a response. It handles long-running operations, streaming, and rich errors far better, and costs more to implement.
Whichever you choose, specify the boring parts explicitly, because these are precisely the ones that get assumed:
| Item | Must be stated | Classic failure if omitted |
|---|---|---|
| Byte order | Little-endian or big-endian, for every multi-byte field | A reading of 4,097 arrives as 272, and the values look plausible enough that nobody questions them for weeks |
| Units and scaling | Physical unit plus the multiplier, e.g. millivolts, 0.01 °C per count | Off-by-ten and Celsius/Fahrenheit bugs |
| Signedness | Signed or unsigned, and the encoding | Negative temperatures read as huge positives |
| Bit numbering | Which end bit 0 sits at | Flags interpreted in reverse |
| Timeouts | Maximum response time per command | Software waits forever, or gives up too early and retries a non-idempotent command |
| Sentinel values | What "no reading yet" or "sensor faulted" looks like | 0 is charted as a real measurement |
| Alignment and padding | Explicit padding bytes in structs | The same struct is a different size on device and host |
Error codes deserve real design
Teams spend weeks on the happy path and ten minutes on errors, then spend months in the field diagnosing "it stopped working." A usable error model is a closed enumeration, so software can switch on it exhaustively; each code says what the caller should do — retry, retry after a delay, reset the device, give up and tell the user; and each is classifiable as transient or permanent, caller's fault or device's fault.
Reserve ranges up front — one block for transport errors, one for protocol, one for application, plus a generous unallocated block — so adding a code later renumbers nothing. And define one code for "unknown command," so a newer app talking to older firmware fails cleanly instead of hanging.
Versioning the contract
The interface will change. Plan for it in the first version, not the third. Practical rules that hold up:
- Number the protocol separately from the firmware. Firmware builds change weekly; the protocol should change rarely and deliberately.
- Additive changes only, within a major version. New registers at new addresses, new opcodes, new optional fields. Never repurpose an address or change the units of an existing field — that is a new major version.
- Negotiate on connect. Both sides declare what they support and operate at the highest common version.
- Feature flags, not version inference. Software should ask "does this device have a barometer" rather than "is this firmware newer than 3.2."
- Keep it under change control along with the rest of the engineering documentation, and tie protocol versions to released firmware versions in a compatibility matrix anyone can read.
Who owns the spec
The most common organizational failure is that nobody owns it — firmware writes a draft, software marks it up in a chat thread, and the authoritative version lives in somebody's head. Assign one named owner, normally the firmware or systems lead, since they are closest to the physical constraints. The owner drafts, but the spec is not final until software has formally reviewed it, because software finds the ambiguities firmware cannot see. Then enforce three rules: the document lives in the same repository as the code, changes go through review like code, and if the implementation disagrees with the spec, the implementation is the bug.
Where possible, generate rather than transcribe. A machine-readable definition of registers, commands, and errors, from which you generate the C headers, the mobile client, and the documentation, eliminates the entire class of bugs where one side's constants drift from the other's. The same discipline applies outward if you ever open an API to customers, where the contract becomes public and much harder to change.
Simulators and stubs: unblocking software
Hardware is late. It is always late, and the first boards go to firmware, not to app developers. If app work cannot start until real hardware exists, you have serialized two teams and added months to the schedule. Three levels of stand-in, in increasing fidelity:
- Mock layer in the app. A fake device object returning canned data behind the same interface as the real driver. A day or two of work, unblocks all UI work, and doubles as the fixture for automated tests.
- Protocol simulator. A program that speaks the real wire protocol — a BLE peripheral advertising the real GATT services, or an MQTT client publishing the real topics — so the app exercises real parsing, reconnection, and error paths. Highest-value item on the list, typically a few days of work.
- Reference hardware. An evaluation board running the real firmware stack with simulated sensor inputs, giving timing behavior close to the final product.
Build the simulator so it can misbehave on demand: drop connections, respond slowly, return every error code, send malformed packets, and report out-of-range values. Nearly every catastrophic field bug in connected products is a case the software never saw because the bench hardware always behaved. On the firmware side, the mirror-image tool is hardware-in-the-loop testing, where the device runs against simulated inputs instead of a simulated host.
Integration bugs to expect
When the two halves finally meet, the same problems appear again and again: endianness and scaling mismatches, struct padding differences between compilers, timestamp epoch disagreements, buffer sizes that differ from the negotiated packet size so long messages silently truncate, commands sent during a device state transition, and reconnection code that assumes the device retained state it actually lost on reset.
Budget an explicit integration period — two to four weeks for a moderately complex product — and schedule the first end-to-end connection as early as possible, even against a stub. A bug found in week six is an afternoon; the same bug in week twenty-six is a release delay.
Projects House develops hardware, firmware, and application software as one program, with the interface contract written and owned before either side starts building. If your product has a seam between electronics and software and you want it specified rather than discovered, get in touch through our contact form.