# loorays/looraysbot architecture

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

- Interactive diagram: https://gitdiagram.com/loorays/looraysbot
- Repository: https://github.com/loorays/looraysbot

## Overview

looraysBot is a distributed ROS mobile-robot system: MCU firmware interfaces with the chassis and sensors, forwards telemetry and accepts control; ROS provides robot processing and navigation; operators use a mobile app or desktop GUI. The README documents the major ROS2 capabilities and the overall UDP-based architecture. Source excerpts confirm MCU initialization and telemetry/control behavior, but do not establish detailed wiring among ROS packages or between the app and robot, so those links are documented at the system level rather than inferred from names.

Main entry points: [`looraysBotMcu/base_esp32s3/main/main.c`](https://github.com/loorays/looraysbot/blob/main/looraysBotMcu/base_esp32s3/main/main.c) (Base firmware), [`looraysBotMcu/base_esp32s3/components/WEBSOCKET_CLIENT/WEBSOCKET_CLIENT.c`](https://github.com/loorays/looraysbot/blob/main/looraysBotMcu/base_esp32s3/components/WEBSOCKET_CLIENT/WEBSOCKET_CLIENT.c) (WebSocket telemetry), [`looraysBotRos2/src/looraysbot_navgation`](https://github.com/loorays/looraysbot/tree/main/looraysBotRos2/src/looraysbot_navgation) (SLAM and navigation), [`looraysBotMcu/base_esp32s3/components/UDP2ROS_LD/UDP2ROS_LD.h`](https://github.com/loorays/looraysbot/blob/main/looraysBotMcu/base_esp32s3/components/UDP2ROS_LD/UDP2ROS_LD.h) (Lidar forwarding)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mcu["Embedded firmware"]
  node_base["Base firmware<br/>[main.c]"]
  node_sensors["Chassis sensors<br/>[ICM42670P.c]"]
  node_drive["PID motor control<br/>[PID.h]"]
  node_lidar_forward["Lidar forwarding<br/>[UDP2ROS_LD.h]"]
  node_status_forward["Status UDP<br/>[UDP2ROS_STATUS.h]"]
  node_mcu_ws["WebSocket telemetry<br/>[WEBSOCKET_CLIENT.c]"]
end

subgraph group_ros["ROS processing"]
  node_ros_comm["UDP communications<br/>[comm_node.cpp]"]
  node_ros_lidar["Lidar driver<br/>[ld14pNode.cpp]"]
  node_imu_filter["IMU filter<br/>[imu_filter_ros.cpp]"]
  node_localization["State estimation<br/>[ros_filter.cpp]"]
  node_slam_nav["SLAM and navigation"]
  node_vision["Vision and gestures<br/>[gesture.py]"]
  node_bringup["ROS launch setup"]
  node_ros1["ROS1 compatibility<br/>[comm_node.cpp]"]
end

subgraph group_operator["Operator interfaces"]
  node_app["Mobile controls<br/>[App.tsx]"]
  node_gui["Desktop dashboard<br/>[main.cpp]"]
  node_rviz["Embedded RViz<br/>[ros2guirviz.h]"]
end

subgraph group_camera["Camera subsystem"]
  node_camera_capture["Camera capture<br/>[ESP32_CAM.c]"]
  node_camera_udp["Camera UDP<br/>[UDP_CAM.c]"]
end

node_operator(("Robot operator"))

node_base -->|"initializes"| node_sensors
node_base -->|"initializes"| node_drive
node_base -->|"starts tasks"| node_lidar_forward
node_base -->|"starts tasks"| node_status_forward
node_base -->|"starts service"| node_mcu_ws
node_mcu_ws -->|"sets velocity"| node_drive
node_mcu_ws -.->|"sends telemetry"| node_operator
node_camera_capture -->|"sends frames"| node_camera_udp
node_operator -->|"controls robot"| node_app
node_operator -->|"monitors robot"| node_gui
node_base -.->|"UDP telemetry"| node_ros_comm
node_lidar_forward -.->|"forwards scans"| node_ros_lidar
node_ros_comm -.->|"publishes sensor data"| node_imu_filter
node_imu_filter -.->|"provides filtered IMU"| node_localization
node_ros_lidar -.->|"provides lidar data"| node_slam_nav
node_localization -.->|"supports navigation"| node_slam_nav
node_camera_udp -.->|"provides images"| node_vision
node_bringup -.->|"launches navigation"| node_slam_nav
node_ros1 -.->|"supports ROS1 operation"| node_operator
node_gui -.->|"embeds visualization"| node_rviz

click node_base "https://github.com/loorays/looraysbot/blob/main/looraysBotMcu/base_esp32s3/main/main.c"
click node_sensors "https://github.com/loorays/looraysbot/blob/main/looraysBotMcu/base_esp32s3/components/ICM42670P/ICM42670P.c"
click node_drive "https://github.com/loorays/looraysbot/blob/main/looraysBotMcu/base_esp32s3/components/PID/PID.h"
click node_lidar_forward "https://github.com/loorays/looraysbot/blob/main/looraysBotMcu/base_esp32s3/components/UDP2ROS_LD/UDP2ROS_LD.h"
click node_status_forward "https://github.com/loorays/looraysbot/blob/main/looraysBotMcu/base_esp32s3/components/UDP2ROS_STATUS/UDP2ROS_STATUS.h"
click node_mcu_ws "https://github.com/loorays/looraysbot/blob/main/looraysBotMcu/base_esp32s3/components/WEBSOCKET_CLIENT/WEBSOCKET_CLIENT.c"
click node_camera_capture "https://github.com/loorays/looraysbot/blob/main/looraysBotMcu/camera_esp32/components/ESP32_CAM/ESP32_CAM.c"
click node_camera_udp "https://github.com/loorays/looraysbot/blob/main/looraysBotMcu/camera_esp32/components/UDP_CAM/UDP_CAM.c"
click node_ros_comm "https://github.com/loorays/looraysbot/blob/main/looraysBotRos2/src/looraysbot_comm/src/comm_node.cpp"
click node_ros_lidar "https://github.com/loorays/looraysbot/blob/main/looraysBotRos2/src/looraysbot_ldlidar/src/ld14pNode.cpp"
click node_imu_filter "https://github.com/loorays/looraysbot/blob/main/looraysBotRos2/src/imu_filter_madgwick/src/imu_filter_ros.cpp"
click node_localization "https://github.com/loorays/looraysbot/blob/main/looraysBotRos2/src/robot_localization-humble-devel/src/ros_filter.cpp"
click node_slam_nav "https://github.com/loorays/looraysbot/tree/main/looraysBotRos2/src/looraysbot_navgation"
click node_vision "https://github.com/loorays/looraysbot/blob/main/looraysBotRos2/src/looraysbot_video/looraysbot_video/gesture.py"
click node_bringup "https://github.com/loorays/looraysbot/blob/main/looraysBotRos2/src/looraysbot_bringup/launch/looraysbot_base.launch.py"
click node_ros1 "https://github.com/loorays/looraysbot/blob/main/looraysbotRos1/src/looraysbot_comm/src/comm_node.cpp"
click node_app "https://github.com/loorays/looraysbot/blob/main/looraysBotApp/src/App.tsx"
click node_gui "https://github.com/loorays/looraysbot/blob/main/looraysBotGui/src/looraysBot_Ui/src/main.cpp"
click node_rviz "https://github.com/loorays/looraysbot/blob/main/looraysBotGui/src/looraysBot_Ui/include/ros2guirviz.h"

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_base,node_sensors,node_drive,node_lidar_forward,node_status_forward,node_mcu_ws toneBlue
class node_ros_comm,node_ros_lidar,node_imu_filter,node_localization,node_slam_nav,node_vision,node_bringup,node_ros1 toneAmber
class node_app,node_gui,node_rviz toneMint
class node_camera_capture,node_camera_udp toneRose
class node_operator toneIndigo
```

## Components

### Embedded firmware

- [Base firmware](https://github.com/loorays/looraysbot/blob/main/looraysBotMcu/base_esp32s3/main/main.c): `looraysBotMcu/base_esp32s3/main/main.c`
- [Chassis sensors](https://github.com/loorays/looraysbot/blob/main/looraysBotMcu/base_esp32s3/components/ICM42670P/ICM42670P.c): `looraysBotMcu/base_esp32s3/components/ICM42670P/ICM42670P.c`
- [PID motor control](https://github.com/loorays/looraysbot/blob/main/looraysBotMcu/base_esp32s3/components/PID/PID.h): `looraysBotMcu/base_esp32s3/components/PID/PID.h`
- [Lidar forwarding](https://github.com/loorays/looraysbot/blob/main/looraysBotMcu/base_esp32s3/components/UDP2ROS_LD/UDP2ROS_LD.h): `looraysBotMcu/base_esp32s3/components/UDP2ROS_LD/UDP2ROS_LD.h`
- [Status UDP](https://github.com/loorays/looraysbot/blob/main/looraysBotMcu/base_esp32s3/components/UDP2ROS_STATUS/UDP2ROS_STATUS.h): `looraysBotMcu/base_esp32s3/components/UDP2ROS_STATUS/UDP2ROS_STATUS.h`
- [WebSocket telemetry](https://github.com/loorays/looraysbot/blob/main/looraysBotMcu/base_esp32s3/components/WEBSOCKET_CLIENT/WEBSOCKET_CLIENT.c): `looraysBotMcu/base_esp32s3/components/WEBSOCKET_CLIENT/WEBSOCKET_CLIENT.c`

### ROS processing

- [UDP communications](https://github.com/loorays/looraysbot/blob/main/looraysBotRos2/src/looraysbot_comm/src/comm_node.cpp): `looraysBotRos2/src/looraysbot_comm/src/comm_node.cpp`
- [Lidar driver](https://github.com/loorays/looraysbot/blob/main/looraysBotRos2/src/looraysbot_ldlidar/src/ld14pNode.cpp): `looraysBotRos2/src/looraysbot_ldlidar/src/ld14pNode.cpp`
- [IMU filter](https://github.com/loorays/looraysbot/blob/main/looraysBotRos2/src/imu_filter_madgwick/src/imu_filter_ros.cpp): `looraysBotRos2/src/imu_filter_madgwick/src/imu_filter_ros.cpp`
- [State estimation](https://github.com/loorays/looraysbot/blob/main/looraysBotRos2/src/robot_localization-humble-devel/src/ros_filter.cpp): `looraysBotRos2/src/robot_localization-humble-devel/src/ros_filter.cpp`
- [SLAM and navigation](https://github.com/loorays/looraysbot/tree/main/looraysBotRos2/src/looraysbot_navgation): `looraysBotRos2/src/looraysbot_navgation`
- [Vision and gestures](https://github.com/loorays/looraysbot/blob/main/looraysBotRos2/src/looraysbot_video/looraysbot_video/gesture.py): `looraysBotRos2/src/looraysbot_video/looraysbot_video/gesture.py`
- [ROS launch setup](https://github.com/loorays/looraysbot/blob/main/looraysBotRos2/src/looraysbot_bringup/launch/looraysbot_base.launch.py): `looraysBotRos2/src/looraysbot_bringup/launch/looraysbot_base.launch.py`
- [ROS1 compatibility](https://github.com/loorays/looraysbot/blob/main/looraysbotRos1/src/looraysbot_comm/src/comm_node.cpp): `looraysbotRos1/src/looraysbot_comm/src/comm_node.cpp`

### Operator interfaces

- [Mobile controls](https://github.com/loorays/looraysbot/blob/main/looraysBotApp/src/App.tsx): `looraysBotApp/src/App.tsx`
- [Desktop dashboard](https://github.com/loorays/looraysbot/blob/main/looraysBotGui/src/looraysBot_Ui/src/main.cpp): `looraysBotGui/src/looraysBot_Ui/src/main.cpp`
- [Embedded RViz](https://github.com/loorays/looraysbot/blob/main/looraysBotGui/src/looraysBot_Ui/include/ros2guirviz.h): `looraysBotGui/src/looraysBot_Ui/include/ros2guirviz.h`

### Camera subsystem

- [Camera capture](https://github.com/loorays/looraysbot/blob/main/looraysBotMcu/camera_esp32/components/ESP32_CAM/ESP32_CAM.c): `looraysBotMcu/camera_esp32/components/ESP32_CAM/ESP32_CAM.c`
- [Camera UDP](https://github.com/loorays/looraysbot/blob/main/looraysBotMcu/camera_esp32/components/UDP_CAM/UDP_CAM.c): `looraysBotMcu/camera_esp32/components/UDP_CAM/UDP_CAM.c`

### Other components

- **Robot operator**

## Connections

- Base firmware → Chassis sensors: initializes (evidence: `looraysBotMcu/base_esp32s3/main/main.c`)
- Base firmware → PID motor control: initializes (evidence: `looraysBotMcu/base_esp32s3/main/main.c`)
- Base firmware → Lidar forwarding: starts tasks (evidence: `looraysBotMcu/base_esp32s3/main/main.c`)
- Base firmware → Status UDP: starts tasks (evidence: `looraysBotMcu/base_esp32s3/main/main.c`)
- Base firmware → WebSocket telemetry: starts service (evidence: `looraysBotMcu/base_esp32s3/main/main.c`)
- WebSocket telemetry → PID motor control: sets velocity (evidence: `looraysBotMcu/base_esp32s3/components/WEBSOCKET_CLIENT/WEBSOCKET_CLIENT.c`)
- WebSocket telemetry → Robot operator: sends telemetry
- Camera capture → Camera UDP: sends frames (evidence: `looraysBotMcu/camera_esp32/components/ESP32_CAM/ESP32_CAM.c`)
- Robot operator → Mobile controls: controls robot
- Robot operator → Desktop dashboard: monitors robot
- Base firmware → UDP communications: UDP telemetry
- Lidar forwarding → Lidar driver: forwards scans
- UDP communications → IMU filter: publishes sensor data
- IMU filter → State estimation: provides filtered IMU
- Lidar driver → SLAM and navigation: provides lidar data
- State estimation → SLAM and navigation: supports navigation
- Camera UDP → Vision and gestures: provides images
- ROS launch setup → SLAM and navigation: launches navigation
- ROS1 compatibility → Robot operator: supports ROS1 operation
- Desktop dashboard → Embedded RViz: embeds visualization