☕️ Coffee Machine Example¶
This example demonstrates a complete traceability chain for a coffee machine system, from high-level requirements down to implementation and test cases.
The BrewMaster Pro 3000 is an advanced automatic coffee machine designed for commercial and high-end residential use. Featuring precision temperature control, customizable brew strength settings, and comprehensive safety mechanisms, it represents the cutting edge of coffee brewing technology. This document traces the complete development lifecycle from initial customer needs through verified implementation.
System Requirements¶
The system requirements capture the fundamental capabilities that the BrewMaster Pro 3000 must deliver to meet customer expectations and safety standards. These high-level requirements define what the system does from an external perspective, focusing on user-visible behavior and safety constraints. Each requirement has been derived from market analysis, customer feedback, and applicable safety regulations for household appliances.
The coffee machine shall be able to brew coffee with user-selected strength (weak, medium, strong). |
The coffee machine shall heat water to the appropriate temperature (85-95°C) for brewing coffee. |
The coffee machine shall provide a user interface with buttons for selecting coffee strength and starting the brewing process. |
The coffee machine shall automatically shut down if the water temperature exceeds 100°C or if no water is detected. |
Software Requirements¶
The software requirements section refines the high-level system requirements into detailed, implementable specifications for the embedded control system. The BrewMaster Pro 3000 runs on a custom Rust-based embedded platform with real-time capabilities, chosen for its memory safety guarantees, zero-cost abstractions, and excellent embedded systems support. These requirements specify precise timing constraints, control algorithms, and safety-critical behavior that must be implemented in software. Each software requirement is traceable back to one or more system requirements, ensuring complete coverage of customer needs.
The temperature control software shall monitor the water temperature sensor and regulate the heating element to maintain temperature between 85-95°C using PID control. |
The software shall continuously monitor water temperature and trigger an emergency shutdown within 100ms if temperature exceeds 100°C to prevent boiling and potential hazards. |
The software shall implement brew strength selection by controlling the water flow rate and brewing time:
|
The software shall process button inputs with debouncing and trigger appropriate actions (strength selection, start brewing, stop/cancel). |
The software shall continuously monitor the water level sensor and prevent brewing operations when water level is below minimum threshold. |
Software Architecture¶
The software architecture defines the modular structure of the BrewMaster Pro 3000’s embedded control system. The architecture follows a layered approach with clear separation of concerns: safety-critical functions are isolated in dedicated modules, control algorithms are encapsulated for reusability, and user interface logic is decoupled from core brewing operations. This modular design enables independent testing, facilitates maintenance, and provides clear interfaces between components.
The architecture emphasizes fail-safe design principles. The Safety Monitor Module operates with the highest priority and can override all other subsystems. Module dependencies are carefully managed to prevent circular references and ensure deterministic behavior. The following diagram shows the architectural modules and their relationships:
Module responsible for PID-based temperature control. Interfaces:
|
Module managing the brewing process state machine. States: IDLE, HEATING, BREWING, COMPLETE, ERROR. Controls pump and valve timing based on selected strength. Waits for temperature ready signal before initiating brew cycle. Monitors safety status continuously.
|
Module handling all user interactions including button debouncing, LED status indicators, and display updates. Interfaces with the Brew Controller to send user commands (strength selection, start/stop).
|
Module performing continuous safety checks on temperature and water level. Implements fail-safe shutdown procedures.
|
Module providing abstraction over hardware sensors and actuators. Handles low-level sensor reading via ADC, signal conditioning, and calibration. Interfaces:
Implements DMA-based ADC sampling at 100Hz with automatic averaging and outlier rejection for robust sensor readings.
|
Component Interfaces¶
The following interfaces define the communication contracts between architectural components. Each interface specifies the data exchanged, protocols used, and timing constraints to ensure deterministic and safe inter-component communication.
Provider: Temperature Controller Module Consumer: Brew Controller Module Description: Provides current temperature readings and heating status to the brew controller. Data Elements:
Protocol: Shared memory with atomic updates, 100ms refresh rate |
Provider: Safety Monitor Module Consumers: Temperature Controller, Brew Controller Description: Emergency shutdown commands from safety monitor to all controlled subsystems. Commands:
Protocol: Interrupt-driven with hardware watchdog backup, highest priority |
Provider: Temperature Controller Module Consumer: Safety Monitor Module Description: Heartbeat and fault status reported by the Temperature Controller to the Safety Monitor for fault detection. Data Elements:
Protocol: Polled by safety monitor at 10Hz |
Provider: Brew Controller Module Consumer: Safety Monitor Module Description: Heartbeat and fault status reported by the Brew Controller to the Safety Monitor for fault detection. Data Elements:
Protocol: Polled by safety monitor at 10Hz |
Provider: User Interface Module Consumer: Brew Controller Module Description: User commands and settings passed from UI to the brewing state machine. Commands:
Protocol: Message queue with event-driven processing, debounced at UI layer |
Provider: Hardware sensors (temperature, water level) Consumers: Temperature Controller, Safety Monitor Description: Raw sensor readings from hardware via ADC. Data Elements:
Protocol: ADC DMA with double buffering, 100Hz sampling rate |
Static View¶
Dynamic View¶
The sequence diagrams below show how the architectural components interact at runtime. Participants map directly to the components defined in the Static View.
The diagrams are generated by needsequence, which traverses the startup_calls
/ shutdown_calls links defined on each component need. Each seq_msg (SEQSTART_01)
need in the chain represents one message; odd hops are participants,
even hops are messages.
Startup Sequence¶
On power-on the system initialises hardware, validates initial sensor readings, then brings all control modules online in dependency order before signalling readiness to the user.
The sequence message needs (SEQSTART_01–SEQSTART_10) are
defined below. COMP_UI_MODULE is the starting participant.
Startup Sequence Messages
HAL hardware initialisation call from UI Module. |
HAL confirms successful ADC calibration to UI Module. |
UI Module requests Safety Monitor to start and run pre-checks. |
Safety Monitor polls HAL for initial sensor readings. |
HAL returns |
Safety Monitor starts Temperature Controller Module. |
Temperature Controller confirms startup via heartbeat on |
Safety Monitor starts Brew Controller Module. |
Brew Controller confirms startup via heartbeat on |
Safety Monitor signals system readiness to UI Module; UI illuminates the Ready LED. |
Safety Shutdown Sequence¶
If the Safety Monitor detects an over-temperature condition it issues
an EMERGENCY_STOP command on INTF_SAFETY_CMD to all controlled
subsystems. All modules must respond within 100 ms.
The sequence message needs (SEQSHTDWN_01–SEQSHTDWN_06) are
defined below. COMP_HAL is the starting participant (it is the
source of the over-temperature sensor reading).
Safety Shutdown Sequence Messages
HAL reports temperature exceeding 100 °C threshold to Safety Monitor
via |
Safety Monitor broadcasts |
Temperature Controller confirms shutdown and reports |
Safety Monitor broadcasts |
Brew Controller confirms abort and reports |
Safety Monitor notifies UI Module of over-temperature fault; UI illuminates the Error LED and displays the fault message. |
Implementation¶
The implementation phase translates the architectural designs into working code. All BrewMaster Pro 3000 software is implemented in Rust, leveraging its memory safety guarantees, zero-cost abstractions, and excellent embedded systems support.
The choice of Rust provides critical advantages for safety-critical applications: compile-time memory safety prevents entire classes of bugs, the type system enforces correct API usage, and the no_std capability enables bare-metal operation if needed. The implementation follows strict coding standards including comprehensive documentation, clippy linting at the pedantic level, and zero unsafe code in safety-critical modules.
Each implementation artifact maps directly to an architectural module,
ensuring traceability from design to code. The code is organized as a
Cargo workspace located in ../../brewmaster-controller/ relative
to this documentation, with clear module boundaries matching the
architectural decomposition.
Rust Interface Implementations¶
The following interface implementations are extracted from the Rust
source code in crates/coffee-machine/src/interfaces.rs. Each
implementation is automatically traced to its corresponding interface
and component specifications through codelinks annotations.
Rust Artifacts
Test Cases¶
Comprehensive testing ensures that the BrewMaster Pro 3000 meets all specified requirements and operates safely under all conditions. The test strategy employs multiple levels:
Unit Tests: Verify individual components in isolation (temperature control, button debouncing, state machine transitions)
Integration Tests: Validate interactions between modules (brew controller coordinating with temperature controller)
System Tests: End-to-end verification of complete brewing cycles
Safety Tests: Dedicated verification of all safety-critical functions under normal and fault conditions
All tests are automated and integrated into the continuous integration pipeline. Safety-critical tests are executed on hardware-in-the-loop test benches that simulate real sensors, actuators, and fault conditions. Test coverage targets are set based on the criticality of each component.
Objective: Verify temperature controller maintains target temperature within ±2°C. Steps:
Expected: PWM duty cycle decreases as temperature approaches target, maintains oscillation within ±2°C of setpoint. |
Objective: Verify all three strength settings produce correct timing and water volume. Test Cases:
|
Objective: Verify button handler correctly debounces rapid inputs. Steps:
Expected: Only 1-2 events triggered (first press + possible bounce after 50ms timeout). |
Objective: Verify safety monitor triggers shutdown on critical conditions. Test Cases:
|
Objective: Verify complete brewing cycle from user input to coffee output. Steps:
Expected: System heats to 85-95°C, dispenses 180ml over 4 minutes, returns to idle state, no safety triggers. |
Traceability Overview¶
Complete traceability is a cornerstone of the BrewMaster Pro 3000 development process. Every line of code can be traced back through architectural designs and requirements to the original customer need or safety regulation. Conversely, every requirement can be traced forward to its implementation and verification test cases. This bidirectional traceability ensures nothing is missed and enables rapid impact analysis when requirements change.
The sphinx-needs tool automates traceability management, maintaining links between artifacts and generating visual diagrams. This example demonstrates:
Requirements → SW Requirements: High-level needs decomposed into software-specific requirements
SW Requirements → Architecture: Requirements mapped to software modules
Architecture → Implementation: Architectural designs realized in code
Implementation → Tests: All implementations verified through test cases
Use the query tools to explore the relationships between these needs and verify complete traceability coverage.
Traceability Diagram¶
The following diagram shows all needs and their connections in this coffee machine example:
Used filter: types(req OR swreq OR component OR interface OR impl OR test)