# ardev1161/rc_agent architecture

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

- Interactive diagram: https://gitdiagram.com/ardev1161/rc_agent
- Repository: https://github.com/ardev1161/rc_agent

## Overview

#### Purpose and entry points
`rc_agent` is a ROS 2 C++ robot-side agent that bridges remote gRPC control/telemetry with ROS topics and Nav2 actions. The executable starts from `main.cpp`; ROS launch integration is provided by `launch/rc_agent.launch.py`. Build/package boundaries are defined by `CMakeLists.txt` and `package.xml`.

#### Process composition and orchestration
The application appears to assemble subsystem controllers around a ROS 2 runtime: networking, robot controls, telemetry adapters, navigation, and system operations. `network/networkcontroller.cpp` is the likely coordination boundary between transport and robot-facing modules, while `system/system.cpp` and `config/configprocessor.cpp` provide host/system and configuration concerns.

#### Remote-control transport boundary
gRPC is the external API boundary for a control station. Protocol schemas define control inputs and sensor/map/navigation responses in `network/protobuf/robot.proto`, with domain contracts split into `network/protobuf/base.proto`, `network/protobuf/navigation.proto`, `network/protobuf/power.proto`, and related schemas. `network/server.cpp` implements robot-side serving; `network/client.cpp` supports outbound client behavior. Generated protobuf/gRPC build integration resides in `network/protobuf/CMakeLists.txt`.

Control flow is remote `Controls` RPC payloads → network controller/server → ROS-facing handlers; telemetry flows in the reverse direction and is serialized as protobuf `Sensors` or map data.

#### ROS base-control and feedback adapter
The base-control module translates remote velocity commands into robot motion and monitors odometry for return telemetry. Its primary boundary is `modules/basecontrol/basecontrol.cpp`, with its interface in `modules/basecontrol/basecontrol.h`. This is the actuator-facing ROS integration point for linear/angular movement, isolating gRPC message semantics from ROS publishers/subscribers.

#### Battery and map telemetry pipelines
Battery state is consumed from ROS battery topics, adapted, and exposed to the network/protobuf layer through `modules/battery/battery_state_node.cpp`, `modules/battery/battery_state_handler.cpp`, and `modules/battery/battery_state_adapter.h`. Map handling similarly receives ROS map data and converts it for remote retrieval in `modules/map/map_node.cpp` and `modules/map/map_node.h`.

There is a parallel `topics/battery/` implementation (`topics/battery/battery_state_node.cpp`), suggesting a second or legacy topic-oriented boundary that should be reconciled when modifying battery ownership.

#### Nav2 command execution
Remote navigation requests are represented internally and dispatched through Nav2 action clients. `modules/nav2/nav_command.cpp` models commands; `modules/nav2/robot_navigator.cpp` owns navigation execution; and `modules/nav2/robot_navigator_handler.cpp` bridges command handling/status reporting. Conversion isolation is explicit in `modules/nav2/robot_navigator_conversions.h`. This stage handles goals such as pose navigation, waypoints, and spinning, returning status to the gRPC sensor/control exchange.

#### Discovery and host operations
LAN control-station discovery uses ARP functionality in `network/arper.cpp` and `network/arper.h`, separate from gRPC transport. Host-level operations such as shell/system commands and system information are bounded in `system/shell.cpp`, `system/system.cpp`, and `system/systeminfo.cpp`; these likely support remote halt/restart and uptime-style controls.

#### Runtime and infrastructure
The material runtime is Linux with ROS 2 (Humble+ recommended), C++17, CMake/colcon, `rclcpp`, Nav2, and gRPC/protobuf. ROS topic/action interfaces connect to robot hardware, sensors, battery publishers, mapping, and Nav2; gRPC and ARP connect the robot to a LAN-based remote control station. Runtime camera configuration is present in `params/gscam2.yaml` and `params/gst_pipeline.yaml`.

Main entry points: [`network/networkcontroller.cpp`](https://github.com/ardev1161/rc_agent/blob/master/network/networkcontroller.cpp) (Network controller), [`modules/nav2/robot_navigator_handler.cpp`](https://github.com/ardev1161/rc_agent/blob/master/modules/nav2/robot_navigator_handler.cpp) (Navigation handler), [`main.cpp`](https://github.com/ardev1161/rc_agent/blob/master/main.cpp) (rc_agent executable), [`system/system.cpp`](https://github.com/ardev1161/rc_agent/blob/master/system/system.cpp) (System operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_transport["Remote transport"]
  node_network_controller["Network controller<br/>orchestrator"]
  node_grpc_server["gRPC server<br/>[server.cpp]"]
  node_grpc_client["gRPC client<br/>[client.cpp]"]
  node_protocol["Control protocol<br/>protobuf contracts<br/>[robot.proto]"]
  node_proto_build["Protobuf build<br/>CMake integration<br/>[CMakeLists.txt]"]
  node_arp_discovery["ARP discovery<br/>LAN discovery<br/>[arper.cpp]"]
end

subgraph group_ros["ROS robot adapters"]
  node_base_control["Base control<br/>ROS motion adapter<br/>[basecontrol.cpp]"]
  node_battery_pipeline["Battery telemetry<br/>ROS telemetry adapter"]
  node_battery_topic["Battery state node<br/>ROS subscriber"]
  node_map_pipeline["Map telemetry<br/>ROS map adapter<br/>[map_node.cpp]"]
  node_nav_handler["Navigation handler<br/>command bridge"]
  node_nav_command["Navigation commands<br/>command model<br/>[nav_command.cpp]"]
  node_navigator["Nav2 navigator<br/>action client"]
  node_ros_runtime(("ROS 2 topics &amp; actions<br/>robot runtime"))
end

subgraph group_host["Host operations"]
  node_config["Configuration processor"]
  node_system["System operations<br/>host controller<br/>[system.cpp]"]
  node_shell["Shell commands<br/>host command executor<br/>[shell.cpp]"]
end

node_entry{{"rc_agent executable<br/>C++ entry point<br/>[main.cpp]"}}
node_launch["ROS launch<br/>launch entry<br/>[rc_agent.launch.py]"]

node_launch -->|"starts"| node_entry
node_entry -->|"initializes"| node_network_controller
node_entry -->|"loads"| node_config
node_entry -->|"initializes"| node_system
node_network_controller -->|"serves through"| node_grpc_server
node_network_controller -->|"uses"| node_grpc_client
node_grpc_server -->|"implements"| node_protocol
node_grpc_client -->|"uses"| node_protocol
node_proto_build -->|"generates"| node_protocol
node_arp_discovery -->|"discovers peers for"| node_network_controller
node_network_controller -->|"control commands"| node_base_control
node_base_control -->|"velocity and odometry"| node_ros_runtime
node_ros_runtime -->|"battery topic"| node_battery_topic
node_battery_topic -->|"state"| node_battery_pipeline
node_battery_pipeline -->|"Sensors telemetry"| node_network_controller
node_ros_runtime -->|"map data"| node_map_pipeline
node_map_pipeline -->|"map telemetry"| node_network_controller
node_network_controller -->|"navigation requests"| node_nav_handler
node_nav_handler -->|"creates"| node_nav_command
node_nav_handler -->|"dispatches"| node_navigator
node_navigator -->|"Nav2 actions"| node_ros_runtime
node_nav_handler -->|"goal status"| node_network_controller
node_system -->|"executes"| node_shell
node_network_controller -->|"host operations"| node_system

click node_entry "https://github.com/ardev1161/rc_agent/blob/master/main.cpp"
click node_network_controller "https://github.com/ardev1161/rc_agent/blob/master/network/networkcontroller.cpp"
click node_grpc_server "https://github.com/ardev1161/rc_agent/blob/master/network/server.cpp"
click node_grpc_client "https://github.com/ardev1161/rc_agent/blob/master/network/client.cpp"
click node_protocol "https://github.com/ardev1161/rc_agent/blob/master/network/protobuf/robot.proto"
click node_proto_build "https://github.com/ardev1161/rc_agent/blob/master/network/protobuf/CMakeLists.txt"
click node_arp_discovery "https://github.com/ardev1161/rc_agent/blob/master/network/arper.cpp"
click node_base_control "https://github.com/ardev1161/rc_agent/blob/master/modules/basecontrol/basecontrol.cpp"
click node_battery_pipeline "https://github.com/ardev1161/rc_agent/blob/master/modules/battery/battery_state_handler.cpp"
click node_battery_topic "https://github.com/ardev1161/rc_agent/blob/master/modules/battery/battery_state_node.cpp"
click node_map_pipeline "https://github.com/ardev1161/rc_agent/blob/master/modules/map/map_node.cpp"
click node_nav_handler "https://github.com/ardev1161/rc_agent/blob/master/modules/nav2/robot_navigator_handler.cpp"
click node_nav_command "https://github.com/ardev1161/rc_agent/blob/master/modules/nav2/nav_command.cpp"
click node_navigator "https://github.com/ardev1161/rc_agent/blob/master/modules/nav2/robot_navigator.cpp"
click node_config "https://github.com/ardev1161/rc_agent/blob/master/config/configprocessor.cpp"
click node_system "https://github.com/ardev1161/rc_agent/blob/master/system/system.cpp"
click node_shell "https://github.com/ardev1161/rc_agent/blob/master/system/shell.cpp"
click node_launch "https://github.com/ardev1161/rc_agent/blob/master/launch/rc_agent.launch.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_network_controller,node_grpc_server,node_grpc_client,node_protocol,node_proto_build,node_arp_discovery toneBlue
class node_base_control,node_battery_pipeline,node_battery_topic,node_map_pipeline,node_nav_handler,node_nav_command,node_navigator,node_ros_runtime toneAmber
class node_config,node_system,node_shell toneMint
class node_entry,node_launch toneNeutral
```

## Components

### Remote transport

LAN-facing control and telemetry boundary.

- [Network controller](https://github.com/ardev1161/rc_agent/blob/master/network/networkcontroller.cpp): orchestrator · Coordinates transport with robot-facing controllers. · `network/networkcontroller.cpp`
- [gRPC server](https://github.com/ardev1161/rc_agent/blob/master/network/server.cpp): RPC server · Serves remote control and telemetry requests. · `network/server.cpp`
- [gRPC client](https://github.com/ardev1161/rc_agent/blob/master/network/client.cpp): RPC client · Supports outbound remote communication. · `network/client.cpp`
- [Control protocol](https://github.com/ardev1161/rc_agent/blob/master/network/protobuf/robot.proto): protobuf contracts · Defines Controls, Sensors, map, navigation, and power messages. · `network/protobuf/robot.proto`
- [Protobuf build](https://github.com/ardev1161/rc_agent/blob/master/network/protobuf/CMakeLists.txt): CMake integration · `network/protobuf/CMakeLists.txt`
- [ARP discovery](https://github.com/ardev1161/rc_agent/blob/master/network/arper.cpp): LAN discovery · Finds control stations on the local network. · `network/arper.cpp`

### ROS robot adapters

ROS topics and Nav2 action integration.

- [Base control](https://github.com/ardev1161/rc_agent/blob/master/modules/basecontrol/basecontrol.cpp): ROS motion adapter · Converts remote velocity commands and odometry feedback. · `modules/basecontrol/basecontrol.cpp`
- [Battery telemetry](https://github.com/ardev1161/rc_agent/blob/master/modules/battery/battery_state_handler.cpp): ROS telemetry adapter · Adapts ROS battery state for protobuf telemetry. · `modules/battery/battery_state_handler.cpp`
- [Battery state node](https://github.com/ardev1161/rc_agent/blob/master/modules/battery/battery_state_node.cpp): ROS subscriber · `modules/battery/battery_state_node.cpp`
- [Map telemetry](https://github.com/ardev1161/rc_agent/blob/master/modules/map/map_node.cpp): ROS map adapter · Converts ROS map data for remote retrieval. · `modules/map/map_node.cpp`
- [Navigation handler](https://github.com/ardev1161/rc_agent/blob/master/modules/nav2/robot_navigator_handler.cpp): command bridge · Bridges remote navigation commands and status. · `modules/nav2/robot_navigator_handler.cpp`
- [Navigation commands](https://github.com/ardev1161/rc_agent/blob/master/modules/nav2/nav_command.cpp): command model · Represents pose, waypoint, and spin requests. · `modules/nav2/nav_command.cpp`
- [Nav2 navigator](https://github.com/ardev1161/rc_agent/blob/master/modules/nav2/robot_navigator.cpp): action client · Executes navigation goals through Nav2. · `modules/nav2/robot_navigator.cpp`
- **ROS 2 topics & actions**: robot runtime · Connects hardware, sensors, mapping, and Nav2.

### Host operations

Robot host configuration and system controls.

- [Configuration processor](https://github.com/ardev1161/rc_agent/blob/master/config/configprocessor.cpp): configuration · `config/configprocessor.cpp`
- [System operations](https://github.com/ardev1161/rc_agent/blob/master/system/system.cpp): host controller · Provides remote host and system-information operations. · `system/system.cpp`
- [Shell commands](https://github.com/ardev1161/rc_agent/blob/master/system/shell.cpp): host command executor · `system/shell.cpp`

### Other components

- [rc_agent executable](https://github.com/ardev1161/rc_agent/blob/master/main.cpp): C++ entry point · Initializes the ROS 2 robot-side agent. · `main.cpp`
- [ROS launch](https://github.com/ardev1161/rc_agent/blob/master/launch/rc_agent.launch.py): launch entry · Launches the agent in a ROS deployment. · `launch/rc_agent.launch.py`

## Connections

- ROS launch → rc_agent executable: starts
- rc_agent executable → Network controller: initializes
- rc_agent executable → Configuration processor: loads
- rc_agent executable → System operations: initializes
- Network controller → gRPC server: serves through
- Network controller → gRPC client: uses
- gRPC server → Control protocol: implements
- gRPC client → Control protocol: uses
- Protobuf build → Control protocol: generates
- ARP discovery → Network controller: discovers peers for
- Network controller → Base control: control commands
- Base control → ROS 2 topics & actions: velocity and odometry
- ROS 2 topics & actions → Battery state node: battery topic
- Battery state node → Battery telemetry: state
- Battery telemetry → Network controller: Sensors telemetry
- ROS 2 topics & actions → Map telemetry: map data
- Map telemetry → Network controller: map telemetry
- Network controller → Navigation handler: navigation requests
- Navigation handler → Navigation commands: creates
- Navigation handler → Nav2 navigator: dispatches
- Nav2 navigator → ROS 2 topics & actions: Nav2 actions
- Navigation handler → Network controller: goal status
- System operations → Shell commands: executes
- Network controller → System operations: host operations