# odriverobotics/odrive architecture

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

- Interactive diagram: https://gitdiagram.com/odriverobotics/odrive
- Repository: https://github.com/odriverobotics/odrive

## Overview

##### Project type and purpose
- This is a full‐stack robotics control system comprising embedded firmware, host‐side libraries/tools, and a browser‐based GUI.
- Its goal is to drive brushless motors via an STM32 MCU board (the “ODrive”), exposing services to PC‐side clients.

##### File structure
- Top‐level modules:
– Firmware (C/C++ for STM32 with FreeRTOS, CMSIS HAL, motor‐control, comms, fibre RPC)
– tools (Python CLI & DFU, fibre‐codegen, test rigs)
– GUI (Vue.js frontend, Python server, fibre‐js)
– Arduino libraries (ArduinoI2C, ODriveArduino)
– docs & analysis scripts
- Embedded‐side layers: Board Support Package (Board/v3), Drivers (STM32, DRV8301, gate drivers), MotorControl algorithms, Communication layer (USB/CAN/UART/I2C), Fibre RPC framework.
- Host‐side layers: Python “tools/odrive” library & CLI, odrivetool scripts, DFU module; fibre‐cpp library; GUI server (odrive_server.py); Vue.js front‐end with socket.io.

##### README
- Confirms firmware is the core, with Python and JS host tools for user interaction.
- Mentions Developer Guide detailing architecture and dependencies.

a. Main components
1. Hardware: ODrive board (STM32F405 MCU, DRV8301 gate drivers, motor & encoder interfaces, USB & CAN transceivers)
2. Embedded firmware:
– HAL/BSP layer (CMSIS, STM32 HAL)
– Drivers (gate driver, ADC, timers, CAN, USB CDC)
– RTOS (FreeRTOS tasks for motor control, comms, USB polling)
– MotorControl module (FOC, estimators, controllers)
– Communication module (ASCII protocol, CAN/UART/I2C interfaces)
– Fibre RPC server (fibre‐cpp integration)
3. Host back end:
– Python tools/odrive library (pyfibre binding to fibre‐cpp)
– odrive_server.py (exposes RPC to GUI via socket.io)
– DFU & firmware upload actions (via Python DFU module)
4. GUI front end:
– Vue.js application (components, store, views)
– fibre‐js client + libfibre‐wasm
– socket.io client for real‐time updates
5. Arduino wrappers:
– ArduinoI2C & ODriveArduino libraries for microcontroller experiments
b. Relationships and interactions
- Firmware ↔ Hardware: low‐level drivers communicate with motor & encoder hardware.
- Firmware ↔ Host: RPC over USB CDC (or CAN) via fibre protocol.
- Host Python server ↔ GUI front end: WebSocket/socket.io RPC forwarding.
- Python tools CLI ↔ Firmware: command‐line RPC.
- Arduino sketches ↔ Firmware: I2C commands to ODrive.
c. Architectural patterns & principles
- Layered architecture on embedded side (HAL → Drivers → RTOS tasks → Application logic → RPC).
- Event‐driven RPC framework (fibre) decoupling comms from motor‐control logic.
- MVC‐style separation in GUI (Vue components, store, views).
- Microservice‐like division: firmware, host server, front end each in its own process.
d. Key technologies/frameworks
- Embedded: STM32F4 HAL, CMSIS, FreeRTOS, DRV8301 driver, C/C++.
- RPC: fibre‐cpp on device, fibre‐js/libfibre‐wasm on client.
- Host: Python 3, pyfibre, socket.io, Flask/asyncio (in odrive_server.py).
- GUI: Vue.js, JavaScript, WebSockets.
- Arduino: Arduino IDE, I2C library.

##### Details to capture
- Multi‐protocol communication (USB CDC, CAN, UART, I2C) between firmware and external clients.
- Fibre RPC boundary on both sides.
- RTOS as the host scheduler for motor control & comms tasks.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Hardware Layer
    Hardware["ODrive Board\n(STM32F405, DRV8301,\nMotor & Encoders,\nUSB/CAN Transceivers)"]:::hardware

    %% Embedded Firmware Layer
    subgraph "Embedded Firmware" 
        direction TB
        BSP["Board Support Package\n(CMSIS, STM32 HAL)"]:::embedded
        Drivers["Drivers\n(STM32 HAL, DRV8301,\nGate Drivers)"]:::embedded
        FreeRTOS["FreeRTOS RTOS"]:::embedded
        MotorControl["MotorControl\n(FOC, Estimators,\nControllers)"]:::embedded
        Comm["Communication\n(USB/CAN/UART/I2C,\nASCII Protocol)"]:::embedded
        FibreRPC["Fibre RPC Server\n(fibre-cpp)"]:::embedded
        BSP --> Drivers --> FreeRTOS --> MotorControl --> Comm --> FibreRPC
        click BSP "https://github.com/odriverobotics/odrive/tree/master/Firmware/Board/v3"
        click Drivers "https://github.com/odriverobotics/odrive/tree/master/Firmware/Drivers"
        click FibreRPC "https://github.com/odriverobotics/odrive/tree/master/Firmware/fibre-cpp"
        click FreeRTOS "https://github.com/odriverobotics/odrive/tree/master/Firmware/ThirdParty/FreeRTOS"
        click MotorControl "https://github.com/odriverobotics/odrive/tree/master/Firmware/MotorControl"
        click Comm "https://github.com/odriverobotics/odrive/tree/master/Firmware/communication"
    end

    %% Host Backend Layer
    subgraph "Host Backend" 
        direction TB
        ToolsCLI["Python Tools & CLI\n(pyfibre bindings,\nODrive library)"]:::host
        DFU["DFU Utilities"]:::host
        Pyfibre["pyfibre Package"]:::host
        OdriveTool["odrivetool\n(scripts & CLI)"]:::host
        TestRigs["Test Rigs & Scripts"]:::host
        ToolsCLI --> DFU
        ToolsCLI --> Pyfibre
        ToolsCLI --> OdriveTool
        ToolsCLI --> TestRigs
        click ToolsCLI "https://github.com/odriverobotics/odrive/tree/master/tools/odrive"
        click DFU "https://github.com/odriverobotics/odrive/blob/master/tools/odrive/dfu.py"
        click DFU "https://github.com/odriverobotics/odrive/tree/master/tools/odrive/dfuse"
        click Pyfibre "https://github.com/odriverobotics/odrive/tree/master/tools/odrive/pyfibre"
        click OdriveTool "https://github.com/odriverobotics/odrive/tree/master/tools/odrivetool"
        click OdriveTool "https://github.com/odriverobotics/odrive/blob/master/tools/odrivetool.bat"
        click TestRigs "https://github.com/odriverobotics/odrive/blob/master/tools/plot_oscilloscope.py"
    end

    %% GUI Frontend Layer
    subgraph "GUI Front End" 
        direction TB
        VueApp["Vue.js Application\n(Components, Store, Views)"]:::frontend
        Config["Build & Config\n(package.json,\nvue.config.js)"]:::frontend
        FibreJS["fibre-js Client\n(libfibre-wasm)"]:::frontend
        Server["RPC Server\n(odrive_server.py,\nsocket.io)"]:::frontend
        VueApp --> Config
        VueApp --> FibreJS
        Server --> FibreJS
        click VueApp "https://github.com/odriverobotics/odrive/tree/master/GUI/src"
        click Config "https://github.com/odriverobotics/odrive/blob/master/GUI/package.json"
        click Config "https://github.com/odriverobotics/odrive/blob/master/GUI/vue.config.js"
        click FibreJS "https://github.com/odriverobotics/odrive/tree/master/GUI/fibre-js"
        click Server "https://github.com/odriverobotics/odrive/blob/master/GUI/server/odrive_server.py"
    end

    %% Arduino Wrappers
    subgraph "Arduino Wrappers"
        direction TB
        ArduinoI2C["ArduinoI2C Examples"]:::embedded
        ODriveArduino["ODriveArduino Library"]:::embedded
        ArduinoI2C --> ODriveArduino
        click ArduinoI2C "https://github.com/odriverobotics/odrive/tree/master/Arduino/ArduinoI2C"
        click ODriveArduino "https://github.com/odriverobotics/odrive/tree/master/Arduino/ODriveArduino"
    end

    %% Documentation
    subgraph "Documentation"
        Docs["Developer Guide & Protocols"]:::docs
        click Docs "https://github.com/odriverobotics/odrive/tree/master/docs/"
        click Docs "https://github.com/odriverobotics/odrive/blob/master/docs/exts/fibre_autodoc.py"
    end

    %% CI and Release
    subgraph "CI & Release"
        Workflows["GitHub Actions Workflows"]:::ci
        Actions["Custom GitHub Actions"]:::ci
        Workflows --> Actions
        click Workflows "https://github.com/odriverobotics/odrive/tree/master/.github/workflows"
        click Actions "https://github.com/odriverobotics/odrive/tree/master/.github/actions"
    end

    %% Analysis & Simulation
    subgraph "Analysis & Simulation"
        Analysis["Simulation Scripts"]:::analysis
        click Analysis "https://github.com/odriverobotics/odrive/tree/master/analysis/Simulation"
    end

    %% Connections
    VueApp -->|"WebSocket RPC"| Server
    Server -->|"Fibre RPC"| FibreRPC
    ToolsCLI -->|"Fibre RPC"| FibreRPC
    OdriveTool -->|"Fibre RPC"| FibreRPC
    ArduinoI2C -->|"I2C Commands"| Comm
    Hardware -->|"Controls & Feedback"| BSP

    %% Styling
    classDef embedded fill:#e0f3ff,stroke:#3399ff,color:#003366;
    classDef host fill:#e6ffe6,stroke:#33cc33,color:#006600;
    classDef frontend fill:#fff2e6,stroke:#ff9933,color:#cc6600;
    classDef hardware fill:#f2f2f2,stroke:#999999,color:#333333;
    classDef docs fill:#f9e6ff,stroke:#cc66cc,color:#660066;
    classDef ci fill:#ffffe6,stroke:#cccc33,color:#666600;
    classDef analysis fill:#e6e6e6,stroke:#999999,color:#333333;
```
