makerspet--oomwoo/docs/ARCHITECTURE.md

OOMWOO Architecture Brief

Status: DRAFT / skeleton. This document defines the system so that modules can be built in parallel without colliding. Sections marked TBD are the gating decisions; until they are filled in, hardware modules that must fit together cannot be finalized. Treat the interface specs as the contract every module agrees to.

1. Purpose/Goal and scope

OOMWOO is an open-source, 3D-printed, ROS2-based home robot vacuum with 2D LiDAR and Home Assistant support. It is designed to be built from scratch by the community, module by module, clean well and to double as an affordable ROS2 development and learning platform.

North star (not MVP): OOMWOO is also the reference hardware for a broader robot application platform. Architectural boundaries (especially the app layer in §6) are drawn with that future in mind, but the MVP below deliberately excludes it.

2. Design principles

• Open and swappable. Every module has a defined interface. Any compliant implementation can replace another. No module depends on the internals of another, only on its published interface.
• Simulation-first. Software must run in Gazebo before it runs on hardware, so contributors with no robot can still build and test.
• Affordable and printable. Target off-the-shelf parts (a CM4/CM5-class compute module, common vacuum LiDARs, sourced Roborock/Dreame/Xiaomi motors and wear parts) and FDM-printable chassis parts.
• Safety is reviewed, not crowd-trusted. Battery, charging, and motor-driver modules pass a maintainer safety review before merge (see §8).
• Reference-design backed. A known-working vacuum (see the references in the README) anchors the geometry and proves feasibility.

3. System overview

   LiDAR (UART, ~5 Hz) · MIPI camera(s) · IMU · serial audio
                    |
      +-------------v-------------------------------+
      |  CPU - CM4 / CM5 (or pin-compatible module) |
      |  ROS2 · SLAM (slam_toolbox) · Nav2 · behavior |
      |  educational variant: ESP32-S3 + micro-ROS  |
      |  (SLAM offboard on a dev PC over Wi-Fi)      |
      +-------------^----------------+---------------+
       serial (cmds/telemetry) +     |  custom serial protocol
       CPU-reset / health GPIO       |  (NOT micro-ROS)
      +-------------+----------------v---------------+
      |  MCU - STM32G070 (FreeRTOS, static alloc)    |
      |  motors · encoders · sensors · charging ctrl |
      |  SAFETY (no Linux/ROS2): bumper/cliff/wheel- |
      |  drop stop · current limit · CPU watchdog    |
      +-------------+--------------------+-----------+
                    |                    |
         +----------+----+      +--------+---------+
         | L/R drive     |      | suction fan,     |
         | wheels, brush |      | bumper, cliff,   |
         |               |      | IR, wheel-drop   |
         +---------------+      +------------------+

   Power: off-the-shelf 4S2P Li-ion pack (built-in BMS).
   The CPU module + MCU sit on one carrier I/O board.

The CPU/MCU split keeps all hard safety on the MCU, independent of Linux/ROS2. Interfaces are largely decided (see §5); refine as the io-pcb spec settles.

4. Coordinate frames and conventions

• TBD: Define base_link origin and orientation (REP-103: x-forward, y-left, z-up). All mechanical mounting points and URDF frames reference this.
• TBD: Define the reference plane (floor contact), robot diameter, and height envelope. These two numbers gate every hardware module. Source these from the sourced parts + a 3D-scanned donor (see source-3d-models); the current baseline is a ~349 mm round body (oomwoo-one URDF).
• Units: millimeters, kilograms, SI. Right-handed frames. Angles in radians.

5. Hardware architecture

5.1 Chassis and reference frame

The chassis is the integration backbone. It publishes the mounting interface every other hardware module targets. Reference geometry (dimensions, wheelbase, motor specs, mass) comes from the sourced parts (BOM) + 3D scans of a donor vacuum (see source-3d-models); the oomwoo-one URDF carries the current ~349 mm round-body baseline.

• TBD: Overall diameter and height budget.
• TBD: Mounting grid / bolt pattern standard (e.g., M3 on a defined pitch).
• TBD: Mass budget per module and total target mass.

5.2 Mechanical interface standard (the contract)

Every hardware module's RFC must specify, against this standard:

• Mounting points (bolt pattern, location relative to base_link).
• Bounding envelope (max size the module may occupy).
• Mass budget.
• Mating tolerances and print orientation.
• TBD: Define the standard connector/fastener set (screw sizes, heat-set inserts, etc.) so parts from different authors actually mate.

5.3 Electrical interface standard (the contract)

• Battery: off-the-shelf pack with a built-in BMS — 4S2P Li-ion, ~14.4 V nominal, ~5200 mAh / ~75 Wh (OEM BRR-2P4S-5200 class), charged 16.8 V CC/CV with NTC temperature sense. Chemistry is now decided; see the BOM.
• TBD: Power rails distributed to modules (VBAT, 5V, 3.3V) and connector types/pinouts.
• CPU ↔ MCU: a custom high-speed serial protocol (not micro-ROS) carries commands/telemetry, plus discrete GPIOs (CPU power on/off, and a CPU-reset line the MCU asserts on missed health packets). The MCU owns motors and sensors; the CPU never drives them directly.
• Sensors: bumper/cliff/wheel-drop and analog IR are MCU-side (digital in / ADC); the LiDAR (UART, ~5 Hz), MIPI camera(s), IMU, and serial audio attach to the CPU.

5.4 Compute (CPU) and real-time controller (MCU)

OOMWOO splits compute across two processors — mirroring how consumer vacuums are built, and, crucially, so that safety never depends on Linux/ROS2.

CPU (compute module). The I/O board is a carrier that accepts a Raspberry Pi Compute Module 4 or 5 and — because the CM4 pinout is a de-facto standard — the many pin-compatible alternative modules (Radxa CM3/CM4, Pine64 SOQuartz, LuckFox Core3566, …), several with an NPU for future on-device vision. The CPU runs ROS2, SLAM (slam_toolbox), Nav2, LiDAR processing, and high-level behavior. CM modules are low-profile (helps the height budget) and swappable (hackable, cheaper, NPU options).

• Minimum target: a 4 GB CM4/CM5 (or Pi 4). Realistic prior art runs slam_toolbox + Nav2 onboard a 4 GB Pi 4. Getting the floor to 2 GB is a goal (ROS2 composable nodes; selectively rewriting heavy Python nodes in Rust/C++) — no guarantee, to be settled by the compute-benchmark. No 8–16 GB module needed.
• Cooling: no dedicated CPU fan — the suction fan's airflow cools the compute board, as in consumer vacuums.
• The earlier bespoke RK3562 reference schematic is dropped in favour of the CM4/CM5 carrier.

MCU (real-time / safety controller). A dedicated microcontroller — tentatively the STM32G070RBT6 (~56 GPIO incl. 16 ADC channels, ~$1 at JLCPCB, LQFP not BGA) — owns motors, encoders, all sensors, battery-charging control, and safety. Its role is fixed: functionality does not migrate onto the CPU, and CPU work does not migrate onto the MCU.

• Firmware is tentatively FreeRTOS (static allocation, watchdog, guaranteed reaction times, CE-oriented) speaking a custom serial protocol — not micro-ROS (the tried-and-true consumer-vacuum approach; cf. the reverse-engineered 3irobotix protocol).
• Hard safety lives here, independent of Linux/ROS2: the MCU stops all motors on a bumper hit, cliff detection, or wheel-drop, current-limits a stuck brush, and watchdogs the CPU — if the CPU's health packets stop, it stops the motors and can reset the CPU.
• Tentative ~60-signal pin budget: see the io-pcb RFC appendix (why the MCU needs a high-GPIO part).

CPU ↔ MCU link. A high-speed serial channel carries commands/telemetry both ways, plus discrete GPIOs — notably the CPU-reset line the MCU asserts on missed health packets, and CPU power on/off. Any LiDAR supported by kaiaai/LDS / lds2d is interface-compatible.

5.5 Two build profiles

The same carrier I/O board + MCU supports two swappable compute configurations:

	Consumer / regular	Educational / lower-cost
CPU-slot module	CM4 / CM5 (or pin-compatible alt)	ESP32-S3 board in the CM4 form factor
Where ROS2 / SLAM runs	onboard (ROS2 + slam_toolbox + Nav2)	offboard on a local dev PC; ESP32-S3 runs micro-ROS
Link	self-contained robot	robot ↔ dev PC over Wi-Fi
Trade-off	plug-and-play for non-experts	cheaper, but Wi-Fi congestion / dead-zones — a learning platform, not a polished consumer product

Onboard SLAM is the default for the consumer version so non-experts can build and use it without setting up a separate ROS2 dev machine. The ESP32-S3 can only be the CPU-slot option — it lacks the ~60 GPIO the MCU role needs, so it never replaces the STM32.

6. Software architecture

6.1 ROS2 graph (MVP)

• Core nodes (MVP): LiDAR driver, base controller (diff-drive), odometry, teleop, SLAM (manual mapping), TF/URDF publisher.
• Interface contract: each software module's RFC declares the ROS2 topics, services, message types, and parameters it publishes/consumes. Modules depend on these interfaces, not on each other's code. See SOFTWARE_INTERFACES.md for the current draft ROS2 graph contract.

6.2 Simulation

• Gazebo + URDF, with a set of residential-layout worlds for navigation and coverage testing. Sim parity is a first-class requirement, not an afterthought.

6.3 Application layer (Phase 2 — north star, NOT in MVP)

A ROS2-agnostic layer that runs third-party apps locally in isolated Podman containers, so app developers need no ROS2 expertise. Documented here only to keep its boundary clean; explicitly out of scope for the Aug 31 MVP.

7. MVP definition (target: 2026-08-31)

In scope: ROS2 on a CM4/CM5-class compute module · LiDAR · manual SLAM/mapping · teleop drive · 3D-printed chassis · Gazebo sim with URDF · evaluation + demo video. No dock, no autonomous exploration, no Home Assistant, no app layer.

Explicit non-goals for MVP: autonomous coverage, docking, auto-empty, mopping, Home Assistant, the app platform, accessories. These are later phases.

Critical-path ownership: the maintainer (+ small core) own the chassis, interface specs, and integration so the MVP does not depend on volunteer delivery timing. Community modules accelerate and improve the MVP; they do not block it.

8. Safety review gate

Battery, charging, motor-driver, and mains-adjacent modules require maintainer safety review before merge. RFCs for these modules must include a hazard note (over-current, thermal, short, mechanical pinch).

The battery risk is reduced by using an off-the-shelf 4S2P Li-ion pack with a built-in BMS (over-charge / over-discharge / short protection); the review then focuses on the 16.8 V CC/CV charging path + NTC temperature sense. Hard safety lives on the MCU, never on Linux/ROS2 — it independently stops motors on bumper/cliff/wheel-drop, current-limits a stuck brush, and watchdog-resets the CPU.

9. Roadmap (phases after MVP)

1. Rechargeable battery + basic dock + autonomous floor mapping.
2. Home Assistant integration.
3. Application layer (Podman app runtime) + first delightful apps.
4. Accessories and novel apps; integrations (e.g., LeRobot arm).

10. Open questions

• Resolved: the MCU runs a custom serial protocol (not micro-ROS); the CPU runs onboard ROS2/SLAM/Nav2. micro-ROS is used only in the educational ESP32-S3 profile (SLAM offboard on a dev PC). See §5.4–5.5.
• Resolved: battery is an off-the-shelf 4S2P Li-ion pack with a built-in BMS, charged 16.8 V CC/CV. See §5.3, §8.
• Can OOMWOO's onboard ROS2 stack fit in 2 GB (composable nodes, selective Rust) rather than 4 GB? To be answered by the compute-benchmark.
• MCU family: STM32G070RBT6 is the tentative pick (GPIO/ADC count, ~$1 at JLCPCB, LQFP) — open to alternatives.
• One hardware-agnostic HAL covering reference vacuum + DIY builds (community idea)?
• Module selection process: who decides which competing implementation wins, and on what criteria? (See each module's acceptance criteria.)