chore: import upstream snapshot with attribution

2026-07-13 12:31:04 +08:00
commit 43552b5423
52 changed files with 4226 additions and 0 deletions
@@ -0,0 +1,236 @@
+# 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](../README.md)) 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](../contributions/source-3d-models));
+  the current baseline is a ~349 mm round body ([oomwoo-one URDF](https://github.com/makerspet/oomwoo-one)).
+- 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](../BOM.md)) + 3D scans of
+a donor vacuum (see [source-3d-models](../contributions/source-3d-models)); the
+[oomwoo-one URDF](https://github.com/makerspet/oomwoo-one) 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](../BOM.md).
+- *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](https://github.com/codetiger/VacuumRobot)).
+- *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](../contributions/io-pcb)
+  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](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.)