# reidlo5135/ros-vehicle-control architecture

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

- Interactive diagram: https://gitdiagram.com/reidlo5135/ros-vehicle-control
- Repository: https://github.com/reidlo5135/ros-vehicle-control

## Overview

#### Purpose and Runtime

This is a ROS 2 Humble C++ workspace for vehicle control. It turns ROS control inputs into vehicle commands, exchanges those commands and vehicle telemetry through SocketCAN, then validates/corrects runtime vehicle state. Target deployment is Ubuntu 22.04 with a SocketCAN-capable vehicle or simulator; `map_handle_msgs` and `robot_status_msgs` are external message dependencies.

#### Process Entry Points and Deployment

Each major capability is an independently built ROS 2 package with a node executable, launch file, and YAML parameters:
- CAN bridge: `can_manager/src/main.cpp`, `can_manager/launch/can_manager.launch.py`, `can_manager/config/can_manager.yaml`
- Motion control: `motion_controller/src/main.cpp`, `motion_controller/launch/motion_controller.launch.py`, `motion_controller/config/motion_controller.yaml`
- Validation: `motion_validation/src/main.cpp`, `motion_validation/launch/motion_validation.launch.py`, `motion_validation/config/motion_validation.yaml`

Presentation-layer node classes own ROS-facing subscriptions, publishers, parameters, and callback orchestration.

#### Motion Controller: Input to Vehicle Intent

`motion_controller` is the upstream command-processing stage. Its presentation node receives ROS control inputs and delegates to application services:
- Command/control logic: `motion_controller/src/application/control.cpp`
- Input/unit/message conversion: `motion_controller/src/application/converter.cpp`
- Motion behavior/orchestration: `motion_controller/src/application/motion.cpp`

Vehicle state and tunable vehicle parameters are isolated in the domain layer at `motion_controller/include/domain/vehicle.hpp` and `motion_controller/include/domain/parameter.hpp`. The boundary is ROS topics at the node layer versus vehicle-oriented control commands produced by application/domain code.

#### CAN Manager: ROS–Bus Boundary

`can_manager` is the hardware/protocol boundary between ROS messages and CAN frames. It explicitly supports both directions:
- CAN-to-ROS translation: `can_manager/src/application/c2r.cpp`
- ROS-to-CAN translation: `can_manager/src/application/r2c.cpp`
- ROS node integration: `can_manager/src/presentation/node.cpp`

Its domain vehicle model and parameters (`can_manager/include/domain/vehicle.hpp`, `can_manager/include/domain/parameter.hpp`) centralize vehicle-specific interpretation rather than exposing raw CAN semantics throughout the workspace. CAN channel and topic configuration belongs in `can_manager/config/can_manager.yaml`.

#### Shared CAN Transport and Utilities

`can_utils` is a reusable native library beneath the CAN manager rather than a ROS node. It contains the SocketCAN-facing adapter and common frame operations:
- Transport adaptation: `can_utils/include/can_utils/adaptor.hpp`, `can_utils/src/adaptor.cpp`
- Sending: `can_utils/include/can_utils/send.hpp`, `can_utils/src/send.cpp`
- Frame dumping/diagnostics: `can_utils/include/can_utils/dump.hpp`, `can_utils/src/dump.cpp`

This package forms the important infrastructure boundary between application-level frame conversion and the underlying CAN interface.

#### Motion Validation: State Assurance Feedback Stage

`motion_validation` consumes runtime vehicle state and applies validation, filtering, and correction before publishing trusted state back into ROS:
- Validation rules: `motion_validation/src/application/vertification.cpp`
- State correction: `motion_validation/src/application/correction.cpp`
- Kalman-based filtering: `motion_validation/src/application/kalman.cpp`

ROS integration is concentrated in `motion_validation/src/presentation/node.cpp`; its parameters are represented by `motion_validation/include/domain/parameter.hpp`. This stage is downstream of CAN-derived runtime data and can provide corrected state for controllers or other vehicle-platform consumers.

#### End-to-End Control Flow

Primary command path: ROS control topics → `motion_controller` conversion/control/motion logic → vehicle command topics → `can_manager` ROS-to-CAN conversion → `can_utils`/SocketCAN → vehicle bus.

Primary feedback path: vehicle CAN frames → `can_utils` → `can_manager` CAN-to-ROS conversion → runtime vehicle-state topics → `motion_validation` verification/Kalman/correction → validated ROS state topics. Vehicle-specific mappings and parameters are package-local, allowing the ROS interfaces, motion policy, and physical CAN transport to evolve at separate boundaries.

Main entry points: [`can_manager/src/presentation/node.cpp`](https://github.com/reidlo5135/ros-vehicle-control/blob/humble/release/2.1.0/can_manager/src/presentation/node.cpp) (CAN ROS node), [`motion_validation/src/presentation/node.cpp`](https://github.com/reidlo5135/ros-vehicle-control/blob/humble/release/2.1.0/motion_validation/src/presentation/node.cpp) (Validation node), [`can_utils/src/adaptor.cpp`](https://github.com/reidlo5135/ros-vehicle-control/blob/humble/release/2.1.0/can_utils/src/adaptor.cpp) (SocketCAN adapter), [`can_manager/src/application/c2r.cpp`](https://github.com/reidlo5135/ros-vehicle-control/blob/humble/release/2.1.0/can_manager/src/application/c2r.cpp) (CAN-to-ROS)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_motion_controller["Motion Controller"]
  node_motion_node["Motion node<br/>ROS node<br/>[main.cpp]"]
  node_motion_app["Control and motion logic<br/>[control.cpp]"]
  node_motion_converter["Input converter<br/>[converter.cpp]"]
  node_motion_domain["Vehicle model<br/>domain<br/>[vehicle.hpp]"]
end

subgraph group_can_manager["CAN Manager"]
  node_can_node["CAN ROS node<br/>[node.cpp]"]
  node_ros_to_can["ROS-to-CAN<br/>[r2c.cpp]"]
  node_can_to_ros["CAN-to-ROS<br/>[c2r.cpp]"]
  node_can_domain["CAN vehicle model<br/>domain<br/>[vehicle.hpp]"]
end

subgraph group_motion_validation["Motion Validation"]
  node_validation_node["Validation node<br/>ROS node<br/>[node.cpp]"]
  node_validation_rules["Validation rules<br/>[vertification.cpp]"]
  node_kalman_filter["Kalman filter<br/>[kalman.cpp]"]
  node_state_correction["State correction<br/>[correction.cpp]"]
end

subgraph group_can_utils["CAN Utilities"]
  node_can_transport["SocketCAN adapter<br/>native transport<br/>[adaptor.cpp]"]
end

node_ros_control(("ROS control topics<br/>ROS topics"))
node_vehicle_commands(("Vehicle command topics<br/>ROS topics"))
node_vehicle_bus{{"Vehicle CAN bus<br/>SocketCAN"}}
node_runtime_state(("Runtime state topics<br/>ROS topics"))
node_validated_state(("Validated state topics<br/>ROS topics"))

node_ros_control -->|"control input"| node_motion_node
node_motion_node --> node_motion_converter
node_motion_converter -->|"normalized input"| node_motion_app
node_motion_domain -.->|"vehicle state and tuning"| node_motion_app
node_motion_app -->|"vehicle commands"| node_vehicle_commands
node_vehicle_commands --> node_can_node
node_can_node --> node_ros_to_can
node_ros_to_can -->|"vehicle mapping"| node_can_domain
node_can_domain -->|"CAN frames"| node_can_transport
node_can_transport -->|"send frames"| node_vehicle_bus
node_vehicle_bus -->|"receive frames"| node_can_transport
node_can_transport -->|"CAN frames"| node_can_to_ros
node_can_to_ros -->|"vehicle mapping"| node_can_domain
node_can_to_ros -->|"ROS state"| node_can_node
node_can_node -->|"publish"| node_runtime_state
node_runtime_state --> node_validation_node
node_validation_node --> node_validation_rules
node_validation_rules -->|"accepted state"| node_kalman_filter
node_kalman_filter -->|"filtered state"| node_state_correction
node_state_correction -->|"trusted state"| node_validation_node
node_validation_node -->|"publish"| node_validated_state

click node_motion_node "https://github.com/reidlo5135/ros-vehicle-control/blob/humble/release/2.1.0/motion_controller/src/main.cpp"
click node_motion_app "https://github.com/reidlo5135/ros-vehicle-control/blob/humble/release/2.1.0/motion_controller/src/application/control.cpp"
click node_motion_converter "https://github.com/reidlo5135/ros-vehicle-control/blob/humble/release/2.1.0/motion_controller/src/application/converter.cpp"
click node_motion_domain "https://github.com/reidlo5135/ros-vehicle-control/blob/humble/release/2.1.0/motion_controller/include/domain/vehicle.hpp"
click node_can_node "https://github.com/reidlo5135/ros-vehicle-control/blob/humble/release/2.1.0/can_manager/src/presentation/node.cpp"
click node_ros_to_can "https://github.com/reidlo5135/ros-vehicle-control/blob/humble/release/2.1.0/can_manager/src/application/r2c.cpp"
click node_can_to_ros "https://github.com/reidlo5135/ros-vehicle-control/blob/humble/release/2.1.0/can_manager/src/application/c2r.cpp"
click node_can_domain "https://github.com/reidlo5135/ros-vehicle-control/blob/humble/release/2.1.0/can_manager/include/domain/vehicle.hpp"
click node_can_transport "https://github.com/reidlo5135/ros-vehicle-control/blob/humble/release/2.1.0/can_utils/src/adaptor.cpp"
click node_validation_node "https://github.com/reidlo5135/ros-vehicle-control/blob/humble/release/2.1.0/motion_validation/src/presentation/node.cpp"
click node_validation_rules "https://github.com/reidlo5135/ros-vehicle-control/blob/humble/release/2.1.0/motion_validation/src/application/vertification.cpp"
click node_kalman_filter "https://github.com/reidlo5135/ros-vehicle-control/blob/humble/release/2.1.0/motion_validation/src/application/kalman.cpp"
click node_state_correction "https://github.com/reidlo5135/ros-vehicle-control/blob/humble/release/2.1.0/motion_validation/src/application/correction.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_motion_node,node_motion_app,node_motion_converter,node_motion_domain toneBlue
class node_can_node,node_ros_to_can,node_can_to_ros,node_can_domain toneAmber
class node_validation_node,node_validation_rules,node_kalman_filter,node_state_correction toneMint
class node_can_transport toneRose
class node_ros_control,node_vehicle_commands,node_vehicle_bus,node_runtime_state,node_validated_state toneNeutral
```

## Components

### Motion Controller

Converts ROS control inputs into vehicle command intent.

- [Motion node](https://github.com/reidlo5135/ros-vehicle-control/blob/humble/release/2.1.0/motion_controller/src/main.cpp): ROS node · Owns subscriptions, publishers, parameters, and callback orchestration. · `motion_controller/src/main.cpp`
- [Control and motion logic](https://github.com/reidlo5135/ros-vehicle-control/blob/humble/release/2.1.0/motion_controller/src/application/control.cpp): application · Converts inputs and produces vehicle-oriented commands. · `motion_controller/src/application/control.cpp`
- [Input converter](https://github.com/reidlo5135/ros-vehicle-control/blob/humble/release/2.1.0/motion_controller/src/application/converter.cpp): application · `motion_controller/src/application/converter.cpp`
- [Vehicle model](https://github.com/reidlo5135/ros-vehicle-control/blob/humble/release/2.1.0/motion_controller/include/domain/vehicle.hpp): domain · Vehicle state and tunable parameters. · `motion_controller/include/domain/vehicle.hpp`

### CAN Manager

Bridges ROS vehicle messages and CAN frames.

- [CAN ROS node](https://github.com/reidlo5135/ros-vehicle-control/blob/humble/release/2.1.0/can_manager/src/presentation/node.cpp): ROS node · ROS-facing integration for bidirectional frame translation. · `can_manager/src/presentation/node.cpp`
- [ROS-to-CAN](https://github.com/reidlo5135/ros-vehicle-control/blob/humble/release/2.1.0/can_manager/src/application/r2c.cpp): application · `can_manager/src/application/r2c.cpp`
- [CAN-to-ROS](https://github.com/reidlo5135/ros-vehicle-control/blob/humble/release/2.1.0/can_manager/src/application/c2r.cpp): application · `can_manager/src/application/c2r.cpp`
- [CAN vehicle model](https://github.com/reidlo5135/ros-vehicle-control/blob/humble/release/2.1.0/can_manager/include/domain/vehicle.hpp): domain · Centralizes vehicle-specific frame interpretation and parameters. · `can_manager/include/domain/vehicle.hpp`

### Motion Validation

Validates and corrects runtime vehicle state.

- [Validation node](https://github.com/reidlo5135/ros-vehicle-control/blob/humble/release/2.1.0/motion_validation/src/presentation/node.cpp): ROS node · Owns ROS state subscriptions, publishing, and callbacks. · `motion_validation/src/presentation/node.cpp`
- [Validation rules](https://github.com/reidlo5135/ros-vehicle-control/blob/humble/release/2.1.0/motion_validation/src/application/vertification.cpp): application · `motion_validation/src/application/vertification.cpp`
- [Kalman filter](https://github.com/reidlo5135/ros-vehicle-control/blob/humble/release/2.1.0/motion_validation/src/application/kalman.cpp): application · Filters runtime vehicle state. · `motion_validation/src/application/kalman.cpp`
- [State correction](https://github.com/reidlo5135/ros-vehicle-control/blob/humble/release/2.1.0/motion_validation/src/application/correction.cpp): application · `motion_validation/src/application/correction.cpp`

### CAN Utilities

Reusable SocketCAN transport library.

- [SocketCAN adapter](https://github.com/reidlo5135/ros-vehicle-control/blob/humble/release/2.1.0/can_utils/src/adaptor.cpp): native transport · Adapts frame I/O to the SocketCAN interface. · `can_utils/src/adaptor.cpp`

### Other components

- **ROS control topics**: ROS topics
- **Vehicle command topics**: ROS topics
- **Vehicle CAN bus**: SocketCAN · Physical vehicle bus or simulator interface.
- **Runtime state topics**: ROS topics
- **Validated state topics**: ROS topics · Trusted state for controllers and vehicle-platform consumers.

## Connections

- ROS control topics → Motion node: control input
- Motion node → Input converter
- Input converter → Control and motion logic: normalized input
- Vehicle model → Control and motion logic: vehicle state and tuning
- Control and motion logic → Vehicle command topics: vehicle commands
- Vehicle command topics → CAN ROS node
- CAN ROS node → ROS-to-CAN
- ROS-to-CAN → CAN vehicle model: vehicle mapping
- CAN vehicle model → SocketCAN adapter: CAN frames
- SocketCAN adapter → Vehicle CAN bus: send frames
- Vehicle CAN bus → SocketCAN adapter: receive frames
- SocketCAN adapter → CAN-to-ROS: CAN frames
- CAN-to-ROS → CAN vehicle model: vehicle mapping
- CAN-to-ROS → CAN ROS node: ROS state
- CAN ROS node → Runtime state topics: publish
- Runtime state topics → Validation node
- Validation node → Validation rules
- Validation rules → Kalman filter: accepted state
- Kalman filter → State correction: filtered state
- State correction → Validation node: trusted state
- Validation node → Validated state topics: publish