{"owner":"makerspet","repo":"oomwoo","hasSkills":true,"totalSkillsCount":1,"totalTokensCount":3382,"categories":["project-spec"],"hasMcp":false,"mcpConfig":null,"found":["docs/ARCHITECTURE.md"],"skills":{"docs/ARCHITECTURE.md":"# OOMWOO Architecture Brief\n\n> *Status: DRAFT / skeleton.* This document defines the system so that modules\n> can be built in parallel without colliding. Sections marked *TBD* are the\n> gating decisions; until they are filled in, hardware modules that must fit\n> together cannot be finalized. Treat the interface specs as the contract every\n> module agrees to.\n\n## 1. Purpose/Goal and scope\n\nOOMWOO is an open-source, 3D-printed, ROS2-based home robot vacuum with 2D LiDAR\nand Home Assistant support. It is designed to be *built from scratch by\nthe community*, module by module, clean well and to double as an affordable ROS2\ndevelopment and learning platform.\n\n*North star (not MVP):* OOMWOO is also the reference hardware for a broader\nrobot application platform. Architectural boundaries (especially the app layer in\n§6) are drawn with that future in mind, but the MVP below deliberately excludes it.\n\n## 2. Design principles\n\n- *Open and swappable.* Every module has a defined interface. Any compliant\n  implementation can replace another. No module depends on the internals of\n  another, only on its published interface.\n- *Simulation-first.* Software must run in Gazebo before it runs on hardware,\n  so contributors with no robot can still build and test.\n- *Affordable and printable.* Target off-the-shelf parts (a CM4/CM5-class compute\n  module, common vacuum LiDARs, sourced Roborock/Dreame/Xiaomi motors and wear\n  parts) and FDM-printable chassis parts.\n- *Safety is reviewed, not crowd-trusted.* Battery, charging, and motor-driver\n  modules pass a maintainer safety review before merge (see §8).\n- *Reference-design backed.* A known-working vacuum (see the references in the\n  [README](../README.md)) anchors the geometry and proves feasibility.\n\n## 3. System overview\n\n```\n   LiDAR (UART, ~5 Hz) · MIPI camera(s) · IMU · serial audio\n                    |\n      +-------------v-------------------------------+\n      |  CPU - CM4 / CM5 (or pin-compatible module) |\n      |  ROS2 · SLAM (slam_toolbox) · Nav2 · behavior |\n      |  educational variant: ESP32-S3 + micro-ROS  |\n      |  (SLAM offboard on a dev PC over Wi-Fi)      |\n      +-------------^----------------+---------------+\n       serial (cmds/telemetry) +     |  custom serial protocol\n       CPU-reset / health GPIO       |  (NOT micro-ROS)\n      +-------------+----------------v---------------+\n      |  MCU - STM32G473 (FreeRTOS, static alloc)    |\n      |  motors · encoders · sensors · charging ctrl |\n      |  SAFETY (no Linux/ROS2): bumper/cliff/wheel- |\n      |  drop stop · current limit · CPU watchdog    |\n      +-------------+--------------------+-----------+\n                    |                    |\n         +----------+----+      +--------+---------+\n         | L/R drive     |      | suction fan,     |\n         | wheels, brush |      | bumper, cliff,   |\n         |               |      | IR, wheel-drop   |\n         +---------------+      +------------------+\n\n   Power: off-the-shelf 4S2P Li-ion pack (built-in BMS).\n   The CPU module + MCU sit on one carrier I/O board.\n```\n\n> The CPU/MCU split keeps *all hard safety on the MCU*, independent of Linux/ROS2.\n> Interfaces are largely decided (see §5); refine as the io-pcb spec settles.\n\n## 4. Coordinate frames and conventions\n\n- *TBD:* Define `base_link` origin and orientation (REP-103: x-forward,\n  y-left, z-up). All mechanical mounting points and URDF frames reference this.\n- *TBD:* Define the reference plane (floor contact), robot diameter, and height\n  envelope. *These two numbers gate every hardware module.* Source these from the *sourced\n  parts* + a 3D-scanned donor (see [source-3d-models](../contributions/source-3d-models));\n  the current baseline is a ~349 mm round body ([oomwoo-one URDF](https://github.com/makerspet/oomwoo-one)).\n- Units: millimeters, kilograms, SI. Right-handed frames. Angles in radians.\n\n## 5. Hardware architecture\n\n### 5.1 Chassis and reference frame\nThe chassis is the *integration backbone*. It publishes the mounting interface\nevery other hardware module targets. Reference geometry (dimensions, wheelbase,\nmotor specs, mass) comes from the *sourced parts* ([BOM](../BOM.md)) + 3D scans of\na donor vacuum (see [source-3d-models](../contributions/source-3d-models)); the\n[oomwoo-one URDF](https://github.com/makerspet/oomwoo-one) carries the current\n~349 mm round-body baseline.\n\n- *TBD:* Overall diameter and height budget.\n- *TBD:* Mounting grid / bolt pattern standard (e.g., M3 on a defined pitch).\n- *TBD:* Mass budget per module and total target mass.\n\n### 5.2 Mechanical interface standard (the contract)\nEvery hardware module's RFC must specify, against this standard:\n- Mounting points (bolt pattern, location relative to `base_link`).\n- Bounding envelope (max size the module may occupy).\n- Mass budget.\n- Mating tolerances and print orientation.\n- *TBD:* Define the standard connector/fastener set (screw sizes, heat-set\n  inserts, etc.) so parts from different authors actually mate.\n\n### 5.3 Electrical interface standard (the contract)\n- *Battery:* off-the-shelf pack with a *built-in BMS* — *4S2P Li-ion*, ~14.4 V\n  nominal, ~5200 mAh / ~75 Wh (OEM BRR-2P4S-5200 class), charged 16.8 V CC/CV with\n  NTC temperature sense. Chemistry is now decided; see the [BOM](../BOM.md).\n- *TBD:* Power rails distributed to modules (VBAT, 5V, 3.3V) and connector types/pinouts.\n- *CPU ↔ MCU:* a *custom high-speed serial protocol* (not micro-ROS) carries\n  commands/telemetry, plus discrete GPIOs (CPU power on/off, and a CPU-reset line\n  the MCU asserts on missed health packets). The *MCU owns motors and sensors*; the\n  CPU never drives them directly.\n- *Sensors:* bumper/cliff/wheel-drop and analog IR are *MCU-side* (digital in / ADC);\n  the *LiDAR (UART, ~5 Hz)*, MIPI camera(s), IMU, and serial audio attach to the *CPU*.\n\n### 5.4 Compute (CPU) and real-time controller (MCU)\n\nOOMWOO splits compute across two processors — mirroring how consumer vacuums are\nbuilt, and, crucially, so that *safety never depends on Linux/ROS2*.\n\n*CPU (compute module).* The I/O board is a *carrier* that accepts a *Raspberry Pi\nCompute Module 4 or 5* and — because the CM4 pinout is a de-facto standard — the\nmany *pin-compatible alternative modules* (Radxa CM3/CM4, Pine64 SOQuartz, LuckFox\nCore3566, …), several with an *NPU* for future on-device vision. The CPU runs\n*ROS2, SLAM (slam_toolbox), Nav2, LiDAR processing, and high-level behavior*. CM\nmodules are low-profile (helps the height budget) and swappable (hackable, cheaper,\nNPU options).\n- *Minimum target: a 4 GB CM4/CM5 (or Pi 4).* Realistic prior art runs\n  slam_toolbox + Nav2 onboard a 4 GB Pi 4. Getting the floor to *2 GB* is a goal\n  (ROS2 composable nodes; selectively rewriting heavy Python nodes in Rust/C++) —\n  *no guarantee*, to be settled by the compute-benchmark. No 8–16 GB module needed.\n- *Cooling:* no dedicated CPU fan — the suction fan's airflow cools the compute\n  board, as in consumer vacuums.\n- The earlier bespoke *RK3562* reference schematic is *dropped* in favour of the\n  CM4/CM5 carrier.\n\n*MCU (real-time / safety controller).* A dedicated *STM32G473VCT6* microcontroller\n(Cortex-M4F, LQFP100, multiple ADCs and timer resources), selected by the current\nI/O-board design, owns *motors, encoders, all sensors, battery-charging control,\nand safety*. Its\nrole is *fixed*: functionality does not migrate onto the CPU, and CPU work does not\nmigrate onto the MCU.\n- Firmware uses a layered *FreeRTOS* design (static allocation, watchdog, bounded\n  reaction times, CE-oriented) speaking a *custom serial protocol — not micro-ROS*\n  (the tried-and-true consumer-vacuum approach; cf. the reverse-engineered\n  [3irobotix protocol](https://github.com/codetiger/VacuumRobot)).\n- *Hard safety lives here, independent of Linux/ROS2:* the MCU stops all motors on\n  a *bumper hit, cliff detection, or wheel-drop*, current-limits a *stuck brush*,\n  and *watchdogs the CPU* — if the CPU's health packets stop, it stops the motors\n  and can *reset the CPU*.\n- Tentative ~60-signal pin budget: see the [io-pcb RFC](../contributions/io-pcb)\n  appendix (why the MCU needs a high-GPIO part).\n\n*CPU ↔ MCU link.* A *high-speed serial* channel carries commands/telemetry both\nways, plus discrete GPIOs — notably the *CPU-reset* line the MCU asserts on missed\nhealth packets, and CPU power on/off. The draft protocol, ROS2 bridge mapping,\nand bringup checklist live in the [io-board-interface RFC](../contributions/io-board-interface).\nAny LiDAR supported by `kaiaai/LDS` / `lds2d` is interface-compatible.\n\n### 5.5 Two build profiles\n\nThe same carrier I/O board + MCU supports two swappable compute configurations:\n\n| | *Consumer / regular* | *Educational / lower-cost* |\n|---|---|---|\n| CPU-slot module | CM4 / CM5 (or pin-compatible alt) | *ESP32-S3* board in the CM4 form factor |\n| Where ROS2 / SLAM runs | *onboard* (ROS2 + slam_toolbox + Nav2) | *offboard* on a local dev PC; ESP32-S3 runs *micro-ROS* |\n| Link | self-contained robot | robot ↔ dev PC over *Wi-Fi* |\n| Trade-off | plug-and-play for non-experts | cheaper, but Wi-Fi congestion / dead-zones — a learning platform, not a polished consumer product |\n\nOnboard SLAM is the default for the consumer version *so non-experts can build and\nuse it* without setting up a separate ROS2 dev machine. The ESP32-S3 can only be\nthe *CPU-slot* option — it lacks the ~60 GPIO the MCU role needs, so it never\nreplaces the STM32.\n\n## 6. Software architecture\n\n### 6.1 ROS2 graph (MVP)\n- Core nodes (MVP): LiDAR driver, base controller (diff-drive), odometry,\n  teleop, SLAM (manual mapping), TF/URDF publisher.\n- *Interface contract:* each software module's RFC declares the ROS2 topics,\n  services, message types, and parameters it publishes/consumes. Modules depend\n  on these interfaces, not on each other's code. See\n  [SOFTWARE_INTERFACES.md](SOFTWARE_INTERFACES.md) for the current draft ROS2\n  graph contract.\n\n### 6.2 Simulation\n- Gazebo + URDF, with a set of residential-layout worlds for navigation and\n  coverage testing. Sim parity is a first-class requirement, not an afterthought.\n\n### 6.3 Application layer (Phase 2 — north star, NOT in MVP)\nA ROS2-agnostic layer that runs third-party apps locally in isolated *Podman*\ncontainers, so app developers need no ROS2 expertise. Documented here only to\nkeep its boundary clean; *explicitly out of scope for the Aug 31 MVP.*\n\n## 7. MVP definition (target: 2026-08-31)\n\n*In scope:* ROS2 on a CM4/CM5-class compute module · LiDAR · manual SLAM/mapping · teleop drive ·\n3D-printed chassis · Gazebo sim with URDF · evaluation + demo video. No dock,\nno autonomous exploration, no Home Assistant, no app layer.\n\n*Explicit non-goals for MVP:* autonomous coverage, docking, auto-empty, mopping,\nHome Assistant, the app platform, accessories. These are later phases.\n\n*Critical-path ownership:* the maintainer (+ small core) own the chassis,\ninterface specs, and integration so the MVP does not depend on volunteer delivery\ntiming. Community modules accelerate and improve the MVP; they do not block it.\n\n## 8. Safety review gate\n\nBattery, charging, motor-driver, and mains-adjacent modules require maintainer\nsafety review before merge. RFCs for these modules must include a hazard note\n(over-current, thermal, short, mechanical pinch).\n\nThe battery risk is *reduced* by using an *off-the-shelf 4S2P Li-ion pack with a\nbuilt-in BMS* (over-charge / over-discharge / short protection); the review then\nfocuses on the *16.8 V CC/CV charging path + NTC temperature sense*. *Hard safety\nlives on the MCU, never on Linux/ROS2* — it independently stops motors on\nbumper/cliff/wheel-drop, current-limits a stuck brush, and watchdog-resets the CPU.\n\n## 9. Roadmap (phases after MVP)\n\n1. Rechargeable battery + basic dock + autonomous floor mapping.\n2. Home Assistant integration.\n3. Application layer (Podman app runtime) + first delightful apps.\n4. Accessories and novel apps; integrations (e.g., LeRobot arm).\n\n## 10. Open questions\n\n- *Resolved:* the MCU runs a *custom serial protocol (not micro-ROS)*; the CPU runs\n  *onboard ROS2/SLAM/Nav2*. micro-ROS is used only in the *educational* ESP32-S3\n  profile (SLAM offboard on a dev PC). See §5.4–5.5.\n- *Resolved:* battery is an off-the-shelf *4S2P Li-ion pack with a built-in BMS*,\n  charged 16.8 V CC/CV. See §5.3, §8.\n- Can OOMWOO's onboard ROS2 stack fit in *2 GB* (composable nodes, selective Rust)\n  rather than 4 GB? To be answered by the compute-benchmark.\n- *Resolved:* the reference I/O board uses *STM32G473VCT6*, superseding the earlier\n  STM32G070 candidate. Pin-compatible alternatives remain a separate board-design\n  decision.\n- One hardware-agnostic HAL covering reference vacuum + DIY builds (community idea)?\n- Module selection process: who decides which competing implementation wins, and\n  on what criteria? (See each module's acceptance criteria.)\n"},"files":{"docs/ARCHITECTURE.md":"# OOMWOO Architecture Brief\n\n> *Status: DRAFT / skeleton.* This document defines the system so that modules\n> can be built in parallel without colliding. Sections marked *TBD* are the\n> gating decisions; until they are filled in, hardware modules that must fit\n> together cannot be finalized. Treat the interface specs as the contract every\n> module agrees to.\n\n## 1. Purpose/Goal and scope\n\nOOMWOO is an open-source, 3D-printed, ROS2-based home robot vacuum with 2D LiDAR\nand Home Assistant support. It is designed to be *built from scratch by\nthe community*, module by module, clean well and to double as an affordable ROS2\ndevelopment and learning platform.\n\n*North star (not MVP):* OOMWOO is also the reference hardware for a broader\nrobot application platform. Architectural boundaries (especially the app layer in\n§6) are drawn with that future in mind, but the MVP below deliberately excludes it.\n\n## 2. Design principles\n\n- *Open and swappable.* Every module has a defined interface. Any compliant\n  implementation can replace another. No module depends on the internals of\n  another, only on its published interface.\n- *Simulation-first.* Software must run in Gazebo before it runs on hardware,\n  so contributors with no robot can still build and test.\n- *Affordable and printable.* Target off-the-shelf parts (a CM4/CM5-class compute\n  module, common vacuum LiDARs, sourced Roborock/Dreame/Xiaomi motors and wear\n  parts) and FDM-printable chassis parts.\n- *Safety is reviewed, not crowd-trusted.* Battery, charging, and motor-driver\n  modules pass a maintainer safety review before merge (see §8).\n- *Reference-design backed.* A known-working vacuum (see the references in the\n  [README](../README.md)) anchors the geometry and proves feasibility.\n\n## 3. System overview\n\n```\n   LiDAR (UART, ~5 Hz) · MIPI camera(s) · IMU · serial audio\n                    |\n      +-------------v-------------------------------+\n      |  CPU - CM4 / CM5 (or pin-compatible module) |\n      |  ROS2 · SLAM (slam_toolbox) · Nav2 · behavior |\n      |  educational variant: ESP32-S3 + micro-ROS  |\n      |  (SLAM offboard on a dev PC over Wi-Fi)      |\n      +-------------^----------------+---------------+\n       serial (cmds/telemetry) +     |  custom serial protocol\n       CPU-reset / health GPIO       |  (NOT micro-ROS)\n      +-------------+----------------v---------------+\n      |  MCU - STM32G473 (FreeRTOS, static alloc)    |\n      |  motors · encoders · sensors · charging ctrl |\n      |  SAFETY (no Linux/ROS2): bumper/cliff/wheel- |\n      |  drop stop · current limit · CPU watchdog    |\n      +-------------+--------------------+-----------+\n                    |                    |\n         +----------+----+      +--------+---------+\n         | L/R drive     |      | suction fan,     |\n         | wheels, brush |      | bumper, cliff,   |\n         |               |      | IR, wheel-drop   |\n         +---------------+      +------------------+\n\n   Power: off-the-shelf 4S2P Li-ion pack (built-in BMS).\n   The CPU module + MCU sit on one carrier I/O board.\n```\n\n> The CPU/MCU split keeps *all hard safety on the MCU*, independent of Linux/ROS2.\n> Interfaces are largely decided (see §5); refine as the io-pcb spec settles.\n\n## 4. Coordinate frames and conventions\n\n- *TBD:* Define `base_link` origin and orientation (REP-103: x-forward,\n  y-left, z-up). All mechanical mounting points and URDF frames reference this.\n- *TBD:* Define the reference plane (floor contact), robot diameter, and height\n  envelope. *These two numbers gate every hardware module.* Source these from the *sourced\n  parts* + a 3D-scanned donor (see [source-3d-models](../contributions/source-3d-models));\n  the current baseline is a ~349 mm round body ([oomwoo-one URDF](https://github.com/makerspet/oomwoo-one)).\n- Units: millimeters, kilograms, SI. Right-handed frames. Angles in radians.\n\n## 5. Hardware architecture\n\n### 5.1 Chassis and reference frame\nThe chassis is the *integration backbone*. It publishes the mounting interface\nevery other hardware module targets. Reference geometry (dimensions, wheelbase,\nmotor specs, mass) comes from the *sourced parts* ([BOM](../BOM.md)) + 3D scans of\na donor vacuum (see [source-3d-models](../contributions/source-3d-models)); the\n[oomwoo-one URDF](https://github.com/makerspet/oomwoo-one) carries the current\n~349 mm round-body baseline.\n\n- *TBD:* Overall diameter and height budget.\n- *TBD:* Mounting grid / bolt pattern standard (e.g., M3 on a defined pitch).\n- *TBD:* Mass budget per module and total target mass.\n\n### 5.2 Mechanical interface standard (the contract)\nEvery hardware module's RFC must specify, against this standard:\n- Mounting points (bolt pattern, location relative to `base_link`).\n- Bounding envelope (max size the module may occupy).\n- Mass budget.\n- Mating tolerances and print orientation.\n- *TBD:* Define the standard connector/fastener set (screw sizes, heat-set\n  inserts, etc.) so parts from different authors actually mate.\n\n### 5.3 Electrical interface standard (the contract)\n- *Battery:* off-the-shelf pack with a *built-in BMS* — *4S2P Li-ion*, ~14.4 V\n  nominal, ~5200 mAh / ~75 Wh (OEM BRR-2P4S-5200 class), charged 16.8 V CC/CV with\n  NTC temperature sense. Chemistry is now decided; see the [BOM](../BOM.md).\n- *TBD:* Power rails distributed to modules (VBAT, 5V, 3.3V) and connector types/pinouts.\n- *CPU ↔ MCU:* a *custom high-speed serial protocol* (not micro-ROS) carries\n  commands/telemetry, plus discrete GPIOs (CPU power on/off, and a CPU-reset line\n  the MCU asserts on missed health packets). The *MCU owns motors and sensors*; the\n  CPU never drives them directly.\n- *Sensors:* bumper/cliff/wheel-drop and analog IR are *MCU-side* (digital in / ADC);\n  the *LiDAR (UART, ~5 Hz)*, MIPI camera(s), IMU, and serial audio attach to the *CPU*.\n\n### 5.4 Compute (CPU) and real-time controller (MCU)\n\nOOMWOO splits compute across two processors — mirroring how consumer vacuums are\nbuilt, and, crucially, so that *safety never depends on Linux/ROS2*.\n\n*CPU (compute module).* The I/O board is a *carrier* that accepts a *Raspberry Pi\nCompute Module 4 or 5* and — because the CM4 pinout is a de-facto standard — the\nmany *pin-compatible alternative modules* (Radxa CM3/CM4, Pine64 SOQuartz, LuckFox\nCore3566, …), several with an *NPU* for future on-device vision. The CPU runs\n*ROS2, SLAM (slam_toolbox), Nav2, LiDAR processing, and high-level behavior*. CM\nmodules are low-profile (helps the height budget) and swappable (hackable, cheaper,\nNPU options).\n- *Minimum target: a 4 GB CM4/CM5 (or Pi 4).* Realistic prior art runs\n  slam_toolbox + Nav2 onboard a 4 GB Pi 4. Getting the floor to *2 GB* is a goal\n  (ROS2 composable nodes; selectively rewriting heavy Python nodes in Rust/C++) —\n  *no guarantee*, to be settled by the compute-benchmark. No 8–16 GB module needed.\n- *Cooling:* no dedicated CPU fan — the suction fan's airflow cools the compute\n  board, as in consumer vacuums.\n- The earlier bespoke *RK3562* reference schematic is *dropped* in favour of the\n  CM4/CM5 carrier.\n\n*MCU (real-time / safety controller).* A dedicated *STM32G473VCT6* microcontroller\n(Cortex-M4F, LQFP100, multiple ADCs and timer resources), selected by the current\nI/O-board design, owns *motors, encoders, all sensors, battery-charging control,\nand safety*. Its\nrole is *fixed*: functionality does not migrate onto the CPU, and CPU work does not\nmigrate onto the MCU.\n- Firmware uses a layered *FreeRTOS* design (static allocation, watchdog, bounded\n  reaction times, CE-oriented) speaking a *custom serial protocol — not micro-ROS*\n  (the tried-and-true consumer-vacuum approach; cf. the reverse-engineered\n  [3irobotix protocol](https://github.com/codetiger/VacuumRobot)).\n- *Hard safety lives here, independent of Linux/ROS2:* the MCU stops all motors on\n  a *bumper hit, cliff detection, or wheel-drop*, current-limits a *stuck brush*,\n  and *watchdogs the CPU* — if the CPU's health packets stop, it stops the motors\n  and can *reset the CPU*.\n- Tentative ~60-signal pin budget: see the [io-pcb RFC](../contributions/io-pcb)\n  appendix (why the MCU needs a high-GPIO part).\n\n*CPU ↔ MCU link.* A *high-speed serial* channel carries commands/telemetry both\nways, plus discrete GPIOs — notably the *CPU-reset* line the MCU asserts on missed\nhealth packets, and CPU power on/off. The draft protocol, ROS2 bridge mapping,\nand bringup checklist live in the [io-board-interface RFC](../contributions/io-board-interface).\nAny LiDAR supported by `kaiaai/LDS` / `lds2d` is interface-compatible.\n\n### 5.5 Two build profiles\n\nThe same carrier I/O board + MCU supports two swappable compute configurations:\n\n| | *Consumer / regular* | *Educational / lower-cost* |\n|---|---|---|\n| CPU-slot module | CM4 / CM5 (or pin-compatible alt) | *ESP32-S3* board in the CM4 form factor |\n| Where ROS2 / SLAM runs | *onboard* (ROS2 + slam_toolbox + Nav2) | *offboard* on a local dev PC; ESP32-S3 runs *micro-ROS* |\n| Link | self-contained robot | robot ↔ dev PC over *Wi-Fi* |\n| Trade-off | plug-and-play for non-experts | cheaper, but Wi-Fi congestion / dead-zones — a learning platform, not a polished consumer product |\n\nOnboard SLAM is the default for the consumer version *so non-experts can build and\nuse it* without setting up a separate ROS2 dev machine. The ESP32-S3 can only be\nthe *CPU-slot* option — it lacks the ~60 GPIO the MCU role needs, so it never\nreplaces the STM32.\n\n## 6. Software architecture\n\n### 6.1 ROS2 graph (MVP)\n- Core nodes (MVP): LiDAR driver, base controller (diff-drive), odometry,\n  teleop, SLAM (manual mapping), TF/URDF publisher.\n- *Interface contract:* each software module's RFC declares the ROS2 topics,\n  services, message types, and parameters it publishes/consumes. Modules depend\n  on these interfaces, not on each other's code. See\n  [SOFTWARE_INTERFACES.md](SOFTWARE_INTERFACES.md) for the current draft ROS2\n  graph contract.\n\n### 6.2 Simulation\n- Gazebo + URDF, with a set of residential-layout worlds for navigation and\n  coverage testing. Sim parity is a first-class requirement, not an afterthought.\n\n### 6.3 Application layer (Phase 2 — north star, NOT in MVP)\nA ROS2-agnostic layer that runs third-party apps locally in isolated *Podman*\ncontainers, so app developers need no ROS2 expertise. Documented here only to\nkeep its boundary clean; *explicitly out of scope for the Aug 31 MVP.*\n\n## 7. MVP definition (target: 2026-08-31)\n\n*In scope:* ROS2 on a CM4/CM5-class compute module · LiDAR · manual SLAM/mapping · teleop drive ·\n3D-printed chassis · Gazebo sim with URDF · evaluation + demo video. No dock,\nno autonomous exploration, no Home Assistant, no app layer.\n\n*Explicit non-goals for MVP:* autonomous coverage, docking, auto-empty, mopping,\nHome Assistant, the app platform, accessories. These are later phases.\n\n*Critical-path ownership:* the maintainer (+ small core) own the chassis,\ninterface specs, and integration so the MVP does not depend on volunteer delivery\ntiming. Community modules accelerate and improve the MVP; they do not block it.\n\n## 8. Safety review gate\n\nBattery, charging, motor-driver, and mains-adjacent modules require maintainer\nsafety review before merge. RFCs for these modules must include a hazard note\n(over-current, thermal, short, mechanical pinch).\n\nThe battery risk is *reduced* by using an *off-the-shelf 4S2P Li-ion pack with a\nbuilt-in BMS* (over-charge / over-discharge / short protection); the review then\nfocuses on the *16.8 V CC/CV charging path + NTC temperature sense*. *Hard safety\nlives on the MCU, never on Linux/ROS2* — it independently stops motors on\nbumper/cliff/wheel-drop, current-limits a stuck brush, and watchdog-resets the CPU.\n\n## 9. Roadmap (phases after MVP)\n\n1. Rechargeable battery + basic dock + autonomous floor mapping.\n2. Home Assistant integration.\n3. Application layer (Podman app runtime) + first delightful apps.\n4. Accessories and novel apps; integrations (e.g., LeRobot arm).\n\n## 10. Open questions\n\n- *Resolved:* the MCU runs a *custom serial protocol (not micro-ROS)*; the CPU runs\n  *onboard ROS2/SLAM/Nav2*. micro-ROS is used only in the *educational* ESP32-S3\n  profile (SLAM offboard on a dev PC). See §5.4–5.5.\n- *Resolved:* battery is an off-the-shelf *4S2P Li-ion pack with a built-in BMS*,\n  charged 16.8 V CC/CV. See §5.3, §8.\n- Can OOMWOO's onboard ROS2 stack fit in *2 GB* (composable nodes, selective Rust)\n  rather than 4 GB? To be answered by the compute-benchmark.\n- *Resolved:* the reference I/O board uses *STM32G473VCT6*, superseding the earlier\n  STM32G070 candidate. Pin-compatible alternatives remain a separate board-design\n  decision.\n- One hardware-agnostic HAL covering reference vacuum + DIY builds (community idea)?\n- Module selection process: who decides which competing implementation wins, and\n  on what criteria? (See each module's acceptance criteria.)\n"},"items":[{"name":"ARCHITECTURE.md","path":"docs/ARCHITECTURE.md","rawUrl":"https://raw.githubusercontent.com/makerspet/oomwoo/HEAD/docs/ARCHITECTURE.md","title":"docs - System Architecture & Module Boundaries","category":"project-spec","format":"markdown","content":"# OOMWOO Architecture Brief\n\n> *Status: DRAFT / skeleton.* This document defines the system so that modules\n> can be built in parallel without colliding. Sections marked *TBD* are the\n> gating decisions; until they are filled in, hardware modules that must fit\n> together cannot be finalized. Treat the interface specs as the contract every\n> module agrees to.\n\n## 1. Purpose/Goal and scope\n\nOOMWOO is an open-source, 3D-printed, ROS2-based home robot vacuum with 2D LiDAR\nand Home Assistant support. It is designed to be *built from scratch by\nthe community*, module by module, clean well and to double as an affordable ROS2\ndevelopment and learning platform.\n\n*North star (not MVP):* OOMWOO is also the reference hardware for a broader\nrobot application platform. Architectural boundaries (especially the app layer in\n§6) are drawn with that future in mind, but the MVP below deliberately excludes it.\n\n## 2. Design principles\n\n- *Open and swappable.* Every module has a defined interface. Any compliant\n  implementation can replace another. No module depends on the internals of\n  another, only on its published interface.\n- *Simulation-first.* Software must run in Gazebo before it runs on hardware,\n  so contributors with no robot can still build and test.\n- *Affordable and printable.* Target off-the-shelf parts (a CM4/CM5-class compute\n  module, common vacuum LiDARs, sourced Roborock/Dreame/Xiaomi motors and wear\n  parts) and FDM-printable chassis parts.\n- *Safety is reviewed, not crowd-trusted.* Battery, charging, and motor-driver\n  modules pass a maintainer safety review before merge (see §8).\n- *Reference-design backed.* A known-working vacuum (see the references in the\n  [README](../README.md)) anchors the geometry and proves feasibility.\n\n## 3. System overview\n\n```\n   LiDAR (UART, ~5 Hz) · MIPI camera(s) · IMU · serial audio\n                    |\n      +-------------v-------------------------------+\n      |  CPU - CM4 / CM5 (or pin-compatible module) |\n      |  ROS2 · SLAM (slam_toolbox) · Nav2 · behavior |\n      |  educational variant: ESP32-S3 + micro-ROS  |\n      |  (SLAM offboard on a dev PC over Wi-Fi)      |\n      +-------------^----------------+---------------+\n       serial (cmds/telemetry) +     |  custom serial protocol\n       CPU-reset / health GPIO       |  (NOT micro-ROS)\n      +-------------+----------------v---------------+\n      |  MCU - STM32G473 (FreeRTOS, static alloc)    |\n      |  motors · encoders · sensors · charging ctrl |\n      |  SAFETY (no Linux/ROS2): bumper/cliff/wheel- |\n      |  drop stop · current limit · CPU watchdog    |\n      +-------------+--------------------+-----------+\n                    |                    |\n         +----------+----+      +--------+---------+\n         | L/R drive     |      | suction fan,     |\n         | wheels, brush |      | bumper, cliff,   |\n         |               |      | IR, wheel-drop   |\n         +---------------+      +------------------+\n\n   Power: off-the-shelf 4S2P Li-ion pack (built-in BMS).\n   The CPU module + MCU sit on one carrier I/O board.\n```\n\n> The CPU/MCU split keeps *all hard safety on the MCU*, independent of Linux/ROS2.\n> Interfaces are largely decided (see §5); refine as the io-pcb spec settles.\n\n## 4. Coordinate frames and conventions\n\n- *TBD:* Define `base_link` origin and orientation (REP-103: x-forward,\n  y-left, z-up). All mechanical mounting points and URDF frames reference this.\n- *TBD:* Define the reference plane (floor contact), robot diameter, and height\n  envelope. *These two numbers gate every hardware module.* Source these from the *sourced\n  parts* + a 3D-scanned donor (see [source-3d-models](../contributions/source-3d-models));\n  the current baseline is a ~349 mm round body ([oomwoo-one URDF](https://github.com/makerspet/oomwoo-one)).\n- Units: millimeters, kilograms, SI. Right-handed frames. Angles in radians.\n\n## 5. Hardware architecture\n\n### 5.1 Chassis and reference frame\nThe chassis is the *integration backbone*. It publishes the mounting interface\nevery other hardware module targets. Reference geometry (dimensions, wheelbase,\nmotor specs, mass) comes from the *sourced parts* ([BOM](../BOM.md)) + 3D scans of\na donor vacuum (see [source-3d-models](../contributions/source-3d-models)); the\n[oomwoo-one URDF](https://github.com/makerspet/oomwoo-one) carries the current\n~349 mm round-body baseline.\n\n- *TBD:* Overall diameter and height budget.\n- *TBD:* Mounting grid / bolt pattern standard (e.g., M3 on a defined pitch).\n- *TBD:* Mass budget per module and total target mass.\n\n### 5.2 Mechanical interface standard (the contract)\nEvery hardware module's RFC must specify, against this standard:\n- Mounting points (bolt pattern, location relative to `base_link`).\n- Bounding envelope (max size the module may occupy).\n- Mass budget.\n- Mating tolerances and print orientation.\n- *TBD:* Define the standard connector/fastener set (screw sizes, heat-set\n  inserts, etc.) so parts from different authors actually mate.\n\n### 5.3 Electrical interface standard (the contract)\n- *Battery:* off-the-shelf pack with a *built-in BMS* — *4S2P Li-ion*, ~14.4 V\n  nominal, ~5200 mAh / ~75 Wh (OEM BRR-2P4S-5200 class), charged 16.8 V CC/CV with\n  NTC temperature sense. Chemistry is now decided; see the [BOM](../BOM.md).\n- *TBD:* Power rails distributed to modules (VBAT, 5V, 3.3V) and connector types/pinouts.\n- *CPU ↔ MCU:* a *custom high-speed serial protocol* (not micro-ROS) carries\n  commands/telemetry, plus discrete GPIOs (CPU power on/off, and a CPU-reset line\n  the MCU asserts on missed health packets). The *MCU owns motors and sensors*; the\n  CPU never drives them directly.\n- *Sensors:* bumper/cliff/wheel-drop and analog IR are *MCU-side* (digital in / ADC);\n  the *LiDAR (UART, ~5 Hz)*, MIPI camera(s), IMU, and serial audio attach to the *CPU*.\n\n### 5.4 Compute (CPU) and real-time controller (MCU)\n\nOOMWOO splits compute across two processors — mirroring how consumer vacuums are\nbuilt, and, crucially, so that *safety never depends on Linux/ROS2*.\n\n*CPU (compute module).* The I/O board is a *carrier* that accepts a *Raspberry Pi\nCompute Module 4 or 5* and — because the CM4 pinout is a de-facto standard — the\nmany *pin-compatible alternative modules* (Radxa CM3/CM4, Pine64 SOQuartz, LuckFox\nCore3566, …), several with an *NPU* for future on-device vision. The CPU runs\n*ROS2, SLAM (slam_toolbox), Nav2, LiDAR processing, and high-level behavior*. CM\nmodules are low-profile (helps the height budget) and swappable (hackable, cheaper,\nNPU options).\n- *Minimum target: a 4 GB CM4/CM5 (or Pi 4).* Realistic prior art runs\n  slam_toolbox + Nav2 onboard a 4 GB Pi 4. Getting the floor to *2 GB* is a goal\n  (ROS2 composable nodes; selectively rewriting heavy Python nodes in Rust/C++) —\n  *no guarantee*, to be settled by the compute-benchmark. No 8–16 GB module needed.\n- *Cooling:* no dedicated CPU fan — the suction fan's airflow cools the compute\n  board, as in consumer vacuums.\n- The earlier bespoke *RK3562* reference schematic is *dropped* in favour of the\n  CM4/CM5 carrier.\n\n*MCU (real-time / safety controller).* A dedicated *STM32G473VCT6* microcontroller\n(Cortex-M4F, LQFP100, multiple ADCs and timer resources), selected by the current\nI/O-board design, owns *motors, encoders, all sensors, battery-charging control,\nand safety*. Its\nrole is *fixed*: functionality does not migrate onto the CPU, and CPU work does not\nmigrate onto the MCU.\n- Firmware uses a layered *FreeRTOS* design (static allocation, watchdog, bounded\n  reaction times, CE-oriented) speaking a *custom serial protocol — not micro-ROS*\n  (the tried-and-true consumer-vacuum approach; cf. the reverse-engineered\n  [3irobotix protocol](https://github.com/codetiger/VacuumRobot)).\n- *Hard safety lives here, independent of Linux/ROS2:* the MCU stops all motors on\n  a *bumper hit, cliff detection, or wheel-drop*, current-limits a *stuck brush*,\n  and *watchdogs the CPU* — if the CPU's health packets stop, it stops the motors\n  and can *reset the CPU*.\n- Tentative ~60-signal pin budget: see the [io-pcb RFC](../contributions/io-pcb)\n  appendix (why the MCU needs a high-GPIO part).\n\n*CPU ↔ MCU link.* A *high-speed serial* channel carries commands/telemetry both\nways, plus discrete GPIOs — notably the *CPU-reset* line the MCU asserts on missed\nhealth packets, and CPU power on/off. The draft protocol, ROS2 bridge mapping,\nand bringup checklist live in the [io-board-interface RFC](../contributions/io-board-interface).\nAny LiDAR supported by `kaiaai/LDS` / `lds2d` is interface-compatible.\n\n### 5.5 Two build profiles\n\nThe same carrier I/O board + MCU supports two swappable compute configurations:\n\n| | *Consumer / regular* | *Educational / lower-cost* |\n|---|---|---|\n| CPU-slot module | CM4 / CM5 (or pin-compatible alt) | *ESP32-S3* board in the CM4 form factor |\n| Where ROS2 / SLAM runs | *onboard* (ROS2 + slam_toolbox + Nav2) | *offboard* on a local dev PC; ESP32-S3 runs *micro-ROS* |\n| Link | self-contained robot | robot ↔ dev PC over *Wi-Fi* |\n| Trade-off | plug-and-play for non-experts | cheaper, but Wi-Fi congestion / dead-zones — a learning platform, not a polished consumer product |\n\nOnboard SLAM is the default for the consumer version *so non-experts can build and\nuse it* without setting up a separate ROS2 dev machine. The ESP32-S3 can only be\nthe *CPU-slot* option — it lacks the ~60 GPIO the MCU role needs, so it never\nreplaces the STM32.\n\n## 6. Software architecture\n\n### 6.1 ROS2 graph (MVP)\n- Core nodes (MVP): LiDAR driver, base controller (diff-drive), odometry,\n  teleop, SLAM (manual mapping), TF/URDF publisher.\n- *Interface contract:* each software module's RFC declares the ROS2 topics,\n  services, message types, and parameters it publishes/consumes. Modules depend\n  on these interfaces, not on each other's code. See\n  [SOFTWARE_INTERFACES.md](SOFTWARE_INTERFACES.md) for the current draft ROS2\n  graph contract.\n\n### 6.2 Simulation\n- Gazebo + URDF, with a set of residential-layout worlds for navigation and\n  coverage testing. Sim parity is a first-class requirement, not an afterthought.\n\n### 6.3 Application layer (Phase 2 — north star, NOT in MVP)\nA ROS2-agnostic layer that runs third-party apps locally in isolated *Podman*\ncontainers, so app developers need no ROS2 expertise. Documented here only to\nkeep its boundary clean; *explicitly out of scope for the Aug 31 MVP.*\n\n## 7. MVP definition (target: 2026-08-31)\n\n*In scope:* ROS2 on a CM4/CM5-class compute module · LiDAR · manual SLAM/mapping · teleop drive ·\n3D-printed chassis · Gazebo sim with URDF · evaluation + demo video. No dock,\nno autonomous exploration, no Home Assistant, no app layer.\n\n*Explicit non-goals for MVP:* autonomous coverage, docking, auto-empty, mopping,\nHome Assistant, the app platform, accessories. These are later phases.\n\n*Critical-path ownership:* the maintainer (+ small core) own the chassis,\ninterface specs, and integration so the MVP does not depend on volunteer delivery\ntiming. Community modules accelerate and improve the MVP; they do not block it.\n\n## 8. Safety review gate\n\nBattery, charging, motor-driver, and mains-adjacent modules require maintainer\nsafety review before merge. RFCs for these modules must include a hazard note\n(over-current, thermal, short, mechanical pinch).\n\nThe battery risk is *reduced* by using an *off-the-shelf 4S2P Li-ion pack with a\nbuilt-in BMS* (over-charge / over-discharge / short protection); the review then\nfocuses on the *16.8 V CC/CV charging path + NTC temperature sense*. *Hard safety\nlives on the MCU, never on Linux/ROS2* — it independently stops motors on\nbumper/cliff/wheel-drop, current-limits a stuck brush, and watchdog-resets the CPU.\n\n## 9. Roadmap (phases after MVP)\n\n1. Rechargeable battery + basic dock + autonomous floor mapping.\n2. Home Assistant integration.\n3. Application layer (Podman app runtime) + first delightful apps.\n4. Accessories and novel apps; integrations (e.g., LeRobot arm).\n\n## 10. Open questions\n\n- *Resolved:* the MCU runs a *custom serial protocol (not micro-ROS)*; the CPU runs\n  *onboard ROS2/SLAM/Nav2*. micro-ROS is used only in the *educational* ESP32-S3\n  profile (SLAM offboard on a dev PC). See §5.4–5.5.\n- *Resolved:* battery is an off-the-shelf *4S2P Li-ion pack with a built-in BMS*,\n  charged 16.8 V CC/CV. See §5.3, §8.\n- Can OOMWOO's onboard ROS2 stack fit in *2 GB* (composable nodes, selective Rust)\n  rather than 4 GB? To be answered by the compute-benchmark.\n- *Resolved:* the reference I/O board uses *STM32G473VCT6*, superseding the earlier\n  STM32G070 candidate. Pin-compatible alternatives remain a separate board-design\n  decision.\n- One hardware-agnostic HAL covering reference vacuum + DIY builds (community idea)?\n- Module selection process: who decides which competing implementation wins, and\n  on what criteria? (See each module's acceptance criteria.)\n","isInternal":false,"tokens":3382,"sizeBytes":12925}],"systemPromptSnippet":"<yakaai_skills repo=\"makerspet/oomwoo\">\n<!-- File: docs/ARCHITECTURE.md (Tokens: ~3382 | Category: project-spec) -->\n# OOMWOO Architecture Brief\n\n> *Status: DRAFT / skeleton.* This document defines the system so that modules\n> can be built in parallel without colliding. Sections marked *TBD* are the\n> gating decisions; until they are filled in, hardware modules that must fit\n> together cannot be finalized. Treat the interface specs as the contract every\n> module agrees to.\n\n## 1. Purpose/Goal and scope\n\nOOMWOO is an open-source, 3D-printed, ROS2-based home robot vacuum with 2D LiDAR\nand Home Assistant support. It is designed to be *built from scratch by\nthe community*, module by module, clean well and to double as an affordable ROS2\ndevelopment and learning platform.\n\n*North star (not MVP):* OOMWOO is also the reference hardware for a broader\nrobot application platform. Architectural boundaries (especially the app layer in\n§6) are drawn with that future in mind, but the MVP below deliberately excludes it.\n\n## 2. Design principles\n\n- *Open and swappable.* Every module has a defined interface. Any compliant\n  implementation can replace another. No module depends on the internals of\n  another, only on its published interface.\n- *Simulation-first.* Software must run in Gazebo before it runs on hardware,\n  so contributors with no robot can still build and test.\n- *Affordable and printable.* Target off-the-shelf parts (a CM4/CM5-class compute\n  module, common vacuum LiDARs, sourced Roborock/Dreame/Xiaomi motors and wear\n  parts) and FDM-printable chassis parts.\n- *Safety is reviewed, not crowd-trusted.* Battery, charging, and motor-driver\n  modules pass a maintainer safety review before merge (see §8).\n- *Reference-design backed.* A known-working vacuum (see the references in the\n  [README](../README.md)) anchors the geometry and proves feasibility.\n\n## 3. System overview\n\n```\n   LiDAR (UART, ~5 Hz) · MIPI camera(s) · IMU · serial audio\n                    |\n      +-------------v-------------------------------+\n      |  CPU - CM4 / CM5 (or pin-compatible module) |\n      |  ROS2 · SLAM (slam_toolbox) · Nav2 · behavior |\n      |  educational variant: ESP32-S3 + micro-ROS  |\n      |  (SLAM offboard on a dev PC over Wi-Fi)      |\n      +-------------^----------------+---------------+\n       serial (cmds/telemetry) +     |  custom serial protocol\n       CPU-reset / health GPIO       |  (NOT micro-ROS)\n      +-------------+----------------v---------------+\n      |  MCU - STM32G473 (FreeRTOS, static alloc)    |\n      |  motors · encoders · sensors · charging ctrl |\n      |  SAFETY (no Linux/ROS2): bumper/cliff/wheel- |\n      |  drop stop · current limit · CPU watchdog    |\n      +-------------+--------------------+-----------+\n                    |                    |\n         +----------+----+      +--------+---------+\n         | L/R drive     |      | suction fan,     |\n         | wheels, brush |      | bumper, cliff,   |\n         |               |      | IR, wheel-drop   |\n         +---------------+      +------------------+\n\n   Power: off-the-shelf 4S2P Li-ion pack (built-in BMS).\n   The CPU module + MCU sit on one carrier I/O board.\n```\n\n> The CPU/MCU split keeps *all hard safety on the MCU*, independent of Linux/ROS2.\n> Interfaces are largely decided (see §5); refine as the io-pcb spec settles.\n\n## 4. Coordinate frames and conventions\n\n- *TBD:* Define `base_link` origin and orientation (REP-103: x-forward,\n  y-left, z-up). All mechanical mounting points and URDF frames reference this.\n- *TBD:* Define the reference plane (floor contact), robot diameter, and height\n  envelope. *These two numbers gate every hardware module.* Source these from the *sourced\n  parts* + a 3D-scanned donor (see [source-3d-models](../contributions/source-3d-models));\n  the current baseline is a ~349 mm round body ([oomwoo-one URDF](https://github.com/makerspet/oomwoo-one)).\n- Units: millimeters, kilograms, SI. Right-handed frames. Angles in radians.\n\n## 5. Hardware architecture\n\n### 5.1 Chassis and reference frame\nThe chassis is the *integration backbone*. It publishes the mounting interface\nevery other hardware module targets. Reference geometry (dimensions, wheelbase,\nmotor specs, mass) comes from the *sourced parts* ([BOM](../BOM.md)) + 3D scans of\na donor vacuum (see [source-3d-models](../contributions/source-3d-models)); the\n[oomwoo-one URDF](https://github.com/makerspet/oomwoo-one) carries the current\n~349 mm round-body baseline.\n\n- *TBD:* Overall diameter and height budget.\n- *TBD:* Mounting grid / bolt pattern standard (e.g., M3 on a defined pitch).\n- *TBD:* Mass budget per module and total target mass.\n\n### 5.2 Mechanical interface standard (the contract)\nEvery hardware module's RFC must specify, against this standard:\n- Mounting points (bolt pattern, location relative to `base_link`).\n- Bounding envelope (max size the module may occupy).\n- Mass budget.\n- Mating tolerances and print orientation.\n- *TBD:* Define the standard connector/fastener set (screw sizes, heat-set\n  inserts, etc.) so parts from different authors actually mate.\n\n### 5.3 Electrical interface standard (the contract)\n- *Battery:* off-the-shelf pack with a *built-in BMS* — *4S2P Li-ion*, ~14.4 V\n  nominal, ~5200 mAh / ~75 Wh (OEM BRR-2P4S-5200 class), charged 16.8 V CC/CV with\n  NTC temperature sense. Chemistry is now decided; see the [BOM](../BOM.md).\n- *TBD:* Power rails distributed to modules (VBAT, 5V, 3.3V) and connector types/pinouts.\n- *CPU ↔ MCU:* a *custom high-speed serial protocol* (not micro-ROS) carries\n  commands/telemetry, plus discrete GPIOs (CPU power on/off, and a CPU-reset line\n  the MCU asserts on missed health packets). The *MCU owns motors and sensors*; the\n  CPU never drives them directly.\n- *Sensors:* bumper/cliff/wheel-drop and analog IR are *MCU-side* (digital in / ADC);\n  the *LiDAR (UART, ~5 Hz)*, MIPI camera(s), IMU, and serial audio attach to the *CPU*.\n\n### 5.4 Compute (CPU) and real-time controller (MCU)\n\nOOMWOO splits compute across two processors — mirroring how consumer vacuums are\nbuilt, and, crucially, so that *safety never depends on Linux/ROS2*.\n\n*CPU (compute module).* The I/O board is a *carrier* that accepts a *Raspberry Pi\nCompute Module 4 or 5* and — because the CM4 pinout is a de-facto standard — the\nmany *pin-compatible alternative modules* (Radxa CM3/CM4, Pine64 SOQuartz, LuckFox\nCore3566, …), several with an *NPU* for future on-device vision. The CPU runs\n*ROS2, SLAM (slam_toolbox), Nav2, LiDAR processing, and high-level behavior*. CM\nmodules are low-profile (helps the height budget) and swappable (hackable, cheaper,\nNPU options).\n- *Minimum target: a 4 GB CM4/CM5 (or Pi 4).* Realistic prior art runs\n  slam_toolbox + Nav2 onboard a 4 GB Pi 4. Getting the floor to *2 GB* is a goal\n  (ROS2 composable nodes; selectively rewriting heavy Python nodes in Rust/C++) —\n  *no guarantee*, to be settled by the compute-benchmark. No 8–16 GB module needed.\n- *Cooling:* no dedicated CPU fan — the suction fan's airflow cools the compute\n  board, as in consumer vacuums.\n- The earlier bespoke *RK3562* reference schematic is *dropped* in favour of the\n  CM4/CM5 carrier.\n\n*MCU (real-time / safety controller).* A dedicated *STM32G473VCT6* microcontroller\n(Cortex-M4F, LQFP100, multiple ADCs and timer resources), selected by the current\nI/O-board design, owns *motors, encoders, all sensors, battery-charging control,\nand safety*. Its\nrole is *fixed*: functionality does not migrate onto the CPU, and CPU work does not\nmigrate onto the MCU.\n- Firmware uses a layered *FreeRTOS* design (static allocation, watchdog, bounded\n  reaction times, CE-oriented) speaking a *custom serial protocol — not micro-ROS*\n  (the tried-and-true consumer-vacuum approach; cf. the reverse-engineered\n  [3irobotix protocol](https://github.com/codetiger/VacuumRobot)).\n- *Hard safety lives here, independent of Linux/ROS2:* the MCU stops all motors on\n  a *bumper hit, cliff detection, or wheel-drop*, current-limits a *stuck brush*,\n  and *watchdogs the CPU* — if the CPU's health packets stop, it stops the motors\n  and can *reset the CPU*.\n- Tentative ~60-signal pin budget: see the [io-pcb RFC](../contributions/io-pcb)\n  appendix (why the MCU needs a high-GPIO part).\n\n*CPU ↔ MCU link.* A *high-speed serial* channel carries commands/telemetry both\nways, plus discrete GPIOs — notably the *CPU-reset* line the MCU asserts on missed\nhealth packets, and CPU power on/off. The draft protocol, ROS2 bridge mapping,\nand bringup checklist live in the [io-board-interface RFC](../contributions/io-board-interface).\nAny LiDAR supported by `kaiaai/LDS` / `lds2d` is interface-compatible.\n\n### 5.5 Two build profiles\n\nThe same carrier I/O board + MCU supports two swappable compute configurations:\n\n| | *Consumer / regular* | *Educational / lower-cost* |\n|---|---|---|\n| CPU-slot module | CM4 / CM5 (or pin-compatible alt) | *ESP32-S3* board in the CM4 form factor |\n| Where ROS2 / SLAM runs | *onboard* (ROS2 + slam_toolbox + Nav2) | *offboard* on a local dev PC; ESP32-S3 runs *micro-ROS* |\n| Link | self-contained robot | robot ↔ dev PC over *Wi-Fi* |\n| Trade-off | plug-and-play for non-experts | cheaper, but Wi-Fi congestion / dead-zones — a learning platform, not a polished consumer product |\n\nOnboard SLAM is the default for the consumer version *so non-experts can build and\nuse it* without setting up a separate ROS2 dev machine. The ESP32-S3 can only be\nthe *CPU-slot* option — it lacks the ~60 GPIO the MCU role needs, so it never\nreplaces the STM32.\n\n## 6. Software architecture\n\n### 6.1 ROS2 graph (MVP)\n- Core nodes (MVP): LiDAR driver, base controller (diff-drive), odometry,\n  teleop, SLAM (manual mapping), TF/URDF publisher.\n- *Interface contract:* each software module's RFC declares the ROS2 topics,\n  services, message types, and parameters it publishes/consumes. Modules depend\n  on these interfaces, not on each other's code. See\n  [SOFTWARE_INTERFACES.md](SOFTWARE_INTERFACES.md) for the current draft ROS2\n  graph contract.\n\n### 6.2 Simulation\n- Gazebo + URDF, with a set of residential-layout worlds for navigation and\n  coverage testing. Sim parity is a first-class requirement, not an afterthought.\n\n### 6.3 Application layer (Phase 2 — north star, NOT in MVP)\nA ROS2-agnostic layer that runs third-party apps locally in isolated *Podman*\ncontainers, so app developers need no ROS2 expertise. Documented here only to\nkeep its boundary clean; *explicitly out of scope for the Aug 31 MVP.*\n\n## 7. MVP definition (target: 2026-08-31)\n\n*In scope:* ROS2 on a CM4/CM5-class compute module · LiDAR · manual SLAM/mapping · teleop drive ·\n3D-printed chassis · Gazebo sim with URDF · evaluation + demo video. No dock,\nno autonomous exploration, no Home Assistant, no app layer.\n\n*Explicit non-goals for MVP:* autonomous coverage, docking, auto-empty, mopping,\nHome Assistant, the app platform, accessories. These are later phases.\n\n*Critical-path ownership:* the maintainer (+ small core) own the chassis,\ninterface specs, and integration so the MVP does not depend on volunteer delivery\ntiming. Community modules accelerate and improve the MVP; they do not block it.\n\n## 8. Safety review gate\n\nBattery, charging, motor-driver, and mains-adjacent modules require maintainer\nsafety review before merge. RFCs for these modules must include a hazard note\n(over-current, thermal, short, mechanical pinch).\n\nThe battery risk is *reduced* by using an *off-the-shelf 4S2P Li-ion pack with a\nbuilt-in BMS* (over-charge / over-discharge / short protection); the review then\nfocuses on the *16.8 V CC/CV charging path + NTC temperature sense*. *Hard safety\nlives on the MCU, never on Linux/ROS2* — it independently stops motors on\nbumper/cliff/wheel-drop, current-limits a stuck brush, and watchdog-resets the CPU.\n\n## 9. Roadmap (phases after MVP)\n\n1. Rechargeable battery + basic dock + autonomous floor mapping.\n2. Home Assistant integration.\n3. Application layer (Podman app runtime) + first delightful apps.\n4. Accessories and novel apps; integrations (e.g., LeRobot arm).\n\n## 10. Open questions\n\n- *Resolved:* the MCU runs a *custom serial protocol (not micro-ROS)*; the CPU runs\n  *onboard ROS2/SLAM/Nav2*. micro-ROS is used only in the *educational* ESP32-S3\n  profile (SLAM offboard on a dev PC). See §5.4–5.5.\n- *Resolved:* battery is an off-the-shelf *4S2P Li-ion pack with a built-in BMS*,\n  charged 16.8 V CC/CV. See §5.3, §8.\n- Can OOMWOO's onboard ROS2 stack fit in *2 GB* (composable nodes, selective Rust)\n  rather than 4 GB? To be answered by the compute-benchmark.\n- *Resolved:* the reference I/O board uses *STM32G473VCT6*, superseding the earlier\n  STM32G070 candidate. Pin-compatible alternatives remain a separate board-design\n  decision.\n- One hardware-agnostic HAL covering reference vacuum + DIY builds (community idea)?\n- Module selection process: who decides which competing implementation wins, and\n  on what criteria? (See each module's acceptance criteria.)\n</yakaai_skills>"}