# unlir/xdrive architecture

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

- Interactive diagram: https://gitdiagram.com/unlir/xdrive
- Repository: https://github.com/unlir/xdrive

## Overview

##### Project type and purpose
- This is an embedded real-time firmware project for a stepper-motor controller (XDrive) with closed-loop control and multifunction interfaces.
- It consists of two firmware images: a USB bootloader (Firmware_BL) and the main application firmware (Firmware_APP), plus electrical schematics, mechanical CAD, photos, and specifications.

##### File structure
- Top level:
- Firmware_APP – main application, built in Keil MDK-ARM (UVProjx).
- Firmware_BL – bootloader image used for in-field USB updates.
- Hardware – PCB schematics and BOM.
- Machinery – enclosure CAD and STL.
- Picture, Specification – documentation.
- Inside Firmware_APP:
- Drivers/CMSIS & STM32F1xx_HAL_Driver – vendor HAL and CMSIS core.
- Core (Inc/Src) – HAL glue, system startup, ISRs.
- Kernel – simple scheduler loop.
- Base_Drivers – board-specific I/O wrappers (GPIO, UART, signal port, encoder, motor driver).
- Base_Math – low-level math utilities (trigonometry, rein_math).
- Control – closed‐loop algorithms: Current_Tracker, Speed_Tracker, Location_Tracker/Interp, Move_Reconstruct, motor_control.
- Debug – UI layer: button, OLED SSD1306, pictures.
- Config – board and linker scripts.
- MDK-ARM – IDE project, linker files, .bin/.hex output.

##### Extract Architectural Insights from the README
- The README confirms two-image structure (bootloader and main), lists update history, and maps directories to functionality.
- It emphasizes stepper motor closed-loop control and multi-function interfaces (USB, buttons, display).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Hardware Column
    subgraph "Hardware" 
        direction TB
        MCU["STM32F103CB MCU"]:::hardware
        Motor["Motor Driver & Stepper Motor"]:::hardware
        Encoder["Rotary Encoder Sensor"]:::hardware
        UI["UI Panel (Buttons & SSD1306 OLED)"]:::hardware
        USBIF["USB Interface"]:::hardware
        Power["Power Supply & Protection"]:::hardware
    end

    %% Software Column
    subgraph "Software Firmware" 
        direction TB
        BL["Bootloader (Firmware_BL)"]:::bootloader
        APP["Application (Firmware_APP)"]:::bootloader
        subgraph "Abstraction Layer"
            direction TB
            HAL["HAL & CMSIS"]:::abstraction
        end
        subgraph "Core System"
            direction TB
            Core["Startup & ISRs"]:::abstraction
        end
        Kernel["Kernel Scheduler"]:::drivers
        subgraph "Base Drivers"
            direction TB
            Drivers["Board Drivers"]:::drivers
        end
        Math["Base Math Utilities"]:::control
        subgraph "Control Layer"
            direction TB
            Control["Control Algorithms"]:::control
        end
        Debug["Debug/UI Layer"]:::ui
        Config["Configuration & Linker Scripts"]:::abstraction
        MDK["Keil MDK-ARM Project & Outputs"]:::abstraction
    end

    %% External Host
    Host["USB Host / PC"]:::external

    %% Connections
    Host -->|"firmware update"| BL
    BL -->|"jump if no update"| APP
    APP --> HAL
    HAL --> Core
    Core --> Kernel
    Kernel --> Drivers
    Kernel --> Control
    Kernel --> Debug
    Kernel --> Math
    Control -->|reads sensor| Drivers
    Control -->|uses math| Math
    Control -->|outputs PWM| Motor
    Drivers -->|GPIO/SPI/I2C| MCU
    Drivers -->|reads| Encoder
    Debug -->|updates display| UI
    USBIF -->|connects| BL
    Power --> MCU

    %% Click Events
    click Hardware "https://github.com/unlir/xdrive/tree/master/Hardware/"
    click BL "https://github.com/unlir/xdrive/tree/master/Firmware_BL/"
    click APP "https://github.com/unlir/xdrive/tree/master/Firmware_APP/"
    click HAL "https://github.com/unlir/xdrive/tree/master/Firmware_APP/Drivers/STM32F1xx_HAL_Driver/"
    click HAL "https://github.com/unlir/xdrive/tree/master/Firmware_APP/Drivers/CMSIS/"
    click Core "https://github.com/unlir/xdrive/tree/master/Firmware_APP/Core/Inc/"
    click Core "https://github.com/unlir/xdrive/tree/master/Firmware_APP/Core/Src/"
    click Kernel "https://github.com/unlir/xdrive/tree/master/Firmware_APP/Kernel/"
    click Drivers "https://github.com/unlir/xdrive/tree/master/Firmware_APP/Base_Drivers/"
    click Math "https://github.com/unlir/xdrive/tree/master/Firmware_APP/Base_Math/"
    click Control "https://github.com/unlir/xdrive/tree/master/Firmware_APP/Control/"
    click Debug "https://github.com/unlir/xdrive/tree/master/Firmware_APP/Debug/"
    click Config "https://github.com/unlir/xdrive/tree/master/Firmware_APP/Config/"
    click MDK "https://github.com/unlir/xdrive/tree/master/Firmware_APP/MDK-ARM/"
    click READMEDoc "https://github.com/unlir/xdrive/blob/master/README.md"
    click Picture "https://github.com/unlir/xdrive/tree/master/Picture/"
    click Spec "https://github.com/unlir/xdrive/tree/master/Specification/"
    click Machinery "https://github.com/unlir/xdrive/tree/master/Machinery/"

    %% Styles
    classDef hardware fill:#a9a9a9,color:#000;
    classDef abstraction fill:#add8e6,color:#000;
    classDef drivers fill:#87cefa,color:#000;
    classDef control fill:#98fb98,color:#000;
    classDef ui fill:#ffa500,color:#000;
    classDef bootloader fill:#f08080,color:#000;
    classDef external fill:#d3d3d3,color:#000;
```
