FixTheRobot Explore Robotics / Systems Engineering / Engineering Guides / Module 01

Engineering Guides · Module 01

Preparing a system block diagram and interface control document

The block diagram shows what connects to what. The interface control document says exactly how, so two teams can build both ends without meeting.

  • Intermediate
  • Module 01: Robotics System Architecture & Requirements
  • Written for ROS 2 Jazzy where ROS 2 is used
  • Sources checked 2026-11-05

Assumptions: A practical template based on the NASA Systems Engineering Handbook; not a standard. All numbers in the example are illustrative and the code is executed by the site’s tests.

1. Engineering problem

Most integration failures sit on an interface: a connector wired the wrong way, a 12 V rail on a 5 V input, a link that cannot carry the data, a frame with a different axis convention. A block diagram makes the structure visible; an interface control document (ICD) makes each connection precise and checkable before hardware exists.

2. When is this needed?

  • After the architecture is chosen and requirements are allocated.
  • Before ordering PCBs, harnesses or connectors.
  • When two people or companies build the two ends of one interface.

3. Selection and design decisions

The NASA handbook’s interface requirements document outline (Appendix L) is a good skeleton: an interface description, the responsibilities of each side, coordinate systems and numerical requirements.

Interface typeWhat the ICD states
PowerSource and sink, nominal voltage and tolerance, maximum current, connector, protection, inrush
Data linkMedium and protocol (CAN, Ethernet, USB, SPI, UART), bit rate, message list, rate, latency limit
ROS 2 topicName, message type, frame_id, rate, QoS, units
MechanicalMounting pattern, fasteners, tolerances, sensor pose in the robot frame
Coordinate framesParent, child, convention (REP 103), source of the transform
SafetySignal type, safe state, response time

4. Advantages and disadvantages

  • Detail vs upkeep: a very detailed ICD goes stale; keep it in version control next to the design and review it at every change.
  • One document vs per-interface sheets: per-interface sheets are easier to assign to an owner.
  • Machine-checkable lists (CSV or YAML) can be validated automatically; prose cannot.

5. Requirements and constraints

  • Every interface has exactly one owner who approves changes.
  • Numbers have units and tolerances.
  • Use 70 % of the link capacity as a design limit unless the protocol datasheet says otherwise (a rule of thumb, not a standard).

6. Architecture

sensors ──data──▶ computer ──cmd──▶ MCU ──▶ motor driver
    ▲                  ▲                      ▲
    └─── power: battery ─▶ DC-DC ─────────┘
Each arrow is one row in the ICD: from, to, medium, rate, voltage, owner.

7. Implementation

  1. List the subsystems from the architecture; give each a short id.
  2. List every connection once, in a table: name, from, to, medium, data rate, link capacity.
  3. List every power connection: source, sink, output voltage, sink input range.
  4. Run a checker over the lists (below) every time they change.
  5. Add the mechanical and frame interfaces and an owner to every row.
subsystems = {"lidar", "computer", "imu", "mcu", "motor_driver", "battery", "dcdc"}
data = [("lidar_points", "lidar", "computer", 90.0, 1000), ("imu_spi", "imu", "mcu", 0.4, 10),
        ("cmd_vel", "computer", "mcu", 0.1, 12), ("camera", "camera", "computer", 700.0, 1000), ("camera_usb", "cam2", "computer", 700.0, 800)]
power = [("battery", "dcdc", 24.0, 9.0, 30.0), ("dcdc", "computer", 12.0, 9.0, 27.0), ("dcdc", "imu", 12.0, 3.0, 5.5), ("battery", "motor_driver", 24.0, 12.0, 30.0)]
findings = []
for name, a, b, rate, link in data:
    for end in (a, b):
        if end not in subsystems:
            findings.append(f"{name}: unknown subsystem '{end}'")
    if rate > 0.7 * link:
        findings.append(f"{name}: {rate} Mbit/s is above 70 % of the {link} Mbit/s link")
for a, b, v, lo, hi in power:
    if not lo <= v <= hi:
        findings.append(f"power {a}->{b}: {v} V is outside the input range {lo}-{hi} V")
print("\n".join(findings) or "no findings")

Printed (checked by the site’s tests):

camera: unknown subsystem 'camera'
camera_usb: unknown subsystem 'cam2'
camera_usb: 700.0 Mbit/s is above 70 % of the 800 Mbit/s link
power dcdc->imu: 12.0 V is outside the input range 3.0-5.5 V

Reading it: camera names a subsystem that was never declared (a typo or a missing block); camera_usb is over the 70 % limit of an 800 Mbit/s link; and a 12 V output is wired to an IMU input that accepts at most 5.5 V, which would destroy it. All four are found before any hardware is bought. The numbers are illustrative.

8. Real examples

  • Example AMR: a 24 V battery feeds the motor driver directly and a DC-DC converter for the computer; LiDAR over Ethernet; IMU over SPI to a microcontroller; velocity commands to the microcontroller over USB or CAN. Each link is a row in the ICD.

9. Failure scenarios

  • A sensor ordered with a 5 V-only input and powered from 12 V.
  • Two teams assume different axis conventions for the same sensor frame.
  • A link works on the bench and saturates when all sensors run together.
  • An interface changed by one side and not recorded.

10. Troubleshooting

  1. Symptom: a device does not power up or resets. Check the ICD row for the voltage and current, then measure.
  2. Symptom: data is lost. Compare the measured rate with the ICD rate and link capacity.
  3. Symptom: transforms look wrong. Check the frame row against REP 103.
  4. Update the ICD first, then the hardware or software.

11. Validation

  • The checker prints no findings after the example errors are fixed.
  • Each interface has one owner.
  • Every row has units.
  • Measured rates on the integrated robot are within the ICD limits.

12. Engineering checklist

13. Further references

Related on FixTheRobot