A robotics interface control document should give both endpoints the same interpretation of each exchanged value and a controlled way to accept changes. Agree units, coordinate frames, timestamp events, transform authority, validity and revision compatibility beside the field definition. Then give the producer, consumer and integration owner a shared acceptance case that can reveal a disagreement.
This matters when a supplier or another team revises an interface that still deserialises successfully. The receiving controller may read metres as millimetres, treat camera axes as body axes or measure age from publication when the producer now stamps acquisition. A useful ICD makes those differences reviewable before the candidate endpoint is accepted.
Control the agreement between the two endpoints
NASA’s interface-management guidance connects interface definitions, compatibility, approved changes and integration verification. It calls for capturing the rationale and assumptions behind interface decisions and for maintaining interface control documentation through configuration management. Those principles inform this worksheet. A robotics project sets its own authority and approval process.
For a data interface, define where the contract begins and ends. Is delivery a message on a transport, acceptance into the controller’s input buffer or conversion into its internal representation? Identify the producer and consumer versions, exchanged object and observation points. Keep a message schema as an attachment to the contract rather than assuming it contains the full agreement.
The robot requirement handoff defines a measurable obligation and its owners. The change-impact dossier follows a proposed change through dependencies. Here, the deliverable is the negotiated endpoint contract and the evidence needed to accept one interface revision.
A fictional docking interface with a semantic revision
DOCK-22 is an invented supervised integration rig for a mobile robot approaching a bay marker. IF-BAY-22 carries a target position and validity record from a vision tracker to the docking controller. All hardware labels, values and revision decisions below are hypothetical. No message exchange, docking trial or robot release has been executed.
Declared configuration DOCK-C1 uses tracker TRK-22 v1, camera CAM-22, controller DCTRL-22 v1 and interface ICD-BAY-22 rev A. Candidate DOCK-C2 proposes TRK-22 v2 and ICD-BAY-22 rev B. The receiving controller still needs a compatible revision. Rev A’s custom supplier contract reports millimetres in base_link and stamps publication. The candidate proposal reports metres in camera_optical and stamps image acquisition. The fields x, y, z and timestamp keep their names.
That is a semantic change even if decoding succeeds. Before approving rev B, both endpoint owners need to agree how the controller converts the position and interprets its age. The candidate manifest must identify their actual implementation, configuration and calibration artifacts. The labels here only establish the teaching scope.
Record endpoint meanings in a negotiated ICD
Keep the proposed rev B agreement, its source and the open acceptance questions together. The table is an editorial worksheet, with role assignments to be made by the project.
| Contract element | Proposed ICD-BAY-22 rev B agreement | Owner and acceptance question |
|---|---|---|
| Identity and boundary | IF-BAY-22, tracker output to controller input adapter. Target position, observation ID, source revision and validity status form one associated record. | Integration owner identifies producer/consumer builds and the exact input acceptance point. |
| Quantity and units | x, y, z represent marker-datum translation in metres. The internal controller target also uses metres. Conversion occurs once at the agreed boundary. | Both endpoint owners demonstrate known quantities. No unit may be inferred from a field name. |
| Frame and axes | Producer uses camera_optical: z forward, x right, y down. Controller transforms the target into base_link with its agreed origin and body axes. | Frame owner documents mounting geometry and the adopted conventions, including any exception. |
| Transform authority | TF-DOCK-22 v1 defines the camera-to-base extrinsics. Calibration authority owns the geometry, integration owns the approved transform provider and consumer uses that reference. | One named provider and calibration applicability argument. Conflicting or missing transforms cannot be silently accepted. |
| Timestamp meaning | Source timestamp denotes the defined image-acquisition event, not publication or callback arrival. CCLK-22 specifies the producer/consumer clock relationship. | Camera and clock owners define the acquisition event precisely and establish the clock evidence. |
| Association and revision | Observation ID combines a boot/session identity with a sequence. Source contract and calibration revisions accompany or resolve from the record. | Endpoint owners define duplicates, restarts, ordering and handling of an unsupported revision. |
| Validity and expiry | Valid use requires agreed target validity, supported revision, applicable transform and acquisition age ≤0.060 s at consumption under CCLK-22. | Consumer owner proves the use decision. The invented age limit needs a real project rationale before adoption. |
| Invalid or absent input | Invalid, expired, untransformable, unassociated or unsupported records cannot supply a new target through this interface. Recovery requires a new accepted valid record. | Both owners define status/reason reporting and challenge every invalid case. Wider robot response is a separate requirement. |
| Change and disposition | ICR-22 proposes rev A → rev B with unit, frame and timestamp changes. Existing approvals remain scoped to their original revisions. | Integration authority records inspected revisions, endpoint findings, gaps and final compatible combination. |
A validity flag and its reason should travel with the observation they qualify. A detached “latest valid” status can refer to a different sample after a restart or queue delay. Likewise, an acquisition timestamp without an agreed clock relationship cannot establish a meaningful consumer-side age.
Use ROS conventions as explicit source material
ROS REP 103 specifies SI units and right-handed coordinate conventions, including body axes x forward, y left, z up and camera optical axes z forward, x right, y down. It recognises justified, documented exceptions. The rev A millimetre representation is a fictional custom contract. A ROS-facing adapter would need an explicit conversion and documented agreement.
REP 105 explains that odom coordinates are continuous but may drift, while map coordinates may change in discrete jumps. It also assigns transform responsibilities in its mobile-platform frame structure. That distinction can matter if a target is stored in map while the controller acts locally. Record which transform and time apply to the stored observation instead of changing its frame label.
The ROS 2 Clock and Time design document describes SystemTime, SteadyTime and ROSTime, including simulated time that can pause or jump. Adopting ROS 2 therefore does not establish a measured clock-offset bound or make all timestamps interchangeable. CCLK-22 must define which time basis the interface actually uses and how validity is checked.
These sources are examples of conventions and design semantics. The guide does not prescribe a ROS package, client-library implementation or middleware profile. If your system uses another stack, retain the same endpoint questions with its own controlled definitions.
Make the acceptance case reveal units and frame errors
CASE-ICD-22 proposes a known-position exercise. For this fictional camera mounting only, the optical-to-body rotation maps [x, y, z] to [z, −x, −y]. The camera origin is translated [0.20, 0.00, 0.40] m from base_link. A producer position [0.10, −0.05, 1.20] m in camera_optical therefore maps to [1.40, −0.10, 0.45] m in base_link.
The calculation is a designed expectation, not a measured calibration or observed docking result. The general transformation is p_base = R × p_optical + t. A real installation needs its own R, t, uncertainty and applicability evidence. The specific axis mapping must not be assumed from the optical-frame name alone.
Under the old fictional rev A contract, that physical target would be represented as [1400, −100, 450] mm in base_link. An unchanged consumer that scales candidate coordinates as millimetres and assumes body axes would produce a different target. Matching field names would not detect the error. Inspect raw values, declared frame, conversion and the consumer’s internal target in the same acceptance case.
| Case | Proposed challenge | Evidence and expected disposition |
|---|---|---|
| CASE-ICD-22A | Known optical-frame target and explicit TF-DOCK-22 reference. | Capture producer record and consumer target. Compare with the independently characterised reference under an agreed tolerance. |
| CASE-ICD-22B | Expiry just below and above the agreed 0.060 s age boundary. | Capture acquisition and consumption events plus clock evidence. Verify the validity decision and avoid a pass based on arrival age. |
| CASE-ICD-22C | Missing transform, unsupported calibration revision or invalid target. | Record the rejected input and command-source association. No new target may be derived from that record. |
| CASE-ICD-22D | Producer restart, duplicate observation or unsupported contract revision. | Show session/sequence and compatibility handling. A previously accepted record must not be silently treated as a new valid target. |
The acceptance plan also needs the independently characterised position reference, tolerances, load and observation rules. A calculated expected value is not evidence that the physical camera mounting matches the model. Keep that measurement question with the calibration owner.
Keep the rejected assumptions and compatible combination
In the proposed ICR-22 review, TRK-22 v2 with DCTRL-22 v1 is held because unit/frame handling and acquisition-age interpretation remain unresolved. The two endpoint owners must inspect ICD-BAY-22 rev B, supply compatibility evidence and identify the accepted receiver build. No real review decision has been made.
Preserve the original proposal, the reason for the hold and the evidence needed to close it. A later rev B agreement should record which producer/consumer/calibration combination it covers. Use the configuration-state guide for the shared distinction between authorised, installed and assessed states. A label saying “latest ICD” is insufficient to reconstruct a mixed-endpoint rig.
Evaluate Arc through a two-sided interface review
Arc’s connected programme model can relate interface records to systems, requirements and verification. Its controlled-change workflow preserves proposed differences, while review records retain named participants and attributable decisions against the inspected context.
Bring one real ICD revision and both endpoint owners to a demo. Represent the unit, frame and timestamp agreement, link the acceptance cases and leave one transform assumption unresolved. Review the proposed revision, record each owner’s finding and demonstrate that the hold and original baseline remain understandable. The evaluation should show how your configured record fields preserve the contract.
Arc’s public reference supports engineering records and controlled review. It does not establish a native ROS transform broadcaster, message validator or automatic compatibility approval. Endpoint implementation and acceptance evidence remain the team’s responsibility.
Questions for the interface review
Does using ROS 2 replace the need for an ICD?
No. ROS conventions provide useful units and frame meanings, but the interfacing parties still need to agree timestamp semantics, validity, ownership, adopted conventions, exceptions and revision handling. The ICD records the contract for the particular producer and consumer.
Should a docking target use map or odom coordinates?
Choose the frame from the consumer’s task and the agreed transform path. REP 105 describes odom as continuous but drifting and map as a longer-term reference that may jump. Neither label alone establishes suitability for a docking command or the validity of a particular transformation.
Who owns the camera-to-base transform?
Name an authority for the physical calibration and a single approved publisher or provider for the transform used at the interface. Record the sensor mounting, calibration revision, frame definitions and validity conditions. A consumer should not silently substitute another transform.
Can a field list stay unchanged while the interface breaks?
Yes. Units, reference frames, timestamp events or validity meanings can change without changing field names or types. Review those semantics at both endpoints and update the acceptance cases before accepting the revision.
Can the teams approve different ICD revisions independently?
Use the project’s agreed approval and compatibility rules. Record the exact revisions each endpoint supports and the jointly accepted combination. An endpoint approval by itself does not establish compatibility with the other side.