Merge pull request #13 from simplefoc/dev

Dev

Author: askuric

.gitignore

@@ -4,4 +4,6 @@
 _site
 Gemfile.lock
 node_modules
-.jekyll-cache
+.jekyll-cache
+bin/just-the-docs
+assets/images/.DS_Store

.jekyll-metadata

@@ -21,6 +21,9 @@ Build flags control the way the compiler generates the code for <span class="sim
 Flag | Architecture | Description
 --- | --- | ---
 `SIMPLEFOC_DISABLE_DEBUG` | All | set this to disable the entire debugging code
+`SIMPLEFOC_PWM_ACTIVE_HIGH` | STM32, RP2040 | sets PWM polarity on phase PWM outputs - default is active high (true) but can be set to false for active low polarity. Affects both high and low side in 6-PWM mode
+`SIMPLEFOC_PWM_LOWSIDE_ACTIVE_HIGH` | STM32, RP2040 | sets PWM polarity on low side phase PWM outputs - default is active high (true) but can be set to false for active low polarity. Affects only low side FETs in 6-PWM mode. No effect in other modes.
+`SIMPLEFOC_PWM_HIGHSIDE_ACTIVE_HIGH` | STM32, RP2040 | sets PWM polarity on high side phase PWM outputs - default is active high (true) but can be set to false for active low polarity. Affects only high side FETs in 6-PWM mode. No effect in other modes.
 `SIMPLEFOC_STM32_DEBUG` | STM32 | set to enable extra debug output for STM32 MCUs.
 `SIMPLEFOC_STM32_MAX_PINTIMERSUSED` | STM32 | maximum number of PWM pins configurable, default is 12 (up to 2x 6PWM, normally that's plenty)
 `SIMPLEFOC_SAMD_DEBUG` | SAMD21 / SAMD51 | set to enable extra debug output for SAMD MCUs.

docs/simplefoc_library/cheatsheet/build_flags.md

@@ -12,7 +12,7 @@ has_toc: false
 
 # Commander interface
 
-Commander is a simple and flexible interface monitoring, supervision, configuration and control using the G-code like communication protocol. The communication is based on `ASCII` character command ids which makes simple and efficient to parse on any mcu. After the command id has been received the function attached to this command is called and provided the remaining string of characters received which follows the command character. 
+Commander is a simple and flexible interface monitoring, supervision, configuration and control using the G-code like communication protocol. The communication is based on `ASCII` character command ids which makes simple and efficient to parse on any MCU. After the command id has been received the function attached to this command is called and provided the remaining string of characters received which follows the command character. 
 
 <img src="extras/Images/cmd_motor.gif" class="img100">
 <img src="extras/Images/cmd_motor_get.gif" class="img100">
@@ -166,7 +166,6 @@ void loop(){
 }
 ```
 Or maybe you wish to tune the velocity PID and you and change the target value of the motor and you wish to remove unnecessary memory overhead due to the other functionalities you do nto necessarily need, then your code could look something like:
-something like this:
 ```cpp
 BLDCMotor motor = .....
 Commander commander = ....

docs/simplefoc_library/code/communication/commander/index.md

@@ -25,7 +25,7 @@ Motion control interface in the `Commander` can be integrated in user's applicat
 
 
 ## Target setting in one line
-Commander interface enables the user to set the target value for the motion control as well as the limits at once. However different motion control strategies have different numbers of limits (angle, velocity, torque) so depending of the motion control mode used the behavior of the command will change:
+Commander interface enables the user to set the target value for the motion control as well as the limits at once. However different motion control strategies have different numbers of limits (angle, velocity, torque) so depending of the motion control mode used the behaviour of the command will change:
 
 This feature is available to the user if any one of the three interfaces is added to the `Commander`.
 

docs/simplefoc_library/code/communication/commander/motion.md

@@ -34,7 +34,7 @@ void loop(){
 }
 ```
 
-You will be able to configure (set and get) itfrom serial monitor:
+You will be able to configure (set and get) it from serial monitor:
 ```sh
 $ ?           # list available commands 
 A: my variable

docs/simplefoc_library/code/communication/commander/scalar.md

@@ -63,7 +63,7 @@ step_dir.attach(&my_value);
 ```
 
 <blockquote class="warning"><p class="heading">⚠️ BEWARE: Suboptimal performance</p>
-The simplest forms of communication such as step/dir are designed to be handled in hardware and software, interrupt based, implementation of these communication interfaces is usually not the optimal solution. It will provide the user a good base for testing purposes, but it is hard guarantee long-term robustness.  
+The simplest forms of communication such as step/dir are designed to be handled in hardware and software, interrupt based, implementation of these communication interfaces is usually not the optimal solution. It will provide the user a good base for testing purposes, but it is hard to guarantee long-term robustness.  
 </blockquote>
 
 

docs/simplefoc_library/code/communication/step_dir.md

@@ -9,8 +9,11 @@ grand_grand_parent: Arduino <span class="simple">Simple<span class="foc">FOC</sp
 ---
 
 # High-side current sensing
+
 High-side current sensing is probably the least common current sensing technique form the three discussed in this library. The main reason why is because it requires high-voltage supporting amplifiers. The shunt resistors are placed in between high-side mosfets and the DC power supply voltage, making the amplifiers always have high voltages on their terminals. The other drawback of this approach is that since the current passing through the shunt resistors is phase current only if the  corresponding high side mosfet is on we can only measure it in those moments. The PWM frequency is usually 20 to 50 kHz, which means that the high-side mosfets turns on and off 20,000 to 50,000 times per second, therefore the synchronization in between PWM setting and ADC acquisition is very very important.
 
-High-side current sensing will be implemented later in the process, once when inline and low-side sensing is supported. The main issue at the moment is very hardware specific synchronisation procedure of the PWM generation and ADC triggering. Therefore it is possible that this implantation will be done one MCU architecture at the time. 
+High-side current sensing will be implemented later in the process, once when inline and low-side sensing is supported. The main issue at the moment is very hardware specific synchronisation procedure of the PWM generation and ADC triggering. Therefore it is possible that this implementation will be done one MCU architecture at a time.
+
+
 <img src="extras/Images/high-side.png" class="width50">
 <img src="extras/Images/high_side_sync.png" class="width40">

docs/simplefoc_library/code/current_sense/high_side.md

@@ -20,7 +20,7 @@ Arduino <span class="simple">Simple<span class="foc">FOC</span>library</span> ha
 
 <img src="extras/Images/comparison_cs.png" class="width40">
 
-up to this moment ( [check the releases <i class="fa fa-tag"></i>](https://github.com/simplefoc/Arduino-FOC/releases) ), Arduino <span class="simple">Simple<span class="foc">FOC</span>library</span> supports in-line current sensing for almost all platforms and low-side current sensing on ESP32 boards, stm32 (f1, f4 and g4 families - one motor), samd21 (one motor) and on the stm32 based B_G431B_ESC1 boards (one motor). 
+up to this moment ( [check the releases <i class="fa fa-tag"></i>](https://github.com/simplefoc/Arduino-FOC/releases) ), Arduino <span class="simple">Simple<span class="foc">FOC</span>library</span> supports in-line current sensing for almost all platforms and low-side current sensing on ESP32 boards, stm32 (f1, f4 and g4 families - one motor), SAMD21 (one motor) and on the STM32 based B-G431B-ESC1 boards (one motor). 
 
 Each one of the current sensing classes will implement all the necessary functionalities for simple and robust implementation of FOC algorithm:
 - Hardware config
@@ -31,7 +31,7 @@ Each one of the current sensing classes will implement all the necessary functio
   - Adaptive alignment with driver phases
 - Reading the phase currents
   - Calculation of the current vector magnitude 
-  - Calculation of the FOC d and q currents 
+  - Calculation of the FOC D and Q currents 
 
 Each of the implemented classes can be used as stand-alone classes and they can be used to read current values on BLDC driver outputs out of scope of the Arduino <span class="simple">Simple<span class="foc">FOC</span>library</span>, see example codes in `utils > current_sense_test`.
 In order for FOC algorithm to work the current sense classes are linked to a `BLDCMotor` class which uses the driver to read the FOC currents.   
@@ -63,4 +63,5 @@ 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).

docs/simplefoc_library/code/current_sense/index.md

@@ -10,27 +10,26 @@ grand_grand_parent: Arduino <span class="simple">Simple<span class="foc">FOC</sp
 
 # In-line current sensing
 
-Inline current sensing technique is the simplest one to use and the most precise one. The shunt resistors are placed in-line with motor phases and the current measured on these shunt resistors will be motor phase current regardless of the state of the PWM duty cycle. This implementation is therefore very suitable for Arduino devices due to the fact that adc can be sampled at any time to read the current and the adc acquisition duration is as important as for the other current sensing approaches. The downside of this approach is the hardware, this current sensing architecture requirers high-precision bidirectional amplifiers with much better PWM rejection than the regular low-side or high-side amplifiers. 
+Inline current sensing technique is the simplest one to use and the most precise one. The shunt resistors are placed in-line with motor phases and the current measured on these shunt resistors will be motor phase current regardless of the state of the PWM duty cycle. This implementation is therefore very suitable for Arduino devices due to the fact that adc can be sampled at any time to read the current and the adc acquisition duration is not as important as for the other current sensing approaches. The downside of this approach is the hardware, this current sensing architecture requires high-precision bidirectional amplifiers with much better PWM rejection than the regular low-side or high-side amplifiers. 
 
 <img src="extras/Images/in-line.png" class="width60"><img src="extras/Images/comparison_cs.png" class="width30">
 
 
 ## Current sensing support per MCU architecture
 
-In-line current sensing is currently supported for almost all MCU architectures supported by the <span class="simple">Simple<span class="foc">FOC</span>library</span>. Only not supported architecture is teh ESP8266 which does not have 2 ADC pins, making it unable to run FOC. 
+In-line current sensing is currently supported for almost all MCU architectures supported by the <span class="simple">Simple<span class="foc">FOC</span>library</span>. The only not supported architecture is the ESP8266 which does not have 2 ADC pins, making it unable to run FOC. 
 
 MCU | In-line Current sensing
 --- | --- 
 Arduino (8-bit) | ✔️ 
 Arduino DUE  | ✔️ 
-stm32  | ✔️ 
-stm32 B_G431B_ESC1 | ❌ 
-esp32/esp32s3 |✔️ 
-esp32s2/esp32c3 |❌ 
-esp8266 | ❌  
-samd21 | ✔️  
-samd51 | ✔️  
-teensy | ✔️ 
+STM32  | ✔️ 
+STM32 B_G431B_ESC1 | ✔️ 
+ESP32 | ✔️ 
+ESP8266 | ❌  
+SAMD21 | ✔️  
+SAMD51 | ✔️  
+Teensy | ✔️ 
 Raspberry Pi Pico | ✔️ 
 Portenta H7 | ✔️ 
 
@@ -45,7 +44,7 @@ Portenta H7 | ✔️
 //  - phC   - C phase adc pin (optional)
 InlineCurrentSense current_sense  = InlineCurrentSense(0.01, 20, A0, A1, A2);
 ```
-To instantiate the inline current sensor using the <span class="simple">Simple<span class="foc">FOC</span>library</span> just create an instance of the class `InlineCurrentSense`. This class takes as a parameter shunt resistance value `shunt_resistor`, amplification gain `gain` and two or three ADC channel pins depending on the available measuring hardware that you might have. It is important to specify right adc channels for right driver/motor phase. So if your pin `A0` measures the phase current `A` and pin `A1` measures the phase current `B` make sure to put provide them to the constructor in that order. 
+To instantiate the inline current sensor using the <span class="simple">Simple<span class="foc">FOC</span>library</span> just create an instance of the class `InlineCurrentSense`. This class takes as a parameter shunt resistance value `shunt_resistor`, amplification gain `gain` and two or three ADC channel pins depending on the available measuring hardware that you might have. It is important to specify right adc channels for right driver/motor phase. So if your pin `A0` measures the phase current `A` and pin `A1` measures the phase current `B` make sure to provide them to the constructor in that order. 
 
 ### Measuring 2 out of 3 currents
 Field Oriented Control algorithm can run with both 2 or 3 phase current measurements.  If measuring 2 out of 3 currents, when defining your `InlineCurrentSense` class put the flag `_NC` (not connected) to the phase value you are not using.