# nationalroboticsleague-nrl/nrl-nationalroboticsleague architecture

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

- Interactive diagram: https://gitdiagram.com/nationalroboticsleague-nrl/nrl-nationalroboticsleague
- Repository: https://github.com/nationalroboticsleague-nrl/nrl-nationalroboticsleague

## Overview

NRL is a dual-ESP32-S3 robotics platform: teams write robot behavior as OpModes, while the libraries provide the control loop, hardware interfaces, telemetry, display, and wireless link to a handheld controller. The repository also documents a project generator and a blocks editor as student-facing authoring capabilities. Several firmware modules are prebuilt or unsampled, so the graph omits unverified internal call paths; documented capabilities and visible header relationships are retained.

Main entry points: [`RobotFirmware/opmodes`](https://github.com/nationalroboticsleague-nrl/nrl-nationalroboticsleague/tree/main/RobotFirmware/opmodes) (Student OpModes), [`RobotFirmware/lib/HexaNRL/src/NRLComms.h`](https://github.com/nationalroboticsleague-nrl/nrl-nationalroboticsleague/blob/main/RobotFirmware/lib/HexaNRL/src/NRLComms.h) (Robot communications), [`lib/HexaServos/src/HexaDCMotor.h`](https://github.com/nationalroboticsleague-nrl/nrl-nationalroboticsleague/blob/main/lib/HexaServos/src/HexaDCMotor.h) (DC motors), [`RobotFirmware/lib/HexaNRL/src/BoardPins.h`](https://github.com/nationalroboticsleague-nrl/nrl-nationalroboticsleague/blob/main/RobotFirmware/lib/HexaNRL/src/BoardPins.h) (Board pin map)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_robot["Robot Runtime"]
  node_opmode["Student OpModes"]
  node_lifecycle["OpMode runtime<br/>[NRLOpMode.h]"]
  node_actions["Action system<br/>[NRLAction.h]"]
  node_driveactions["Drive actions<br/>[DriveActions.h]"]
  node_tankdrive["Tank drive<br/>[TankDrive.h]"]
  node_telemetry["Telemetry API<br/>[NRLTelemetry.h]"]
  node_bot["Robot ESP32<br/>[RobotMain.ino]"]
end

subgraph group_hardware["Robot Hardware"]
  node_motors["DC motors<br/>[HexaDCMotor.h]"]
  node_servos["Servo motors<br/>[HexaServo.h]"]
  node_power["Power sensing<br/>[HexaPower.h]"]
  node_imu["IMU sensing<br/>[HexaIMU.h]"]
  node_display["Robot OLED<br/>[HexaOLED.h]"]
  node_pins["Board pin map<br/>[BoardPins.h]"]
end

subgraph group_controller["Controller Link"]
  node_comms["Robot communications<br/>[NRLComms.h]"]
  node_controller["Handheld controller"]
end

subgraph group_authoring["Student Authoring"]
  node_editor["Blocks editor AST<br/>[nrl-ast.mjs]"]
  node_projectgen["Project generator<br/>[nrl_new_project.py]"]
end

node_team(("Robot team"))

node_team -->|"writes behavior"| node_opmode
node_opmode -->|"implements hooks"| node_lifecycle
node_lifecycle -->|"runs actions"| node_actions
node_opmode -.->|"uses drive routines"| node_driveactions
node_driveactions -->|"controls drive"| node_tankdrive
node_tankdrive -->|"uses motors"| node_motors
node_opmode -.->|"reports telemetry"| node_comms
node_telemetry -->|"sends telemetry"| node_comms
node_bot -.->|"runs wireless link"| node_comms
node_controller -->|"pairs via ESP-NOW"| node_comms
node_opmode -.->|"commands"| node_motors
node_opmode -.->|"commands"| node_servos
node_opmode -->|"reads rails"| node_power
node_opmode -.->|"reads orientation"| node_imu
node_opmode -.->|"updates display"| node_display
node_pins -->|"defines pins"| node_motors
node_pins -->|"defines channels"| node_power
node_team -->|"authors blocks"| node_editor
node_team -->|"creates project"| node_projectgen

click node_opmode "https://github.com/nationalroboticsleague-nrl/nrl-nationalroboticsleague/tree/main/RobotFirmware/opmodes"
click node_lifecycle "https://github.com/nationalroboticsleague-nrl/nrl-nationalroboticsleague/blob/main/RobotFirmware/lib/HexaNRL/src/NRLOpMode.h"
click node_actions "https://github.com/nationalroboticsleague-nrl/nrl-nationalroboticsleague/blob/main/RobotFirmware/lib/HexaNRL/src/NRLAction.h"
click node_driveactions "https://github.com/nationalroboticsleague-nrl/nrl-nationalroboticsleague/blob/main/RobotFirmware/lib/HexaNRL/src/DriveActions.h"
click node_tankdrive "https://github.com/nationalroboticsleague-nrl/nrl-nationalroboticsleague/blob/main/RobotFirmware/lib/HexaNRL/src/TankDrive.h"
click node_comms "https://github.com/nationalroboticsleague-nrl/nrl-nationalroboticsleague/blob/main/RobotFirmware/lib/HexaNRL/src/NRLComms.h"
click node_telemetry "https://github.com/nationalroboticsleague-nrl/nrl-nationalroboticsleague/blob/main/RobotFirmware/lib/HexaNRL/src/NRLTelemetry.h"
click node_motors "https://github.com/nationalroboticsleague-nrl/nrl-nationalroboticsleague/blob/main/lib/HexaServos/src/HexaDCMotor.h"
click node_servos "https://github.com/nationalroboticsleague-nrl/nrl-nationalroboticsleague/blob/main/lib/HexaServos/src/HexaServo.h"
click node_power "https://github.com/nationalroboticsleague-nrl/nrl-nationalroboticsleague/blob/main/lib/HexaPower/src/HexaPower.h"
click node_imu "https://github.com/nationalroboticsleague-nrl/nrl-nationalroboticsleague/blob/main/lib/HexaIMU/src/HexaIMU.h"
click node_display "https://github.com/nationalroboticsleague-nrl/nrl-nationalroboticsleague/blob/main/lib/HexaOLED/src/HexaOLED.h"
click node_pins "https://github.com/nationalroboticsleague-nrl/nrl-nationalroboticsleague/blob/main/RobotFirmware/lib/HexaNRL/src/BoardPins.h"
click node_editor "https://github.com/nationalroboticsleague-nrl/nrl-nationalroboticsleague/blob/main/tools/blocks-editor/nrl-ast.mjs"
click node_projectgen "https://github.com/nationalroboticsleague-nrl/nrl-nationalroboticsleague/blob/main/tools/nrl_new_project.py"
click node_bot "https://github.com/nationalroboticsleague-nrl/nrl-nationalroboticsleague/blob/main/RobotFirmware/src/RobotMain.ino"

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_opmode,node_lifecycle,node_actions,node_driveactions,node_tankdrive,node_telemetry,node_bot toneBlue
class node_motors,node_servos,node_power,node_imu,node_display,node_pins toneAmber
class node_comms,node_controller toneMint
class node_editor,node_projectgen toneRose
class node_team toneIndigo
```

## Components

### Robot Runtime

- [Student OpModes](https://github.com/nationalroboticsleague-nrl/nrl-nationalroboticsleague/tree/main/RobotFirmware/opmodes): `RobotFirmware/opmodes`
- [OpMode runtime](https://github.com/nationalroboticsleague-nrl/nrl-nationalroboticsleague/blob/main/RobotFirmware/lib/HexaNRL/src/NRLOpMode.h): `RobotFirmware/lib/HexaNRL/src/NRLOpMode.h`
- [Action system](https://github.com/nationalroboticsleague-nrl/nrl-nationalroboticsleague/blob/main/RobotFirmware/lib/HexaNRL/src/NRLAction.h): `RobotFirmware/lib/HexaNRL/src/NRLAction.h`
- [Drive actions](https://github.com/nationalroboticsleague-nrl/nrl-nationalroboticsleague/blob/main/RobotFirmware/lib/HexaNRL/src/DriveActions.h): `RobotFirmware/lib/HexaNRL/src/DriveActions.h`
- [Tank drive](https://github.com/nationalroboticsleague-nrl/nrl-nationalroboticsleague/blob/main/RobotFirmware/lib/HexaNRL/src/TankDrive.h): `RobotFirmware/lib/HexaNRL/src/TankDrive.h`
- [Telemetry API](https://github.com/nationalroboticsleague-nrl/nrl-nationalroboticsleague/blob/main/RobotFirmware/lib/HexaNRL/src/NRLTelemetry.h): `RobotFirmware/lib/HexaNRL/src/NRLTelemetry.h`
- [Robot ESP32](https://github.com/nationalroboticsleague-nrl/nrl-nationalroboticsleague/blob/main/RobotFirmware/src/RobotMain.ino): `RobotFirmware/src/RobotMain.ino`

### Robot Hardware

- [DC motors](https://github.com/nationalroboticsleague-nrl/nrl-nationalroboticsleague/blob/main/lib/HexaServos/src/HexaDCMotor.h): `lib/HexaServos/src/HexaDCMotor.h`
- [Servo motors](https://github.com/nationalroboticsleague-nrl/nrl-nationalroboticsleague/blob/main/lib/HexaServos/src/HexaServo.h): `lib/HexaServos/src/HexaServo.h`
- [Power sensing](https://github.com/nationalroboticsleague-nrl/nrl-nationalroboticsleague/blob/main/lib/HexaPower/src/HexaPower.h): `lib/HexaPower/src/HexaPower.h`
- [IMU sensing](https://github.com/nationalroboticsleague-nrl/nrl-nationalroboticsleague/blob/main/lib/HexaIMU/src/HexaIMU.h): `lib/HexaIMU/src/HexaIMU.h`
- [Robot OLED](https://github.com/nationalroboticsleague-nrl/nrl-nationalroboticsleague/blob/main/lib/HexaOLED/src/HexaOLED.h): `lib/HexaOLED/src/HexaOLED.h`
- [Board pin map](https://github.com/nationalroboticsleague-nrl/nrl-nationalroboticsleague/blob/main/RobotFirmware/lib/HexaNRL/src/BoardPins.h): `RobotFirmware/lib/HexaNRL/src/BoardPins.h`

### Controller Link

- [Robot communications](https://github.com/nationalroboticsleague-nrl/nrl-nationalroboticsleague/blob/main/RobotFirmware/lib/HexaNRL/src/NRLComms.h): `RobotFirmware/lib/HexaNRL/src/NRLComms.h`
- **Handheld controller**

### Student Authoring

- [Blocks editor AST](https://github.com/nationalroboticsleague-nrl/nrl-nationalroboticsleague/blob/main/tools/blocks-editor/nrl-ast.mjs): `tools/blocks-editor/nrl-ast.mjs`
- [Project generator](https://github.com/nationalroboticsleague-nrl/nrl-nationalroboticsleague/blob/main/tools/nrl_new_project.py): `tools/nrl_new_project.py`

### Other components

- **Robot team**

## Connections

- Robot team → Student OpModes: writes behavior (evidence: `README.md`)
- Student OpModes → OpMode runtime: implements hooks (evidence: `RobotFirmware/lib/HexaNRL/src/NRLOpMode.h`)
- OpMode runtime → Action system: runs actions (evidence: `RobotFirmware/lib/HexaNRL/src/NRLOpMode.h`)
- Student OpModes → Drive actions: uses drive routines
- Drive actions → Tank drive: controls drive (evidence: `RobotFirmware/lib/HexaNRL/src/DriveActions.h`)
- Tank drive → DC motors: uses motors (evidence: `RobotFirmware/lib/HexaNRL/src/TankDrive.h`)
- Student OpModes → Robot communications: reports telemetry
- Telemetry API → Robot communications: sends telemetry (evidence: `RobotFirmware/lib/HexaNRL/src/NRLTelemetry.h`)
- Robot ESP32 → Robot communications: runs wireless link
- Handheld controller → Robot communications: pairs via ESP-NOW (evidence: `README.md`)
- Student OpModes → DC motors: commands
- Student OpModes → Servo motors: commands
- Student OpModes → Power sensing: reads rails (evidence: `README.md`)
- Student OpModes → IMU sensing: reads orientation
- Student OpModes → Robot OLED: updates display
- Board pin map → DC motors: defines pins (evidence: `RobotFirmware/lib/HexaNRL/src/BoardPins.h`)
- Board pin map → Power sensing: defines channels (evidence: `RobotFirmware/lib/HexaNRL/src/BoardPins.h`)
- Robot team → Blocks editor AST: authors blocks (evidence: `tools/blocks-editor/nrl-ast.mjs`)
- Robot team → Project generator: creates project (evidence: `README.md`)
