Merge pull request #151 from simplefoc/dev

release v2.2.1

Author: askuric

.github/workflows/ccpp.yml

@@ -12,7 +12,8 @@ jobs:
           - arduino:sam:arduino_due_x                # arduino due
           - arduino:samd:nano_33_iot                 # samd21
           - adafruit:samd:adafruit_metro_m4          # samd51
-          - esp32:esp32:esp32doit-devkit-v1          # esm32
+          - esp32:esp32:esp32                        # esp32
+          - esp32:esp32:esp32s2                      # esp32s2
           - STM32:stm32:GenF1:pnum=BLUEPILL_F103C8   # stm32 bluepill
           - STM32:stm32:Nucleo_64:pnum=NUCLEO_F411RE # stm32 nucleo
           - arduino:mbed_rp2040:pico                 # rpi pico
@@ -36,15 +37,19 @@ jobs:
             platform-url: https://adafruit.github.io/arduino-board-index/package_adafruit_index.json
             sketch-names: single_full_control_example.ino
 
-          - arduino-boards-fqbn: esp32:esp32:esp32doit-devkit-v1 # esp32 
-            platform-url: https://dl.espressif.com/dl/package_esp32_index.json
+          - arduino-boards-fqbn: esp32:esp32:esp32s2 # esp32s2
+            platform-url: https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_dev_index.json
+            sketch-names: bldc_driver_3pwm_standalone.ino, stepper_driver_2pwm_standalone.ino, stepper_driver_4pwm_standalone 
+            
+          - arduino-boards-fqbn: esp32:esp32:esp32 # esp32 
+            platform-url: https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_dev_index.json
             sketch-names: esp32_position_control.ino, esp32_i2c_dual_bus_example.ino, esp32_current_control_low_side.ino, esp32_spi_alt_example.ino
 
           - arduino-boards-fqbn: STM32:stm32:GenF1:pnum=BLUEPILL_F103C8 # bluepill - hs examples
             platform-url: https://github.com/stm32duino/BoardManagerFiles/raw/master/STM32/package_stm_index.json 
             sketch-names: bluepill_position_control.ino, stm32_i2c_dual_bus_example.ino, stm32_spi_alt_example.ino
 
-          - arduino-boards-fqbn: STM32:stm32:Nucleo_64:pnum=NUCLEO_F411RE # one full example
+          - arduino-boards-fqbn: STM32:stm32:Nucleo_64:pnum=NUCLEO_F411RE # nucleo one full example
             platform-url: https://github.com/stm32duino/BoardManagerFiles/raw/master/STM32/package_stm_index.json 
             sketch-names: single_full_control_example.ino, stm32_spi_alt_example.ino
 

README.md

@@ -4,6 +4,7 @@
 ![Library Compile](https://github.com/simplefoc/Arduino-FOC/workflows/Library%20Compile/badge.svg)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![arduino-library-badge](https://www.ardu-badge.com/badge/Simple%20FOC.svg?)](https://www.ardu-badge.com/badge/Simple%20FOC.svg)
+[![status](https://joss.theoj.org/papers/4382445f249e064e9f0a7f6c1bb06b1d/status.svg)](https://joss.theoj.org/papers/4382445f249e064e9f0a7f6c1bb06b1d)
 
 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.
@@ -17,33 +18,30 @@ Therefore this is an attempt to:
    - See also [@byDagor](https://github.com/byDagor)'s *fully-integrated* ESP32 based board: [Dagor Brushless Controller](https://github.com/byDagor/Dagor-Brushless-Controller)
 
 
+
 <blockquote class="info">
-   <p class="heading">NEW RELEASE 📢: <span class="simple">Simple<span class="foc">FOC</span>library</span> v2.2 - <a href="https://github.com/simplefoc/Arduino-FOC/releases/tag/v2.2">see release</a></p>
+   <p class="heading">NEW RELEASE 📢: <span class="simple">Simple<span class="foc">FOC</span>library</span> v2.2.1 <a href="https://github.com/simplefoc/Arduino-FOC/releases/tag/v2.2.1">see release</a></p>
    <ul>
-   <li>Sensor floating point error bugfix (initial solution) #83, #37</li>
-   <li>Sensor class restructuring - <b>slight API change</b> - <a href="https://docs.simplefoc.com/sensors">docs</a></li>
-   <li>Restructured the generic code and simplified adding new mcus: <b>IMPORTANT: an additional compiler flag needed for PlatformIO</b> see <a href="https://github.com/simplefoc/Arduino-FOC/issues/99">issue</a> and <a href="https://docs.simplefoc.com/library_platformio">PlatformIO docs</a></li>
-   <li>Removed initial jump #110, #111</li>
-   <li>Double to float transformation of the code - performance increase by <a href="https://github.com/sDessens">@sDessens</a> (#100), <a href="https://github.com/KaSroka">@KaSroka</a> (#100)  </li>
-   <li> <a href="https://docs.simplefoc.com/docs_chinese"><b>Docs webiste translated to Chinese!</b></a> 🎉: Awesome work 😃 by <a href="https://github.com/MINQING1101">@MINQING1101</a>, <a href="https://github.com/Deng-ge-open-source">@Deng-ge-open-source</a> and <a href="https://github.com/mingggggggg">@mingggggggg</a></li>
-   <li>New MCU support - <a href="https://docs.simplefoc.com/microcontrollers">docs</a>
+      <li>Sensor class init bugfix <a href="https://github.com/simplefoc/Arduino-FOC/issues/121">#121</a></li>
+      <li>Voltage/current limit handling bugs <a href="https://github.com/simplefoc/Arduino-FOC/issues/118">#118</a></li>
+      <li>Added the new motion control interface to the commander <a href="https://docs.simplefoc.com/commander_target">see docs</a>
       <ul>
-         <li>Support for arduino leonardo #108 </li>
-         <li>Initial support for portenta h7 board in collaboration with <img src="https://docs.simplefoc.com/extras/Images/arduino.png" height="15px"><a href="https://www.arduino.cc/">Arduino</a></li>
-         <li>Initial support for esp8266</li>
+         <li>New target setting - possible to set the position, velocity and torque target at once</li>
+         <li>Separated the motion control interface from full motor callback - only motion control and torque control type, enable disable and target setting</li>
       </ul>
-   </li>
-   <li>Low side current sensing initial support - <a href="https://docs.simplefoc.com/current_sense">docs</a>
+      </li>
+      <li>New MCU support <a href="https://docs.simplefoc.com/microcontrollers">see docs</a>
       <ul>
-         <li>Initial support for stm32 B_G431B_ESC1 by <a href="https://github.com/sDessens">@sDessens</a>: PR #73</li>
-         <li>Initial support for samd21 by <a href="https://github.com/maxlem">@maxlem</a>: PR #79</li>
-         <li>Initial support for esp32 by <a href="https://github.com/maxlem">@byDagor</a></li>
-      </ul> 
-   </li>
-   </ul>
+        <li>NRF52 series mcus support by <a href="https://github.com/Polyphe">@Polyphe</a></li>
+        <li><b>esp32 arduino package transfer to v2.0.1+</b> - helpful <a href="https://github.com/simplefoc/Arduino-FOC/pull/92/149">PR#149</a> by <a href="https://github.com/samguns">samguns</a></li>
+        <li>Initial support for esp32s2 and esp32s3 - separation of the esp32 mcpwm and led implementation</li>
+      </ul>
+      </li>
+      <li>Generic sensor class - to implement a new sensor only implement one function <a href="https://docs.simplefoc.com/generic_sensor">see docs</a></li>
+      </ul>
 </blockquote>
 
-## Arduino *SimpleFOClibrary* v2.1
+## Arduino *SimpleFOClibrary* v2.2
 
 <p align="">
 <a href="https://youtu.be/Y5kLeqTc6Zk">
@@ -73,7 +71,7 @@ This video demonstrates the *Simple**FOC**library* basic usage, electronic conne
 
 <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>
 
-## Arduino *SimpleFOCShield* v2.0.3
+## Arduino *SimpleFOCShield* v2.0.4
 <p align="">
 <a href="https://youtu.be/G5pbo0C6ujE">
 <img src="https://docs.simplefoc.com/extras/Images/foc_shield_video.jpg"  height="320px">

examples/hardware_specific_examples/SimpleFOCShield/version_v2/single_full_control_example/single_full_control_example.ino

@@ -17,7 +17,7 @@ InlineCurrentSense current_sense = InlineCurrentSense(0.01, 50.0, A0, A2);
 
 // commander communication instance
 Commander command = Commander(Serial);
-void doTarget(char* cmd){ command.scalar(&motor.target, cmd); }
+void doMotion(char* cmd){ command.motion(&motor, cmd); }
 // void doMotor(char* cmd){ command.motor(&motor, cmd); }
 
 void setup() {
@@ -74,7 +74,7 @@ void setup() {
   motor.target = 2;
 
   // subscribe motor to the commander
-  command.add('T', doTarget, "target");
+  command.add('T', doMotion, "motion control");
   // command.add('M', doMotor, "motor");
 
   // Run user commands to configure and the motor (find the full command list in docs.simplefoc.com)

examples/motion_control/open_loop_motor_control/open_loop_position_example/open_loop_position_example.ino

@@ -18,18 +18,29 @@ float target_position = 0;
 // instantiate the commander
 Commander command = Commander(Serial);
 void doTarget(char* cmd) { command.scalar(&target_position, cmd); }
+void doLimit(char* cmd) { command.scalar(&motor.voltage_limit, cmd); }
+void doVelocity(char* cmd) { command.scalar(&motor.velocity_limit, cmd); }
 
 void setup() {
 
   // driver config
   // power supply voltage [V]
   driver.voltage_power_supply = 12;
+  // limit the maximal dc voltage the driver can set
+  // as a protection measure for the low-resistance motors
+  // this value is fixed on startup
+  driver.voltage_limit = 6;
   driver.init();
   // link the motor and the driver
   motor.linkDriver(&driver);
 
   // limiting motor movements
+  // limit the voltage to be set to the motor
+  // start very low for high resistance motors
+  // currnet = resistance*voltage, so try to be well under 1Amp
   motor.voltage_limit = 3;   // [V]
+  // limit/set the velocity of the transition in between 
+  // target angles
   motor.velocity_limit = 5; // [rad/s] cca 50rpm
   // open loop control config
   motor.controller = MotionControlType::angle_openloop;
@@ -39,6 +50,8 @@ void setup() {
 
   // add target command T
   command.add('T', doTarget, "target angle");
+  command.add('L', doLimit, "voltage limit");
+  command.add('V', doLimit, "movement velocity");
 
   Serial.begin(115200);
   Serial.println("Motor ready!");

examples/motion_control/open_loop_motor_control/open_loop_velocity_example/open_loop_velocity_example.ino

@@ -19,19 +19,26 @@ float target_velocity = 0;
 // instantiate the commander
 Commander command = Commander(Serial);
 void doTarget(char* cmd) { command.scalar(&target_velocity, cmd); }
+void doLimit(char* cmd) { command.scalar(&motor.voltage_limit, cmd); }
 
 void setup() {
 
   // driver config
   // power supply voltage [V]
   driver.voltage_power_supply = 12;
+  // limit the maximal dc voltage the driver can set
+  // as a protection measure for the low-resistance motors
+  // this value is fixed on startup
+  driver.voltage_limit = 6;
   driver.init();
   // link the motor and the driver
   motor.linkDriver(&driver);
 
   // limiting motor movements
+  // limit the voltage to be set to the motor
+  // start very low for high resistance motors
+  // currnet = resistance*voltage, so try to be well under 1Amp
   motor.voltage_limit = 3;   // [V]
-  motor.velocity_limit = 5; // [rad/s] cca 50rpm
 
   // open loop control config
   motor.controller = MotionControlType::velocity_openloop;
@@ -41,6 +48,7 @@ void setup() {
 
   // add target command T
   command.add('T', doTarget, "target velocity");
+  command.add('L', doLimit, "voltage limit");
 
   Serial.begin(115200);
   Serial.println("Motor ready!");

examples/utils/calibration/find_pole_pair_number/encoder/find_pole_pairs_number/find_pole_pairs_number.ino

@@ -73,6 +73,7 @@ void setup() {
   while(motor_angle <= pp_search_angle){
     motor_angle += 0.01f;
     motor.move(motor_angle);
+    _delay(1);
   }
   _delay(1000);
   // read the encoder value for 180

examples/utils/calibration/find_pole_pair_number/magnetic_sensor/find_pole_pairs_number/find_pole_pairs_number.ino

@@ -73,6 +73,7 @@ void setup() {
     motor_angle += 0.01f;
     sensor.update(); // keep track of the overflow
     motor.move(motor_angle);
+    _delay(1);
   }
   _delay(1000);
   // read the sensor value for 180

examples/utils/current_sense_test/generic_current_sense/generic_current_sense.ino

@@ -0,0 +1,59 @@
+/**
+ * An example code for the generic current sensing implementation
+*/
+#include <SimpleFOC.h>
+
+
+// user defined function for reading the phase currents
+// returning the value per phase in amps
+PhaseCurrent_s readCurrentSense(){
+  PhaseCurrent_s c;
+  // dummy example only reading analog pins
+  c.a = analogRead(A0);
+  c.b = analogRead(A1);
+  c.c = analogRead(A2); // if no 3rd current sense set it to 0
+  return(c);
+}
+
+// user defined function for intialising the current sense
+// it is optional and if provided it will be called in current_sense.init()
+void initCurrentSense(){
+  pinMode(A0,INPUT);
+  pinMode(A1,INPUT);
+  pinMode(A2,INPUT);
+}
+
+
+// GenericCurrentSense class constructor
+// it receives the user defined callback for reading the current sense
+// and optionally the user defined callback for current sense initialisation
+GenericCurrentSense current_sense = GenericCurrentSense(readCurrentSense, initCurrentSense);
+
+
+void setup() {
+  // if callbacks are not provided in the constructor 
+  // they can be assigned directly: 
+  //current_sense.readCallback = readCurrentSense;
+  //current_sense.initCallback = initCurrentSense;
+  
+  // initialise the current sensing
+  current_sense.init();
+
+  
+  Serial.begin(115200);
+  Serial.println("Current sense ready.");
+}
+
+void loop() {
+
+    PhaseCurrent_s currents = current_sense.getPhaseCurrents();
+    float current_magnitude = current_sense.getDCCurrent();
+
+    Serial.print(currents.a); // milli Amps
+    Serial.print("\t");
+    Serial.print(currents.b); // milli Amps
+    Serial.print("\t");
+    Serial.print(currents.c); // milli Amps
+    Serial.print("\t");
+    Serial.println(current_magnitude); // milli Amps
+}

examples/utils/sensor_test/generic_sensor/generic_sensor.ino

@@ -0,0 +1,51 @@
+/**
+ *  Generic sensor example code 
+ * 
+ * This is a code intended to demonstrate how to implement the generic sensor class 
+ * 
+ */
+
+#include <SimpleFOC.h>
+
+// sensor reading function example
+//  for the magnetic sensor with analog communication
+// returning an angle in radians in between 0 and 2PI
+float readSensor(){
+  return analogRead(A0)*_2PI/1024.0;
+}
+
+// sensor intialising function
+void initSensor(){
+  pinMode(A0,INPUT);
+}
+
+// generic sensor class contructor
+// - read sensor callback 
+// - init sensor callback (optional)
+GenericSensor sensor = GenericSensor(readSensor, initSensor);
+
+void setup() {
+  // monitoring port
+  Serial.begin(115200);
+
+  // if callbacks are not provided in the constructor 
+  // they can be assigned directly: 
+  //sensor.readCallback = readSensor;
+  //sensor.initCallback = initSensor;
+
+  sensor.init();
+
+  Serial.println("Sensor ready");
+  _delay(1000);
+}
+
+void loop() {
+  // iterative function updating the sensor internal variables
+  // it is usually called in motor.loopFOC()
+  sensor.update();
+
+  // display the angle and the angular velocity to the terminal
+  Serial.print(sensor.getAngle());
+  Serial.print("\t");
+  Serial.println(sensor.getVelocity());
+}

examples/utils/sensor_test/magnetic_sensors/magnetic_sensor_i2c/magnetic_sensor_i2c_dual_bus_examples/esp32_i2c_dual_bus_example/esp32_i2c_dual_bus_example.ino

@@ -18,7 +18,7 @@ void setup() {
 
   // Normally SimpleFOC will call begin for i2c but with esp32 begin() is the only way to set pins!
   // It seems safe to call begin multiple times
-  Wire1.begin(19, 23, 400000);
+  Wire1.begin(19, 23, (uint32_t)400000);
 
   sensor0.init();
   sensor1.init(&Wire1);

keywords.txt

@@ -22,6 +22,8 @@ LowsideCurrentSense	KEYWORD1
 CurrentSense	KEYWORD1   
 Commander	KEYWORD1   
 StepDirListener	KEYWORD1   
+GenericCurrentSense	KEYWORD1   
+GenericSensor	KEYWORD1   
 
 
 initFOC	KEYWORD2
@@ -102,6 +104,8 @@ lpf	KEYWORD2
 motor	KEYWORD2
 handlePWM	KEYWORD2
 enableInterrupt	KEYWORD2
+readCallback	KEYWORD2
+initCallback	KEYWORD2
 
 
 
@@ -118,6 +122,7 @@ pullup	KEYWORD2
 quadrature	KEYWORD2
 foc_modulation	KEYWORD2
 target	KEYWORD2
+motion	KEYWORD2
 pwm_frequency	KEYWORD2
 dead_zone	KEYWORD2
 gain_a	KEYWORD2

library.properties

@@ -1,5 +1,5 @@
 name=Simple FOC
-version=2.2
+version=2.2.1
 author=Simplefoc <[email protected]>
 maintainer=Simplefoc <[email protected]>
 sentence=A library demistifying FOC for BLDC motors