# toyotainfotech/ramn architecture

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

- Interactive diagram: https://gitdiagram.com/toyotainfotech/ramn
- Repository: https://github.com/toyotainfotech/ramn

## Overview

RAMN is a miniature automotive CAN/CAN-FD testbed built from programmable ECUs. Its principal workflow is to generate or receive vehicle-network traffic, decode signals and update simulated sensors, actuators, and displays; users can also interact through USB and host-side diagnostic tools. Documented companion workflows include CARLA closed-loop driving, virtual CAN, and ECU bootloading. The sampled firmware shows the main simulation calls and screen dispatch, but not the complete CAN receive/transmit or host-script implementations, so those connections are limited to documented capabilities.

Main entry points: [`firmware/RAMNV1/Core/Src/main.c`](https://github.com/toyotainfotech/ramn/blob/main/firmware/RAMNV1/Core/Src/main.c) (RTOS application), [`firmware/RAMNV1/USB_CompositeDevice/App/usb_device.c`](https://github.com/toyotainfotech/ramn/blob/main/firmware/RAMNV1/USB_CompositeDevice/App/usb_device.c) (USB composite device), [`scripts/carla`](https://github.com/toyotainfotech/ramn/tree/main/scripts/carla) (CARLA integration), [`firmware/RAMNV1/Core/Src/ramn_screen_manager.c`](https://github.com/toyotainfotech/ramn/blob/main/firmware/RAMNV1/Core/Src/ramn_screen_manager.c) (Screen manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["ECU runtime"]
  node_main["RTOS application<br/>[main.c]"]
  node_screenmanager["Screen manager"]
  node_screens["Display screens"]
  node_eeprom[("Persistent settings<br/>[ramn_eeprom.c]")]
end

subgraph group_vehicle["Vehicle behavior"]
  node_sensors["Sensors<br/>[ramn_sensors.c]"]
  node_simulator["Vehicle simulator<br/>[ramn_simulator.c]"]
  node_actuators["Actuators<br/>[ramn_actuators.c]"]
  node_custom["Custom behavior<br/>[ramn_customize.c]"]
end

subgraph group_protocols["CAN and diagnostics"]
  node_dbc["DBC traffic<br/>[ramn_dbc.c]"]
  node_canformats["CAN signal codecs"]
  node_diagnostics["Diagnostic protocols"]
end

subgraph group_interfaces["Device interfaces"]
  node_usb["USB composite device<br/>[usb_device.c]"]
  node_cdc["CDC / serial CLI<br/>[ramn_cdc.c]"]
  node_gsusb["gs_usb adapter<br/>[ramn_gsusb.c]"]
end

subgraph group_host["Host tools"]
  node_diagtools["Diagnostic scripts"]
  node_bootloader["Bootloader scripts"]
  node_vcan["Virtual CAN bridge<br/>[RAMN_VCAND.py]"]
  node_carla["CARLA integration"]
end

node_user(("User"))
node_canbus(("CAN/CAN-FD network"))
node_carlaext(("CARLA simulator"))

node_main -->|"updates"| node_sensors
node_main -->|"updates"| node_simulator
node_main -->|"applies controls"| node_actuators
node_main -->|"sends traffic"| node_dbc
node_main -->|"updates"| node_custom
node_main -->|"runs display"| node_screenmanager
node_screenmanager -->|"dispatches updates"| node_screens
node_user -->|"runs"| node_diagtools
node_diagtools -->|"sends requests"| node_diagnostics
node_user -->|"runs"| node_bootloader
node_bootloader -.->|"programs ECU"| node_usb
node_user -->|"runs"| node_vcan
node_vcan -.->|"bridges traffic"| node_canbus
node_user -->|"runs"| node_carla
node_carla -.->|"controls vehicle"| node_carlaext
node_carla -.->|"exchanges traffic"| node_canbus
node_canbus -->|"delivers frames"| node_main
node_usb -->|"routes serial data"| node_cdc
node_usb -->|"routes CAN data"| node_gsusb
node_gsusb -->|"transmits frames"| node_canbus
node_dbc -->|"uses codecs"| node_canformats

click node_main "https://github.com/toyotainfotech/ramn/blob/main/firmware/RAMNV1/Core/Src/main.c"
click node_screenmanager "https://github.com/toyotainfotech/ramn/blob/main/firmware/RAMNV1/Core/Src/ramn_screen_manager.c"
click node_screens "https://github.com/toyotainfotech/ramn/tree/main/firmware/RAMNV1/Core/Src"
click node_sensors "https://github.com/toyotainfotech/ramn/blob/main/firmware/RAMNV1/Core/Src/ramn_sensors.c"
click node_simulator "https://github.com/toyotainfotech/ramn/blob/main/firmware/RAMNV1/Core/Src/ramn_simulator.c"
click node_actuators "https://github.com/toyotainfotech/ramn/blob/main/firmware/RAMNV1/Core/Src/ramn_actuators.c"
click node_custom "https://github.com/toyotainfotech/ramn/blob/main/firmware/RAMNV1/Core/Src/ramn_customize.c"
click node_dbc "https://github.com/toyotainfotech/ramn/blob/main/firmware/RAMNV1/Core/Src/ramn_dbc.c"
click node_canformats "https://github.com/toyotainfotech/ramn/blob/main/firmware/RAMNV1/Core/Src/ramn_can_database.c"
click node_diagnostics "https://github.com/toyotainfotech/ramn/tree/main/firmware/RAMNV1/Core/Src"
click node_usb "https://github.com/toyotainfotech/ramn/blob/main/firmware/RAMNV1/USB_CompositeDevice/App/usb_device.c"
click node_cdc "https://github.com/toyotainfotech/ramn/blob/main/firmware/RAMNV1/Core/Src/ramn_cdc.c"
click node_gsusb "https://github.com/toyotainfotech/ramn/blob/main/firmware/RAMNV1/Core/Src/ramn_gsusb.c"
click node_eeprom "https://github.com/toyotainfotech/ramn/blob/main/firmware/RAMNV1/Core/Src/ramn_eeprom.c"
click node_diagtools "https://github.com/toyotainfotech/ramn/tree/main/scripts/diagnostics"
click node_bootloader "https://github.com/toyotainfotech/ramn/tree/main/scripts/STbootloader"
click node_vcan "https://github.com/toyotainfotech/ramn/blob/main/scripts/vcand/RAMN_VCAND.py"
click node_carla "https://github.com/toyotainfotech/ramn/tree/main/scripts/carla"

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_main,node_screenmanager,node_screens,node_eeprom,node_user toneBlue
class node_sensors,node_simulator,node_actuators,node_custom toneAmber
class node_dbc,node_canformats,node_diagnostics toneMint
class node_usb,node_cdc,node_gsusb toneRose
class node_diagtools,node_bootloader,node_vcan,node_carla,node_canbus,node_carlaext toneIndigo
```

## Components

### ECU runtime

- [RTOS application](https://github.com/toyotainfotech/ramn/blob/main/firmware/RAMNV1/Core/Src/main.c): `firmware/RAMNV1/Core/Src/main.c`
- [Screen manager](https://github.com/toyotainfotech/ramn/blob/main/firmware/RAMNV1/Core/Src/ramn_screen_manager.c): `firmware/RAMNV1/Core/Src/ramn_screen_manager.c`
- [Display screens](https://github.com/toyotainfotech/ramn/tree/main/firmware/RAMNV1/Core/Src): `firmware/RAMNV1/Core/Src`
- [Persistent settings](https://github.com/toyotainfotech/ramn/blob/main/firmware/RAMNV1/Core/Src/ramn_eeprom.c): `firmware/RAMNV1/Core/Src/ramn_eeprom.c`

### Vehicle behavior

- [Sensors](https://github.com/toyotainfotech/ramn/blob/main/firmware/RAMNV1/Core/Src/ramn_sensors.c): `firmware/RAMNV1/Core/Src/ramn_sensors.c`
- [Vehicle simulator](https://github.com/toyotainfotech/ramn/blob/main/firmware/RAMNV1/Core/Src/ramn_simulator.c): `firmware/RAMNV1/Core/Src/ramn_simulator.c`
- [Actuators](https://github.com/toyotainfotech/ramn/blob/main/firmware/RAMNV1/Core/Src/ramn_actuators.c): `firmware/RAMNV1/Core/Src/ramn_actuators.c`
- [Custom behavior](https://github.com/toyotainfotech/ramn/blob/main/firmware/RAMNV1/Core/Src/ramn_customize.c): `firmware/RAMNV1/Core/Src/ramn_customize.c`

### CAN and diagnostics

- [DBC traffic](https://github.com/toyotainfotech/ramn/blob/main/firmware/RAMNV1/Core/Src/ramn_dbc.c): `firmware/RAMNV1/Core/Src/ramn_dbc.c`
- [CAN signal codecs](https://github.com/toyotainfotech/ramn/blob/main/firmware/RAMNV1/Core/Src/ramn_can_database.c): `firmware/RAMNV1/Core/Src/ramn_can_database.c`
- [Diagnostic protocols](https://github.com/toyotainfotech/ramn/tree/main/firmware/RAMNV1/Core/Src): `firmware/RAMNV1/Core/Src`

### Device interfaces

- [USB composite device](https://github.com/toyotainfotech/ramn/blob/main/firmware/RAMNV1/USB_CompositeDevice/App/usb_device.c): `firmware/RAMNV1/USB_CompositeDevice/App/usb_device.c`
- [CDC / serial CLI](https://github.com/toyotainfotech/ramn/blob/main/firmware/RAMNV1/Core/Src/ramn_cdc.c): `firmware/RAMNV1/Core/Src/ramn_cdc.c`
- [gs_usb adapter](https://github.com/toyotainfotech/ramn/blob/main/firmware/RAMNV1/Core/Src/ramn_gsusb.c): `firmware/RAMNV1/Core/Src/ramn_gsusb.c`

### Host tools

- [Diagnostic scripts](https://github.com/toyotainfotech/ramn/tree/main/scripts/diagnostics): `scripts/diagnostics`
- [Bootloader scripts](https://github.com/toyotainfotech/ramn/tree/main/scripts/STbootloader): `scripts/STbootloader`
- [Virtual CAN bridge](https://github.com/toyotainfotech/ramn/blob/main/scripts/vcand/RAMN_VCAND.py): `scripts/vcand/RAMN_VCAND.py`
- [CARLA integration](https://github.com/toyotainfotech/ramn/tree/main/scripts/carla): `scripts/carla`

### Other components

- **User**
- **CAN/CAN-FD network**
- **CARLA simulator**

## Connections

- RTOS application → Sensors: updates
- RTOS application → Vehicle simulator: updates
- RTOS application → Actuators: applies controls
- RTOS application → DBC traffic: sends traffic
- RTOS application → Custom behavior: updates
- RTOS application → Screen manager: runs display
- Screen manager → Display screens: dispatches updates
- User → Diagnostic scripts: runs
- Diagnostic scripts → Diagnostic protocols: sends requests
- User → Bootloader scripts: runs
- Bootloader scripts → USB composite device: programs ECU
- User → Virtual CAN bridge: runs
- Virtual CAN bridge → CAN/CAN-FD network: bridges traffic
- User → CARLA integration: runs
- CARLA integration → CARLA simulator: controls vehicle
- CARLA integration → CAN/CAN-FD network: exchanges traffic
- CAN/CAN-FD network → RTOS application: delivers frames
- USB composite device → CDC / serial CLI: routes serial data
- USB composite device → gs_usb adapter: routes CAN data
- gs_usb adapter → CAN/CAN-FD network: transmits frames
- DBC traffic → CAN signal codecs: uses codecs