# tue-audri/prius_interface architecture

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

- Interactive diagram: https://gitdiagram.com/tue-audri/prius_interface
- Repository: https://github.com/tue-audri/prius_interface

## Overview

This repository is a ROS 2 interface stack for bringing Toyota Prius CAN data into the Autoware ecosystem, with an additional ZeroMQ-to-ROS bridge package.

At a high level, the repo has three architectural parts:

1. `panda_can_rcv` — CAN ingestion and decoding
2. `panda_msgs` — shared ROS message definitions
3. `autoware_zmq_ros_bridge` — ZeroMQ-to-ROS bridge for Autoware-facing data exchange

Main system boundary and data flow

- Vehicle CAN bus data enters the system through `panda_can_rcv`.
- Raw CAN frames are decoded using Toyota DBC files in `panda_can_rcv/config`.
- The decoded data is converted into ROS messages defined in `panda_msgs`.
- Those messages are published into the ROS 2 graph for downstream Autoware components.
- In parallel, `autoware_zmq_ros_bridge` provides a bridge from an external ZeroMQ transport into ROS 2, suggesting a second ingress/egress path for Autoware-related data.

Subsystem details

1. `panda_can_rcv`
This is the main functional package for receiving CAN data.

Key files:
- `panda_can_rcv/can_interface.py` — lower-level CAN access boundary
- `panda_can_rcv/can_listener_node.py` — ROS 2 node that likely owns the runtime loop and publishing
- `panda_can_rcv/message_relay.py` — conversion/relay layer between decoded CAN signals and ROS messages
- `config/panda_params.yaml` — runtime parameters
- `config/toyota_filtered.dbc`
- `config/toyota_tnga_k_pt_generated.dbc`

Architecture role:
- Acts as the hardware-facing adapter.
- Separates raw CAN reception from ROS publishing.
- Uses DBC files as the signal decoding layer, which is important because it means the node is not just forwarding frames; it is translating vehicle-specific bus messages into semantic signals.

Likely data path inside the package:
- CAN hardware/bus -> `can_interface.py`
- Raw frame handling -> `can_listener_node.py`
- Signal interpretation via DBC definitions
- ROS publication via `message_relay.py`

Launch/runtime:
- `launch/can_listener.launch.py` starts the listener node with parameters from YAML.

2. `panda_msgs`
This package contains the shared message contract used by the runtime nodes.

Contents:
- `msg/CANMessage.msg`
- `msg/PandaHealthStatus.msg`

Architecture role:
- Defines the data schema boundary between producers and consumers.
- Keeps message definitions separate from node logic, so both CAN ingestion and any downstream Autoware consumers can depend on a stable interface.
- This is a classic ROS package boundary: behavior lives in Python nodes, data contracts live in a dedicated message package.

Build system:
- Uses ROS 2 CMake-style packaging, unlike the Python node packages.

3. `autoware_zmq_ros_bridge`
This package is a second transport adapter.

Key files:
- `autoware_zmq_ros_bridge/autoware_zmq_listener_node.py`
- `config/autoware_zmq_params.yaml`
- `launch/autoware_zmq_bridge.launch.py`

Architecture role:
- Bridges ZeroMQ-based communication into the ROS 2 graph.
- The node name suggests it is a listener, so it likely receives messages on a ZMQ socket and republishes or translates them into ROS topics.
- This introduces a transport boundary separate from CAN: ZeroMQ on one side, ROS 2 on the other.

Why it matters architecturally:
- It implies the system is not limited to direct vehicle bus integration.
- It provides a decoupled integration path for external Autoware-related producers/consumers that use ZMQ instead of native ROS topics.

Important boundaries in the repo

- Hardware boundary: CAN bus / vehicle interface in `panda_can_rcv`
- Transport boundary: ZeroMQ in `autoware_zmq_ros_bridge`
- Schema boundary: ROS message types in `panda_msgs`
- Configuration boundary: YAML parameter files and DBC files under each package’s `config/`
- Runtime orchestration boundary: ROS 2 launch files under each package’s `launch/`

Technology and runtime implications

- The repo is ROS 2-based.
- The node packages are Python packages (`setup.py`, `setup.cfg`, `package.xml`), so the runtime logic is implemented in Python nodes.
- `panda_msgs` is a ROS message package built separately from the Python nodes.
- The Toyota DBC files are a key external artifact because they define how raw CAN frames are semantically decoded.
- The launch files indicate the system is designed to be started as ROS 2 nodes with parameter injection, not as standalone scripts.

Repository structure as an architecture diagram

If you were drawing this system, the central elements would be:

- On one side, the Toyota Prius CAN bus feeding `panda_can_rcv`
- In the middle, `panda_msgs` as the shared ROS contract
- On another side, `autoware_zmq_ros_bridge` connecting a ZeroMQ endpoint to the ROS 2 graph
- Downstream, Autoware Universe components consuming the published ROS topics and messages

In short: this repo is an integration layer for vehicle signals and Autoware, with CAN decoding as the core function, ROS messages as the internal interface, and a ZeroMQ bridge as an additional transport adapter.

Main entry points: [`panda_can_rcv/panda_can_rcv/can_listener_node.py`](https://github.com/tue-audri/prius_interface/blob/HEAD/panda_can_rcv/panda_can_rcv/can_listener_node.py) (Listener Node), [`panda_can_rcv/panda_can_rcv/message_relay.py`](https://github.com/tue-audri/prius_interface/blob/HEAD/panda_can_rcv/panda_can_rcv/message_relay.py) (Message Relay), [`panda_msgs/msg/CANMessage.msg`](https://github.com/tue-audri/prius_interface/blob/HEAD/panda_msgs/msg/CANMessage.msg) (CAN Message), [`panda_msgs/msg/PandaHealthStatus.msg`](https://github.com/tue-audri/prius_interface/blob/HEAD/panda_msgs/msg/PandaHealthStatus.msg) (Health Status)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "CAN Ingestion"
  node_can_bus(("CAN Bus<br/>vehicle transport"))
  node_can_interface["CAN Interface<br/>python adapter<br/>[can_interface.py]"]
  node_can_listener["Listener Node<br/>ros2 node"]
  node_message_relay["Message Relay<br/>translation layer<br/>[message_relay.py]"]
  node_panda_params["CAN Params<br/>runtime config<br/>[panda_params.yaml]"]
  node_toyota_dbc1["Toyota DBC<br/>signal db"]
  node_toyota_dbc2["Toyota Gen DBC<br/>signal db"]
  node_can_launch["CAN Launch<br/>launch file"]
end

subgraph "ROS Messages"
  node_can_message["CAN Message<br/>ros msg<br/>[CANMessage.msg]"]
  node_health_message["Health Status<br/>ros msg"]
  node_msgs_pkg[("panda_msgs<br/>ros package")]
end

subgraph "ZeroMQ Bridge"
  node_zmq_listener["ZMQ Listener<br/>ros2 node"]
  node_zmq_params["ZMQ Params<br/>runtime config"]
  node_zmq_launch["Bridge Launch<br/>launch file"]
  node_zmq_endpoint(("ZMQ Endpoint<br/>transport endpoint"))
end

node_ros_graph(("ROS 2 Graph<br/>middleware"))

node_can_bus -->|"frames"| node_can_interface
node_can_interface -->|"raw data"| node_can_listener
node_can_listener -->|"decode"| node_toyota_dbc1
node_can_listener -->|"decode"| node_toyota_dbc2
node_can_listener -->|"relay"| node_message_relay
node_message_relay -->|"publishes"| node_can_message
node_message_relay -->|"publishes"| node_health_message
node_can_launch -->|"starts"| node_can_listener
node_can_launch -->|"loads"| node_panda_params
node_can_listener -->|"publishes"| node_ros_graph
node_can_message -->|"consumed by"| node_ros_graph
node_health_message -->|"consumed by"| node_ros_graph
node_zmq_endpoint -->|"messages"| node_zmq_listener
node_zmq_launch -->|"starts"| node_zmq_listener
node_zmq_launch -->|"loads"| node_zmq_params
node_zmq_listener -->|"publishes"| node_ros_graph
node_msgs_pkg -->|"defines"| node_can_message
node_msgs_pkg -->|"defines"| node_health_message

click node_can_interface "https://github.com/tue-audri/prius_interface/blob/main/panda_can_rcv/panda_can_rcv/can_interface.py"
click node_can_listener "https://github.com/tue-audri/prius_interface/blob/main/panda_can_rcv/panda_can_rcv/can_listener_node.py"
click node_message_relay "https://github.com/tue-audri/prius_interface/blob/main/panda_can_rcv/panda_can_rcv/message_relay.py"
click node_panda_params "https://github.com/tue-audri/prius_interface/blob/main/panda_can_rcv/config/panda_params.yaml"
click node_toyota_dbc1 "https://github.com/tue-audri/prius_interface/blob/main/panda_can_rcv/config/toyota_filtered.dbc"
click node_toyota_dbc2 "https://github.com/tue-audri/prius_interface/blob/main/panda_can_rcv/config/toyota_tnga_k_pt_generated.dbc"
click node_can_launch "https://github.com/tue-audri/prius_interface/blob/main/panda_can_rcv/launch/can_listener.launch.py"
click node_can_message "https://github.com/tue-audri/prius_interface/blob/main/panda_msgs/msg/CANMessage.msg"
click node_health_message "https://github.com/tue-audri/prius_interface/blob/main/panda_msgs/msg/PandaHealthStatus.msg"
click node_msgs_pkg "https://github.com/tue-audri/prius_interface/tree/main/panda_msgs"
click node_zmq_listener "https://github.com/tue-audri/prius_interface/blob/main/autoware_zmq_ros_bridge/autoware_zmq_ros_bridge/autoware_zmq_listener_node.py"
click node_zmq_params "https://github.com/tue-audri/prius_interface/blob/main/autoware_zmq_ros_bridge/config/autoware_zmq_params.yaml"
click node_zmq_launch "https://github.com/tue-audri/prius_interface/blob/main/autoware_zmq_ros_bridge/launch/autoware_zmq_bridge.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_can_bus,node_can_interface,node_can_listener,node_message_relay,node_panda_params,node_toyota_dbc1,node_toyota_dbc2,node_can_launch toneBlue
class node_can_message,node_health_message,node_msgs_pkg toneAmber
class node_zmq_listener,node_zmq_params,node_zmq_launch,node_zmq_endpoint toneMint
class node_ros_graph toneNeutral
```

## Components

### CAN Ingestion

Vehicle CAN reception and decoding pipeline.

- **CAN Bus**: vehicle transport · Prius CAN frames entering the stack.
- [CAN Interface](https://github.com/tue-audri/prius_interface/blob/HEAD/panda_can_rcv/panda_can_rcv/can_interface.py): python adapter · Low-level boundary for receiving CAN frames. · `panda_can_rcv/panda_can_rcv/can_interface.py`
- [Listener Node](https://github.com/tue-audri/prius_interface/blob/HEAD/panda_can_rcv/panda_can_rcv/can_listener_node.py): ros2 node · Owns runtime loop and CAN ingest orchestration. · `panda_can_rcv/panda_can_rcv/can_listener_node.py`
- [Message Relay](https://github.com/tue-audri/prius_interface/blob/HEAD/panda_can_rcv/panda_can_rcv/message_relay.py): translation layer · Converts decoded CAN signals into ROS messages. · `panda_can_rcv/panda_can_rcv/message_relay.py`
- [CAN Params](https://github.com/tue-audri/prius_interface/blob/HEAD/panda_can_rcv/config/panda_params.yaml): runtime config · ROS parameters for CAN listener behavior. · `panda_can_rcv/config/panda_params.yaml`
- [Toyota DBC](https://github.com/tue-audri/prius_interface/blob/HEAD/panda_can_rcv/config/toyota_filtered.dbc): signal db · Filtered Toyota CAN signal definitions. · `panda_can_rcv/config/toyota_filtered.dbc`
- [Toyota Gen DBC](https://github.com/tue-audri/prius_interface/blob/HEAD/panda_can_rcv/config/toyota_tnga_k_pt_generated.dbc): signal db · Generated Toyota TGNA K PT decoding definitions. · `panda_can_rcv/config/toyota_tnga_k_pt_generated.dbc`
- [CAN Launch](https://github.com/tue-audri/prius_interface/blob/HEAD/panda_can_rcv/launch/can_listener.launch.py): launch file · Starts the CAN listener node with parameters. · `panda_can_rcv/launch/can_listener.launch.py`

### ROS Messages

Shared message contracts used across packages.

- [CAN Message](https://github.com/tue-audri/prius_interface/blob/HEAD/panda_msgs/msg/CANMessage.msg): ros msg · Shared message for CAN-derived data. · `panda_msgs/msg/CANMessage.msg`
- [Health Status](https://github.com/tue-audri/prius_interface/blob/HEAD/panda_msgs/msg/PandaHealthStatus.msg): ros msg · Shared message for system health reporting. · `panda_msgs/msg/PandaHealthStatus.msg`
- [panda_msgs](https://github.com/tue-audri/prius_interface/tree/HEAD/panda_msgs): ros package · Dedicated ROS message contract package. · `panda_msgs`

### ZeroMQ Bridge

External ZMQ transport bridged into ROS 2.

- [ZMQ Listener](https://github.com/tue-audri/prius_interface/blob/HEAD/autoware_zmq_ros_bridge/autoware_zmq_ros_bridge/autoware_zmq_listener_node.py): ros2 node · Receives ZeroMQ data and bridges it into ROS. · `autoware_zmq_ros_bridge/autoware_zmq_ros_bridge/autoware_zmq_listener_node.py`
- [ZMQ Params](https://github.com/tue-audri/prius_interface/blob/HEAD/autoware_zmq_ros_bridge/config/autoware_zmq_params.yaml): runtime config · Parameters for the ZeroMQ bridge node. · `autoware_zmq_ros_bridge/config/autoware_zmq_params.yaml`
- [Bridge Launch](https://github.com/tue-audri/prius_interface/blob/HEAD/autoware_zmq_ros_bridge/launch/autoware_zmq_bridge.launch.py): launch file · Starts the ZeroMQ-to-ROS bridge. · `autoware_zmq_ros_bridge/launch/autoware_zmq_bridge.launch.py`
- **ZMQ Endpoint**: transport endpoint · External ZeroMQ producer or consumer outside ROS.

### Other components

- **ROS 2 Graph**: middleware · Shared ROS 2 runtime where downstream Autoware components subscribe.

## Connections

- CAN Bus → CAN Interface: frames · Vehicle CAN frames enter through the interface boundary.
- CAN Interface → Listener Node: raw data · Listener node consumes incoming frames.
- Listener Node → Toyota DBC: decode · Filtered DBC definitions decode vehicle signals.
- Listener Node → Toyota Gen DBC: decode · Generated DBC definitions decode vehicle signals.
- Listener Node → Message Relay: relay · Decoded signals are converted for publication.
- Message Relay → CAN Message: publishes · CAN-derived data is emitted as a shared ROS message.
- Message Relay → Health Status: publishes · Health/status information is emitted as a shared ROS message.
- CAN Launch → Listener Node: starts · Launch file brings up the CAN listener node.
- CAN Launch → CAN Params: loads · Runtime parameters are injected from YAML.
- Listener Node → ROS 2 Graph: publishes · ROS topics enter the shared ROS 2 graph.
- CAN Message → ROS 2 Graph: consumed by · Downstream Autoware components subscribe to CAN messages.
- Health Status → ROS 2 Graph: consumed by · Downstream components can monitor health messages.
- ZMQ Endpoint → ZMQ Listener: messages · External ZeroMQ traffic enters the bridge.
- Bridge Launch → ZMQ Listener: starts · Launch file brings up the bridge node.
- Bridge Launch → ZMQ Params: loads · Bridge parameters are injected from YAML.
- ZMQ Listener → ROS 2 Graph: publishes · ZeroMQ data is translated into ROS 2 topics.
- panda_msgs → CAN Message: defines · Message package owns the CAN message contract.
- panda_msgs → Health Status: defines · Message package owns the health status contract.
