# ifurusato/ros architecture

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

- Interactive diagram: https://gitdiagram.com/ifurusato/ros
- Repository: https://github.com/ifurusato/ros

## Overview

This repository is a Python robot operating system for Raspberry Pi differential-drive robots. Its principal workflow is to configure and discover hardware, collect sensor or operator events, prioritize behavior through the subsumption/BBS control layers, and command the motors. The graph includes documented sensor, display, and device capabilities; unsampled implementation details are represented only where the README supports them, so uncertain internal wiring is omitted.

Main entry points: [`lib`](https://github.com/ifurusato/ros/tree/master/lib) (Sensor drivers), [`lib/message_factory.py`](https://github.com/ifurusato/ros/blob/master/lib/message_factory.py) (Event messages), [`lib/motors.py`](https://github.com/ifurusato/ros/blob/master/lib/motors.py) (Drive motors), [`ros.py`](https://github.com/ifurusato/ros/blob/master/ros.py) (ROS runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime and setup"]
  node_ros["ROS runtime<br/>[ros.py]"]
  node_config["YAML configuration<br/>[config_loader.py]"]
  node_i2c["I²C discovery<br/>[i2c_scanner.py]"]
  node_events["Event messages<br/>[message_factory.py]"]
  node_bus["Message bus<br/>[message_bus.py]"]
  node_asyncbus["Async message queue"]
end

subgraph group_inputs["Inputs and sensing"]
  node_sensors["Sensor drivers"]
  node_composites["Composite ranging<br/>[lidar.py]"]
  node_gamepad["Gamepad input<br/>[gamepad.py]"]
  node_ifs["IFS controls<br/>[ifs.py]"]
end

subgraph group_behavior["Behavior and control"]
  node_arbitrator["Task arbitrator<br/>[arbitrator.py]"]
  node_fsm["Behavior state machines<br/>[fsm.py]"]
  node_controller["Robot controller<br/>[controller.py]"]
  node_pid["PID and odometry<br/>[pid_motor_ctrl.py]"]
end

subgraph group_outputs["Actuation and feedback"]
  node_motors["Drive motors<br/>[motors.py]"]
  node_thunderborg["ThunderBorg driver<br/>[ThunderBorg3.py]"]
  node_ultraborg["UltraBorg driver<br/>[UltraBorg3.py]"]
  node_displays["LED displays<br/>[rgbmatrix.py]"]
end

node_operator(("Operator"))
node_environment(("Robot environment"))
node_hardware{{"Robot hardware"}}

node_operator -->|"provides controls"| node_gamepad
node_operator -.->|"triggers events"| node_ifs
node_ros -->|"loads settings"| node_config
node_ros -->|"discovers devices"| node_i2c
node_ros -->|"initializes bus"| node_bus
node_sensors -->|"measures"| node_environment
node_environment -->|"physical signals"| node_sensors
node_sensors -.->|"creates events"| node_events
node_composites -.->|"reports ranging"| node_events
node_gamepad -->|"creates events"| node_events
node_ifs -.->|"creates events"| node_events
node_events -->|"publishes messages"| node_bus
node_bus -.->|"queues messages"| node_asyncbus
node_asyncbus -.->|"dispatches tasks"| node_arbitrator
node_arbitrator -->|"prioritizes behavior"| node_fsm
node_fsm -->|"selects actions"| node_controller
node_controller -->|"commands motion"| node_motors
node_controller -.->|"updates feedback"| node_displays
node_pid -->|"regulates velocity"| node_motors
node_motors -->|"sets drive power"| node_thunderborg
node_motors -->|"drives wheels"| node_hardware
node_thunderborg -->|"controls motors"| node_hardware
node_ultraborg -.->|"controls servo and sonar"| node_hardware
node_displays -.->|"shows status"| node_hardware
node_hardware -->|"supplies readings"| node_sensors
node_i2c -->|"identifies devices"| node_sensors
node_i2c -.->|"identifies devices"| node_composites

click node_ros "https://github.com/ifurusato/ros/blob/master/ros.py"
click node_config "https://github.com/ifurusato/ros/blob/master/lib/config_loader.py"
click node_i2c "https://github.com/ifurusato/ros/blob/master/lib/i2c_scanner.py"
click node_events "https://github.com/ifurusato/ros/blob/master/lib/message_factory.py"
click node_bus "https://github.com/ifurusato/ros/blob/master/lib/message_bus.py"
click node_asyncbus "https://github.com/ifurusato/ros/blob/master/lib/async_message_bus.py"
click node_sensors "https://github.com/ifurusato/ros/tree/master/lib"
click node_composites "https://github.com/ifurusato/ros/blob/master/lib/lidar.py"
click node_gamepad "https://github.com/ifurusato/ros/blob/master/lib/gamepad.py"
click node_ifs "https://github.com/ifurusato/ros/blob/master/lib/ifs.py"
click node_arbitrator "https://github.com/ifurusato/ros/blob/master/lib/arbitrator.py"
click node_fsm "https://github.com/ifurusato/ros/blob/master/lib/fsm.py"
click node_controller "https://github.com/ifurusato/ros/blob/master/lib/controller.py"
click node_pid "https://github.com/ifurusato/ros/blob/master/lib/pid_motor_ctrl.py"
click node_motors "https://github.com/ifurusato/ros/blob/master/lib/motors.py"
click node_thunderborg "https://github.com/ifurusato/ros/blob/master/lib/ThunderBorg3.py"
click node_ultraborg "https://github.com/ifurusato/ros/blob/master/lib/UltraBorg3.py"
click node_displays "https://github.com/ifurusato/ros/blob/master/lib/rgbmatrix.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_ros,node_config,node_i2c,node_events,node_bus,node_asyncbus toneBlue
class node_sensors,node_composites,node_gamepad,node_ifs toneAmber
class node_arbitrator,node_fsm,node_controller,node_pid toneMint
class node_motors,node_thunderborg,node_ultraborg,node_displays toneRose
class node_operator,node_environment,node_hardware toneIndigo
```

## Components

### Runtime and setup

- [ROS runtime](https://github.com/ifurusato/ros/blob/master/ros.py): `ros.py`
- [YAML configuration](https://github.com/ifurusato/ros/blob/master/lib/config_loader.py): `lib/config_loader.py`
- [I²C discovery](https://github.com/ifurusato/ros/blob/master/lib/i2c_scanner.py): `lib/i2c_scanner.py`
- [Event messages](https://github.com/ifurusato/ros/blob/master/lib/message_factory.py): `lib/message_factory.py`
- [Message bus](https://github.com/ifurusato/ros/blob/master/lib/message_bus.py): `lib/message_bus.py`
- [Async message queue](https://github.com/ifurusato/ros/blob/master/lib/async_message_bus.py): `lib/async_message_bus.py`

### Inputs and sensing

- [Sensor drivers](https://github.com/ifurusato/ros/tree/master/lib): `lib`
- [Composite ranging](https://github.com/ifurusato/ros/blob/master/lib/lidar.py): `lib/lidar.py`
- [Gamepad input](https://github.com/ifurusato/ros/blob/master/lib/gamepad.py): `lib/gamepad.py`
- [IFS controls](https://github.com/ifurusato/ros/blob/master/lib/ifs.py): `lib/ifs.py`

### Behavior and control

- [Task arbitrator](https://github.com/ifurusato/ros/blob/master/lib/arbitrator.py): `lib/arbitrator.py`
- [Behavior state machines](https://github.com/ifurusato/ros/blob/master/lib/fsm.py): `lib/fsm.py`
- [Robot controller](https://github.com/ifurusato/ros/blob/master/lib/controller.py): `lib/controller.py`
- [PID and odometry](https://github.com/ifurusato/ros/blob/master/lib/pid_motor_ctrl.py): `lib/pid_motor_ctrl.py`

### Actuation and feedback

- [Drive motors](https://github.com/ifurusato/ros/blob/master/lib/motors.py): `lib/motors.py`
- [ThunderBorg driver](https://github.com/ifurusato/ros/blob/master/lib/ThunderBorg3.py): `lib/ThunderBorg3.py`
- [UltraBorg driver](https://github.com/ifurusato/ros/blob/master/lib/UltraBorg3.py): `lib/UltraBorg3.py`
- [LED displays](https://github.com/ifurusato/ros/blob/master/lib/rgbmatrix.py): `lib/rgbmatrix.py`

### Other components

- **Operator**
- **Robot environment**
- **Robot hardware**

## Connections

- Operator → Gamepad input: provides controls
- Operator → IFS controls: triggers events
- ROS runtime → YAML configuration: loads settings
- ROS runtime → I²C discovery: discovers devices
- ROS runtime → Message bus: initializes bus
- Sensor drivers → Robot environment: measures
- Robot environment → Sensor drivers: physical signals
- Sensor drivers → Event messages: creates events
- Composite ranging → Event messages: reports ranging
- Gamepad input → Event messages: creates events
- IFS controls → Event messages: creates events
- Event messages → Message bus: publishes messages
- Message bus → Async message queue: queues messages
- Async message queue → Task arbitrator: dispatches tasks
- Task arbitrator → Behavior state machines: prioritizes behavior
- Behavior state machines → Robot controller: selects actions
- Robot controller → Drive motors: commands motion
- Robot controller → LED displays: updates feedback
- PID and odometry → Drive motors: regulates velocity
- Drive motors → ThunderBorg driver: sets drive power
- Drive motors → Robot hardware: drives wheels
- ThunderBorg driver → Robot hardware: controls motors
- UltraBorg driver → Robot hardware: controls servo and sonar
- LED displays → Robot hardware: shows status
- Robot hardware → Sensor drivers: supplies readings
- I²C discovery → Sensor drivers: identifies devices
- I²C discovery → Composite ranging: identifies devices