# gigi74168/openrobots architecture

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

- Interactive diagram: https://gitdiagram.com/gigi74168/openrobots
- Repository: https://github.com/gigi74168/openrobots

## Overview

Aérobot is a local Roomba-control system: an ESPHome device speaks the Roomba Open Interface, exposes robot state and controls to Home Assistant, and Home Assistant provides vacuum controls, scheduling, notifications, and a joystick. A separate AppDaemon mapper turns pose and collision data into a persisted occupancy map and publishes it through MQTT. The README says the firmware and integrations have not been verified on hardware; edges reflect documented flows and the shown mapper calls, not an inspected end-to-end deployment.

Main entry points: [`firmware/components/roomba_oi/roomba_oi.cpp`](https://github.com/gigi74168/openrobots/blob/main/firmware/components/roomba_oi/roomba_oi.cpp) (Roomba OI component), [`mapper/appdaemon/roomba_map.py`](https://github.com/gigi74168/openrobots/blob/main/mapper/appdaemon/roomba_map.py) (Mapper app), [`ha/dashboard.yaml`](https://github.com/gigi74168/openrobots/blob/main/ha/dashboard.yaml) (HA dashboard), [`firmware/roomba.yaml`](https://github.com/gigi74168/openrobots/blob/main/firmware/roomba.yaml) (ESPHome configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_robot["Robot interface"]
  node_firmware_config["ESPHome configuration<br/>[roomba.yaml]"]
  node_oi_component["Roomba OI component<br/>[roomba_oi.cpp]"]
  node_oi_config["ESPHome component setup<br/>[__init__.py]"]
  node_roomba["Roomba 696"]
end

subgraph group_ha["Home Assistant"]
  node_dashboard["HA dashboard<br/>[dashboard.yaml]"]
  node_joystick["Joystick card"]
  node_ha_package["Vacuum and automations"]
  node_ha_core["Home Assistant"]
  node_map_image["Map image and stats"]
end

subgraph group_mapping["Room mapping"]
  node_appdaemon["Mapper app<br/>[roomba_map.py]"]
  node_map_core["Occupancy map<br/>[mapper_core.py]"]
  node_map_state[("Saved map state<br/>[roomba_map.py]")]
  node_mqtt["MQTT broker"]
end

subgraph group_hardware["Physical hardware"]
  node_gyro["MPU6050 gyroscope"]
end

node_user(("Home user"))

node_user -->|"uses"| node_dashboard
node_dashboard -->|"hosts"| node_joystick
node_dashboard -->|"offers controls"| node_ha_package
node_ha_package -->|"configures"| node_ha_core
node_joystick -->|"calls services"| node_ha_core
node_ha_core -->|"sends controls"| node_firmware_config
node_firmware_config -->|"configures"| node_oi_config
node_oi_config -->|"registers"| node_oi_component
node_oi_component -->|"serial commands"| node_roomba
node_roomba -->|"sensor stream"| node_oi_component
node_gyro -->|"feeds heading"| node_oi_component
node_oi_component -->|"publishes state"| node_ha_core
node_ha_core -->|"provides pose and collisions"| node_appdaemon
node_appdaemon -->|"updates and renders"| node_map_core
node_appdaemon -->|"loads and saves"| node_map_state
node_appdaemon -->|"publishes PNG and stats"| node_mqtt
node_mqtt -->|"delivers map"| node_ha_core
node_ha_core -->|"exposes map"| node_map_image
node_map_image -->|"appears on"| node_dashboard

click node_dashboard "https://github.com/gigi74168/openrobots/blob/main/ha/dashboard.yaml"
click node_joystick "https://github.com/gigi74168/openrobots/blob/main/ha/www/aerobot-joystick-card.js"
click node_ha_package "https://github.com/gigi74168/openrobots/blob/main/ha/aerobot_package.yaml"
click node_firmware_config "https://github.com/gigi74168/openrobots/blob/main/firmware/roomba.yaml"
click node_oi_component "https://github.com/gigi74168/openrobots/blob/main/firmware/components/roomba_oi/roomba_oi.cpp"
click node_oi_config "https://github.com/gigi74168/openrobots/blob/main/firmware/components/roomba_oi/__init__.py"
click node_appdaemon "https://github.com/gigi74168/openrobots/blob/main/mapper/appdaemon/roomba_map.py"
click node_map_core "https://github.com/gigi74168/openrobots/blob/main/mapper/mapper_core.py"
click node_map_state "https://github.com/gigi74168/openrobots/blob/main/mapper/appdaemon/roomba_map.py"
click node_map_image "https://github.com/gigi74168/openrobots/blob/main/ha/aerobot_package.yaml"

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_firmware_config,node_oi_component,node_oi_config,node_roomba,node_user toneBlue
class node_dashboard,node_joystick,node_ha_package,node_ha_core,node_map_image toneAmber
class node_appdaemon,node_map_core,node_map_state,node_mqtt toneMint
class node_gyro toneRose
```

## Components

### Robot interface

- [ESPHome configuration](https://github.com/gigi74168/openrobots/blob/main/firmware/roomba.yaml): `firmware/roomba.yaml`
- [Roomba OI component](https://github.com/gigi74168/openrobots/blob/main/firmware/components/roomba_oi/roomba_oi.cpp): `firmware/components/roomba_oi/roomba_oi.cpp`
- [ESPHome component setup](https://github.com/gigi74168/openrobots/blob/main/firmware/components/roomba_oi/__init__.py): `firmware/components/roomba_oi/__init__.py`
- **Roomba 696**

### Home Assistant

- [HA dashboard](https://github.com/gigi74168/openrobots/blob/main/ha/dashboard.yaml): `ha/dashboard.yaml`
- [Joystick card](https://github.com/gigi74168/openrobots/blob/main/ha/www/aerobot-joystick-card.js): `ha/www/aerobot-joystick-card.js`
- [Vacuum and automations](https://github.com/gigi74168/openrobots/blob/main/ha/aerobot_package.yaml): `ha/aerobot_package.yaml`
- **Home Assistant**
- [Map image and stats](https://github.com/gigi74168/openrobots/blob/main/ha/aerobot_package.yaml): `ha/aerobot_package.yaml`

### Room mapping

- [Mapper app](https://github.com/gigi74168/openrobots/blob/main/mapper/appdaemon/roomba_map.py): `mapper/appdaemon/roomba_map.py`
- [Occupancy map](https://github.com/gigi74168/openrobots/blob/main/mapper/mapper_core.py): `mapper/mapper_core.py`
- [Saved map state](https://github.com/gigi74168/openrobots/blob/main/mapper/appdaemon/roomba_map.py): `mapper/appdaemon/roomba_map.py`
- **MQTT broker**

### Physical hardware

- **MPU6050 gyroscope**

### Other components

- **Home user**

## Connections

- Home user → HA dashboard: uses (evidence: `README.md`)
- HA dashboard → Joystick card: hosts (evidence: `README.md`)
- HA dashboard → Vacuum and automations: offers controls (evidence: `README.md`)
- Vacuum and automations → Home Assistant: configures (evidence: `README.md`)
- Joystick card → Home Assistant: calls services (evidence: `ha/www/aerobot-joystick-card.js`)
- Home Assistant → ESPHome configuration: sends controls (evidence: `README.md`)
- ESPHome configuration → ESPHome component setup: configures
- ESPHome component setup → Roomba OI component: registers (evidence: `firmware/components/roomba_oi/__init__.py`)
- Roomba OI component → Roomba 696: serial commands (evidence: `README.md`)
- Roomba 696 → Roomba OI component: sensor stream (evidence: `README.md`)
- MPU6050 gyroscope → Roomba OI component: feeds heading (evidence: `README.md`)
- Roomba OI component → Home Assistant: publishes state (evidence: `README.md`)
- Home Assistant → Mapper app: provides pose and collisions (evidence: `README.md`)
- Mapper app → Occupancy map: updates and renders (evidence: `mapper/appdaemon/roomba_map.py`)
- Mapper app → Saved map state: loads and saves (evidence: `mapper/appdaemon/roomba_map.py`)
- Mapper app → MQTT broker: publishes PNG and stats (evidence: `mapper/appdaemon/roomba_map.py`)
- MQTT broker → Home Assistant: delivers map (evidence: `README.md`)
- Home Assistant → Map image and stats: exposes map (evidence: `README.md`)
- Map image and stats → HA dashboard: appears on (evidence: `README.md`)
