Update

.github/workflows/ccpp.yml

@@ -16,6 +16,7 @@ jobs:
           - adafruit:samd:adafruit_metro_m4          # samd51
           - esp32:esp32:esp32doit-devkit-v1          # esp32
           - esp32:esp32:esp32s2                      # esp32s2
+          - esp32:esp32:esp32s3                      # esp32s3
           - STMicroelectronics:stm32:GenF1:pnum=BLUEPILL_F103C8   # stm32 bluepill
           - STMicroelectronics:stm32:Nucleo_64:pnum=NUCLEO_F411RE # stm32 nucleo
           - STMicroelectronics:stm32:GenF4:pnum=GENERIC_F405RGTX  # stm32f405 - odrive
@@ -26,7 +27,7 @@ jobs:
           - arduino-boards-fqbn: arduino:avr:uno # arudino uno - compiling almost all examples
             sketch-names: '**.ino'
             required-libraries: PciManager
-            sketches-exclude: bluepill_position_control, esp32_position_control, esp32_i2c_dual_bus_example, stm32_i2c_dual_bus_example, magnetic_sensor_spi_alt_example, osc_esp32_3pwm, osc_esp32_fullcontrol, nano33IoT_velocity_control, smartstepper_control,esp32_current_control_low_side, stm32_spi_alt_example, esp32_spi_alt_example, B_G431B_ESC1, odrive_example_spi, odrive_example_encoder, single_full_control_example, double_full_control_example
+            sketches-exclude: bluepill_position_control, esp32_position_control, esp32_i2c_dual_bus_example, stm32_i2c_dual_bus_example, magnetic_sensor_spi_alt_example, osc_esp32_3pwm, osc_esp32_fullcontrol, nano33IoT_velocity_control, smartstepper_control,esp32_current_control_low_side, stm32_spi_alt_example, esp32_spi_alt_example, B_G431B_ESC1, odrive_example_spi, odrive_example_encoder, single_full_control_example, double_full_control_example, stm32_current_control_low_side
 
           - arduino-boards-fqbn: arduino:sam:arduino_due_x # arduino due - one full example
             sketch-names: single_full_control_example.ino
@@ -51,6 +52,10 @@ jobs:
             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:esp32s3 # esp32s3
+            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
+
           - arduino-boards-fqbn: esp32:esp32:esp32doit-devkit-v1 # 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
@@ -68,11 +73,11 @@ jobs:
 
           - arduino-boards-fqbn: STMicroelectronics:stm32:GenF4:pnum=GENERIC_F405RGTX  # stm32f405 - odrive
             platform-url: https://github.com/stm32duino/BoardManagerFiles/raw/main/package_stmicroelectronics_index.json 
-            sketch-names: odrive_example_encoder.ino, odrive_example_spi.ino
+            sketch-names: odrive_example_encoder.ino, odrive_example_spi.ino, stm32_current_control_low_side.ino
 
           - arduino-boards-fqbn: STMicroelectronics:stm32:Nucleo_64:pnum=NUCLEO_F411RE # nucleo one full example
             platform-url: https://github.com/stm32duino/BoardManagerFiles/raw/main/package_stmicroelectronics_index.json 
-            sketch-names: single_full_control_example.ino, stm32_spi_alt_example.ino, sdouble_full_control_example.ino
+            sketch-names: single_full_control_example.ino, stm32_spi_alt_example.ino, sdouble_full_control_example.ino, stm32_current_control_low_side.ino
 
 
       # Do not cancel all jobs / architectures if one job fails

README.md

@@ -1,11 +1,17 @@
-# Arduino Simple Field Oriented Control (FOC) library 
-
+# 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 
 
 ![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)
+![GitHub release (latest by date)](https://img.shields.io/github/v/release/simplefoc/arduino-foc)
+![GitHub Release Date](https://img.shields.io/github/release-date/simplefoc/arduino-foc?color=blue)
+![GitHub commits since tagged version](https://img.shields.io/github/commits-since/simplefoc/arduino-foc/latest/dev)
+![GitHub commit activity (branch)](https://img.shields.io/github/commit-activity/m/simplefoc/arduino-foc/dev)
+
 [![arduino-library-badge](https://www.ardu-badge.com/badge/Simple%20FOC.svg?)](https://www.ardu-badge.com/badge/Simple%20FOC.svg)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![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.
 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>
@@ -18,54 +24,31 @@ Therefore this is an attempt to:
    - *Medium-power* BLDC driver (<30Amps): [Arduino <span class="simple">Simple<b>FOC</b>PowerShield</span> ](https://github.com/simplefoc/Arduino-SimpleFOC-PowerShield).
    - See also [@byDagor](https://github.com/byDagor)'s *fully-integrated* ESP32 based board: [Dagor Brushless Controller](https://github.com/byDagor/Dagor-Brushless-Controller)
 
-<h3>NEWS 📢: SimpleFOClibrary has been published in the Journal of Open Source Software</h3>
-<p>
-  <b>SimpleFOC</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>
-
-<blockquote class="info">
-   <p class="heading">NEW RELEASE 📢: <span class="simple">Simple<span class="foc">FOC</span>library</span> v2.2.2 <a href="https://github.com/simplefoc/Arduino-FOC/releases/tag/v2.2.2">see release</a></p>
-   <ul>
-      <li>GenericCurrentSense bugfix and testing</li>
-      <li>bugfix leonardo #170</li>
-      <li>bugfix - no index search after specifying natural direction</li>
-      <li>Low level API restructuring
-         <ul dir="auto">
-            <li>Driver API</li>
-            <li>Current sense API</li>
-         </ul>
-      </li>
-      <li>New debugging interface - <a href="https://docs.simplefoc.com/debugging">see in docs</a>
-         <ul dir="auto">
-            <li>Static class SimpleFOCDebug</li>
-         </ul>
-      </li>
-      <li>CurrentSense API change - added method <code class="highlighter-rouge">linkDriver()</code> - <a href="https://docs.simplefoc.com/current_sense">see in docs</a></li>
-      <li>Low-side current sensing - <a href="https://docs.simplefoc.com/low_side_current_sense">see in docs</a>
-         <ul dir="auto">
-            <li>ESP32 generic support for multiple motors</li>
-            <li>Added low-side current sensing support for stm32 - only one motor
-            <ul dir="auto">
-               <li>f1 family</li>
-               <li>f4 family</li>
-               <li>g4 family</li>
-            </ul>
-            </li>
-         </ul>
-      </li>
-      <li>New appraoch for current estimation for torque control using voltage - <a href="https://docs.simplefoc.com/voltage_torque_mode">see in docs </a>
-         <ul dir="auto">
-            <li>Support for motor KV rating - back emf estimation</li>
-            <li>Using motor phase resistance</li>
-         </ul>
-      </li>
-      <li>KV rating and phase resistance used for open-loop current limiting as well - <a href="https://docs.simplefoc.com/open_loop_motion_control">see in docs </a> </li>
-   </ul>
-</blockquote>
-
-## Arduino *SimpleFOClibrary* v2.2
+> NEW RELEASE 📢 : <span class="simple">Simple<span class="foc">FOC</span>library</span> v2.2.3
+> - stm32 low-side current sensing 
+>    - g4 supported
+>    - thoroughly tested f1/f4/g4 - [#187](https://github.com/simplefoc/Arduino-FOC/issues/187)
+>    - bg431b: added support for VBAT and TEMPERATURE readings [#222](https://github.com/simplefoc/Arduino-FOC/pull/222)
+> - bugfixing
+>    - leonardo
+>    - mega2560 [#190](https://github.com/simplefoc/Arduino-FOC/issues/190)
+>    - inline current sense without driver [#188](https://github.com/simplefoc/Arduino-FOC/issues/188)
+>    - bg431b support current sense fix [#210](https://github.com/simplefoc/Arduino-FOC/pull/210)
+>    - StepperDriver4PWM wrong init  [#182](https://github.com/simplefoc/Arduino-FOC/issues/182)
+>    - open loop back-emf vlotage issue [#219](https://github.com/simplefoc/Arduino-FOC/issues/219)
+>    - SAMD51 compile issue [#217](https://github.com/simplefoc/Arduino-FOC/issues/217)
+>    - ESP32-S3 compile issue [#198](https://github.com/simplefoc/Arduino-FOC/issues/198)
+>    - ESP32 compile issue [#208](https://github.com/simplefoc/Arduino-FOC/issues/208), [#207](https://github.com/simplefoc/Arduino-FOC/issues/207)
+>    - magnetic sensor direction finding more robust [#173](https://github.com/simplefoc/Arduino-FOC/issues/173), [#164](https://github.com/simplefoc/Arduino-FOC/pull/164)
+>    - `StepDirListener` improved timing [#169](https://github.com/simplefoc/Arduino-FOC/issues/169), [#209](https://github.com/simplefoc/Arduino-FOC/pull/209)
+> - API changes
+>    - `setPhaseVoltage` is now public function 
+>    - `getVelocity` can now be called as many times as necessary (it recalculates the velocity if the time between calls is longer then `minDeltaT` - default 0.1ms)
+>    - BG431 board can be used only with `LowsideCurrentSense` class!
+>    - `initFOC` fails if current sense not initialised
+>       - driver and curent sense have to be well initialised for `initFOC` to start
+>       - `cs.init()` and `driver.init()` return `1` if well initialised and `0` if failed 
+## Arduino *SimpleFOClibrary* v2.2.3
 
 <p align="">
 <a href="https://youtu.be/Y5kLeqTc6Zk">

examples/hardware_specific_examples/DRV8302_driver/stm32_current_control_low_side/stm32_current_control_low_side.ino

@@ -0,0 +1,167 @@
+/**
+ * Comprehensive BLDC motor control example using encoder and the DRV8302 board
+ *
+ * Using serial terminal user can send motor commands and configure the motor and FOC in real-time:
+ * - configure PID controller constants
+ * - change motion control loops
+ * - monitor motor variabels
+ * - set target values
+ * - check all the configuration values
+ *
+ * check the https://docs.simplefoc.com for full list of motor commands
+ *
+ */
+#include <SimpleFOC.h>
+
+// DRV8302 pins connections
+// don't forget to connect the common ground pin
+#define INH_A PA8
+#define INH_B PA9
+#define INH_C PA10
+
+#define EN_GATE PB7
+#define M_PWM PB4
+#define M_OC PB3
+#define OC_ADJ PB6
+#define OC_GAIN PB5
+
+#define IOUTA PA0
+#define IOUTB PA1
+#define IOUTC PA2
+
+// Motor instance
+BLDCMotor motor = BLDCMotor(7);
+BLDCDriver3PWM driver = BLDCDriver3PWM(INH_A, INH_B, INH_C, EN_GATE);
+
+// DRV8302 board has 0.005Ohm shunt resistors and the gain of 12.22 V/V
+LowsideCurrentSense cs = LowsideCurrentSense(0.005f, 12.22f, IOUTA, IOUTB, IOUTC);
+
+// encoder instance
+Encoder encoder = Encoder(PB14, PB15, 2048);
+
+// Interrupt routine intialisation
+// channel A and B callbacks
+void doA(){encoder.handleA();}
+void doB(){encoder.handleB();}
+
+
+// commander interface
+Commander command = Commander(Serial);
+void onMotor(char* cmd){ command.motor(&motor, cmd); }
+
+void setup() {
+
+  // initialize encoder sensor hardware
+  encoder.init();
+  encoder.enableInterrupts(doA, doB);
+  // link the motor to the sensor
+  motor.linkSensor(&encoder);
+
+  // DRV8302 specific code
+  // M_OC  - enable overcurrent protection
+  pinMode(M_OC,OUTPUT);
+  digitalWrite(M_OC,LOW);
+  // M_PWM  - enable 3pwm mode
+  pinMode(M_PWM,OUTPUT);
+  digitalWrite(M_PWM,HIGH);
+  // OD_ADJ - set the maximum overcurrent limit possible
+  // Better option would be to use voltage divisor to set exact value
+  pinMode(OC_ADJ,OUTPUT);
+  digitalWrite(OC_ADJ,HIGH);
+  pinMode(OC_GAIN,OUTPUT);
+  digitalWrite(OC_GAIN,LOW);
+
+
+  // driver config
+  // power supply voltage [V]
+  driver.voltage_power_supply = 19;
+  driver.pwm_frequency = 15000; // suggested under 18khz
+  driver.init();
+  // link the motor and the driver
+  motor.linkDriver(&driver);
+  // link current sense and the driver
+  cs.linkDriver(&driver);
+
+  // align voltage
+  motor.voltage_sensor_align = 0.5;
+
+  // control loop type and torque mode 
+  motor.torque_controller = TorqueControlType::voltage;
+  motor.controller = MotionControlType::torque;
+  motor.motion_downsample = 0.0;
+
+  // velocity loop PID
+  motor.PID_velocity.P = 0.2;
+  motor.PID_velocity.I = 5.0;
+  // Low pass filtering time constant 
+  motor.LPF_velocity.Tf = 0.02;
+  // angle loop PID
+  motor.P_angle.P = 20.0;
+  // Low pass filtering time constant 
+  motor.LPF_angle.Tf = 0.0;
+  // current q loop PID 
+  motor.PID_current_q.P = 3.0;
+  motor.PID_current_q.I = 100.0;
+  // Low pass filtering time constant 
+  motor.LPF_current_q.Tf = 0.02;
+  // current d loop PID
+  motor.PID_current_d.P = 3.0;
+  motor.PID_current_d.I = 100.0;
+  // Low pass filtering time constant 
+  motor.LPF_current_d.Tf = 0.02;
+
+  // Limits 
+  motor.velocity_limit = 100.0; // 100 rad/s velocity limit
+  motor.voltage_limit = 12.0;   // 12 Volt limit 
+  motor.current_limit = 2.0;    // 2 Amp current limit
+
+
+  // use monitoring with serial for motor init
+  // monitoring port
+  Serial.begin(115200);
+  // comment out if not needed
+  motor.useMonitoring(Serial);
+  motor.monitor_variables = _MON_CURR_Q | _MON_CURR_D; // monitor the two currents d and q
+  motor.monitor_downsample = 0;
+
+  // initialise motor
+  motor.init();
+
+  cs.init();
+  // driver 8302 has inverted gains on all channels
+  cs.gain_a *=-1;
+  cs.gain_b *=-1;
+  cs.gain_c *=-1;
+  motor.linkCurrentSense(&cs);
+
+  // align encoder and start FOC
+  motor.initFOC();
+
+  // set the inital target value
+  motor.target = 0;
+
+  // define the motor id
+  command.add('M', onMotor, "motor");
+
+  Serial.println(F("Full control example: "));
+  Serial.println(F("Run user commands to configure and the motor (find the full command list in docs.simplefoc.com) \n "));
+  Serial.println(F("Initial motion control loop is voltage loop."));
+  Serial.println(F("Initial target voltage 2V."));
+
+  _delay(1000);
+}
+
+
+void loop() {
+  // iterative setting FOC phase voltage
+  motor.loopFOC();
+
+  // iterative function setting the outter loop target
+  motor.move();
+
+  // monitoring the state variables
+  motor.monitor();
+
+  // user communication
+  command.run();
+}

library.properties

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

src/BLDCMotor.cpp

@@ -121,7 +121,15 @@ int  BLDCMotor::initFOC( float zero_electric_offset, Direction _sensor_direction
   // and checks the direction of measuremnt.
   _delay(500);
   if(exit_flag){
-    if(current_sense) exit_flag *= alignCurrentSense();
+    if(current_sense){ 
+      if (!current_sense->initialized) {
+        motor_status = FOCMotorStatus::motor_calib_failed;
+        SIMPLEFOC_DEBUG("MOT: Init FOC error, current sense not initialized");
+        exit_flag = 0;
+      }else{
+        exit_flag *= alignCurrentSense();
+      }
+    }
     else SIMPLEFOC_DEBUG("MOT: No current sense.");
   }
 
@@ -175,7 +183,7 @@ int BLDCMotor::alignSensor() {
     for (int i = 0; i <=500; i++ ) {
       float angle = _3PI_2 + _2PI * i / 500.0f;
       setPhaseVoltage(voltage_sensor_align, 0,  angle);
-	  sensor->update();
+	    sensor->update();
       _delay(2);
     }
     // take and angle in the middle
@@ -185,7 +193,7 @@ int BLDCMotor::alignSensor() {
     for (int i = 500; i >=0; i-- ) {
       float angle = _3PI_2 + _2PI * i / 500.0f ;
       setPhaseVoltage(voltage_sensor_align, 0,  angle);
-	  sensor->update();
+	    sensor->update();
       _delay(2);
     }
     sensor->update();
@@ -337,7 +345,7 @@ void BLDCMotor::move(float new_target) {
   //                        when switching to a 2-component representation.
   if( controller!=MotionControlType::angle_openloop && controller!=MotionControlType::velocity_openloop ) 
     shaft_angle = shaftAngle(); // read value even if motor is disabled to keep the monitoring updated but not in openloop mode
-  // get angular velocity 
+  // get angular velocity  TODO the velocity reading probably also shouldn't happen in open loop modes?
   shaft_velocity = shaftVelocity(); // read value even if motor is disabled to keep the monitoring updated
 
   // if disabled do nothing
@@ -628,9 +636,11 @@ float BLDCMotor::velocityOpenloop(float target_velocity){
 
   // use voltage limit or current limit
   float Uq = voltage_limit;
-  if(_isset(phase_resistance)) 
-    Uq = _constrain(current_limit*phase_resistance + voltage_bemf,-voltage_limit, voltage_limit);
-
+  if(_isset(phase_resistance)){
+    Uq = _constrain(current_limit*phase_resistance + fabs(voltage_bemf),-voltage_limit, voltage_limit);
+    // recalculate the current  
+    current.q = (Uq - fabs(voltage_bemf))/phase_resistance;
+  }
   // set the maximal allowed voltage (voltage_limit) with the necessary angle
   setPhaseVoltage(Uq,  0, _electricalAngle(shaft_angle, pole_pairs));
 
@@ -666,8 +676,11 @@ float BLDCMotor::angleOpenloop(float target_angle){
 
   // use voltage limit or current limit
   float Uq = voltage_limit;
-  if(_isset(phase_resistance)) 
-    Uq = _constrain(current_limit*phase_resistance + voltage_bemf,-voltage_limit, voltage_limit);
+  if(_isset(phase_resistance)){
+    Uq = _constrain(current_limit*phase_resistance + fabs(voltage_bemf),-voltage_limit, voltage_limit);
+    // recalculate the current  
+    current.q = (Uq - fabs(voltage_bemf))/phase_resistance;
+  }
   // set the maximal allowed voltage (voltage_limit) with the necessary angle
   // sensor precision: this calculation is OK due to the normalisation
   setPhaseVoltage(Uq,  0, _electricalAngle(_normalizeAngle(shaft_angle), pole_pairs));