ready for the v2.2.2

Author: askuric

_includes/js/custom.js

@@ -101,7 +101,9 @@ var classProps = [
     "quadrature",
     "pullup",
     "voltage_limit",
+    "current_limit",
     "voltage_power_supply",
+    "controller",
     "index_search_velocity",
     "controller",
     "velocity_limit",

…mplefoc_library/reference/build_flags.md …plefoc_library/cheatsheet/build_flags.mddocs/simplefoc_library/reference/build_flags.md renamed to docs/simplefoc_library/cheatsheet/build_flags.md docs/simplefoc_library/reference/build_flags.md renamed to docs/simplefoc_library/cheatsheet/build_flags.md

@@ -2,8 +2,8 @@
 layout: default
 title: Build Flags
 nav_order: 2
-permalink: /reference/build_flags
-parent: Reference
+permalink: /cheetsheet/build_flags
+parent: Options Cheat Sheet
 grand_parent: Arduino <span class="simple">Simple<span class="foc">FOC</span>library</span>
 has_children: False
 has_toc: False

docs/simplefoc_library/cheatsheet/index.md

@@ -0,0 +1,23 @@
+---
+layout: default
+title: Options Cheat Sheet
+nav_order: 9
+permalink: /options_cheetsheet
+parent: Arduino <span class="simple">Simple<span class="foc">FOC</span>library</span>
+has_children: True
+has_toc: False
+---
+
+
+# Options Cheat Sheet 
+
+Find in these pages a summary of library options and build flags for your reference.
+
+## Options
+
+[Commonly used options](cheetsheet/options_reference) of <span class="simple">Simple<span class="foc">FOC</span>library</span> objects.
+
+## Build flags
+
+[Build flags](cheetsheet/build_flags) control the way the compiler generates the code for <span class="simple">Simple<span class="foc">FOC</span>library</span>.
+

…s/simplefoc_library/reference/options.md …/simplefoc_library/cheatsheet/options.mddocs/simplefoc_library/reference/options.md renamed to docs/simplefoc_library/cheatsheet/options.md docs/simplefoc_library/reference/options.md renamed to docs/simplefoc_library/cheatsheet/options.md

@@ -2,8 +2,8 @@
 layout: default
 title: Options Reference
 nav_order: 1
-permalink: /reference/options_reference
-parent: Reference
+permalink: /cheetsheet/options_reference
+parent: Options Cheat Sheet
 grand_parent: Arduino <span class="simple">Simple<span class="foc">FOC</span>library</span>
 has_children: False
 has_toc: False

docs/simplefoc_library/code/debug.md

@@ -7,7 +7,7 @@ parent: Writing the Code
 grand_parent: Arduino <span class="simple">Simple<span class="foc">FOC</span>library</span> 
 ---
 
-# Debugging SimpleFOClibrary sketches
+# Debugging <span class="simple">Simple<span class="foc">FOC</span>library</span>  sketches
 
 So you hooked everything up, downloaded your sketch, applied power, and... nothing. Or another common scenario: motor jerks around and makes terrible sounds.
 

docs/simplefoc_library/code/monitoring.md

@@ -48,7 +48,7 @@ The monitoring function can output 7 different motor specific variables:
 - `target` - current target value, specific to the motion control used (either current [A], voltage [V], velocity [rad/s], or position [rad])
 - `voltage.q` - [V] - set voltage in q direction
 - `voltage.d` - [V] - set voltage in d direction
-- `current.q` - [mA] - measured current in q direction ( if current sense available )
+- `current.q` - [mA] - measured current in q direction ( if current sense available ) or estimated current if no current sense but provided phase resistance
 - `current.d` - [mA] - measured current in d direction ( if current sense available )
 - `shaft_velocity` - [rad/s] - motor velocity
 - `shaft_angle` - [rad] - motor position

docs/simplefoc_library/code/motion_control/closed_loop_control/torque_control/dc_current.md

@@ -62,7 +62,7 @@ InlineCurrentSense current_sense = InlineCurrentSense(0.01, 50.0, A0, A2);
 
 // instantiate the commander
 Commander command = Commander(Serial);
-void doTarget(char* cmd) { command.variable(&motor.target, cmd); }
+void doTarget(char* cmd) { command.scalar(&motor.target, cmd); }
 
 void setup() { 
 

docs/simplefoc_library/code/motion_control/closed_loop_control/torque_control/foc_current.md

@@ -73,7 +73,7 @@ InlineCurrentSense current_sense = InlineCurrentSense(0.01, 50.0, A0, A2);
 
 // instantiate the commander
 Commander command = Commander(Serial);
-void doTarget(char* cmd) { command.variable(&motor.target, cmd); }
+void doTarget(char* cmd) { command.scalar(&motor.target, cmd); }
 
 void setup() { 
 

docs/simplefoc_library/code/motion_control/open_loop/angle_openloop.md

@@ -39,7 +39,16 @@ motor.controller = MotionControlType::angle_openloop;
 
 You can test this algorithm by running the examples in the `motion_control/open_loop_motor_control/` folder.
 
-This control algorithm is very simple. User sets the target angle it wants to achieve <i>a<sub>d</sub></i>. The algorithm only subtracts the current angle <i>a<sub>c</sub></i> and the desired angle <i>a<sub>d</sub></i> to find the direction it needs to move and goes in that direction with the highest velocity possible `motor.velocity_limit`(max velocity). To set this velocity it uses the same algorithm as for [velocity open-loop control](velocity_openloop). It integrates the velocity it in time to find out what is the angle it needs to set to the motor <i>a<sub>c</sub></i> in order to achieve it. Then the maximal allowed voltage `motor.voltage_limit` is going to be applied in the direction of the <i>a<sub>c</sub></i> using `SinePWM` or `SpaceVector` modulation.
+This control algorithm is very simple. User sets the target angle it wants to achieve <i>a<sub>d</sub></i>. The algorithm only subtracts the current angle <i>a<sub>c</sub></i> and the desired angle <i>a<sub>d</sub></i> to find the direction it needs to move and goes in that direction with the highest velocity possible `motor.velocity_limit`(max velocity). To set this velocity it uses the same algorithm as for [velocity open-loop control](velocity_openloop). It integrates the velocity it in time to find out what is the angle it needs to set to the motor <i>a<sub>c</sub></i> in order to achieve it. Then the maximal allowed voltage `motor.voltage_limit` is going to be applied in the direction of the <i>a<sub>c</sub></i> using `SinePWM` or `SpaceVector` modulation. 
+
+```cpp
+// calculate the distance from the target
+d_angle = target_angle - past_angle;
+// constrain the distance with maximal allowable displacement
+d_angle = constrain(d_angle, -velocity_limit*d_time, velocity_limit*d_time)
+// calculate the next angle
+next_angle = past_angle + d_angle;
+```
 
 ## Configuration
 ``` cpp
@@ -54,16 +63,36 @@ motor.velocity_limit = 20;
 motor.voltage_limit = 3;   // Volts
 // or current  - if phase resistance provided
 motor.current_limit = 0.5 // Amps
+
+```
+
+The angle open-loop control will (if not provided phase resistance) set the voltage to the motor equal to the `motor.voltage_limit`
+
+```cpp
+voltage = voltage_limit; // Volts
 ```
+This is very ineficeint, as for different motors with different phase resistances the same voltage values can produce wildly different currents.
+For gimbal motor, you can run it in the open loop with the voltage limits of 5-10 Volts and it will reach the currents of 0.5-2 amps as it has the pahse resistance from 5-15 Ohms. For drone motors, the voltage limits should stay very low, under 1 volt. Because they have pahse resisatnce of 0.05 to 0.2 Ohms.
 
-This type of motion control is highly inefficient therefore try not to use to high value for `motor.voltage_limit`. We suggest you to provide the motor class with the `phase_resistance` value and set the `motor.current_limit` instead the voltage limit. This current might be surpassed but at least you will know an approximate current your motor is drawing. You can calculate the current the motor is going to be producing by checking the motor resistance `phase_resistance` and evaluating:
+### Current limiting approaches
+
+We suggest you to provide the motor class with the `phase_resistance` value and set the `motor.current_limit` instead the voltage limit. This current might be surpassed but at least you will know an approximate current your motor is drawing. You can calculate the current the motor is going to be producing by checking the motor resistance `phase_resistance` and evaluating:
+```cpp
+voltage = current_limit * phase_resistance; // Amps
+```
+The best way to use this control strategy would be to provide both phase resistance value and KV rating of your motor. The the library would be able to calculate he back-emf voltage and much more precisely estimate the consumed current. And with the current and the back-emf current the library can set much more appropriate voltage to the motor.
 ```cpp
-voltage_limit = current_limit * phase_resistance; // Amps
+voltage = current_limit*phase_resistance + desired_velocity/KV; // Amps
 ```
 
+### Velocity limit
+
 The maximal velocity `motor.velocity_limit` value is going to determine how fast your motor goes in between positions. The higher the value the faster the transition. But since we are turning the motor in open-loop we will not be able to know if the motor can follow the velocity. So make sure to put the `velocity_limit` value that is achievable for your motor. Also beware that for higher velocities and more holding torque you will need to increase the `motor.voltage_limit` or `motor.current_limit` variable as well.
 
+### Changing limits in real-time
+
 Also, you can change the voltage limit `motor.voltage_limit` (`motor.current_limit`) and transition velocity `motor.velocity_limit` in real-time if you need this kind of behavior in your application.
+
 ## Position open-loop control example
 Here is one basic example of the velocity open-loop control with the complete configuration. The program will set the target position of `0 RAD` and maintain it, and the user can change the target position using serial terminal.
 ```cpp
@@ -74,12 +103,11 @@ Here is one basic example of the velocity open-loop control with the complete co
 BLDCMotor motor = BLDCMotor(11);
 BLDCDriver3PWM driver = BLDCDriver3PWM(9, 5, 6, 8);
 
-//target variable
-float target_position = 0;
-
 // instantiate the commander
 Commander command = Commander(Serial);
-void doTarget(char* cmd) { command.variable(&target_position, cmd); }
+void doTarget(char* cmd) { command.scalar(&motor.target, cmd); }
+void doLimitVolt(char* cmd) { command.scalar(&motor.voltage_limit, cmd); }
+void doLimitVelocity(char* cmd) { command.scalar(&motor.velocity_limit, cmd); }
 
 void setup() {
 
@@ -98,9 +126,13 @@ void setup() {
 
   // init motor hardware
   motor.init();
+  motor.initFOC();
 
   // add target command T
   command.add('T', doTarget, "target angle");
+  command.add('L', doLimitVolt, "voltage limit");
+  command.add('V', doLimitVelocity, "velocity limit");
+
 
   Serial.begin(115200);
   Serial.println("Motor ready!");
@@ -109,9 +141,10 @@ void setup() {
 }
 
 void loop() {
+  motor.loopFOC(); 
   // open  loop angle movements
   // using motor.voltage_limit and motor.velocity_limit
-  motor.move(target_position);
+  motor.move();
 
   // user communication
   command.run();

docs/simplefoc_library/code/motion_control/open_loop/velocity_openloop.md

@@ -48,20 +48,37 @@ next_angle = past_angle + target_velocity*d_time;
 You need to know the  `target_velocity`, sample time `d_time` and past value of the angle `past_angle` you have set to the motor.
 
 ## Configuration
+There are only three main parameters of the velocity open-loop control
 ```cpp
-// choose FOC modulation (optional) - default SinePWM
-motor.foc_modulation = FOCModulationType::SpaceVectorPWM;
+// choose FOC modulation (optional) - SinePWM or SpaceVectorPWM
+motor.foc_modulation = FOCModulationType::SinePWM;
 
 // limiting voltage 
 motor.voltage_limit = 3;   // Volts
 // or current  - if phase resistance provided
 motor.current_limit = 0.5 // Amps
 ```
 
-This type of motion control is highly inefficient therefore try not to use to high value for `motor.voltage_limit`. We suggest you to provide the motor class with the `phase_resistance` value and set the `motor.current_limit` instead the voltage limit. This current might be surpassed but at least you will know an approximate current your motor is drawing. You can calculate the current the motor is going to be producing by checking the motor resistance `phase_resistance` and evaluating:
+The velocity open-loop control will (if not provided phase resistance) set the voltage to the motor equal to the `motor.voltage_limit`
+
+```cpp
+voltage = voltage_limit; // Volts
+```
+This is very ineficeint, as for different motors with different phase resistances the same voltage values can produce wildly different currents.
+For gimbal motor, you can run it in the open loop with the voltage limits of 5-10 Volts and it will reach the currents of 0.5-2 amps as it has the pahse resistance from 5-15 Ohms. For drone motors, the voltage limits should stay very low, under 1 volt. Because they have pahse resisatnce of 0.05 to 0.2 Ohms.
+
+### Current limiting approaches
+
+We suggest you to provide the motor class with the `phase_resistance` value and set the `motor.current_limit` instead the voltage limit. This current might be surpassed but at least you will know an approximate current your motor is drawing. You can calculate the current the motor is going to be producing by checking the motor resistance `phase_resistance` and evaluating:
 ```cpp
-voltage_limit = current_limit * phase_resistance; // Amps
+voltage = current_limit * phase_resistance; // Amps
 ```
+The best way to use this control strategy would be to provide both phase resistance value and KV rating of your motor. The the library would be able to calculate he back-emf voltage and much more precisely estimate the consumed current. And with the current and the back-emf current the library can set much more appropriate voltage to the motor.
+```cpp
+voltage = current_limit*phase_resistance + desired_velocity/KV; // Amps
+```
+
+### Changing limits in real-time
 
 Also, you can change the voltage/current limit in real-time if you need this kind of behavior in your application.
 
@@ -75,15 +92,13 @@ Here is one basic example of the velocity open-loop control with the complete co
 
 // BLDC motor & driver instance
 // BLDCMotor( pp number , phase resistance)
-BLDCMotor motor = BLDCMotor(11 , 12.5); 
+BLDCMotor motor = BLDCMotor(11 , 12.5, 100); 
 BLDCDriver3PWM driver = BLDCDriver3PWM(9, 5, 6, 8);
 
-//target variable
-float target_velocity = 2; // rad/s
-
 // instantiate the commander
 Commander command = Commander(Serial);
-void doTarget(char* cmd) { command.variable(&target_velocity, cmd); }
+void doTarget(char* cmd) { command.scalar(&motor.target, cmd); }
+void doLimitCurrent(char* cmd) { command.scalar(&motor.current_limit, cmd); }
 
 void setup() {
 
@@ -102,9 +117,11 @@ void setup() {
 
   // init motor hardware
   motor.init();
+  motor.initFOC();
 
   // add target command T
   command.add('T', doTarget, "target velocity");
+  command.add('C', doLimitCurrent, "current limit");
 
   Serial.begin(115200);
   Serial.println("Motor ready!");
@@ -113,10 +130,10 @@ void setup() {
 }
 
 void loop() {
-
+  motor.loopFOC();
   // open loop velocity movement
   // using motor.current_limit and motor.velocity_limit
-  motor.move(target_velocity);
+  motor.move();
 
   // user communication
   command.run();