SimpleFOClibrary - Simple Field Oriented Control (FOC) library

A Cross-Platform FOC implementation for BLDC and Stepper motors
based on the Arduino IDE and PlatformIO

We live in very exciting times 😃! BLDC motors are entering the hobby community more and more and many great projects have already emerged leveraging their far superior dynamics and power capabilities. These motors have numerous advantages over regular DC motors but they have one big disadvantage, the complexity of control. Even though it has become relatively easy to design and manufacture PCBs and create our own hardware solutions for driving BLDC motors, the proper low-cost solutions have been challenging to develop. One of the reasons for this is the apparent complexity of writing the driving algorithms, Field Oriented Control (FOC) being one of the most efficient ones. The solutions that can be found online are almost exclusively very specific for certain hardware configurations and microcontroller architectures. Similar to BLDCs, Stepper motors can hugely benefit from FOC control, but the solutions for FOC controlled stepper motors are even more scarce.
Therefore this is an attempt to:

• 🎯 Demystify FOC algorithm and make a robust but simple Arduino library: Arduino SimpleFOClibrary
  • Support as many motor + sensor + driver + mcu combinations out there
  • Make transitioning from one hardware combination to another as seamless as possible
• 🎯 Develop modular and easy to use FOC supporting driver boards
  • For official driver boards see SimpleFOCBoards
  • Many many more boards developed by the community members, see SimpleFOC Community

NEXT RELEASE 📢 : SimpleFOClibrary v2.4.0

• STM32

  • Added support for ADC reads in addition to Lowside current sense #506
  • Added support for multiple motors low-side CS (one per ADC) with ADC current sensing #503
  • BG341 low-side current sense sync was lost in v2.3.5 - fixed #482

• ESP32

  • Many ESP32 safety optimisations by @uLipe: #490,#491,#492,#493,#495
  • Better ADC-Timer alignement for more stable current sensing See this commit
  • Now compiles for all v3.x arduino-esp32 versions (v2.3.5 was compatible with v3.2.x)
  • adcRead small refactor - no more magic numbers

• Others

  • Teensy4 support for phase state setting #498 by @Ragiton
  • Added support for Arduino Nano Matter board by @silabs-szabog : #485

• Major New features

  • Add current and voltage feed forward terms to motor classes by @Copper280z in #454
  • Velocity Calculation rework by @Copper280z in #45
  • Motion control - docs
    • Added custom motion control mode - see in docs and in examples
    • Added angle_nocascade control mode for position control without velocity cascade - see in docs - #384
    • Now all the closed and open loop modes can be used with any torque control modes (voltage and current)
      • Ex. velocity_openloop with foc_current torque control
  • Torque control - docs
    • Added estimated_current torque control mode for model-based current estimation without current sensing - see in docs
    • Now we can easily switch between voltage and estimated current control

• Docs updates - see docs

  • Write the code page updated - see docs
  • Better step-by-step setup guides - see docs
  • New motion control documentation - see docs
  • New torque/FOC control documentation - see docs
  • Theory corner updated and extended - see docs
  • Library source updated and extended - see docs
  • Practical guides updated and extended - see docs
    • Motor parameter measurement guide - see docs
    • PID tuning guides - see docs

• Examples

  • align_current_sense.ino example added to the examples/utils/current_sense_test allowing to verify the alignment between the driver and the current sense phases

• Changelog

  • See the release notes for more details: see release
  • See the milestones: v2.3.6 (unreleased) and v2.4.0

Arduino SimpleFOClibrary

This video is a bit outdated but it demonstrates the SimpleFOClibrary basic usage, electronic connections and shows its capabilities.

Features

• Easy install:
  • Arduino IDE: Arduino Library Manager integration
  • PlatformIO
• Open-Source: Full code and documentation available on github
• Goal:
  • Support as many sensor + motor + driver + current sense combinations as possible
  • Make transitioning from one hardware combination to another as seamless as possible
  • Provide up-to-date and in-depth documentation with API references and examples
• Easy to setup and configure:
  • Easy hardware configuration
  • Each hardware component is a C++ object (easy to understand)
  • Easy tuning the control loops
  • Advanced control features: velocity and current feed-forward, improved velocity calculation
  • SimpleFOCStudio configuration GUI tool for real-time tuning and monitoring
  • Built-in communication and monitoring via Serial, I2C, or custom protocols
• Cross-platform:
  • Seamless code transfer from one microcontroller family to another
  • Supports multiple MCU architectures:
    • Arduino: UNO R4, UNO, MEGA, DUE, Leonardo, Nano, Nano33, MKR ....
    • STM32 (Nucleo, Bluepill, B-G431B-ESC1, H7 family, etc.)
    • ESP32 (ESP32, ESP32-S2, ESP32-S3, ESP32-C3, ESP32-C6)
    • Teensy (3.x, 4.x)
    • RP2040/RP2350 (Raspberry Pi Pico)
    • SAMD (Arduino Zero, MKR boards)
    • MBED (Portenta, Nano 33 BLE)
    • Silabs
    • many more ...

Documentation

Full API code documentation as well as example projects and step by step guides can be found on our docs website.

Getting Started

Depending on if you want to use this library as the plug and play Arduino library or you want to get insight in the algorithm and make changes there are two ways to install this code.

• Full library installation Docs
• PlatformIO Docs

Arduino SimpleFOClibrary installation to Arduino IDE

Arduino Library Manager

The simplest way to get hold of the library is directly by using Arduino IDE and its integrated Library Manager.

• Open Arduino IDE and start Arduino Library Manager by clicking: Tools > Manage Libraries....
• Search for Simple FOC library and install the latest version.
• Reopen Arduino IDE and you should have the library examples in File > Examples > Simple FOC.

Using Github website

• Go to the github repository
• Click first on Clone or Download > Download ZIP.
• Unzip it and place it in Arduino Libraries folder. Windows: Documents > Arduino > libraries.
• Reopen Arduino IDE and you should have the library examples in File > Examples > Simple FOC.

Using terminal

• Open terminal and run

cd #Arduino libraries folder
git clone https://github.com/simplefoc/Arduino-FOC.git

• Reopen Arduino IDE and you should have the library examples in File > Examples > Simple FOC.

Community and contributing

For all the questions regarding the potential implementation, applications, supported hardware and similar please visit our community forum or our discord server.

It is always helpful to hear the stories/problems/suggestions of people implementing the code and you might find a lot of answered questions there already!

Github Issues & Pull requests

Please do not hesitate to leave an issue if you have problems/advices/suggestions regarding the code!

Pull requests are welcome, but let's first discuss them in community forum!

If you'd like to contribute to this project but you are not very familiar with github, don't worry, let us know either by posting at the community forum , by posting a github issue or at our discord server.

If you are familiar, we accept pull requests to the dev branch!

Arduino code example

This is a simple Arduino code example implementing the velocity control program of a BLDC motor with encoder.

NOTE: This program uses all the default control parameters.

#include <SimpleFOC.h>

//  BLDCMotor( pole_pairs )
BLDCMotor motor = BLDCMotor(11);
//  BLDCDriver( pin_pwmA, pin_pwmB, pin_pwmC, enable (optional) )
BLDCDriver3PWM driver = BLDCDriver3PWM(9, 10, 11, 8);
//  Encoder(pin_A, pin_B, CPR)
Encoder encoder = Encoder(2, 3, 2048);
// channel A and B callbacks
void doA(){encoder.handleA();}
void doB(){encoder.handleB();}


void setup() {  
  // initialize encoder hardware
  encoder.init();
  // hardware interrupt enable
  encoder.enableInterrupts(doA, doB);
  // link the motor to the sensor
  motor.linkSensor(&encoder);
  
  // power supply voltage [V]
  driver.voltage_power_supply = 12;
  // initialise driver hardware
  driver.init();
  // link driver
  motor.linkDriver(&driver);

  // set control loop type to be used
  motor.controller = MotionControlType::velocity;
  // initialize motor
  motor.init();
  
  // align encoder and start FOC
  motor.initFOC();
}

void loop() {
  // FOC algorithm function
  motor.loopFOC();

  // velocity control loop function
  // setting the target velocity or 2rad/s
  motor.move(2);
}

You can find more details in the SimpleFOC documentation.

Example projects

Here are some of the SimpleFOClibrary and SimpleFOCShield application examples.

Citing the SimpleFOC

We are very happy that SimpleFOClibrary has been used as a component of several research project and has made its way to several scientific papers. We are hoping that this trend is going to continue as the project matures and becomes more robust! A short resume paper about SimpleFOC has been published in the Journal of Open Source Software:

SimpleFOC: A Field Oriented Control (FOC) Library for Controlling Brushless Direct Current (BLDC) and Stepper Motors.
A. Skuric, HS. Bank, R. Unger, O. Williams, D. González-Reyes
Journal of Open Source Software, 7(74), 4232, https://doi.org/10.21105/joss.04232

If you are interested in citing SimpleFOClibrary or some other component of SimpleFOCproject in your research, we suggest you to cite our paper:

@article{simplefoc2022,
  doi = {10.21105/joss.04232},
  url = {https://doi.org/10.21105/joss.04232},
  year = {2022},
  publisher = {The Open Journal},
  volume = {7},
  number = {74},
  pages = {4232},
  author = {Antun Skuric and Hasan Sinan Bank and Richard Unger and Owen Williams and David González-Reyes},
  title = {SimpleFOC: A Field Oriented Control (FOC) Library for Controlling Brushless Direct Current (BLDC) and Stepper Motors},
  journal = {Journal of Open Source Software}
}