v2.2.3

askuric · askuric · commit 123d81ed5c6a · 2022-10-15T11:31:18.000+02:00
diff --git a/_includes/js/custom.js b/_includes/js/custom.js
@@ -16,7 +16,9 @@ var libraires =[
     "LowsideCurrentSense.h",
     "InlineCurrentSense.h",
     "MySensor.h",
-    "Sensor.h"
+    "Sensor.h",
+    "SimpleFOCDrivers.h",
+    "MagneticSensorAS5048A.h"
 ]
 
 var defines =[
diff --git a/docs/boards/simplefoc_shield/fabrication/index.md b/docs/boards/simplefoc_shield/fabrication/index.md
@@ -2,7 +2,7 @@
 layout: default
 title: Board Fabrication
 description: "Arduino SimpleFOCShield board fabrication"
-parent: Arduino <span class="simple">Simple<span class="foc">FOC</span>Shield</span>
+parent: <span class="simple">Simple<span class="foc">FOC</span>Shield</span>
 grand_parent: <span class="simple">Simple<span class="foc">FOC</span> Boards</span>
 nav_order: 2
 permalink: /arduino_simplefoc_shield_fabrication
diff --git a/docs/boards/simplefoc_shield/fabrication/shield_fabrication_v1.md b/docs/boards/simplefoc_shield/fabrication/shield_fabrication_v1.md
@@ -3,7 +3,7 @@ layout: default
 title: v1.3.3
 description: "Arduino SimpleFOCShield board fabrication"
 parent: Board Fabrication
-grand_parent: Arduino <span class="simple">Simple<span class="foc">FOC</span>Shield</span>
+grand_parent: <span class="simple">Simple<span class="foc">FOC</span>Shield</span>
 grand_grand_parent: <span class="simple">Simple<span class="foc">FOC</span> Boards</span>
 nav_order: 1
 permalink: /arduino_simplefoc_shield_fabrication_v1
diff --git a/docs/boards/simplefoc_shield/fabrication/shield_fabrication_v2.md b/docs/boards/simplefoc_shield/fabrication/shield_fabrication_v2.md
@@ -3,7 +3,7 @@ layout: default
 title: v2.0.4
 description: "Arduino SimpleFOCShield board fabrication"
 parent: Board Fabrication
-grand_parent: Arduino <span class="simple">Simple<span class="foc">FOC</span>Shield</span>
+grand_parent: <span class="simple">Simple<span class="foc">FOC</span>Shield</span>
 grand_grand_parent: <span class="simple">Simple<span class="foc">FOC</span> Boards</span>
 nav_order: 2
 permalink: /arduino_simplefoc_shield_fabrication_v2
diff --git a/docs/boards/simplefoc_shield/getting_started/code.md b/docs/boards/simplefoc_shield/getting_started/code.md
@@ -5,7 +5,7 @@ parent: Getting Started
 description: "Writing the Arduino program for your SimpleFOCShield."
 nav_order: 3
 permalink: /foc_shield_code
-grand_parent: Arduino <span class="simple">Simple<span class="foc">FOC</span>Shield</span>
+grand_parent: <span class="simple">Simple<span class="foc">FOC</span>Shield</span>
 grand_grand_parent: <span class="simple">Simple<span class="foc">FOC</span> Boards</span>
 ---
 
diff --git a/docs/boards/simplefoc_shield/getting_started/connections.md b/docs/boards/simplefoc_shield/getting_started/connections.md
@@ -5,7 +5,7 @@ parent: Getting Started
 description: "Connecting SimpleFOCShield with your hardware."
 nav_order: 2
 permalink: /foc_shield_connect_hardware
-grand_parent: Arduino <span class="simple">Simple<span class="foc">FOC</span>Shield</span>
+grand_parent: <span class="simple">Simple<span class="foc">FOC</span>Shield</span>
 grand_grand_parent: <span class="simple">Simple<span class="foc">FOC</span> Boards</span>
 ---
 
diff --git a/docs/boards/simplefoc_shield/getting_started/index.md b/docs/boards/simplefoc_shield/getting_started/index.md
@@ -2,7 +2,7 @@
 layout: default
 title: Getting Started
 description: "Getting started with Arduino SimpleFOCShield"
-parent: Arduino <span class="simple">Simple<span class="foc">FOC</span>Shield</span>
+parent: <span class="simple">Simple<span class="foc">FOC</span>Shield</span>
 grand_parent: <span class="simple">Simple<span class="foc">FOC</span> Boards</span>
 nav_order: 1
 permalink: /arduino_simplefoc_shield_installation
diff --git a/docs/boards/simplefoc_shield/getting_started/soldering_pads/index.md b/docs/boards/simplefoc_shield/getting_started/soldering_pads/index.md
@@ -5,7 +5,7 @@ parent: Getting Started
 description: "Configuring your SimpleFOCShield by soldering the pads."
 nav_order: 1
 permalink: /pads_soldering
-grand_parent: Arduino <span class="simple">Simple<span class="foc">FOC</span>Shield</span>
+grand_parent: <span class="simple">Simple<span class="foc">FOC</span>Shield</span>
 grand_grand_parent: <span class="simple">Simple<span class="foc">FOC</span> Boards</span>
 has_children: true
 has_toc: false
diff --git a/docs/boards/simplefoc_shield/getting_started/soldering_pads/pads_v1.md b/docs/boards/simplefoc_shield/getting_started/soldering_pads/pads_v1.md
@@ -6,7 +6,7 @@ grand_parent: Getting Started
 description: "Configuring your SimpleFOCShield by soldering the pads."
 nav_order: 1
 permalink: /pads_soldering_v1
-grand_grand_parent: Arduino <span class="simple">Simple<span class="foc">FOC</span>Shield</span>
+grand_grand_parent: <span class="simple">Simple<span class="foc">FOC</span>Shield</span>
 grand_grand_grand_parent: <span class="simple">Simple<span class="foc">FOC</span> Boards</span>
 ---
 # Hardware configuration using soldering pads <br> <span class="simple">Simple<span class="foc">FOC</span>Shield</span> <small>v1</small>
diff --git a/docs/boards/simplefoc_shield/getting_started/soldering_pads/pads_v2.md b/docs/boards/simplefoc_shield/getting_started/soldering_pads/pads_v2.md
@@ -6,7 +6,7 @@ grand_parent: Getting Started
 description: "Configuring your SimpleFOCShield by soldering the pads."
 nav_order: 2
 permalink: /pads_soldering_v2
-grand_grand_parent: Arduino <span class="simple">Simple<span class="foc">FOC</span>Shield</span>
+grand_grand_parent: <span class="simple">Simple<span class="foc">FOC</span>Shield</span>
 grand_grand_grand_parent: <span class="simple">Simple<span class="foc">FOC</span> Boards</span>
 ---
 # Hardware configuration using soldering pads <br> <span class="simple">Simple<span class="foc">FOC</span>Shield</span> <small>v2</small>
diff --git a/docs/boards/simplefoc_shield/index.md b/docs/boards/simplefoc_shield/index.md
@@ -1,6 +1,6 @@
 ---
 layout: default
-title: Arduino <span class="simple">Simple<span class="foc">FOC</span>Shield</span>
+title: <span class="simple">Simple<span class="foc">FOC</span>Shield</span>
 parent: <span class="simple">Simple<span class="foc">FOC</span> Boards</span>
 description: "Arduino SimpleFOCShield board showcase."
 nav_order: 1
diff --git a/docs/simplefoc_library/code/current_sense/index.md b/docs/simplefoc_library/code/current_sense/index.md
@@ -42,7 +42,7 @@ The current sense code will be written in a way to support as many different dri
 Also make sure to follow our [community forum](https://community.simplefoc.com), a lot of discussions is being held about current sensing and its applications!
 
 ## Current sensing support per MCU architecture
-    
+   
 MCU | In-line | Low-side | High-side
 --- | --- |--- |--- 
 Arduino (8-bit) | ✔️ | ❌ |  ❌
@@ -51,14 +51,16 @@ stm32 (in general) | ✔️ | ❌ |  ❌
 stm32f1 family | ✔️ | ✔️ (one motor) |  ❌
 stm32f4 family | ✔️ | ✔️ (one motor) |  ❌
 stm32g4 family | ✔️ | ✔️ (one motor) |  ❌
-stm32 B_G431B_ESC1 | ✔️ | ✔️ |  ❌
-esp32 | ✔️ | ✔️ |  ❌
+stm32 B_G431B_ESC1 | ❌ | ✔️ (one motor) |  ❌
+esp32/esp32s3 | ✔️ | ✔️ |  ❌
+esp32s2/esp32c3 |  ✔️ | ❌ |  ❌ 
 esp8266 | ❌ | ❌ |  ❌ 
 samd21 | ✔️ | ✔️ (one motor) |  ❌ 
 samd51 | ✔️ | ❌ |  ❌ 
 teensy | ✔️ | ❌ |  ❌
 Raspberry Pi Pico | ✔️ | ❌ |  ❌
 Portenta H7 | ✔️ | ❌ |  ❌
+nRF52 | ✔️ | ❌ |  ❌
 
 ## Digging deeper
 For more theoretical explanations and source code implementations of the current sensing and its integration into the FOC and motion  check out the [digging deeper section](digging_deeper).
diff --git a/docs/simplefoc_library/code/current_sense/inline.md b/docs/simplefoc_library/code/current_sense/inline.md
@@ -24,8 +24,9 @@ MCU | In-line Current sensing
 Arduino (8-bit) | ✔️ 
 Arduino DUE  | ✔️ 
 stm32  | ✔️ 
-stm32 B_G431B_ESC1 | ✔️ 
-esp32 | ✔️ 
+stm32 B_G431B_ESC1 | ❌ 
+esp32/esp32s3 |✔️ 
+esp32s2/esp32c3 |❌ 
 esp8266 | ❌  
 samd21 | ✔️  
 samd51 | ✔️  
diff --git a/docs/simplefoc_library/code/current_sense/low_side.md b/docs/simplefoc_library/code/current_sense/low_side.md
@@ -31,8 +31,9 @@ stm32 (in general) |❌
 stm32f1 family | ✔️ (one motor) 
 stm32f4 family | ✔️ (one motor) 
 stm32g4 family | ✔️ (one motor) 
-stm32 B_G431B_ESC1 | ✔️ 
-esp32 |✔️ 
+stm32 B_G431B_ESC1 | ✔️ (one motor) 
+esp32/esp32s3 |✔️ 
+esp32s2/esp32c3 |❌ 
 esp8266 | ❌ 
 samd21 | ✔️/❌ (one motor, poorly tested) 
 samd51 | ❌ 
diff --git a/docs/simplefoc_library/code/drivers/bldc_driver/bldc_driver_3pwm.md b/docs/simplefoc_library/code/drivers/bldc_driver/bldc_driver_3pwm.md
@@ -119,6 +119,22 @@ Once when all the necessary configuration parameters are set the driver function
 driver.init();
 ```
 
+This function is responsible for:
+- determining and configuring the hardware timer for PWM generation
+- verifying that all provided pins can be used to generate PWM
+- configuring the PWM channels
+
+If for some reason the driver configuration fails this function will return `0` if everything went well the function will return `1`. So we suggest you to check if the init function was executed successfully before continuing
+```cpp
+Serial.print("Driver init ");
+// init driver
+if (driver.init())  Serial.println("success!");
+else{
+  Serial.println("failed!");
+  return;
+}
+```
+
 ## Step 3. Using `BLDCDriver3PWM` in real-time
 
 BLDC driver class was developed to be used with the <span class="simple">Simple<span class="foc">FOC</span>library</span> and to provide the abstraction layer for FOC algorithm implemented in the `BLDCMotor` class. But the `BLDCDriver3PWM` class can used as a standalone class as well and once can choose to implement any other type of control algorithm using the bldc driver.  
diff --git a/docs/simplefoc_library/code/drivers/bldc_driver/bldc_driver_6pwm.md b/docs/simplefoc_library/code/drivers/bldc_driver/bldc_driver_6pwm.md
@@ -186,6 +186,22 @@ Once when all the necessary configuration parameters are set the driver function
 driver.init();
 ```
 
+This function is responsible for:
+- determining and configuring the hardware timer for PWM generation
+- verifying that all provided pins can be used to generate PWM
+- configuring the PWM channels
+
+If for some reason the driver configuration fails this function will return `0` if everything went well the function will return `1`. So we suggest you to check if the init function was executed successfully before continuing
+```cpp
+Serial.print("Driver init ");
+// init driver
+if (driver.init())  Serial.println("success!");
+else{
+  Serial.println("failed!");
+  return;
+}
+```
+
 ## Step 3. Using  `BLDCDriver6PWM` in real-time
 
 BLDC driver class was developed to be used with the <span class="simple">Simple<span class="foc">FOC</span>library</span> and to provide the abstraction layer for FOC algorithm implemented in the `BLDCMotor` class. But the `BLDCDriver3PWM` class can used as a standalone class as well and once can choose to implement any other type of control algorithm using the bldc driver.  
diff --git a/docs/simplefoc_library/code/drivers/stepper_driver/stepper_driver_2pwm.md b/docs/simplefoc_library/code/drivers/stepper_driver/stepper_driver_2pwm.md
@@ -99,6 +99,22 @@ Once when all the necessary configuration parameters are set the driver function
 driver.init();
 ```
 
+This function is responsible for:
+- determining and configuring the hardware timer for PWM generation
+- verifying that all provided pins can be used to generate PWM
+- configuring the PWM channels
+
+If for some reason the driver configuration fails this function will return `0` if everything went well the function will return `1`. So we suggest you to check if the init function was executed successfully before continuing
+```cpp
+Serial.print("Driver init ");
+// init driver
+if (driver.init())  Serial.println("success!");
+else{
+  Serial.println("failed!");
+  return;
+}
+```
+
 ## Step 3. Using encoder in real-time
 
 BLDC driver class was developed to be used with the <span class="simple">Simple<span class="foc">FOC</span>library</span> and to provide the abstraction layer for FOC algorithm implemented in the `StepperMotor` class. But the `StepperDriver4PWM` class can used as a standalone class as well and once can choose to implement any other type of control algorithm using the bldc driver.  
diff --git a/docs/simplefoc_library/code/drivers/stepper_driver/stepper_driver_4pwm.md b/docs/simplefoc_library/code/drivers/stepper_driver/stepper_driver_4pwm.md
@@ -77,6 +77,22 @@ Once when all the necessary configuration parameters are set the driver function
 driver.init();
 ```
 
+This function is responsible for:
+- determining and configuring the hardware timer for PWM generation
+- verifying that all provided pins can be used to generate PWM
+- configuring the PWM channels
+
+If for some reason the driver configuration fails this function will return `0` if everything went well the function will return `1`. So we suggest you to check if the init function was executed successfully before continuing
+```cpp
+Serial.print("Driver init ");
+// init driver
+if (driver.init())  Serial.println("success!");
+else{
+  Serial.println("failed!");
+  return;
+}
+```
+
 ## Step 3. Using encoder in real-time
 
 BLDC driver class was developed to be used with the <span class="simple">Simple<span class="foc">FOC</span>library</span> and to provide the abstraction layer for FOC algorithm implemented in the `StepperMotor` class. But the `StepperDriver4PWM` class can used as a standalone class as well and once can choose to implement any other type of control algorithm using the bldc driver.  
diff --git a/docs/simplefoc_library/code/drivers_library.md b/docs/simplefoc_library/code/drivers_library.md
@@ -49,15 +49,15 @@ It is steadily growing, but at the moment we have:
 
 ## How can I use it?
 
-```c++
+```cpp
 #include "SimpleFOCDrivers.h"
 ```
 
 It is in the arduino library manager, called "Simple FOC Drivers". Install as normal for arduino libraries in Arduino IDE or PlatformIO.
 
 To use some code from the library, include the specific driver module you want. For example:
 
-```c++
+```cpp
 #include "encoders/as5048a/MagneticSensorAS5048A.h"
 ```
 
diff --git a/docs/simplefoc_library/code/motors/bldc_motors.md b/docs/simplefoc_library/code/motors/bldc_motors.md
@@ -237,12 +237,22 @@ motor.initFOC();
 <blockquote class="info"><p class="heading"> Can be skipped for openloop control!</p>If no sensor is attached this function will not really do anything, but you can still call it if necessary or more convenient. </blockquote>
 
 This function does several things:
+- Checks if driver (and current sense if available) are well initialised
 - Checks/modifies position sensor direction in respect to the motor's direction
 - Searches for encoder index if necessary
 - Finds the motor electrical offset in respect to the position sensor
 - Checks/modifies current sense pinout and gains signs if one available to make sure it aligned with the driver 
 
-This function is a final check function and it will disable your motor and display you a message what is wrong. (when using the [monitoring](monitoring) ). If everything is well configured, after the call of this function FOC is ready and our setup is done!  
+If for some reason the `initFOC` fails this function will return `0` and it will disable your motor and display you a message what is wrong (when using the [monitoring](monitoring) ). If everything is well configured, the call of this function will return `1` and the our setup is done, FOC is ready to be used! So we suggest you to check if the init function was executed successfully before continuing:
+
+```cpp
+// init current sense
+if (motor.initFOC())  Serial.println("FOC init success!");
+else{
+  Serial.println("FOC init failed!");
+  return;
+}
+```
 
 The alignment procedure will have to move your motor several times and might not be desirable behavior, therefore for most of the position sensors (except encodes) and current senses, this alignment procedure can be skipped by following the steps 6.1 an 6.2. 
 
diff --git a/docs/simplefoc_library/code/motors/stepper_motors.md b/docs/simplefoc_library/code/motors/stepper_motors.md
@@ -203,12 +203,22 @@ motor.initFOC();
 <blockquote class="info"><p class="heading"> Can be skipped for openloop control!</p>If no sensor is attached this function will not really do anything, but you can still call it if necessary or more convenient. </blockquote>
 
 This function does several things:
+- Checks if driver (and current sense if available) are well initialised
 - Checks/modifies position sensor direction in respect to the motor's direction
 - Searches for encoder index if necessary
 - Finds the motor electrical offset in respect to the position sensor
+- Checks/modifies current sense pinout and gains signs if one available to make sure it aligned with the driver 
 
-This function is a final check function and it will disable your motor and display you a message what is wrong. (when using the [monitoring](monitoring) ). If everything is well configured, after the call of this function FOC is ready and our setup is done!  
+If for some reason the `initFOC` fails this function will return `0` and it will disable your motor and display you a message what is wrong (when using the [monitoring](monitoring) ). If everything is well configured, the call of this function will return `1` and the our setup is done, FOC is ready to be used! So we suggest you to check if the init function was executed successfully before continuing:
 
+```cpp
+// init current sense
+if (motor.initFOC())  Serial.println("FOC init success!");
+else{
+  Serial.println("FOC init failed!");
+  return;
+}
+```
 The alignment procedure will have to move your motor several times and might not be desirable behavior, therefore for most of the position sensors (except encodes) and current senses, this alignment procedure can be skipped by following the steps 5.1. 
 
 ### Step 5.1 Skip alignment - position sensor
diff --git a/docs/simplefoc_library/code/sensors/encoder.md b/docs/simplefoc_library/code/sensors/encoder.md
@@ -255,6 +255,16 @@ class Encoder{
 }
 ```
 
+<blockquote markdown="1" class="info">
+<p class="heading" markdown="1">Calling `getVelocity` multiple times</p>
+When calling `getVelocity` it will only calculate the velocity if the elapsed time from the previous call is longer than the time specified in teh variable `min_elapsed_time` (default 100us). If the elapsed time from the last call is shorter than `min_elapsed_time` the function will return previously calculated value. Variable `min_elapsed_time` can be changed easily if necessary:
+
+```cpp
+encoder.min_elapsed_time = 0.0001; // 100us by default
+```
+</blockquote>
+
+
 Here is a quick example:
 ```cpp
 #include <SimpleFOC.h>
diff --git a/docs/simplefoc_library/code/sensors/generic.md b/docs/simplefoc_library/code/sensors/generic.md
@@ -59,6 +59,15 @@ class GenericSensor{
 }
 ```
 
+<blockquote markdown="1" class="info">
+<p class="heading" markdown="1">Calling `getVelocity` multiple times</p>
+When calling `getVelocity` it will only calculate the velocity if the elapsed time from the previous call is longer than the time specified in teh variable `min_elapsed_time` (default 100us). If the elapsed time from the last call is shorter than `min_elapsed_time` the function will return previously calculated value. Variable `min_elapsed_time` can be changed easily if necessary:
+
+```cpp
+sensor.min_elapsed_time = 0.0001; // 100us by default
+```
+</blockquote>
+
 Here is a quick example:
 ```cpp
 #include <SimpleFOC.h>
diff --git a/docs/simplefoc_library/code/sensors/hall_sensor.md b/docs/simplefoc_library/code/sensors/hall_sensor.md
@@ -34,6 +34,14 @@ sensor.pullup = Pullup::USE_INTERN;
 ```
 <blockquote class="warning"><p class="heading">Arduino Pullup 20kΩ</p> Be careful when using internal pullups, Arduino has relatively high valued pullups around 20kΩ, which means that you might have some problems for higher velocities (for shorted impulse durations). Recommended pull-up values are in between 1kΩ and 5kΩ.</blockquote>
 
+### Step 2.1 Velocity outlier removal
+
+From the release v2.2.3 `HallSensor` class implements the outlier removal for its velocity calculations. It is based on a simple principle where all the calculated velocities higher than a certain maximal expected velocity are considered to be an outlier. To modify the maximal expected motor velocity, you can modify the variable `velocity_max`. This variable is set to 1000rad/s by default which is a good starting point for most applications. Except if you are using very high performance motors, then 1000 rad/s (~10,000 rpm) could still be reachable by the motor in which case please increase this value to a number outside the motor's reach.
+
+```cpp
+// maximal expected velocity
+sensor.velocity_max = 1000; // 1000rad/s by default ~10,000 rpm
+```
 ## Step 3. Interrupt setup
 There are two ways you can run hall sensors with Simple FOC library.
 - Using [hardware external interrupt](#hardware-external-interrupt) 
@@ -181,6 +189,15 @@ class HallSensor{
 }
 ```
 
+<blockquote markdown="1" class="info">
+<p class="heading" markdown="1">Calling `getVelocity` multiple times</p>
+When calling `getVelocity` it will only calculate the velocity if the elapsed time from the previous call is longer than the time specified in teh variable `min_elapsed_time` (default 100us). If the elapsed time from the last call is shorter than `min_elapsed_time` the function will return previously calculated value. Variable `min_elapsed_time` can be changed easily if necessary:
+
+```cpp
+sensor.min_elapsed_time = 0.0001; // 100us by default
+```
+</blockquote>
+
 Here is a quick example using only hardware interrupts:
 ```cpp
 #include <SimpleFOC.h>
diff --git a/docs/simplefoc_library/code/sensors/magnetic/magnetic_sensor_analog.md b/docs/simplefoc_library/code/sensors/magnetic/magnetic_sensor_analog.md
@@ -83,6 +83,16 @@ class MagneticSensorAnalog{
 }
 ```
 
+<blockquote markdown="1" class="info">
+<p class="heading" markdown="1">Calling `getVelocity` multiple times</p>
+When calling `getVelocity` it will only calculate the velocity if the elapsed time from the previous call is longer than the time specified in teh variable `min_elapsed_time` (default 100us). If the elapsed time from the last call is shorter than `min_elapsed_time` the function will return previously calculated value. Variable `min_elapsed_time` can be changed easily if necessary:
+
+```cpp
+sensor.min_elapsed_time = 0.0001; // 100us by default
+```
+</blockquote>
+
+
 Here is a quick example for AS5600 magnetic sensor using it's analog output:
 ```cpp
 #include <SimpleFOC.h>
diff --git a/docs/simplefoc_library/code/sensors/magnetic/magnetic_sensor_i2c.md b/docs/simplefoc_library/code/sensors/magnetic/magnetic_sensor_i2c.md
diff --git a/docs/simplefoc_library/code/sensors/magnetic/magnetic_sensor_pwm.md b/docs/simplefoc_library/code/sensors/magnetic/magnetic_sensor_pwm.md
diff --git a/docs/simplefoc_library/code/sensors/magnetic/magnetic_sensor_spi.md b/docs/simplefoc_library/code/sensors/magnetic/magnetic_sensor_spi.md
diff --git a/docs/simplefoc_library/hardware/mcus/index.md b/docs/simplefoc_library/hardware/mcus/index.md
diff --git a/docs/simplefoc_library/index.md b/docs/simplefoc_library/index.md
diff --git a/index.md b/index.md
