# anhyeonseo/mobile-bimanual-home-assistant architecture

> Architecture diagram of the GitHub repository anhyeonseo/mobile-bimanual-home-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anhyeonseo/mobile-bimanual-home-assistant
- Repository: https://github.com/anhyeonseo/mobile-bimanual-home-assistant

## Overview

ALOHA Mini is a mobile household manipulation platform: a request is planned into a fetch workflow, the robot navigates and observes at safe stops, then manipulates, verifies, and recovers as needed. The repository also contains a ROS task/gateway layer, an arm bridge, and STM32 actuator firmware. The README documents several perception and semantic-mapping capabilities as future work; those are shown as planned branches, not as verified runtime links. Unsampled implementation details are omitted where their connections are not evidenced.

Main entry points: [`ros2_ws/src/home_robot_tasks/home_robot_tasks/execution.py`](https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/ros2_ws/src/home_robot_tasks/home_robot_tasks/execution.py) (Task executor), [`ros2_ws/src/home_robot_tasks/home_robot_tasks/application.py`](https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/ros2_ws/src/home_robot_tasks/home_robot_tasks/application.py) (Application service), [`ros2_ws/src/so101_arm_bridge/so101_arm_bridge/bimanual_stream_adapter.py`](https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/ros2_ws/src/so101_arm_bridge/so101_arm_bridge/bimanual_stream_adapter.py) (Bimanual stream adapter), [`firmware/stm32_g474_single_arm/Core/Src/main.c`](https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/firmware/stm32_g474_single_arm/Core/Src/main.c) (STM32 board loop)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_task["Task planning"]
  node_app["Application service<br/>[application.py]"]
  node_fetch["Fetch planner<br/>[fetch.py]"]
  node_executor["Task executor<br/>[execution.py]"]
  node_gateway["HTTP gateway<br/>[gateway.py]"]
  node_replay["Event replay<br/>[replay.py]"]
end

subgraph group_perception["Perception and navigation"]
  node_nav["Map navigation<br/>[navigation.py]"]
  node_search["Object search<br/>[search.py]"]
  node_perception["RGB-D perception<br/>[perception.py]"]
  node_recovery["Failure recovery<br/>[recovery.py]"]
end

subgraph group_manipulation["Manipulation execution"]
  node_manipulation["Manipulation port"]
  node_skills["Skill ports<br/>[skill_ports.py]"]
  node_routes["Arm route builder<br/>[arm_routes.py]"]
end

subgraph group_bridge["Robot bridge"]
  node_adapter["Bimanual stream adapter"]
  node_protocol["Stream protocol"]
  node_transport["Stream transport"]
  node_limits["Joint limits<br/>[limit_manifest.py]"]
end

subgraph group_firmware["Actuator firmware"]
  node_board["STM32 board loop<br/>[main.c]"]
  node_mobile_output["Mobile output<br/>[mobile_output.h]"]
  node_feedback["Mobile feedback"]
  node_servo_output["Servo output"]
  node_servo_transport["Servo transport<br/>[servo_transport.h]"]
  node_lift["Lift controller<br/>[lift_controller.c]"]
  node_bus["Shared bus router<br/>[bus_router.c]"]
end

node_user(("Task requester"))
node_actor{{"Robot hardware"}}

node_user -->|"submits request"| node_gateway
node_gateway -->|"routes requests"| node_app
node_app -->|"plans fetch"| node_fetch
node_app -->|"plans navigation"| node_nav
node_app -.->|"starts execution"| node_executor
node_executor -->|"dispatches skills"| node_manipulation
node_executor -->|"records events"| node_replay
node_executor -.->|"requests observation"| node_search
node_search -.->|"uses RGB-D"| node_perception
node_executor -.->|"handles failure"| node_recovery
node_manipulation -->|"uses skill ports"| node_skills
node_routes -->|"builds arm routes"| node_adapter
node_adapter -->|"encodes stream"| node_protocol
node_adapter -->|"sends stream"| node_transport
node_adapter -->|"loads limits"| node_limits
node_board -->|"polls feedback"| node_feedback
node_board -->|"initializes output"| node_servo_output
node_feedback -->|"uses output state"| node_mobile_output
node_servo_output -.->|"uses transport"| node_servo_transport
node_lift -.->|"controls lift"| node_actor
node_bus -.->|"routes bus traffic"| node_actor
node_board -.->|"controls actuators"| node_actor

click node_app "https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/ros2_ws/src/home_robot_tasks/home_robot_tasks/application.py"
click node_fetch "https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/ros2_ws/src/home_robot_tasks/home_robot_tasks/fetch.py"
click node_executor "https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/ros2_ws/src/home_robot_tasks/home_robot_tasks/execution.py"
click node_gateway "https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/ros2_ws/src/home_robot_tasks/home_robot_tasks/gateway.py"
click node_replay "https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/ros2_ws/src/home_robot_tasks/home_robot_tasks/replay.py"
click node_nav "https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/ros2_ws/src/home_robot_tasks/home_robot_tasks/navigation.py"
click node_search "https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/ros2_ws/src/home_robot_tasks/home_robot_tasks/search.py"
click node_perception "https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/ros2_ws/src/home_robot_tasks/home_robot_tasks/perception.py"
click node_recovery "https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/ros2_ws/src/home_robot_tasks/home_robot_tasks/recovery.py"
click node_manipulation "https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/ros2_ws/src/home_robot_tasks/home_robot_tasks/manipulation_port.py"
click node_skills "https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/ros2_ws/src/home_robot_tasks/home_robot_tasks/skill_ports.py"
click node_routes "https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/ros2_ws/src/home_robot_tasks/home_robot_tasks/arm_routes.py"
click node_adapter "https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/ros2_ws/src/so101_arm_bridge/so101_arm_bridge/bimanual_stream_adapter.py"
click node_protocol "https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/ros2_ws/src/so101_arm_bridge/so101_arm_bridge/stream_protocol_v2.py"
click node_transport "https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/ros2_ws/src/so101_arm_bridge/so101_arm_bridge/stream_transport_v2.py"
click node_limits "https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/ros2_ws/src/so101_arm_bridge/so101_arm_bridge/limit_manifest.py"
click node_board "https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/firmware/stm32_g474_single_arm/Core/Src/main.c"
click node_mobile_output "https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/firmware/stm32_actuator/include/actuator_core/mobile_output.h"
click node_feedback "https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/firmware/stm32_g474_single_arm/Core/Inc/mobile_servo_feedback.h"
click node_servo_output "https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/firmware/stm32_g474_single_arm/Core/Inc/mobile_servo_output.h"
click node_servo_transport "https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/firmware/stm32_g474_single_arm/Core/Inc/servo_transport.h"
click node_lift "https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/firmware/stm32_actuator/src/lift_controller.c"
click node_bus "https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/firmware/stm32_actuator/src/bus_router.c"

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_app,node_fetch,node_executor,node_gateway,node_replay toneBlue
class node_nav,node_search,node_perception,node_recovery toneAmber
class node_manipulation,node_skills,node_routes toneMint
class node_adapter,node_protocol,node_transport,node_limits,node_user toneRose
class node_board,node_mobile_output,node_feedback,node_servo_output,node_servo_transport,node_lift,node_bus,node_actor toneIndigo
```

## Components

### Task planning

- [Application service](https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/ros2_ws/src/home_robot_tasks/home_robot_tasks/application.py): `ros2_ws/src/home_robot_tasks/home_robot_tasks/application.py`
- [Fetch planner](https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/ros2_ws/src/home_robot_tasks/home_robot_tasks/fetch.py): `ros2_ws/src/home_robot_tasks/home_robot_tasks/fetch.py`
- [Task executor](https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/ros2_ws/src/home_robot_tasks/home_robot_tasks/execution.py): `ros2_ws/src/home_robot_tasks/home_robot_tasks/execution.py`
- [HTTP gateway](https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/ros2_ws/src/home_robot_tasks/home_robot_tasks/gateway.py): `ros2_ws/src/home_robot_tasks/home_robot_tasks/gateway.py`
- [Event replay](https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/ros2_ws/src/home_robot_tasks/home_robot_tasks/replay.py): `ros2_ws/src/home_robot_tasks/home_robot_tasks/replay.py`

### Perception and navigation

- [Map navigation](https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/ros2_ws/src/home_robot_tasks/home_robot_tasks/navigation.py): `ros2_ws/src/home_robot_tasks/home_robot_tasks/navigation.py`
- [Object search](https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/ros2_ws/src/home_robot_tasks/home_robot_tasks/search.py): `ros2_ws/src/home_robot_tasks/home_robot_tasks/search.py`
- [RGB-D perception](https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/ros2_ws/src/home_robot_tasks/home_robot_tasks/perception.py): `ros2_ws/src/home_robot_tasks/home_robot_tasks/perception.py`
- [Failure recovery](https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/ros2_ws/src/home_robot_tasks/home_robot_tasks/recovery.py): `ros2_ws/src/home_robot_tasks/home_robot_tasks/recovery.py`

### Manipulation execution

- [Manipulation port](https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/ros2_ws/src/home_robot_tasks/home_robot_tasks/manipulation_port.py): `ros2_ws/src/home_robot_tasks/home_robot_tasks/manipulation_port.py`
- [Skill ports](https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/ros2_ws/src/home_robot_tasks/home_robot_tasks/skill_ports.py): `ros2_ws/src/home_robot_tasks/home_robot_tasks/skill_ports.py`
- [Arm route builder](https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/ros2_ws/src/home_robot_tasks/home_robot_tasks/arm_routes.py): `ros2_ws/src/home_robot_tasks/home_robot_tasks/arm_routes.py`

### Robot bridge

- [Bimanual stream adapter](https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/ros2_ws/src/so101_arm_bridge/so101_arm_bridge/bimanual_stream_adapter.py): `ros2_ws/src/so101_arm_bridge/so101_arm_bridge/bimanual_stream_adapter.py`
- [Stream protocol](https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/ros2_ws/src/so101_arm_bridge/so101_arm_bridge/stream_protocol_v2.py): `ros2_ws/src/so101_arm_bridge/so101_arm_bridge/stream_protocol_v2.py`
- [Stream transport](https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/ros2_ws/src/so101_arm_bridge/so101_arm_bridge/stream_transport_v2.py): `ros2_ws/src/so101_arm_bridge/so101_arm_bridge/stream_transport_v2.py`
- [Joint limits](https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/ros2_ws/src/so101_arm_bridge/so101_arm_bridge/limit_manifest.py): `ros2_ws/src/so101_arm_bridge/so101_arm_bridge/limit_manifest.py`

### Actuator firmware

- [STM32 board loop](https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/firmware/stm32_g474_single_arm/Core/Src/main.c): `firmware/stm32_g474_single_arm/Core/Src/main.c`
- [Mobile output](https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/firmware/stm32_actuator/include/actuator_core/mobile_output.h): `firmware/stm32_actuator/include/actuator_core/mobile_output.h`
- [Mobile feedback](https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/firmware/stm32_g474_single_arm/Core/Inc/mobile_servo_feedback.h): `firmware/stm32_g474_single_arm/Core/Inc/mobile_servo_feedback.h`
- [Servo output](https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/firmware/stm32_g474_single_arm/Core/Inc/mobile_servo_output.h): `firmware/stm32_g474_single_arm/Core/Inc/mobile_servo_output.h`
- [Servo transport](https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/firmware/stm32_g474_single_arm/Core/Inc/servo_transport.h): `firmware/stm32_g474_single_arm/Core/Inc/servo_transport.h`
- [Lift controller](https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/firmware/stm32_actuator/src/lift_controller.c): `firmware/stm32_actuator/src/lift_controller.c`
- [Shared bus router](https://github.com/anhyeonseo/mobile-bimanual-home-assistant/blob/main/firmware/stm32_actuator/src/bus_router.c): `firmware/stm32_actuator/src/bus_router.c`

### Other components

- **Task requester**
- **Robot hardware**

## Connections

- Task requester → HTTP gateway: submits request
- HTTP gateway → Application service: routes requests (evidence: `ros2_ws/src/home_robot_tasks/home_robot_tasks/application.py`)
- Application service → Fetch planner: plans fetch (evidence: `ros2_ws/src/home_robot_tasks/home_robot_tasks/application.py`)
- Application service → Map navigation: plans navigation (evidence: `ros2_ws/src/home_robot_tasks/home_robot_tasks/application.py`)
- Application service → Task executor: starts execution (evidence: `ros2_ws/src/home_robot_tasks/home_robot_tasks/application.py`)
- Task executor → Manipulation port: dispatches skills (evidence: `ros2_ws/src/home_robot_tasks/home_robot_tasks/execution.py`)
- Task executor → Event replay: records events (evidence: `ros2_ws/src/home_robot_tasks/home_robot_tasks/execution.py`)
- Task executor → Object search: requests observation
- Object search → RGB-D perception: uses RGB-D
- Task executor → Failure recovery: handles failure
- Manipulation port → Skill ports: uses skill ports (evidence: `ros2_ws/src/home_robot_tasks/home_robot_tasks/manipulation_port.py`)
- Arm route builder → Bimanual stream adapter: builds arm routes (evidence: `ros2_ws/src/home_robot_tasks/home_robot_tasks/arm_routes.py`)
- Bimanual stream adapter → Stream protocol: encodes stream (evidence: `ros2_ws/src/so101_arm_bridge/so101_arm_bridge/bimanual_stream_adapter.py`)
- Bimanual stream adapter → Stream transport: sends stream (evidence: `ros2_ws/src/so101_arm_bridge/so101_arm_bridge/bimanual_stream_adapter.py`)
- Bimanual stream adapter → Joint limits: loads limits (evidence: `ros2_ws/src/so101_arm_bridge/so101_arm_bridge/bimanual_stream_adapter.py`)
- STM32 board loop → Mobile feedback: polls feedback (evidence: `firmware/stm32_g474_single_arm/Core/Src/main.c`)
- STM32 board loop → Servo output: initializes output (evidence: `firmware/stm32_g474_single_arm/Core/Src/main.c`)
- Mobile feedback → Mobile output: uses output state (evidence: `firmware/stm32_g474_single_arm/Core/Inc/mobile_servo_feedback.h`)
- Servo output → Servo transport: uses transport (evidence: `firmware/stm32_g474_single_arm/Core/Inc/mobile_servo_output.h`)
- Lift controller → Robot hardware: controls lift
- Shared bus router → Robot hardware: routes bus traffic
- STM32 board loop → Robot hardware: controls actuators
