# makerspet/oomwoo architecture

> Architecture diagram of the GitHub repository makerspet/oomwoo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/makerspet/oomwoo
- Repository: https://github.com/makerspet/oomwoo

## Overview

OOMWOO is an open-source, community-built robot-vacuum project, not a single integrated runtime in this repository. The README describes the intended user journey and major capabilities; the tree contains contribution proposals and selected reference implementations. The arrows below reflect documented project workflow and capability relationships, not verified runtime wiring. Most subsystem source was not sampled, so the graph uses supported contribution directories and leaves uncertain integration links out.

Main entry points: [`contributions/nav-localize`](https://github.com/makerspet/oomwoo/tree/main/contributions/nav-localize) (Navigation), [`contributions/control-app`](https://github.com/makerspet/oomwoo/tree/main/contributions/control-app) (Control App), [`contributions/README.md`](https://github.com/makerspet/oomwoo/blob/main/contributions/README.md) (RFC Board), [`contributions/urdf-gazebo-sim`](https://github.com/makerspet/oomwoo/tree/main/contributions/urdf-gazebo-sim) (Gazebo Simulation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_project["Project Workflow"]
  node_rfc["RFC Board<br/>[README.md]"]
  node_system_design["System Design<br/>[ARCHITECTURE.md]"]
end

subgraph group_robot["Robot Software"]
  node_robot_description["Robot Description"]
  node_simulation["Gazebo Simulation"]
  node_localization["Mapping &amp; Localization"]
  node_navigation["Navigation"]
  node_obstacle_avoidance["Obstacle Avoidance"]
  node_cleaning["Cleaning Jobs"]
  node_control_app["Control App"]
end

subgraph group_hardware["Hardware Modules"]
  node_io_interface["CPU–MCU Interface"]
  node_firmware["I/O Firmware"]
  node_electronics["I/O Board"]
end

subgraph group_safety["Docking &amp; Safety"]
  node_dock_cycle["Dock Homing"]
  node_recovery["Recovery Safety<br/>[recovery_node.py]"]
end

node_contributor(("Builder / Contributor"))
node_home_assistant["Home Assistant"]
node_cloud["Cloud Services"]

node_contributor -->|"selects module"| node_rfc
node_rfc -->|"guides design"| node_system_design
node_contributor -->|"develops against"| node_simulation
node_robot_description -->|"describes robot"| node_simulation
node_localization -->|"provides map pose"| node_navigation
node_navigation -->|"avoids obstacles"| node_obstacle_avoidance
node_navigation -->|"supports cleaning"| node_cleaning
node_control_app -->|"customizes operation"| node_cleaning
node_electronics -->|"hosts firmware"| node_firmware
node_io_interface -->|"defines wire protocol"| node_firmware
node_home_assistant -.->|"local control"| node_control_app
node_cloud -.->|"optional features"| node_control_app

click node_rfc "https://github.com/makerspet/oomwoo/blob/main/contributions/README.md"
click node_system_design "https://github.com/makerspet/oomwoo/blob/main/docs/ARCHITECTURE.md"
click node_robot_description "https://github.com/makerspet/oomwoo/tree/main/contributions/urdf-gazebo-sim"
click node_simulation "https://github.com/makerspet/oomwoo/tree/main/contributions/urdf-gazebo-sim"
click node_localization "https://github.com/makerspet/oomwoo/tree/main/contributions/nav-localize"
click node_navigation "https://github.com/makerspet/oomwoo/tree/main/contributions/nav-localize"
click node_obstacle_avoidance "https://github.com/makerspet/oomwoo/tree/main/contributions/obstacle-avoidance"
click node_cleaning "https://github.com/makerspet/oomwoo/tree/main/contributions/cleaning-jobs"
click node_control_app "https://github.com/makerspet/oomwoo/tree/main/contributions/control-app"
click node_io_interface "https://github.com/makerspet/oomwoo/blob/main/contributions/io-board-interface/xbattlax/tools/oomwoo_mcu_frame.py"
click node_firmware "https://github.com/makerspet/oomwoo/tree/main/contributions/mcu-io-firmware"
click node_electronics "https://github.com/makerspet/oomwoo/tree/main/contributions/io-pcb"
click node_dock_cycle "https://github.com/makerspet/oomwoo/blob/main/contributions/dock-cycle/xbattlax/tools/oomwoo_dock_ir_model.py"
click node_recovery "https://github.com/makerspet/oomwoo/blob/main/contributions/recovery-safety/xbattlax/oomwoo_recovery_safety/oomwoo_recovery_safety/recovery_node.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_rfc,node_system_design toneBlue
class node_robot_description,node_simulation,node_localization,node_navigation,node_obstacle_avoidance,node_cleaning,node_control_app toneAmber
class node_io_interface,node_firmware,node_electronics toneMint
class node_dock_cycle,node_recovery toneRose
class node_contributor,node_home_assistant,node_cloud toneIndigo
```

## Components

### Project Workflow

- [RFC Board](https://github.com/makerspet/oomwoo/blob/main/contributions/README.md): `contributions/README.md`
- [System Design](https://github.com/makerspet/oomwoo/blob/main/docs/ARCHITECTURE.md): `docs/ARCHITECTURE.md`

### Robot Software

- [Robot Description](https://github.com/makerspet/oomwoo/tree/main/contributions/urdf-gazebo-sim): `contributions/urdf-gazebo-sim`
- [Gazebo Simulation](https://github.com/makerspet/oomwoo/tree/main/contributions/urdf-gazebo-sim): `contributions/urdf-gazebo-sim`
- [Mapping & Localization](https://github.com/makerspet/oomwoo/tree/main/contributions/nav-localize): `contributions/nav-localize`
- [Navigation](https://github.com/makerspet/oomwoo/tree/main/contributions/nav-localize): `contributions/nav-localize`
- [Obstacle Avoidance](https://github.com/makerspet/oomwoo/tree/main/contributions/obstacle-avoidance): `contributions/obstacle-avoidance`
- [Cleaning Jobs](https://github.com/makerspet/oomwoo/tree/main/contributions/cleaning-jobs): `contributions/cleaning-jobs`
- [Control App](https://github.com/makerspet/oomwoo/tree/main/contributions/control-app): `contributions/control-app`

### Hardware Modules

- [CPU–MCU Interface](https://github.com/makerspet/oomwoo/blob/main/contributions/io-board-interface/xbattlax/tools/oomwoo_mcu_frame.py): `contributions/io-board-interface/xbattlax/tools/oomwoo_mcu_frame.py`
- [I/O Firmware](https://github.com/makerspet/oomwoo/tree/main/contributions/mcu-io-firmware): `contributions/mcu-io-firmware`
- [I/O Board](https://github.com/makerspet/oomwoo/tree/main/contributions/io-pcb): `contributions/io-pcb`

### Docking & Safety

- [Dock Homing](https://github.com/makerspet/oomwoo/blob/main/contributions/dock-cycle/xbattlax/tools/oomwoo_dock_ir_model.py): `contributions/dock-cycle/xbattlax/tools/oomwoo_dock_ir_model.py`
- [Recovery Safety](https://github.com/makerspet/oomwoo/blob/main/contributions/recovery-safety/xbattlax/oomwoo_recovery_safety/oomwoo_recovery_safety/recovery_node.py): `contributions/recovery-safety/xbattlax/oomwoo_recovery_safety/oomwoo_recovery_safety/recovery_node.py`

### Other components

- **Builder / Contributor**
- **Home Assistant**
- **Cloud Services**

## Connections

- Builder / Contributor → RFC Board: selects module
- RFC Board → System Design: guides design
- Builder / Contributor → Gazebo Simulation: develops against
- Robot Description → Gazebo Simulation: describes robot
- Mapping & Localization → Navigation: provides map pose
- Navigation → Obstacle Avoidance: avoids obstacles
- Navigation → Cleaning Jobs: supports cleaning
- Control App → Cleaning Jobs: customizes operation
- I/O Board → I/O Firmware: hosts firmware
- CPU–MCU Interface → I/O Firmware: defines wire protocol
- Home Assistant → Control App: local control
- Cloud Services → Control App: optional features