based on the Arduino IDE and PlatformIO
A Cross-Platform FOC implementation for BLDC and Stepper motors
We live in very exciting times
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
🎯 Develop a modular FOC supporting BLDC driver boards:- NEW
📢 : Minimalistic BLDC driver (<3Amps) : SimpleFOCMini . - Low-power gimbal driver (<5Amps) : Arduino SimpleFOCShield.
- Medium-power BLDC driver (<30Amps): Arduino SimpleFOCPowerShield .
- See also @byDagor's fully-integrated ESP32 based board: Dagor Brushless Controller
- NEW
NEW RELEASE
📢 : SimpleFOClibrary v2.3.0
- Arduino Mega 6pwm more timers supported
- Arduino boards - frequency change support either 32kHz or 4kHz
- Arduino Uno - synched timers in 3pwm and 6pwm mode #71
- Teensy 3.x initial support for 6pwm
- Teensy 4.x initial support for 6pwm
- Example for v3.1 SimpleFOCShield
- RP2040 compatibility for earlehillpower core #234 #236
- More flexible monitoring API
- start, end and separator characters
- decimal places (settable through commander)
- Added machine readable verbose mode in
Commander
#233- SimpleFOCWebController - Web based user interface for SimpleFOC by @geekuillaume - webcontroller.simplefoc.com
- bugfix -
MagneticSensorPWM
multiple occasions - #258- bugfix - current sense align - added offset exchange when exchanging pins
- bugfix - trapezoid 150 fixed
- bugfix - 4pwm on ESP8266 #224
- Additional
InlineCurrentSense
andLowsideCurrentSense
constructor using milliVolts per Amp #253- STM32L4xx current sense support by @Triple6 (discord) #257
- phase disable in 6pwm mode
- stm32 - software and hardware 6pwm
- atmega328
- atmega2560
- Lag compensation using motor inductance #246
- current control through voltage torque mode enhancement
- extended
BLDCMotor
andStepperMotor
constructors to receive the inductance paramerer- can also be set using
motor.phase_inductance
or throughCommander
Arduino SimpleFOClibrary v2.3
This video 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 combination as possible.
- Provide the up-to-date and in-depth documentation with API references and the examples
- Easy to setup and configure:
- Easy hardware configuration
- Each hardware component is a C++ object (easy to understand)
- Easy tuning the control loops
- SimpleFOCStudio configuration GUI tool
- Built-in communication and monitoring
- Cross-platform:
- Seamless code transfer from one microcontroller family to another
- Supports multiple MCU architectures:
- Arduino: UNO, MEGA, DUE, Leonardo ....
- STM32
- ESP32
- Teensy
- 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.
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 porject 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.
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}
}