Requirements, design and documentation for robot software

Most failed robot projects do not fail because the team could not write code. They fail because the team built the wrong thing, or built the right thing without being able to show that it works. Requirements engineering is the discipline of deciding, writing down and checking what the system must do. Design turns those requirements into a structure. Documentation keeps both understandable as people come and go. This lesson covers practical techniques suited to robot teams: use cases and operational scenarios, well-formed requirements with verification methods, interface control documents, architecture decision records and traceability.

From needs to requirements

Requirements start with stakeholders: the customer who pays, the operators who work beside the robot, maintenance technicians, safety officers, regulators and the team itself. Each has needs expressed in their own words: 'the robot must not get in the way of forklifts', 'I want to swap the battery in five minutes'. The engineer's job is to turn these into requirements that are specific enough to design against and test.

Robot teams often begin with an operational design domain (ODD), a description of the conditions under which the robot is meant to work: the environment (indoor warehouse, aisles at least 1.8 m wide, concrete floor, slopes under 2 %), the lighting, the people and vehicles present, temperatures, network coverage and so on. The ODD bounds the problem. A requirement such as 'the robot shall localize to within 5 cm' only means something inside a stated ODD, and behaviour outside it, such as stopping and calling for help, must be specified too.

Use cases and scenarios describe how the system is used. A use case names an actor and a goal ('operator sends robot to dock') and lists the main sequence of steps plus alternative and exception flows (dock occupied, path blocked, battery critical). For robots, scenario lists are especially valuable because they become test cases, both in simulation and on the real robot. Writing the exception flows is where most of the value lies; the happy path is usually obvious.

Writing good requirements

A good requirement is necessary, unambiguous, verifiable, feasible and singular (one requirement per statement). The conventional form uses 'shall' for mandatory requirements: 'The robot shall stop within 0.5 m of a detected person when travelling at up to 1.5 m/s.' It names a measurable quantity, a condition and a limit. Contrast 'The robot shall be safe around people', which no test could ever confirm. The EARS templates (easy approach to requirements syntax) help by giving patterns such as 'When <trigger>, the <system> shall <response>' and 'While <state>, the <system> shall <response>'.

Requirements fall into functional requirements (what the robot does: navigate to a station, pick a tote) and non-functional or quality requirements (how well: latency, availability, accuracy, maintainability, security). Robots also have many constraints imposed from outside: a maximum mass, a power budget, a required safety standard, a supported operating system. Each requirement should carry an identifier, a rationale explaining why it exists, its source, its priority and its verification method.

Requirements for reliability and statistics

Many robot requirements are statistical, because the world is variable. A requirement like 'the robot shall successfully dock 99 % of the time' raises a practical question: how many trials are needed to show it? If the robot docks successfully in all n trials, a common approximation (the rule of three) says the 95 % upper confidence bound on the failure rate is about 3/n. To show a failure rate below 1 % with no failures observed, you need about 300 successful trials. To show 99.9 %, you need about 3000. This is one reason simulation is so valuable: it makes thousands of trials affordable, provided the simulation is trustworthy (lessons 5 and 8).

import math
# Trials needed to claim failure rate below p with 95 % confidence and zero failures seen:
# (1 - p)^n <= 0.05  ->  n >= ln(0.05) / ln(1 - p)
for p in (0.05, 0.01, 0.001):
    n = math.ceil(math.log(0.05) / math.log(1 - p))
    print(f"failure rate < {p:.3f}: need {n} consecutive successes (rule of three gives {3/p:.0f})")
# With failures allowed, use the binomial distribution: probability of seeing <= k failures
def p_at_most(k, n, p):
    return sum(math.comb(n, i) * p**i * (1 - p)**(n - i) for i in range(k + 1))
print(f"chance a 1-percent robot shows 0 failures in 300 runs: {p_at_most(0, 300, 0.01):.3f}")
print(f"chance a 2-percent robot shows <= 1 failure in 300 runs: {p_at_most(1, 300, 0.02):.3f}")

failure rate < 0.050: need 59 consecutive successes (rule of three gives 60)
failure rate < 0.010: need 299 consecutive successes (rule of three gives 300)
failure rate < 0.001: need 2995 consecutive successes (rule of three gives 3000)
chance a 1-percent robot shows 0 failures in 300 runs: 0.049
chance a 2-percent robot shows <= 1 failure in 300 runs: 0.017

The last two lines show the other side: even a robot that fails 2 % of the time has a small but real chance of passing a short test. Acceptance tests should therefore be designed with both risks in mind, the risk of rejecting a good system and the risk of accepting a bad one, and the requirement should say which statistic is used.

Interfaces and interface control documents

Interfaces are where robot projects break. A camera team publishes images in one frame convention and the perception team assumes another; a motor drive expects velocity in revolutions per minute and receives radians per second. An interface control document (ICD) defines each interface precisely: message type and fields, units, coordinate frames, rates, latency budget, quality-of-service settings, ownership, error handling and versioning. In ROS 2, much of this is captured in the .msg, .srv and .action definitions themselves, which is a strong reason to write them carefully, with units in field names or comments and with REP 103 (units and conventions) and REP 105 (frames) followed consistently.

# DockStatus.msg  (listing) -- an interface definition doubles as documentation
# Published by: dock_manager at 2 Hz, QoS reliable, transient local depth 1
std_msgs/Header header        # stamp = time of last state change; frame_id = "map"
uint8 STATE_IDLE=0
uint8 STATE_APPROACHING=1
uint8 STATE_DOCKED=2
uint8 STATE_FAULT=3
uint8 state
float32 distance_to_dock_m     # along the approach path (m); NaN if unknown
float32 charge_current_a       # amperes into the battery; 0 when not docked
string fault_text              # empty unless state == STATE_FAULT

Interfaces also need versioning rules. Adding an optional field is usually compatible; changing the meaning or units of a field is not, and should create a new message type or a new topic. Teams that share message packages across many repositories pin versions and run compatibility checks in continuous integration (lesson 7).

Design decisions and architecture decision records

Every project makes hundreds of design decisions: which SLAM library, which middleware vendor, whether to use behaviour trees or state machines, whether to run perception on a GPU module. Months later, nobody remembers why. An architecture decision record (ADR) is a short document, often a page, that captures one significant decision: the context and forces at play, the options considered, the decision, and its consequences, good and bad. ADRs are numbered, dated and kept in the repository next to the code, and they are never edited after acceptance; a later ADR supersedes an earlier one if the decision changes.

Traceability and the V-model

Traceability links each requirement to the design elements that implement it and the tests that verify it, and back again. It answers questions like 'which tests must be rerun if we change the stopping requirement?' and 'which requirement does this test exist for?'. Safety standards such as ISO 13849, IEC 61508 and ISO 26262, met in ROB-320, require traceability for safety functions. The V-model pictures the relationship: the left side descends from needs through system requirements and architecture to detailed design and code; the right side ascends through unit, integration and system tests to acceptance, with each level of testing verifying the matching level of design.

Agile teams sometimes see the V-model as heavyweight, but the two fit together: a sprint can still trace its stories to requirements and its acceptance criteria to tests. What matters is that the links exist and are kept current, ideally in tools that live alongside the code, such as requirement IDs in test names and a script that reports untested requirements.

Documentation that stays alive

Documentation decays unless it is cheap to maintain. Practical habits help: keep docs in the repository as Markdown or reStructuredText so they are reviewed with code; generate API documentation from code comments (for example with Doxygen or Sphinx, as the ROS documentation system does); keep a README in every package stating what it does, its interfaces and how to run its tests; and write runbooks for operators and field technicians in plain language. A good test is whether a new team member can build, run and test a package in a day using only its documentation.