Robot Interface Control Documents: How to Define Signals, APIs, States, and Error Handling Before Integration

Integration problems rarely start with the robot failing. They start with two teams assuming they agreed on something they never wrote down. The robot expects a signal on pin 7. The PLC sends it on pin 12. The API documentation lists a field called “status” without defining what values it can take. The fleet manager assumes the robot will pause when a door opens. The robot assumes the fleet manager told it to stop.

An Interface Control Document (ICD) exists to prevent these mismatches. It is a formal engineering document that defines exactly how two systems communicate: what signals cross the boundary, what each one means, who sends what, and what happens when things go wrong. This article explains what an ICD should cover when integrating robots, what standards and protocols are relevant, and what to verify with your supplier before signing off on integration.

What an ICD Is

The concept comes from systems engineering. NASA's Systems Engineering Handbook defines the framework for interface management, including Interface Requirements Documents (IRD) and Interface Control Documents (ICD). The distinction matters:

• An IRD defines what interfaces are needed: what data must flow between systems, what performance is required, what constraints apply.
• An ICD defines how those interfaces work: the specific signals, data fields, timing, protocols, connectors, and error handling.

An ICD is a configuration-controlled document. It has a version number. Changes go through a formal review. When the robot supplier updates their firmware and changes an API field, the ICD should reflect that change, and both parties should know about it before deployment, not after a mysterious production failure. For coordination across integration parties, see integration planning and coordination.

What an ICD Should Cover for Robot Integration

A robot system interface is not just an API endpoint. It spans multiple layers:

Physical Layer

Mechanical mounting dimensions, connector types, cable routing, and physical access for maintenance. If the robot docks at a station, the physical interface includes the dock geometry, alignment tolerances, and connection mechanism.

Electrical Layer

I/O signals, voltage levels, current ratings, and grounding schemes. How many digital inputs and outputs are available? What voltage do they expect? Are there analog signals? What about safety-rated signals that must meet specific performance levels?

Data Layer

API endpoints, data field definitions, data formats, engineering units, refresh rates, and communication protocols. If the robot exposes a REST API, what endpoints are available? What does each field mean? What are the valid values? How often is data refreshed? For WMS-specific integration patterns, see AMR-WMS integration.

State Layer

The state machine that governs interaction. A typical sequence might be: ready, request, arrived, transfer, complete, error. But who owns each state? Who transitions it? What happens when a state transition fails? Can the system recover, and if so, how?

Responsibility Layer

Who sends each signal? Who receives it? Who owns the state? Who has authority to change configurations? When something fails, whose responsibility is it to respond?

Error Handling Layer

What happens when the network drops? When a message is duplicated? When a timeout occurs? When the device fails? When a human operator needs to take over? Each of these scenarios needs a defined response, not an assumption.

Relevant Standards and Protocols

OPC UA: Cross-Vendor Interoperability

OPC Unified Architecture (OPC UA) is a platform-independent, service-oriented industrial communication architecture developed by the OPC Foundation. It provides a framework for exchanging structured data across systems. Security features must be selected and configured for the deployment; naming the protocol alone does not demonstrate secure integration.

Standardized information models help systems interpret data consistently. An ICD should identify the implemented profiles, information models, namespaces, security configuration, and tested interoperability boundaries.

For robot integration, OPC UA offers a framework for cross-vendor data exchange. But whether a specific robot supports OPC UA, and which Companion Specifications it implements, needs to be verified with the supplier. Support for the standard is not universal.

VDA 5050: AGV/AMR Communication

VDA 5050 Version 3.0.0, published in March 2026, describes communication between a central control system and mobile robots for intralogistics. Specify the exact supported version and schema in the ICD rather than relying on a general compatibility claim.

VDA 5050 is built on MQTT and JSON. It defines message types, topics, message structures, AGV states, order formats, and actions. The published VDA 5050 specification assigns QoS by topic; record the requirements from the agreed version in the ICD. Message-delivery QoS is not a guarantee that a physical task executes exactly once. The standard also uses MQTT's Last Will and Testament mechanism, which allows the fleet management system to detect when an AGV disconnects unexpectedly. Note that Last Will and Testament is a notification mechanism, not a data persistence feature: it alerts the system that a connection was lost, but it does not preserve the AGV's current order or task state. Order persistence depends on how the fleet management system handles disconnection scenarios, not on the MQTT protocol itself. For multi-vendor fleet deployments, see VDA 5050 for multi-vendor AMR fleets.

Verify compatibility using the actual robot, adapter, and fleet-manager versions. Include tests for reconnects, duplicate commands, rejected actions, and recovery after interrupted transfers. A shared protocol name does not prove that all optional functions or vendor extensions interoperate.

MQTT: The Transport Layer

MQTT is an OASIS-standardized publish/subscribe messaging protocol. It supports delivery quality-of-service levels, retained messages, and Will messages. Document which features the selected protocol version and implementation use. A Will message can signal an unexpected disconnection, but reconstructing robot task state and safely resuming work require application-level logic.

OpenAPI Specification: API Documentation

If a robot supplier provides a REST API, the OpenAPI Specification provides a standardized format for describing endpoints, request/response formats, authentication methods, and error codes. It can be used as the API section of an ICD, ensuring both parties work from the same definition.

Building an ICD: A Practical Approach

Step 1: Define the Interface Boundary

Draw the line between the two systems. Everything that crosses that line is in scope. Everything that stays on one side is out of scope. This sounds obvious, but in practice, teams often disagree about where the boundary sits.

Step 2: Catalog Every Signal and Data Field

List every I/O signal, every API endpoint, every data field, and every state. For each one, document: name, direction (who sends, who receives), data type, valid values, engineering units, refresh rate, and purpose.

Step 3: Define the State Machine

Map out every state the interface can be in, every transition, and every condition for each transition. Include error states and recovery paths. Who can trigger each transition? What happens when a transition fails?

Step 4: Specify Error Handling

For each failure mode (network drop, message duplication, timeout, device failure, human takeover), define the expected response. Do not leave this to assumptions. “The robot will retry three times” is a spec. “It should figure something out” is not.

Step 5: Assign Responsibility

For each signal, state, and error scenario, document who is responsible. When the robot stops at a station and the conveyor does not start, whose problem is it? When the fleet manager sends a cancel order and the robot is mid-transfer, who handles the abort?

Step 6: Version Control

The ICD is a living document. Every change goes through review. When the supplier releases a firmware update that changes an API field, the ICD must be updated and communicated before deployment. For broader configuration baseline management, see robot configuration management.

What to Verify With Your Supplier

Supported protocols. Does the robot support OPC UA, MQTT, REST API, Modbus, Profinet, or other protocols? “Open API” on a datasheet does not mean “fully documented and ready to integrate.” Ask for the actual API documentation, not just the claim.

Authentication. How does the API authenticate: API key, OAuth, certificates, or no authentication? This affects both security and integration complexity.

API versioning and compatibility. What is the current API version? What is the supplier's policy on backward compatibility when new versions are released? Will your integration break on the next firmware update?

Callbacks and webhooks. Does the robot support callbacks or webhooks for asynchronous events, or do you have to poll?

I/O count and type. How many digital and analog I/O points are available? What are the voltage and current ratings? Are any safety-rated?

Error codes. Are error codes defined and documented? Is there a reference table?

Timeout and retry behavior. What happens on timeout? How many retries? What is the backoff strategy?

Simulator or test environment. Can you test your integration against a simulator or test instance before deploying to the production robot? This is critical for de-risking integration.

Common Pitfalls

Assuming “open API” means “ready to integrate.” An API that exists but lacks documentation, versioning, or error handling is not an integration-ready interface. It is a liability.

Treating navigation accuracy as docking accuracy. A robot's navigation specification (how accurately it reaches a target zone) is not the same as its docking accuracy (how precisely it aligns with a physical interface). These are different measurements with different tolerances.

Skipping error handling in the ICD. Teams happily define the happy path and leave error handling to “common sense.” In production, the happy path is the easy part. Error handling is where integrations fail.

Not version-controlling the ICD. When the supplier changes the API and nobody updates the ICD, the document becomes worse than useless because teams trust it.

What to Ask Your Supplier

• What communication protocols does this robot support (OPC UA, MQTT, REST, Modbus, Profinet)?
• Can you provide complete API documentation, including error codes and field definitions?
• What is your API versioning and backward compatibility policy?
• Does the robot support VDA 5050? Which version?
• How many I/O points are available, and what are their ratings?
• Is a simulator or test environment available for pre-deployment integration testing?
• What happens on network timeout: retry, abort, or safe state?
• Who owns each interface state: the robot, the fleet manager, or the PLC?