Home

Awesome

SimpleFOClibrary - Simple Field Oriented Control (FOC) library <br>

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

AVR build STM32 build ESP32 build RP2040 build SAMD build Teensy build

GitHub release (latest by date) GitHub Release Date GitHub commits since tagged version GitHub commit activity (branch)

arduino-library-badge PlatformIO Registry License: MIT status

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. BLDC 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 are yet to come. One of the reasons for this is the apparent complexity of writing the BLDC driving algorithms, Field oriented control (FOC) being an example of one of the most efficient ones. The solutions that can be found on-line are almost exclusively very specific for certain hardware configuration and the microcontroller architecture used. Additionally, most of the efforts at this moment are still channeled towards the high-power applications of the BLDC motors and proper low-cost and low-power FOC supporting boards are very hard to find today and even may not exist. <br> Therefore this is an attempt to:

NEXT RELEASE 📢 : <span class="simple">Simple<span class="foc">FOC</span>library</span> v2.3.4

Arduino SimpleFOClibrary v2.3.4

<p align=""> <a href="https://youtu.be/Y5kLeqTc6Zk"> <img src="https://docs.simplefoc.com/extras/Images/youtube.png" height="320px"> </a> </p>

This video demonstrates the SimpleFOClibrary basic usage, electronic connections and shows its capabilities.

Features

<p align=""> <img src="https://docs.simplefoc.com/extras/Images/uno_l6234.jpg" height="170px"> <img src="https://docs.simplefoc.com/extras/Images/hmbgc_v22.jpg" height="170px"> <img src="https://docs.simplefoc.com/extras/Images/foc_shield_v13.jpg" height="170px"></p>

Documentation

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

image

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.

Using Github website

Using terminal

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

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.

<p align="center"> <a href="https://youtu.be/Ih-izQyXJCI"> <img src="https://docs.simplefoc.com/extras/Images/youtube_pendulum.png" height="200px" > </a> <a href="https://youtu.be/xTlv1rPEqv4"> <img src="https://docs.simplefoc.com/extras/Images/youtube_haptic.png" height="200px" > </a> <a href="https://youtu.be/RI4nNMF608I"> <img src="https://docs.simplefoc.com/extras/Images/youtube_drv8302.png" height="200px" > </a> <a href="https://youtu.be/zcb86TRxTxc"> <img src="https://docs.simplefoc.com/extras/Images/youtube_stepper.png" height="200px" > </a> </p>

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:

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

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}
}