What Should a Device Protocol Specification Include?

A device connects successfully, but the application still cannot use it reliably. The missing information is often outside the command table: when a request is allowed, how a response is matched, what a timeout means, and which behavior changes after a firmware update. This guide explains what a device protocol specification should include so firmware, application, and backend teams can implement the same contract.

A device protocol specification is the implementation contract between a device and the software that communicates with it.

It defines how to establish communication, encode requests, interpret responses, and recover when something goes wrong. It also explains what each operation changes on the device, when that change becomes effective, and how the application can confirm it.

A command table is only one part of this contract.

For example, an entry that says “send 0x21 to start measurement” leaves important questions unanswered:

• Which device states allow the command?
• Does the response confirm acceptance or completion?
• How long can measurement take?
• Can the application retry after a timeout?
• Does the result arrive as a response or an unsolicited event?

A useful specification answers these questions without requiring developers to infer behavior from a demo application.

Start by identifying exactly what the document describes.

Include the device family, hardware revisions, firmware versions, protocol version, and document revision. Name the team responsible for maintaining the specification and resolving implementation questions.

Keep firmware and protocol versions separate. A firmware release may fix internal behavior without changing the communication contract, while a protocol change may affect several firmware releases.

The document should also state its boundaries. For example:

“This specification covers communication between the mobile application and the controller. It does not define the controller’s internal sensor bus or cloud API.”

For every unresolved behavior, record an owner and a decision deadline. “To be confirmed” is more useful than an undocumented assumption, but it should not remain unresolved when dependent integration work begins.

Explain how the application reaches the device before describing individual commands.

The required information depends on the interface.

BLE GATT

Document discovery identifiers, service and characteristic UUIDs, characteristic properties, security requirements, notification or indication setup, and payload limits.

A UUID list alone is insufficient. The specification must explain which characteristic carries commands, which carries results, and what initialization is required before communication begins.

GATT defines services, characteristics, descriptors, and procedures such as reads, writes, notifications, and indications. Your device-specific documentation must explain how those mechanisms implement the product workflow.

The Bluetooth SIG Bluetooth LE Primer (https://www.bluetooth.com/bluetooth-le-primer/) provides the underlying terminology.

UART or Serial

Document the electrical interface, connector pinout, voltage levels, baud rate, data bits, parity, stop bits, and flow control.

Distinguish the physical interface from the message format. Matching serial settings does not mean that two implementations agree on packet boundaries or command meanings.

TCP

Document the connection initiator, address discovery, port, encryption requirements, message framing, and reconnect behavior.

Explain how the receiver reconstructs messages from the byte stream. Do not assume that one read operation returns one complete application message.

UDP

Document endpoints, datagram limits, discovery behavior, and application rules for packet loss, duplication, or reordering.

State whether the application needs acknowledgements and how it identifies repeated requests.

MQTT

Document broker connection requirements, topic structure, QoS, retention policy, session behavior, and command-response mapping.

Explain how device identity relates to topics and how the application distinguishes message delivery from device execution.

Connection Startup Sequence

Include a numbered startup sequence appropriate to the product:

1. Discover the intended device.
2. Establish the connection and required security.
3. Discover the available interfaces.
4. Enable result notifications or subscriptions.
5. Read the protocol version and capabilities.
6. Read the current device state.
7. Begin application commands.

Define what happens when any step fails and whether it can be repeated safely.

The receiver must know exactly where each message begins and ends.

For a custom binary protocol, document:

• Header or synchronization bytes.
• Length-field size and what the length includes.
• Message type and request identifier.
• Payload layout and maximum size.
• Checksum or CRC, if used.
• Escaping, padding, and fragmentation rules.
• Recovery behavior after malformed input.

Your framing rules should explain how to handle incomplete input and multiple messages received together.

For each field, define its offset, width, type, byte order, permitted values, and meaning. Include units, scaling, signedness, and invalid-value markers where relevant.

Example: Temperature Field

The following is an illustrative field definition, not a standard device format.

• Field name: temperature.
• Type: signed 16-bit integer, using two’s complement.
• Byte order: little-endian.
• Unit: 0.01 degrees Celsius.
• Example bytes: 29 09.
• Decoded integer: 2345.
• Displayed value: 23.45 degrees Celsius.
• Invalid marker: 00 80, meaning no valid reading.

“Two bytes of temperature data” would not provide enough information to decode the same value consistently.

Checksum and CRC Definitions

If a CRC is used, specify:

• Polynomial.
• Initial value.
• Input and output reflection settings.
• Final XOR value.
• Covered byte range.
• Transmitted byte order.
• A verified test vector.

Naming only “CRC-16” leaves room for incompatible implementations.

For an existing standard protocol, reference the exact specification and document device-specific mappings and extensions. The Modbus Organization’s specifications (https://www.modbus.org/modbus-specifications), for example, provide the base contract; an individual product still needs its supported functions and register meanings documented.

Each command needs a complete entry, not just an identifier and payload example.

Document the following information:

• Identifier and name: How the receiver recognizes the operation.
• Purpose: What the operation does.
• Preconditions: Required device state, permissions, and configuration.
• Request: Field definitions and validation rules.
• Response: Response fields and their meaning.
• Completion evidence: What proves the requested outcome.
• Timing: Acceptance and completion expectations.
• Side effects: Changes to hardware, stored settings, or other operations.
• Retry rules: Whether repeating the request is safe.
• Errors: Rejection and execution-failure conditions.

Example: SET_REPORT_INTERVAL

The following example illustrates the level of detail needed. Its behavior is a reference design, not a specification for a particular product.

Purpose

Change the interval used for periodic telemetry reports.

Request fields

• requestId: Application request identifier.
• intervalSeconds: Integer from 1 to 3600.

Preconditions

The session must be authenticated, and the device must not be updating firmware.

Acceptance

The device validates the request and reserves it for processing.

Completion

The device persists the interval and verifies it by reading it back.

Result

The response includes requestId and the effective intervalSeconds.

Activation

The next reporting interval begins when the command succeeds.

Persistence

The setting survives a restart.

Duplicate handling

During the documented deduplication window, the same requestId and payload return the existing status or result.

Conflict handling

The same requestId with a different payload is rejected.

Errors

• INVALID_ARGUMENT.
• BUSY.
• UNAUTHORIZED.
• STORAGE_FAILURE.

A real specification must also define the identifier format, deduplication window, timing limits, and error encoding for the actual product.

A low-level response may confirm that data reached a communication component without proving that the requested operation completed.

Define the acknowledgement stages your application can observe:

• Received: The message reached the application handler.
• Accepted: Validation passed and execution was scheduled.
• Completed: The documented success condition was met.
• Rejected: The request was not accepted for execution.
• Failed: Execution was attempted but did not meet the completion condition.

Not every command needs every stage. A simple read may return its result immediately, while calibration may need an acceptance response followed by a later completion event.

Document how each response is matched to the original request. Specify whether unsolicited events use the same channel and how clients distinguish them.

Also define the limits of the evidence. Reading back an output register confirms a register value; it does not necessarily prove that the attached mechanism moved.

The application should show the strongest result that the protocol actually establishes.

The same command may be valid while idle and invalid during calibration or a firmware update.

List the externally relevant device states and the operations permitted in each. Describe transitions caused by commands, physical inputs, errors, and restart.

Concurrency Rules

Answer these questions explicitly:

• Can multiple requests be outstanding?
• Are commands executed in order?
• Can reads occur during a long-running operation?
• Does the device queue conflicting commands or reject them?
• What happens when two authorized clients issue conflicting requests?

Include a maximum queue depth or request rate where resource limits matter.

Timing and Timeout Rules

Specify acceptance and completion timeouts separately.

An acceptance timeout describes how long the caller waits for the device to accept or reject a request. A completion timeout describes how long the operation may take after acceptance.

A timeout should describe what the caller knows. If the device may have executed a command before its response was lost, the outcome is uncertain.

The specification must provide a status query, reconciliation procedure, or other recovery path before recommending a retry.

Create a consistent error model that distinguishes invalid requests from temporary operating conditions and hardware failures.

For each error, document:

• A stable machine-readable code.
• The condition that produces it.
• Whether execution started.
• Whether partial effects are possible.
• The recommended next action.

For example, INVALID_ARGUMENT usually requires correcting the request. BUSY may allow a later attempt under a defined policy. STORAGE_FAILURE may require inspection rather than repeated retries.

Disconnection and Restart

Explain what happens after disconnection and reboot.

State which settings persist, which pending commands survive, and whether previous results remain available.

If the device can restart after performing an operation but before recording its result, explain how the system resolves that uncertainty. Repeating a command may be harmless for a configuration setting but unacceptable for dispensing or another physical action.

Malformed Messages

For binary streams, specify how the parser recovers after an invalid length, unknown message type, or failed integrity check.

A parser that waits indefinitely for an impossible frame can block otherwise valid traffic.

Define buffer limits and the conditions under which input is discarded or the connection is reset.

Describe who is allowed to connect and what each identity can do.

Cover authentication, authorization, encryption requirements, provisioning, credential rotation, and device ownership transfer where applicable.

Separate transport security from operation permissions. An encrypted connection does not by itself mean that its client should be allowed to reset the device or replace its configuration.

For commands that require replay protection, define the freshness mechanism and what happens after restart or clock loss.

A request identifier is useful for correlation, but it is not automatically proof that a request is authentic or recent.

Do not place real production credentials in the specification. Use placeholders and describe how authorized teams obtain the required configuration.

Explain how clients discover supported behavior before using it.

Include a compatibility matrix linking hardware, firmware, and protocol versions. Where features are optional, provide capability discovery rather than expecting applications to infer support from product names.

Document how implementations handle:

• Unknown command identifiers.
• Unsupported enum values.
• Additional optional fields.
• Missing required fields.
• Deprecated operations.

An unknown value should not silently trigger a different physical action.

For every protocol change, record the affected fields, behavioral differences, compatibility impact, and migration guidance.

Keep older specifications available for devices that remain deployed on earlier firmware.

Include more than a successful request and response.

Provide fixtures for:

• Minimum and maximum valid values.
• Invalid inputs.
• Unsupported commands.
• Truncated frames.
• Duplicate requests.
• Interrupted operations.
• Delayed or missing responses.

Each fixture should identify the protocol version, exact input, expected decoded values, expected response, and expected device behavior.

For binary protocols, include raw hexadecimal messages alongside their decoded interpretation.

For stream transports, test the same message split across several reads and several messages combined into one read.

Captured traffic is valuable when its device and firmware context are known. Remove sensitive identifiers and credentials, and distinguish observed behavior from behavior guaranteed by the specification.

A simulator helps teams develop without continuous hardware access, but real-device tests are still needed to verify timing, persistence, and physical outcomes.

Before handing the interface to another team, confirm that the package includes:

• Document owner, revision history, and supported versions.
• Connection settings and initialization sequence.
• Message framing and complete field definitions.
• Command requests, responses, and completion conditions.
• Device states and concurrency rules.
• Timing, retry, expiration, and duplicate-handling rules.
• Error codes and recovery procedures.
• Authentication and operation permissions.
• Compatibility and capability-discovery rules.
• Verified examples, test fixtures, and known limitations.

Ask an engineer who did not design the firmware to implement one read command, one state-changing command, and one failure-recovery path using the documentation alone.

Every clarification they need reveals a gap worth closing.

Is a Vendor SDK Enough Without a Protocol Specification?

An SDK can simplify integration, but its API may hide transport behavior, retry policies, and device limitations.

Obtain documentation for its supported workflows, errors, threading model, version compatibility, and diagnostic facilities.

Access to the underlying protocol becomes particularly valuable when investigating failures or supporting a platform the SDK does not cover.

Can Packet Captures Replace Missing Documentation?

Packet captures can reveal message structure and observed behavior. They cannot establish every valid value, unsupported state, timing guarantee, or firmware difference.

Treat them as evidence to validate with the device team, not as a complete specification.

Should App and Firmware Teams Maintain Separate Specifications?

Use one authoritative communication contract with clear ownership.

Each team can maintain implementation notes, but command semantics and wire formats should not diverge across separate documents.

What Should Be Documented First When Time Is Limited?

Start with connection setup, framing, the critical commands, completion evidence, and failure recovery.

Mark unverified behavior explicitly and prioritize the gaps that block testing or could cause unintended device actions.

A useful protocol specification allows different teams to produce compatible implementations and diagnose failures from shared evidence.

If your interface currently exists across spreadsheets, SDK samples, packet captures, and firmware comments, YUNJI’s Device Protocol Integration service (https://yunji-node.com/solutions/device-protocol-integration) can help organize that material into a documented and verified communication layer.

For an integration review, prepare the current protocol notes, representative hardware, firmware versions, sample traffic, and the application workflows that must work reliably.