# hmarthens1/rpi4-robot-board architecture

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

- Interactive diagram: https://gitdiagram.com/hmarthens1/rpi4-robot-board
- Repository: https://github.com/hmarthens1/rpi4-robot-board

## Overview

This repository provides a Raspberry Pi robot-board driver plus ROS 2 status, command, and vision nodes. The principal control workflow is a ROS client sending a command to the command node, which applies safety checks and drives board, arm, or GPIO hardware; status reports battery and sonar readings. A separate camera workflow produces lane and object-detection outputs. Python CLI and library access the same board capabilities. Some subsystem details are documented but unsampled, so their internal links are omitted.

Main entry points: [`ros2/robot_status/src/command_node.cpp`](https://github.com/hmarthens1/rpi4-robot-board/blob/main/ros2/robot_status/src/command_node.cpp) (Command node), [`ros2/robot_vision/src/vision_node.cpp`](https://github.com/hmarthens1/rpi4-robot-board/blob/main/ros2/robot_vision/src/vision_node.cpp) (Vision node), [`robot_board/cli.py`](https://github.com/hmarthens1/rpi4-robot-board/blob/main/robot_board/cli.py) (Board CLI), [`ros2/robot_status/src/status_node.cpp`](https://github.com/hmarthens1/rpi4-robot-board/blob/main/ros2/robot_status/src/status_node.cpp) (Status node)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_py["Python board driver"]
  node_python_cli["Board CLI<br/>[cli.py]"]
  node_python_board["Board driver<br/>[board.py]"]
  node_python_periph["GPIO peripherals<br/>[peripherals.py]"]
  node_python_sonar["Sonar driver<br/>[sonar.py]"]
  node_mecanum["Mecanum mixer<br/>[mecanum.py]"]
end

subgraph group_status["ROS board control"]
  node_command["Command node<br/>[command_node.cpp]"]
  node_status_node["Status node<br/>[status_node.cpp]"]
  node_cpp_board["Board driver<br/>[board.cpp]"]
  node_i2c["I2C transport<br/>[i2c.cpp]"]
  node_cpp_periph["GPIO peripherals<br/>[peripherals.cpp]"]
  node_cpp_sonar["Sonar driver<br/>[sonar.cpp]"]
  node_arm_ik["Arm kinematics<br/>[arm.cpp]"]
end

subgraph group_vision["ROS vision"]
  node_vision_node["Vision node<br/>[vision_node.cpp]"]
  node_lane["Lane detection<br/>[lane.cpp]"]
  node_seeker["Lane seeker<br/>[lane_seeker.cpp]"]
  node_yolox["YOLOX detection<br/>[yolox.cpp]"]
end

node_operator(("Robot operator"))
node_board_hw{{"Board hardware"}}
node_gpio_hw{{"GPIO hardware"}}
node_sonar_hw{{"Sonar module"}}
node_ros_clients(("ROS clients"))
node_command_result["Command results"]
node_status_topics["Status topics"]
node_camera{{"USB camera"}}
node_vision_topics["Vision topics"]

node_operator -->|"runs commands"| node_python_cli
node_python_cli -->|"reads battery"| node_python_board
node_python_cli -->|"tests peripherals"| node_python_periph
node_python_cli -->|"reads distance"| node_python_sonar
node_python_board -->|"I2C controls"| node_board_hw
node_python_periph -->|"drives GPIO"| node_gpio_hw
node_python_sonar -->|"I2C reads"| node_sonar_hw
node_mecanum -->|"mixes wheel speeds"| node_python_board
node_ros_clients -->|"sends commands"| node_command
node_command -->|"commands motors"| node_cpp_board
node_command -->|"controls LEDs"| node_cpp_periph
node_command -->|"checks clearance"| node_cpp_sonar
node_command -->|"solves arm moves"| node_arm_ik
node_command -->|"publishes results"| node_command_result
node_cpp_board -->|"transfers board data"| node_i2c
node_cpp_sonar -->|"transfers sonar data"| node_i2c
node_status_node -->|"reads battery"| node_cpp_board
node_status_node -->|"reads range"| node_cpp_sonar
node_status_node -->|"publishes status"| node_status_topics
node_ros_clients -->|"subscribes topics"| node_status_node
node_camera -->|"supplies frames"| node_vision_node
node_vision_node -->|"detects lanes"| node_lane
node_vision_node -->|"updates seeking"| node_seeker
node_vision_node -->|"detects objects"| node_yolox
node_vision_node -->|"publishes vision"| node_vision_topics
node_ros_clients -->|"configures vision"| node_vision_node

click node_python_cli "https://github.com/hmarthens1/rpi4-robot-board/blob/main/robot_board/cli.py"
click node_python_board "https://github.com/hmarthens1/rpi4-robot-board/blob/main/robot_board/board.py"
click node_python_periph "https://github.com/hmarthens1/rpi4-robot-board/blob/main/robot_board/peripherals.py"
click node_python_sonar "https://github.com/hmarthens1/rpi4-robot-board/blob/main/robot_board/sonar.py"
click node_mecanum "https://github.com/hmarthens1/rpi4-robot-board/blob/main/robot_board/mecanum.py"
click node_command "https://github.com/hmarthens1/rpi4-robot-board/blob/main/ros2/robot_status/src/command_node.cpp"
click node_status_node "https://github.com/hmarthens1/rpi4-robot-board/blob/main/ros2/robot_status/src/status_node.cpp"
click node_cpp_board "https://github.com/hmarthens1/rpi4-robot-board/blob/main/ros2/robot_status/src/board.cpp"
click node_i2c "https://github.com/hmarthens1/rpi4-robot-board/blob/main/ros2/robot_status/src/i2c.cpp"
click node_cpp_periph "https://github.com/hmarthens1/rpi4-robot-board/blob/main/ros2/robot_status/src/peripherals.cpp"
click node_cpp_sonar "https://github.com/hmarthens1/rpi4-robot-board/blob/main/ros2/robot_status/src/sonar.cpp"
click node_arm_ik "https://github.com/hmarthens1/rpi4-robot-board/blob/main/ros2/robot_status/src/arm.cpp"
click node_vision_node "https://github.com/hmarthens1/rpi4-robot-board/blob/main/ros2/robot_vision/src/vision_node.cpp"
click node_lane "https://github.com/hmarthens1/rpi4-robot-board/blob/main/ros2/robot_vision/src/lane.cpp"
click node_seeker "https://github.com/hmarthens1/rpi4-robot-board/blob/main/ros2/robot_vision/src/lane_seeker.cpp"
click node_yolox "https://github.com/hmarthens1/rpi4-robot-board/blob/main/ros2/robot_vision/src/yolox.cpp"

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_python_cli,node_python_board,node_python_periph,node_python_sonar,node_mecanum,node_ros_clients toneBlue
class node_command,node_status_node,node_cpp_board,node_i2c,node_cpp_periph,node_cpp_sonar,node_arm_ik toneAmber
class node_vision_node,node_lane,node_seeker,node_yolox toneMint
class node_operator,node_board_hw,node_gpio_hw,node_sonar_hw,node_command_result,node_status_topics,node_camera,node_vision_topics toneIndigo
```

## Components

### Python board driver

- [Board CLI](https://github.com/hmarthens1/rpi4-robot-board/blob/main/robot_board/cli.py): `robot_board/cli.py`
- [Board driver](https://github.com/hmarthens1/rpi4-robot-board/blob/main/robot_board/board.py): `robot_board/board.py`
- [GPIO peripherals](https://github.com/hmarthens1/rpi4-robot-board/blob/main/robot_board/peripherals.py): `robot_board/peripherals.py`
- [Sonar driver](https://github.com/hmarthens1/rpi4-robot-board/blob/main/robot_board/sonar.py): `robot_board/sonar.py`
- [Mecanum mixer](https://github.com/hmarthens1/rpi4-robot-board/blob/main/robot_board/mecanum.py): `robot_board/mecanum.py`

### ROS board control

- [Command node](https://github.com/hmarthens1/rpi4-robot-board/blob/main/ros2/robot_status/src/command_node.cpp): `ros2/robot_status/src/command_node.cpp`
- [Status node](https://github.com/hmarthens1/rpi4-robot-board/blob/main/ros2/robot_status/src/status_node.cpp): `ros2/robot_status/src/status_node.cpp`
- [Board driver](https://github.com/hmarthens1/rpi4-robot-board/blob/main/ros2/robot_status/src/board.cpp): `ros2/robot_status/src/board.cpp`
- [I2C transport](https://github.com/hmarthens1/rpi4-robot-board/blob/main/ros2/robot_status/src/i2c.cpp): `ros2/robot_status/src/i2c.cpp`
- [GPIO peripherals](https://github.com/hmarthens1/rpi4-robot-board/blob/main/ros2/robot_status/src/peripherals.cpp): `ros2/robot_status/src/peripherals.cpp`
- [Sonar driver](https://github.com/hmarthens1/rpi4-robot-board/blob/main/ros2/robot_status/src/sonar.cpp): `ros2/robot_status/src/sonar.cpp`
- [Arm kinematics](https://github.com/hmarthens1/rpi4-robot-board/blob/main/ros2/robot_status/src/arm.cpp): `ros2/robot_status/src/arm.cpp`

### ROS vision

- [Vision node](https://github.com/hmarthens1/rpi4-robot-board/blob/main/ros2/robot_vision/src/vision_node.cpp): `ros2/robot_vision/src/vision_node.cpp`
- [Lane detection](https://github.com/hmarthens1/rpi4-robot-board/blob/main/ros2/robot_vision/src/lane.cpp): `ros2/robot_vision/src/lane.cpp`
- [Lane seeker](https://github.com/hmarthens1/rpi4-robot-board/blob/main/ros2/robot_vision/src/lane_seeker.cpp): `ros2/robot_vision/src/lane_seeker.cpp`
- [YOLOX detection](https://github.com/hmarthens1/rpi4-robot-board/blob/main/ros2/robot_vision/src/yolox.cpp): `ros2/robot_vision/src/yolox.cpp`

### Other components

- **Robot operator**
- **Board hardware**
- **GPIO hardware**
- **Sonar module**
- **ROS clients**
- **Command results**
- **Status topics**
- **USB camera**
- **Vision topics**

## Connections

- Robot operator → Board CLI: runs commands (evidence: `README.md`)
- Board CLI → Board driver: reads battery (evidence: `robot_board/cli.py`)
- Board CLI → GPIO peripherals: tests peripherals (evidence: `robot_board/cli.py`)
- Board CLI → Sonar driver: reads distance (evidence: `robot_board/cli.py`)
- Board driver → Board hardware: I2C controls (evidence: `README.md`)
- GPIO peripherals → GPIO hardware: drives GPIO (evidence: `robot_board/peripherals.py`)
- Sonar driver → Sonar module: I2C reads (evidence: `README.md`)
- Mecanum mixer → Board driver: mixes wheel speeds (evidence: `README.md`)
- ROS clients → Command node: sends commands (evidence: `README.md`)
- Command node → Board driver: commands motors (evidence: `ros2/robot_status/src/command_node.cpp`)
- Command node → GPIO peripherals: controls LEDs (evidence: `ros2/robot_status/src/command_node.cpp`)
- Command node → Sonar driver: checks clearance (evidence: `ros2/robot_status/src/command_node.cpp`)
- Command node → Arm kinematics: solves arm moves (evidence: `ros2/robot_status/src/command_node.cpp`)
- Command node → Command results: publishes results (evidence: `README.md`)
- Board driver → I2C transport: transfers board data
- Sonar driver → I2C transport: transfers sonar data
- Status node → Board driver: reads battery (evidence: `README.md`)
- Status node → Sonar driver: reads range (evidence: `README.md`)
- Status node → Status topics: publishes status (evidence: `README.md`)
- ROS clients → Status node: subscribes topics (evidence: `README.md`)
- USB camera → Vision node: supplies frames (evidence: `ros2/robot_vision/src/vision_node.cpp`)
- Vision node → Lane detection: detects lanes (evidence: `ros2/robot_vision/src/vision_node.cpp`)
- Vision node → Lane seeker: updates seeking (evidence: `ros2/robot_vision/src/vision_node.cpp`)
- Vision node → YOLOX detection: detects objects (evidence: `ros2/robot_vision/src/vision_node.cpp`)
- Vision node → Vision topics: publishes vision (evidence: `ros2/robot_vision/src/vision_node.cpp`)
- ROS clients → Vision node: configures vision (evidence: `ros2/robot_vision/src/vision_node.cpp`)