# rnd-ash/ultimate-nag52-fw architecture

> Architecture diagram of the GitHub repository rnd-ash/ultimate-nag52-fw, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rnd-ash/ultimate-nag52-fw
- Repository: https://github.com/rnd-ash/ultimate-nag52-fw

## Overview

##### Project type and purpose
- This is an embedded‐firmware project (written in C/C++ with PlatformIO/CMake) for the Ultimate NAG52 722.6 Transmission Control Unit (TCU).
- Its goal is to run on a microcontroller board, interface with transmission hardware (solenoids, sensors), communicate over CAN and USB, provide diagnostics, and manage gear‐shifting logic and calibration.

##### File structure
- Top-level: platformio.ini, CMakeLists.txt, sdkconfig, main src/ and include/, a lib/ directory with reusable modules (CAN definitions, ECU data, utility code), scripts/, tests/.
- src/ subdivides by functionality:
- canbus (CAN HAL and bus drivers)
- diag (diagnostic endpoints, flasher, KWP2000)
- nvs (persistent storage abstractions)
- adaptation, behaviour, shifting_algo (core TCU control algorithms)
- solenoids, tcu_io, sensors, pressure_manager, models (hardware interface + models)
- egs_calibration, maps (calibration data management)
- main.cpp – application entry point and task setup
- lib/ provides generic support: core math, CAN-message definitions for multiple ECU types, DTC manager, code‐generation scripts.
- Configuration/build files: platformio.ini, CMakeLists.txt, sdkconfig.unified, doxygen configs, GitHub workflows.

##### Key insights from README.md
- Confirms this is the TCU firmware for 722.6 gearbox, running on a custom hardware board.
- Emphasizes diagnostic, calibration, and CAN network integration.
- Build and documentation via Doxygen and PlatformIO.

A. Hardware Layer
- Microcontroller (center): CPU, RAM, Flash, peripheral buses.
- External buses: CAN bus (to vehicle ECUs), USB (for diagnostics & flashing).
- Hardware interfaces: Solenoid driver circuits, sensors (speed, temperature, pressure), e-fuse, IO expanders.
B. Firmware Software Layers (inside MCU)
1. Bootloader/Flasher (src/diag/flasher): initializes the device and performs updates.
2. HAL / Platform Abstraction
– canbus/can_hal.*
– efuse/efuse.*
– board_config.*
– tcu_io/tcu_io.*
– nvs (eeprom_config, module_settings)
3. Core Services
– CAN message routing (src/canbus/can_egs5x, can_custom, can_hfm)
– Diagnostic server (src/diag/endpoints/*.cpp, kwp2000)
– Data storage and DTC management (lib/dtcs, src/stored_*)
4. Control Logic
– Behaviour & driving profiler (src/behaviour)
– Adaptation (shift adaptation)
– Shifting algorithm (shift_crossover, shift_release, helpers)
– Gearbox model & torque converter (src/models, torque_converter)
– Solenoid control (src/solenoids)
– Pressure management (src/pressure_manager)
5. Configuration & Calibration
– Map loader and stored tables (src/maps, stored_map)
– Calibration engine (src/egs_calibration)
6. Application Entry (src/main.cpp)
– Starts RTOS tasks/loops, schedules sensor reads, CAN traffic, control loops.

##### Relationships and data flows
- Sensors → HAL → Control Logic → Solenoid drivers
- Control Logic ↔ Calibration & stored maps
- Control Logic & diagnostic ↔ CAN bus (external ECUs, tuner tools)
- Diagnostic server → USB (PC tool) & CAN endpoints
- Persistent settings (NVS) ←→ Control Logic

##### Architectural patterns & design principles
- Layered architecture: HAL → Services → Control Logic → Application
- Modularity: each functional area in its own directory and namespace
- Separation of concerns: distinct CAN stacks per ECU version, separate diagnostic endpoints
- RTOS/task‐based scheduling implied in main (not shown in file tree but typical for embedded)

##### Technologies & frameworks
- PlatformIO or ESP-IDF (sdkconfig) + CMake
- Doxygen for documentation
- Python/Perl scripts for code‐generation (lib/gen_headers, scripts/*.py)
- GitHub Actions for CI and docs deployment

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Hardware Layer"
        MCU["Microcontroller\nCPU, RAM, Flash"]:::hw
        Sensors["Sensors\n(speed, temperature, pressure)"]:::hw
        SolDrivers["Solenoid Drivers"]:::hw
        EFuse["E-Fuse & IO Expanders"]:::hw
        CANBus["CAN Bus\n(to Vehicle ECUs)"]:::hw
        USBPort["USB Port\n(diagnostics & flashing)"]:::hw
    end

    MCU --> Sensors
    MCU --> SolDrivers
    MCU --> EFuse
    MCU --> CANBus
    MCU --> USBPort

    subgraph "MCU Firmware"
        subgraph "HAL Layer"
            CANHAL["CAN HAL"]:::hal
            BoardCfg["Board Config"]:::hal
            EFuseDrv["eFuse Driver"]:::hal
            TCUIO["TCU I/O Abstraction"]:::hal
            NVS["NVS / Storage Abstraction"]:::storage
        end

        subgraph "Core Services"
            CANRouter["CAN Message Routing"]:::service
            DiagServ["Diagnostic Server"]:::service
            DTCMgr["DTC Manager"]:::service
        end

        subgraph "Control Logic"
            Behaviour["Behaviour & Driving Profiler"]:::ctrl
            Adaptation["Shift Adaptation"]:::ctrl
            ShiftingAlg["Shifting Algorithm"]:::ctrl
            Models["Gearbox & Torque Converter Models"]:::ctrl
            SolControl["Solenoid Control"]:::ctrl
            PressureMgr["Pressure Management"]:::ctrl
        end

        subgraph "Config & Calibration"
            Maps["Map Loader & Stored Tables"]:::storage
            Calib["Calibration Engine"]:::storage
        end

        subgraph "Application Entry"
            MainApp["main.cpp & Task Scheduler"]:::app
        end
    end

    Sensors -->|"ADC readings"| TCUIO
    TCUIO -->|"Sensor Data"| Behaviour
    Behaviour -->|"Driving Data"| ShiftingAlg
    Adaptation -->|"Adaptive Params"| ShiftingAlg
    ShiftingAlg -->|"Control Commands"| SolControl
    SolControl -->|"PWM/On-Off Signals"| SolDrivers
    PressureMgr -->|"Pressure Commands"| SolDrivers

    NVS -->|"Settings"| Adaptation
    Maps -->|"Stored Maps"| ShiftingAlg
    Calib -->|"Calibration Data"| Behaviour

    CANBus --> CANHAL
    CANHAL --> CANRouter
    CANRouter --> DiagServ
    CANRouter --> ShiftingAlg
    DiagServ --> CANBus
    DiagServ --> USBPort

    DTCMgr --> DiagServ

    MainApp --> Sensors
    MainApp --> CANHAL
    MainApp --> CANRouter
    MainApp --> Behaviour
    MainApp --> DiagServ

    subgraph "External Tools"
        VehicleECUs["Vehicle ECUs"]:::external
        PCTool["PC Tuning Tool"]:::external
        Scripts["Calibration & Code-Gen Scripts"]:::external
    end

    VehicleECUs -->|"J1939 CAN"| CANBus
    PCTool --> USBPort
    PCTool --> CANBus
    Scripts --> Maps
    Scripts --> Calib

    click CANHAL "https://github.com/rnd-ash/ultimate-nag52-fw/blob/main/src/canbus/can_hal.cpp"
    click BoardCfg "https://github.com/rnd-ash/ultimate-nag52-fw/blob/main/src/board_config.cpp"
    click EFuseDrv "https://github.com/rnd-ash/ultimate-nag52-fw/blob/main/src/efuse/efuse.c"
    click TCUIO "https://github.com/rnd-ash/ultimate-nag52-fw/blob/main/src/tcu_io/tcu_io.cpp"
    click NVS "https://github.com/rnd-ash/ultimate-nag52-fw/blob/main/src/nvs/all_keys.cpp"
    click CANRouter "https://github.com/rnd-ash/ultimate-nag52-fw/blob/main/src/canbus/can_custom.cpp"
    click DiagServ "https://github.com/rnd-ash/ultimate-nag52-fw/blob/main/src/diag/diag_data.cpp"
    click DTCMgr "https://github.com/rnd-ash/ultimate-nag52-fw/blob/main/lib/dtcs/dtc_manager.cpp"
    click Behaviour "https://github.com/rnd-ash/ultimate-nag52-fw/blob/main/src/behaviour/driving_profiler.cpp"
    click Adaptation "https://github.com/rnd-ash/ultimate-nag52-fw/blob/main/src/adaptation/shift_adaptation.cpp"
    click ShiftingAlg "https://github.com/rnd-ash/ultimate-nag52-fw/blob/main/src/shifting_algo/s_algo.cpp"
    click Models "https://github.com/rnd-ash/ultimate-nag52-fw/blob/main/src/models/clutch_speed.cpp"
    click SolControl "https://github.com/rnd-ash/ultimate-nag52-fw/blob/main/src/solenoids/solenoids.cpp"
    click PressureMgr "https://github.com/rnd-ash/ultimate-nag52-fw/blob/main/src/pressure_manager.cpp"
    click Maps "https://github.com/rnd-ash/ultimate-nag52-fw/blob/main/src/maps.cpp"
    click Calib "https://github.com/rnd-ash/ultimate-nag52-fw/blob/main/src/egs_calibration/calibration.cpp"
    click MainApp "https://github.com/rnd-ash/ultimate-nag52-fw/blob/main/src/main.cpp"
    click Scripts "https://github.com/rnd-ash/ultimate-nag52-fw/blob/main/scripts/egs52_dumping.py"

    classDef hw fill:#F5F5F5,stroke:#333,stroke-width:1px
    classDef hal fill:#D0E6FF,stroke:#333,stroke-width:1px
    classDef service fill:#FFE1B3,stroke:#333,stroke-width:1px
    classDef ctrl fill:#BFFCC6,stroke:#333,stroke-width:1px
    classDef storage fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef app fill:#F2F2F2,stroke:#333,stroke-width:1px
    classDef external fill:#FFD1DC,stroke:#333,stroke-width:1px
```
