FEAT added stepper and pwm freq docs

Author: askuric

_includes/js/custom.js

@@ -5,6 +5,7 @@ var libraires =[
     "Encoder.h",
     "FOCutils.h",
     "BLDCMotor.h",
+    "StepperMotor.h",
     "HallSensor.h",
     "MagneticSensor.h",
     "MagneticSensorSPI.h",
@@ -36,6 +37,7 @@ var defines =[
 
 var classNames = [
     "BLDCMotor",
+    "StepperMotor",
     "Encoder",
     "MagneticSensor",
     "MagneticSensorSPI",

docs/simplefoc_library/code/communication.md

@@ -144,7 +144,7 @@ motor.command(serialReceiveUserCommand());
 MagneticSensorSPI AS5x4x = MagneticSensorSPI(10, 14, 0x3FFF);
 
 // motor instance
-BLDCMotor motor = BLDCMotor(9, 5, 6, 11, 8);
+StepperMotor motor = StepperMotor(9, 10, 5, 6, 50);
 
 void setup() {
 
@@ -153,9 +153,6 @@ void setup() {
   // link the motor to the sensor
   motor.linkSensor(&AS5x4x);
 
-  // choose FOC modulation
-  motor.foc_modulation = FOCModulationType::SpaceVectorPWM;
-
   // power supply voltage [V]
   motor.voltage_power_supply = 12;
 

docs/simplefoc_library/code/index.md

@@ -101,13 +101,19 @@ Sensor is initialized hardware pins by running `sensor.init()`.
 For full documentation of the setup and all configuration parameters please visit the <a href="sensors"> position sensors docs</a>.
 
 
-## Step 2. <a href="motor_initialization" class="remove_dec"> BLDC motor setup</a>
-After the position sensor we proceed to initializing and configuring the BLDC motor handled by `BLDCMotor` class and it is defined by setting:
-- phase `A`, `B` and `C` pin number: `9`,`5` and `6`
-- `pole_pairs` number of the motor: `11`
-- `enable` pin number *(optional)*: `8`
-
-Here is a how it looks in code:
+## Step 2. <a href="motor_initialization" class="remove_dec"> Motor setup</a>
+After the position sensor we proceed to initializing and configuring the motor. The library supports BLDC motors handled by `BLDCMotor` class and stepper motors handled by `StepperMotor` class. `BLDCMotor` class instantiated by providing:
+- phase `A`, `B` and `C` pin number
+- `pole_pairs` number of the motor
+- `enable` pin number *(optional)*
+
+And `StepperMotor` it is defined by setting:
+- phase `1A`, `1B` pin number
+- phase `2A`, `2B` pin number
+- `pole_pairs` number of the motor
+- `enable1` and `enable2` pin numbers *(optional)*
+
+In this example we will use BLDC motor:
 ```cpp
 #include <SimpleFOC.h>
 
@@ -189,7 +195,7 @@ For full documentation of the setup and all configuration parameters please visi
 
 ## Step 4. <a href="monitoring" class="remove_dec"> Monitoring</a>
 
-`BLDCMotor` class enables optional monitoring functionality. For enabling the monitoring feature make sure you call `motor.useMonitoring()` with the `Serial` port instance you want to output to. It uses `Serial` class to output motor initialization status during the `motor.init()` function, as well as in `motor.initFOC()` function.
+`BLDCMotor` and `StepperMotor` classes provide monitoring functionality. For enabling the monitoring feature make sure you call `motor.useMonitoring()` with the `Serial` port instance you want to output to. It uses `Serial` class to output motor initialization status during the `motor.init()` function, as well as in `motor.initFOC()` function.
 
 If you are interested to output motors state variables in real-time (even though it will impact the performance - writing the Serial port is slow!) add the `motor.monitor()` function call to the Arduino `loop()` function. 
 
@@ -249,7 +255,7 @@ void setup() {
   // link motor and sensor
   // configure motor
 
-  // use monitoring with the BLDCMotor
+  // use monitoring
   Serial.begin(115200);
   // monitoring port
   motor.useMonitoring(Serial);

docs/simplefoc_library/code/monitoring.md

@@ -10,7 +10,7 @@ grand_parent: Arduino <span class="simple">Simple<span class="foc">FOC</span>lib
 
 # Monitoring functionality
 
-`BLDCMotor` class supports monitoring using `Serial` port which is enabled by:
+Both `BLDCMotor` and `StepperMotor` classes support monitoring using `Serial` port which is enabled by:
 ```cpp
 motor.useMonitoring(Serial);
 ```

docs/simplefoc_library/code/motor.md

@@ -1,40 +1,52 @@
 ---
 layout: default
-title: BLDC Motor
+title: Motor & Driver
 nav_order: 2
 parent: Using the Code
 permalink: /motor_initialization
 grand_parent: Arduino <span class="simple">Simple<span class="foc">FOC</span>library</span>
 ---
 
-# Motor setup
+# Motor & Driver configuration
 
 <div class="width60">
-<img src="extras/Images/mot2.jpg" style="width:24%;display:inline"><img src="extras/Images/bigger.jpg" style="width:24%;display:inline"><img src="extras/Images/big.jpg" style="width:24%;display:inline"><img src="extras/Images/mot.jpg" style="width:24%;display:inline">
+<img src="extras/Images/mot2.jpg" style="width:20%;display:inline"><img src="extras/Images/bigger.jpg" style="width:20%;display:inline"><img src="extras/Images/mot.jpg" style="width:20%;display:inline"><img src="extras/Images/nema17_2.jpg" style="width:20%;display:inline"><img src="extras/Images/nema17_1.jpg" style="width:20%;display:inline">
 </div>
 
-All BLDC motors are handled with the `BLDCMotor` class. This class is the heart ❤️ of the  Arduino <span class="simple">Simple<span class="foc">FOC</span>library</span>. <br>
-It implements:
-- BLDC motor & BLDC driver hardware support 
+All BLDC motors are handled with the `BLDCMotor` class and stepper motor are handled by `StepperMotor` class. These classes are the heart ❤️ of the Arduino <span class="simple">Simple<span class="foc">FOC</span>library</span>. <br>
+They implement:
+- BLDC/Stepper motor configuration 
+- BLDC/Stepper driver hardware support 
 - FOC algorithm
 - Motion control loops
 - Monitoring
 - User communication interface
 
 ## Step 1. Hardware setup
-To initialize the hardware of the BLDC motor and BLDC driver you need to specify the `pwm` pin numbers, number of `pole pairs` of the motor and optionally `enable` pin.
+To configure the BLDC motor and define the interface to the BLDC driver you need to specify the 3 `pwm` pin numbers for each motor phase, number of `pole pairs` of the motor and optionally `enable` pin.
 ```cpp
 //  BLDCMotor( int phA, int phB, int phC, int pp, int en)
 //  - phA, phB, phC - motor A,B,C phase pwm pins
 //  - pp            - pole pair number
 //  - enable pin    - (optional input)
 BLDCMotor motor = BLDCMotor(9, 10, 11, 11, 8);
 ```
+
+For the stepper motor and stepper driver you need to specify the 4 `pwm` pin numbers (2 for each phase), number of `pole pairs` of the motor and optionally `enable1` and `enable2` pin numbers.
+```cpp
+// StepperMotor( int phA, int phB, int phC, int pp, int cpr, int en)
+// - ph1A, ph1B    - motor phase 1 pwm pins
+// - ph2A, ph2B    - motor phase 2 pwm pins
+// - pp            - pole pair number
+// - enable1 pin   - (optional input)
+// - enable2 pin   - (optional input)
+StepperMotor motor = StepperMotor(5,6, 9,10, 50, 7, 8);
+```
 <blockquote class="info"><p class="heading">Pole pair number </p>
-If you are not sure what your `pole_paris` number is I included an example code to estimate your <code class="highlighter-rouge">pole_paris</code> number in the examples <code class="highlighter-rouge">find_pole_pairs_number.ino</code>.
+If you are not sure what your <code class="highlighter-rouge">pole_paris</code> number is I included an example code to estimate your <code class="highlighter-rouge">pole_paris</code> number in the examples <code class="highlighter-rouge">find_pole_pairs_number.ino</code>.
  </blockquote>
 
-When you have your `motor` defined you can start the configuration. 
+The important thing to note is that the rest of the configuration explained in the following text does not depend which motor you are using. Therefore, once when you have your `motor` defined you can start the configuration. 
 
 ## Step 2. Linking the sensor 
 Once when you have the `motor` defined and the sensor initialized you need to link the `motor` and the `sensor` by executing:    
@@ -138,6 +150,29 @@ Finally the configuration is terminated by running `init()` function which prepa
 motor.init();
 ```
 
+### Step 3.3 PWM frequency configuration (optional)
+If you wish to change the PWM frequency provide the value in hertz to the `init()` function. For example, to set the pwm frequency of 30khz the code will look like:
+```cpp
+// Motor hardware init function 
+motor.init(30000);
+```
+<blockquote class="warning">
+⚠️ Arduino devices based on ATMega328 and ATMega2560 chips have fixed pwm frequency of 32kHz.
+</blockquote>
+
+Here is a list of different microcontrollers and their PWM frequency and resolution used with the  Arduino <span class="simple">Simple<span class="foc">FOC</span>library</span>.
+
+MCU | default frequency | MAX frequency | PWM resolution | configurable 
+--- | --- | --- | --- | ---
+Arduino UNO(Atmega328) | 32 kHz | 32 kHz | 8bit | no
+Arduino MEGA | 32kHz | 32kHz | 8bit | no
+STM32 | 50kHz | 50kHz | 14bit | yes
+ESP32 | 20kHz | 30kHz | 10bit | yes
+Teensy | 50kHz | 50kHz | 8bit | yes
+
+All of these settings are defined in the `hardware_utils.cpp/h` of the library source. 
+
+
 ## Step 4. Field Oriented Control initialization
 
 After the motor and sensor are initialized and configured, and before we can start the motion control we need to initialize the FOC algorithm. 
@@ -186,7 +221,7 @@ The faster you can run this function the better!
 Finally, when we can set the phase voltages to the motor using the FOC algorithm we can proceed to the motion control. And this is done with `motor.move()` function.
 
 ```cpp
-// Function executing the control loops configured by the motor.controller parameter of the BLDCMotor. 
+// Function executing the control loops configured by the motor.controller parameter of the motor. 
 // - This function doesn't need to be run upon each loop execution - depends of the use case
 //
 // target  Either voltage, angle or velocity based on the motor.controller

…mplefoc_library/hardware/BLDC_drivers.md …library/hardware/drivers/BLDC_drivers.mddocs/simplefoc_library/hardware/BLDC_drivers.md renamed to docs/simplefoc_library/hardware/drivers/BLDC_drivers.md docs/simplefoc_library/hardware/BLDC_drivers.md renamed to docs/simplefoc_library/hardware/drivers/BLDC_drivers.md

@@ -1,15 +1,16 @@
 ---
 layout: default
 title: BLDC drivers
-parent: Supported Hardware
-nav_order: 2
+nav_order: 1
 description: "Arduino Simple Field Oriented Control (FOC) library ."
 permalink: /bldc_drivers
-grand_parent: Arduino <span class="simple">Simple<span class="foc">FOC</span>library</span>
+parent: Drivers
+grand_parent: Supported Hardware
+grand_grand_parent: Arduino <span class="simple">Simple<span class="foc">FOC</span>library</span>
 ---
 
 # BLDC motor drivers
-This library will be compatible with the most of the 3 phase BLDC motor drivers. Such as [<i class="fa fa-file"></i> L6234](https://www.st.com/en/motor-drivers/l6234.html), [<i class="fa fa-file"></i> DRV8305](https://www.ti.com/product/DRV8305), [<i class="fa fa-file"></i> DRV8313](https://www.ti.com/product/DRV8313)  or even [<i class="fa fa-file"></i> L293](http://www.ti.com/lit/ds/symlink/l293.pdf). 
+This library will be compatible with the most of 3 phase BLDC motor drivers. Such as [<i class="fa fa-file"></i> L6234](https://www.st.com/en/motor-drivers/l6234.html), [<i class="fa fa-file"></i> DRV8305](https://www.ti.com/product/DRV8305), [<i class="fa fa-file"></i> DRV8313](https://www.ti.com/product/DRV8313)  or even [<i class="fa fa-file"></i> L293](http://www.ti.com/lit/ds/symlink/l293.pdf). **In order for BLDC driver board to work with the library it needs to be controllable using 3 pwm signals.**
 
 At this moment, a low-cost BLDC driver board is still reasonably hard to find making our choice of hardware is quiet restricted. This is the one of the motivations to develop the <span class="simple">Simple<span class="foc">FOC</span>Shield</span>, a versatile and simple BLDC driver. Fortunately, the community is starting to gain momentum in this direction and it is probably a matter of time before BLDC motors become a standard in the hobby community as well, what is really exciting! 😃
 
@@ -22,7 +23,7 @@ Here are some BLDC driver boards that are designed for gimbal motors and work wi
 
 Examples | Description | Specifications | Link | Price
 ---- | ---- | ---- | ---
-[<img src="extras/Images/hor_cad_shield.jpg" style="height:100px">](https://simplefoc.com/simplefoc_shield_product)| Arduino<br> <span class="simple">Simple<span class="foc">FOC</span>Shield</span>| - L6234 chip <br> - 1 motor <br>- Arduino Shield <br> - Encoder Pullups | [More info](https://simplefoc.com/simplefoc_shield_product) | 15€
+[<img src="https://raw.githubusercontent.com/simplefoc/Arduino-SimpleFOCShield/master/images/top.png" style="height:100px">](https://simplefoc.com/simplefoc_shield_product)| Arduino<br> <span class="simple">Simple<span class="foc">FOC</span>Shield</span>| - L6234 chip <br> - 1 motor <br>- Arduino Shield <br> - Encoder Pullups | [More info](https://simplefoc.com/simplefoc_shield_product) | 15€
 [<img src="extras/Images/l6234.jpg" style="height:100px">](https://www.ebay.com/itm/L6234-Breakout-Board/153204519965?hash=item23abb3741d:g:LE4AAOSwe35bctgg) | Drotek L6234<br> breakout board | - L6234 chip <br> - 1 motor <br> - 25x25mm | [Drotek](https://store-drotek.com/212-brushless-gimbal-controller-l6234.html)<br> [Ebay](https://www.ebay.fr/itm/L6234-Breakout-Board-/153204519965) | 30€
 
 Alternatively, you can find gimbal controller boards with integrated BLDC drivers and microcontroller chips such as HMBGC V2.2 and BGC 3.0 similar boards.

docs/simplefoc_library/hardware/drivers/index.md

@@ -0,0 +1,35 @@
+---
+layout: default
+title: Drivers
+parent: Supported Hardware
+nav_order: 2
+description: "Arduino Simple Field Oriented Control (FOC) library ."
+permalink: /drivers
+grand_parent: Arduino <span class="simple">Simple<span class="foc">FOC</span>library</span>
+has_children: true
+has_toc: false
+---
+
+# Supported driver boards
+
+Arduino <span class="simple">Simple<span class="foc">FOC</span>library</span> has a goal to support as many BLDC and stepper motor drivers as possible. Till this moment there are two kinds of motor drivers supported by this library:
+
+- [BLDC motor driver <i class="fa fa-external-link"></i>](bldc_drivers)
+    - **3 PWM signals** ( 3 phase )
+    - gimbal motor drivers or high-performance boards
+- [Stepper drivers <i class="fa fa-external-link"></i>](stepper_drivers)
+    - **4 PWM signals** ( 2 phase )
+    - Stepper drivers or double DC motor drivers
+
+## 📢 Make sure to read this before settling for a driver!
+Before running any BLDC motor with the <span class="simple">Simple<span class="foc">FOC</span>library</span> please make sure your hardware can handle the currents your motor requires. 
+
+The simplest way to do it is by checking the motor phase resistance `R`. Either check the datasheet of your motor and search for the resistance value or measure it yourself using a multimeter. Then check the value of your power supply voltage `V_dc` and once when you have the values you can find the maximum current `I_max` value by calculating:
+```cpp
+I_max = V_dc/R
+```
+Finally check the value of the maximum current `I_max` with the datasheet of your driver board. If the `I_max` is too high you can lower the power supply voltage `V_dc` in order prevent too high peaks of the current. If you are not able to change your power supply voltage you can limit the voltage set to motor in software. 
+<blockquote class="warning">
+    <p class="heading">NOTE</p>
+    The equation above calculates the worst case maximum current <code class="highlighter-rouge">I_max</code> and in most cases calculated <code class="highlighter-rouge">I_max</code> is higher than the actual value. Maximum current depends both of the motor hardware such as winding configuration and the control algorithm.  
+</blockquote>