# simplefoc/arduino-foc architecture

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

- Interactive diagram: https://gitdiagram.com/simplefoc/arduino-foc
- Repository: https://github.com/simplefoc/arduino-foc

## Overview

This project is an Arduino and PlatformIO library for Field Oriented Control (FOC) targeting BLDC and stepper motors. Its main purpose is to provide modular, easy-to-use motor control algorithms along with hardware‐abstraction for sensors, drivers, and current sensing. The library is designed to support a wide variety of hardware configurations (across different MCU families such as Arduino, STM32, ESP32, Teensy, etc.) and to simplify the complexity of implementing efficient FOC algorithms.

##### Main Components
- Motor Control Core: This encapsulates the FOC algorithm, motion controllers (velocity, position, and torque control), and tuning of control loops.
- Hardware Abstraction Layers: There are separate modules for drivers (e.g., BLDCDriver3PWM, BLDCDriver6PWM, StepperDriverXPWM), current sensing (both low-side and inline), and sensor processing (encoder, hall sensor, magnetic sensor).
- Communication & Debug: Includes the components for serial or OSC based communications (Commander, StepDirListener, SimpleFOCDebug) to enable configuration, monitoring, and debugging.
- Hardware-specific Implementations: Various directories like src/drivers/hardware_specific, src/current_sense/hardware_specific, and subdirectories for different MCU families (e.g., for ESP32, STM32, SAMD, Teensy) indicate that the library isolates hardware-dependent implementations in clear modules.
- Examples & Utilities: Numerous examples for motor control modes, calibration, and communication tests show real-world implementations/components interacting with the core library.

##### Relationships and Interactions
- The Motor Control Core (FOC routines) receives data from the Sensor Modules. Based on sensor feedback (position, velocity, or torque), it computes control signals (for example, current control loops).
- The computed control signals are then passed to the Driver modules, which are hardware-specific and generate the required PWM outputs.
- The Current Sensing modules continuously monitor actual current flows using either inline or low-side methods and supply feedback to the control loop.
- The Communication modules facilitate side channels for monitoring, debugging, and configuration (tuning of PID parameters, etc.).

##### Architectural Patterns and Principles
- Modularity: Each hardware component (motor, sensor, driver, current sense) is implemented as a distinct C++ object with clear interfaces.
- Abstraction: Hardware-specific details are encapsulated in separate directories, enabling a platform-independent core.
- Layered Approach: There is a separation between the high-level FOC algorithm (in src/common and the motor classes) and the lower-level hardware drivers/sensors (in src/drivers, src/current_sense, and src/sensors).
- Extensibility: The architecture supports adding new motor or sensor types by simply extending the base classes, making it easier to support multiple hardware combinations.

##### Relevant Technologies and Frameworks
- Arduino IDE and PlatformIO for building/deployment.
- C++ as the core programming language.
- GitHub Actions workflows (found in the .github/workflows folder) for CI, demonstrating integration across different platforms (Arduino, STM32, ESP32, etc.).
- Modern motor control techniques such as PID tuning and FOC along with dedicated support for various MCU architectures.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Control Layer"
        FOC["Motor Control Core"]:::core
        Debug["Communication & Debug"]:::comm
    end

    subgraph "Hardware Abstraction"
        Sensors["Sensor Processing"]:::sensor
        Drivers["Driver Modules"]:::driver
        Current["Current Sensing"]:::currentsense
    end

    subgraph "Hardware-specific Implementations"
        MCU_Drivers["MCU Specific Drivers"]:::hardwareimp
        MCU_Current["MCU Specific Current Sensing"]:::hardwareimp
    end

    subgraph "Examples & Utilities"
        Examples["Examples & Utilities"]:::examples
    end

    Sensors -->|"sensorData"| FOC
    Current -->|"currentFeedback"| FOC
    FOC -->|"controlCommand"| Drivers
    FOC -->|"debugInfo"| Debug
    Drivers -->|"hardwareInterface"| MCU_Drivers
    Current -->|"hardwareInterface"| MCU_Current
    Examples -->|"demonstrates"| FOC

    click FOC "https://github.com/simplefoc/arduino-foc/blob/master/src/common/base_classes/FOCMotor.cpp"
    click FOC "https://github.com/simplefoc/arduino-foc/blob/master/src/common/base_classes/FOCMotor.h"
    click FOC "https://github.com/simplefoc/arduino-foc/blob/master/src/common/foc_utils.cpp"
    click FOC "https://github.com/simplefoc/arduino-foc/blob/master/src/common/foc_utils.h"
    click Drivers "https://github.com/simplefoc/arduino-foc/tree/master/src/drivers"
    click Sensors "https://github.com/simplefoc/arduino-foc/tree/master/src/sensors"
    click Current "https://github.com/simplefoc/arduino-foc/tree/master/src/current_sense"
    click Debug "https://github.com/simplefoc/arduino-foc/tree/master/src/communication"
    click MCU_Drivers "https://github.com/simplefoc/arduino-foc/tree/master/src/drivers/hardware_specific"
    click MCU_Current "https://github.com/simplefoc/arduino-foc/tree/master/src/current_sense/hardware_specific"
    click Examples "https://github.com/simplefoc/arduino-foc/tree/master/examples"

    classDef core fill:#FFDDC1,stroke:#D2691E,stroke-width:2px;
    classDef comm fill:#C1FFD7,stroke:#008000,stroke-width:2px;
    classDef sensor fill:#C1DFFF,stroke:#00008B,stroke-width:2px;
    classDef driver fill:#F0E68C,stroke:#B8860B,stroke-width:2px;
    classDef currentsense fill:#FFC0CB,stroke:#FF69B4,stroke-width:2px;
    classDef hardwareimp fill:#E6E6FA,stroke:#800080,stroke-width:2px;
    classDef examples fill:#D3D3D3,stroke:#696969,stroke-width:2px;
```
