wehub-resource-sync
237 lines
12 KiB
Markdown
237 lines
12 KiB
Markdown
# 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.)
|