Merge pull request #46 from andrewschalk/master

Fixing some typos in the doc's theory section

Author: runger1101001

docs/simplefoc_library/digging_deeper/theory/FOC_routine.md

@@ -17,11 +17,11 @@ Field oriented control algorithm's main task is to take user defined voltage <i>
 
 <img src="../extras/Images/voltage_loop.png">
 
-FOC algorithm calculates the phase voltages which create the magnetic field in the motor's stator which are exactly 90 degrees "behind" the magnetic field of the permanent magnets of the rotor, creating a pushing effect. Here is a very nice animation of what happens inside of the motor when running simplified version of the the FOC called six-step modulation. 
+The FOC algorithm calculates the phase voltages which create the magnetic field in the motor's stator which are exactly 90 degrees "behind" the magnetic field of the permanent magnets of the rotor, creating a pushing effect. Here is a very nice animation of what happens inside of the motor when running simplified version of the the FOC called six-step modulation. 
 
-<iframe src='https://gfycat.com/ifr/MealyDeafeningHarpyeagle' frameborder='0' scrolling='no' allowfullscreen width='640' height='404'></iframe><p> <a href="https://gfycat.com/mealydeafeningharpyeagle">via Gfycat</a></p>
+<img src="../extras/Images/FOC_6_step_modulation.gif" >
 
-Another way to look at why we need 90 degree angle in between rotor and stator fields if by remembering the equation of the electric force generated by the wire passing through the magnetic field:
+Another way to look at why we need 90 degree angle in between rotor and stator fields is by remembering the equation of the electric force generated by the wire passing through the magnetic field:
 
 ```cpp
 F = B*I*L*sin(alpha)
@@ -32,12 +32,12 @@ Where `B` is the strength of the magnetic field, `L` is the length of the wire,
 
 ## How to calculate the appropriate voltages <i>u<sub>a</sub></i>,<i>u<sub>b</sub></i> and <i>u<sub>c</sub></i> 
 
-Since the <span class="simple">Simple<span class="foc">FOC</span>library</span> is intended for education about the FOC algorithm as well for enabling various applications, the two most standard versions of the FOC modulation are implemented in this library. 
+Since the <span class="simple">Simple<span class="foc">FOC</span>library</span> is intended for education about the FOC algorithm as well for enabling various applications, the two most standard versions of FOC modulation are implemented in this library. 
 
 - Sinusoidal PWM: `SinePWM`
 - Space Vector PWM: `SpaceVectorPWM`
 
-You can configure them by setting the value of `motor.foc_modulation` variable:
+You can configure them by setting the value of the `motor.foc_modulation` variable:
 ```cpp
 motor.foc_modulation = FOCModulationType::SinePWM; // default
 // or
@@ -65,7 +65,7 @@ $$u_b = \frac{-U_{\alpha} + \sqrt{3}U_{\beta}}{2}$$
 
 $$u_c = \frac{-U_{\alpha} - \sqrt{3}U_{\beta}}{2}$$
 
-Here is the code of implementation of the Sinusoidal PWM in the <span class="simple">Simple<span class="foc">FOC</span>library</span>:
+Here is the implementation of Sinusoidal PWM in the <span class="simple">Simple<span class="foc">FOC</span>library</span>:
 ```cpp
 // Method using FOC to set Uq to the motor at the optimal angle
 void BLDCMotor::setPhaseVoltage(float Uq, float angle_el) {
@@ -100,7 +100,7 @@ In the first step we find the sector <i>s</i> the rotor is currently in. The ang
 <img src="../extras/Images/svm_1.png" style="margin-left:50px;margin-top:10px;margin-bottom:10px;width:250px"><br>
 
 
-Second step is projecting the <i>T<sub>0,1,2</sub></i> values to the appropriate duty-cycles <i>T<sub>a,b,c</sub></i> which depend directly of the sector the motor is currently in.
+The second step is projecting the <i>T<sub>0,1,2</sub></i> values to the appropriate duty-cycles <i>T<sub>a,b,c</sub></i> which depend directly on the sector the motor is currently in.
 
 Sector | <i>T<sub>a</sub></i> | <i>T<sub>b</sub></i> | <i>T<sub>c</sub></i>
 --- | --- | --- | ---
@@ -111,7 +111,7 @@ Sector | <i>T<sub>a</sub></i> | <i>T<sub>b</sub></i> | <i>T<sub>c</sub></i>
 5| <i>T<sub>2</sub></i> + <i>T<sub>0</sub></i>/2|<i>T<sub>0</sub></i>/2 | <i>T<sub>1</sub></i> + <i>T<sub>2</sub></i> + <i>T<sub>0</sub></i>/2
 6| <i>T<sub>1</sub></i> + <i>T<sub>2</sub></i> + <i>T<sub>0</sub></i>/2| <i>T<sub>0</sub></i>/2| <i>T<sub>1</sub></i> + <i>T<sub>0</sub></i>/2
 
-Here is one example of a pwm signal generated using SVM table for parameters: <i>s = 2</i>, <i><i>T<sub>1</sub></i> = 1/8 = 0.125</i>, <i><i>T<sub>2</sub></i> = 1/8 = 0.125</i> and <i><i>T<sub>0</sub></i> = 1/2 = 0.5</i>
+Here is one example of a pwm signal generated using the SVM table for parameters: <i>s = 2</i>, <i><i>T<sub>1</sub></i> = 1/8 = 0.125</i>, <i><i>T<sub>2</sub></i> = 1/8 = 0.125</i> and <i><i>T<sub>0</sub></i> = 1/2 = 0.5</i>
 
 <img src="../extras/Images/svm_dc.png" >
 
@@ -202,7 +202,7 @@ Sinusoidal | Space Vector
 --- | ---
 <img src="../extras/Images/0.5.jpg" class="img400"> | <img src="../extras/Images/svm0.5.jpg"  class="img400">
 
-There are several key differences in between these two algorithms. But in terms of <span class="simple">Simple<span class="foc">FOC</span>library</span> all that you need to know is that Space Vector algorithm better uses the maximal voltage range of the power supply. In the tables above, you can see that for <i>U<sub>q</sub> = 0.5V</i> the magnitude of sine waves generated by the Sinusoidal modulation is exactly equal to 1, and Space vector modulation is not quite there yet. The "double sine" wave produced by the space vector has lower magnitude by the factor of `2/sqrt(3) = 1.15` which means that it can deliver 15% more power to the motor using same power supply. 
+There are several key differences between these two algorithms. But in terms of the <span class="simple">Simple<span class="foc">FOC</span>library</span> all that you need to know is that the Space Vector algorithm better uses the maximal voltage range of the power supply. In the tables above, you can see that for <i>U<sub>q</sub> = 0.5V</i> the magnitude of sine waves generated by the Sinusoidal modulation is exactly equal to 1, and Space vector modulation is not quite there yet. The "double sine" wave produced by the space vector has lower magnitude by the factor of `2/sqrt(3) = 1.15` which means that it can deliver 15% more power to the motor using same power supply. 
 
 This means, for your power-supply with the voltage <i>V<sub>power_supply</sub></i>, when using `SinePWM` you will be able to set maximal <i>U<sub>q</sub> = 0.5 V<sub>power_supply</sub> </i> and if using `SpaceVectorPWM` you will be able to set <i>U<sub>q</sub> = 0.58 V<sub>power_supply</sub> </i> 
 
@@ -213,7 +213,7 @@ The power supply voltage <i>V<sub>power_supply</sub></i> you should specify by c
 motor.voltage_power_supply = 12;
 ```
 <blockquote class="warning"> <p class="heading">What if I don't specify this parameter?</p>
-If you don't <code class="highlighter-rouge">motor.voltage_power_supply</code>, the algorithm will still work but your <code class="highlighter-rouge">motor.voltage_q</code> value will no longer be equal to the real output voltage.
+If you don't specify <code class="highlighter-rouge">motor.voltage_power_supply</code>, the algorithm will still work but your <code class="highlighter-rouge">motor.voltage_q</code> value will no longer be equal to the real output voltage.
 </blockquote>
 <img src="../extras/Images/sine_foc.png" >
 
@@ -222,7 +222,7 @@ If you don't <code class="highlighter-rouge">motor.voltage_power_supply</code>,
 
 If you try to put voltage <i>U<sub>q</sub></i> higher than <i>U<sub>q</sub> = 0.5 V<sub>power_supply</sub> </i>  for `SinePWM` or <i>U<sub>q</sub> = 0.58 V<sub>power_supply</sub> </i>  for `SpaceVectorPWM`, it will still work but the <i>U<sub>a,b,c</sub></i> signals will be saturated.
 
-Here are few images of the `SinePWM` for different <i>U<sub>q</sub></i>  values.
+Here are a few images of the `SinePWM` for different <i>U<sub>q</sub></i> values.
 
 <i>U<sub>q</sub> = 0.5 V<sub>power_supply</sub> </i> | <i>U<sub>q</sub> = 0.6 V<sub>power_supply</sub> </i> | <i>U<sub>q</sub> = V<sub>power_supply</sub> </i>
 --- | --- | ---
@@ -232,7 +232,7 @@ Basically what you can see on images is that the <i>U<sub>a,b,c</sub></i> are sa
 The motor is still getting some increase of power, but it is no longer linear or smooth. 
 
 <blockquote class="warning"> <p class="heading">RULE OF THUMB</p>
-In reality the motor can see the difference all the way till <i>U<sub>q</sub> ~ 0.7 V<sub>power_supply</sub> </i>. After this value the <i>U<sub>a,b,c</sub></i> are too saturated and further increase of <i>U<sub>q</sub></i> doesn't result in increase of motor power.
+In reality the motor can see the difference all the way till <i>U<sub>q</sub> ~ 0.7 V<sub>power_supply</sub> </i>. After this value the <i>U<sub>a,b,c</sub></i> are too saturated and further increase of <i>U<sub>q</sub></i> doesn't result in an increase of motor power.
 
 But every motor is a bit different and you can check these values empirically on your own easily. Just put the motor in the voltage control and see after which value of the voltage <i>U<sub>q</sub></i> you can no longer see the improvement in motor power (it will stop accelerating).
 </blockquote>

docs/simplefoc_library/digging_deeper/theory/init.md

@@ -18,29 +18,29 @@ This page has been extracted from the [SimpleFOC Community forum](https://commun
 
 # Motor and sensor alignment procedure
 
-The motor and sensor alignment procedure is a crucial part of the motor control. It is the procedure that is used to find the correspondence in between the electrical angle of the motor and the angle of the sensor. This is a very important step because it is the first step in the motor control and it has to be done correctly in order for BLDC or Stepper motor to be able to move at all. 😃
+The motor and sensor alignment procedure is a crucial part of motor control. It is the procedure that is used to find the difference between the electrical angle of the motor and the angle of the sensor. This is a very important step because it is the first step in motor control and it has to be done correctly in order for BLDC or Stepper motor to be able to move at all. 😃
 
 
 ## Basic principles of the BLDC
 Every BLDC motor has windings in its stator and permanent magnets in its rotor. Here is a quick graphic of a very simple 1 pole pair motor. This motor has three phases and each phase has one pair windings. 
 
 <img src="extras/Images/init1.png" class="width30">
 
-Once the current is passed through the winding coils the motor phases it induces a magnetic field in the windings with a polarity depending on the current polarity. In my figures I am going to simplify this effect and draw the coils in color red/blue - north/south as if they were magnets.
+When current is passed through the winding coils, a magnetic field is induced in the windings with a polarity depending on the current polarity. In my figures I am going to simplify this effect and draw the coils in color red/blue - north/south as if they were magnets.
 
-So whenever you apply certain current through the motor coils, they will generate the magnetic field and the motor's rotor will try to align with the coils magnetic filed. Here is an example of the motor behavior for two different initial positions by applying current in the phase `a` 
+So whenever current flows through the motor coils, a magnetic field is generated and the motor's rotor will try to align with the coils' magnetic field. Here is an example of the motor behavior for two different initial positions by applying current in the phase `a` 
 
 <img src="extras/Images/init2.png">
 
-From the graphic, and whats intuitive, you can see that regardless of the rotor's initial position, when you set a certain magnetic field in the stator windings the motor will always try to align with that magnetic field, and in a case of this simple motor it will always some to the same position. 
+From the graphic, and what's intuitive, you can see that regardless of the rotor's initial position, when you set a certain magnetic field in the stator windings the motor will always try to align with that magnetic field, and in a case of this simple motor it will always come to the same position.
 
 ## Definition of the field vectors
 
-Now when talking about how to align different magnetic fields, what does it mean in practice and how do we characterise the force that actually makes the rotor move it is usual to introduce the field vectors. Basically the magnetic field vector by its length shows the strength of the magnetic field and its direction will be determined going from the north to south pole. It is very simple, here is a quick visualisation:
+Now when talking about how to align different magnetic fields, it is usual to introduce the field vectors. What does it mean in practice and how do we characterise the force that actually makes the rotor move? The magnetic field vector shows the strength of the magnetic field by its length and its direction will be determined going from the north to south pole. It is very simple, here is a quick visualisation:
 
 <img src="extras/Images/init3.png">
 
-Now when we defined the vectors of the magnetic field based on the motor's physics the force that turns the rotor of the motor depends of the strength of the two magnetic fields (  \\(B_r\\) - strength of rotor's permanent magnets and \\(B_s\\) - strength of the field in the coils produced by the current \\(I\\)) and  fields and the angle in between them
+Now when we defined the vectors of the magnetic field based on the motor's physics, the force that turns the rotor of the motor depends on the strength of the two magnetic fields (  \\(B_r\\) - strength of rotor's permanent magnets and \\(B_s\\) - strength of the field in the coils produced by the current \\(I\\)) and  fields and the angle in between them
 
 $$
 F \sim B_r\cdot B_s\cdot sin(\theta)
@@ -55,7 +55,7 @@ $$
 <img src="extras/Images/init4.png">
 
 
-Basically this relationship means that the motor's torque will be directly proportional to the two magnetic fields but also to the sine of the angle between them. And in particular as we cannot control the magnetic filed of the rotor's magnets, we will have to control strength and orientation of the magnetic field vector of the stator windings (field oriented control). 
+This relationship means that the motor's torque will be directly proportional to the two magnetic fields but also to the sine of the angle between them. As we cannot control the magnetic field of the rotor's magnets, we will have to control the strength and orientation of the magnetic field vector of the stator windings (field oriented control).
 
 ## Control of the field vector orientation (FOC)
 From the force equation we can see that we can see that in order to use maximally our current and produce the maximal force we need to keep the angle in between the two vectors at 90 degrees, because \\(sin(90) = 1\\). In that case the force pushing the rotor to move ( creating the motor's torque) will be proportional only to the current \\(I\\) and \\(B_r\\)
@@ -87,17 +87,17 @@ One simpler variant of bldc motor control is trapezoidal control (or six-step) t
 
 <img src="extras/Images/init5.jpeg">
 
-As you can see the idea is very similar as the FOC (field oriented control) but the angle in between the vectors is not always kept at 90 degrees as we do using the FOC. 
+As you can see the idea is very similar to field oriented control but the angle in between the vectors is not always kept at 90 degrees as we do using FOC.
 
 ## SimpleFOClibrary init procedure
 
-In the init procedure we are searching to find the correspondence in between the 0 angle to the position sensor we are using and the electrical 0 angle of out motor which is usually defined by the magnetic field vector of the phase `a` . As shown on the second image and on the one below we could set the stators magnetic field orientation to -180 degrees and we will be sure that the motor will always align to the 0 electric angle.
+In the init procedure we are searching to find the difference between the 0 angle to the position sensor we are using and the electrical 0 angle of our motor which is usually defined by the magnetic field vector of the phase `a`. As shown on the second image and on the one below we could set the stator's magnetic field orientation to -180 degrees and we will be sure that the motor will always align to the 0 electric angle.
 
 <img src="extras/Images/init6.png">
 
 Then we can just read the sensor value and add 90 degrees to it and use it as our target position to set out stator magnetic field vector \\(B_s\\) to. 
 
-As we will be always adding the 90 degrees to our sensor angles, in literature many approaches (park + clarke) are defined not for the actual rotor position but for the rotor angle+90 degrees. instead of searching for the relationship in between the position sensor angle and the electric angle 0, we often search for electric angle 90. And in order to force the rotor to go to the 90 degrees, you need to apply the 90-180 = -90 or 270 degrees. 
+As we will be always adding 90 degrees to our sensor angles, in literature, many approaches (park + clarke) are defined not for the actual rotor position but for the rotor angle+90 degrees. instead of searching for the relationship between the position sensor angle and the electric angle 0, we often search for electric angle 90. In order to force the rotor to go to 90 degrees, you need to apply the 90-180 = -90 or 270 degrees.
 
 Here is an example:
 
@@ -106,9 +106,9 @@ Here is an example:
 Or: 
 <img src="extras/Images/init8.png">
 
-Remembering the offset in between the position sensor angle and the rotor's electrical 90 degrees angle avoids the need for adding the 90 degrees in the formulas, at least for the sinusoidal modulation. But the approaches of finding the 0 or 90 degree angles are equivalent, its a choice of implementation.
+Remembering the offset between the position sensor angle and the rotor's electrical 90 degrees angle avoids the need for adding the 90 degrees in the formulas, at least for the sinusoidal modulation. But the approaches of finding the 0 or 90 degree angles are equivalent, it's a choice of implementation.
 
 ## Limitations SimpleFOClibrary's alignment procedure
-This is a quiet standard procedure, and probably one of the most simple ones. But there are certainly limitations. The biggest downside is, as we are only doing one measurement it can happen that the rotor due to some physical imperfections (or sometimes just friction) does not go exactly to 90 degrees but some angle close to it. So in that case the force generated by the motor will not be 100 efficient because we will not be able to maintain \\(sin(90) = 1\\). This could be avoided by taking multiple measurements and doing some averaging or some more fancy statistics.
+This is a standard procedure, and probably one of the most simple ones. But there are certainly limitations. The biggest downside is, it can happen that the rotor, due to some physical imperfections, (or sometimes just friction) does not go exactly to 90 degrees but some angle close to it. Since we are only performing one measurement, we will not know that this angle is incorrect. So in that case the force generated by the motor will be less efficient because we will not be able to maintain \\(sin(90) = 1\\). This could be avoided by taking multiple measurements and doing some averaging or some more fancy statistics.
 
-The other downside of course is that if we do the calibration only once at the init, we are absolutely unaware if something happens in during the operation of your motor. If the sensor drifts, it could be potentially possible to account for the change in the alignment, but at the moment we do not implement such a feature.
+The other downside of course is that if we do the calibration only once at the init, we are absolutely unaware if something happens during the operation of the motor. If the sensor drifts, it could be possible to account for the change in the alignment, but at the moment we do not implement such a feature.