You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/simplefoc_library/code/current_sense/index.md
+20-1
Original file line number
Diff line number
Diff line change
@@ -17,7 +17,10 @@ Arduino <span class="simple">Simple<span class="foc">FOC</span>library</span> ha
17
17
-[Low-side current sensing](low_side_current_sense) - *initial support*
18
18
-[High-side current sensing](high_side_current_sense) - *Not supported yet*
19
19
20
-
up to this moment ( [check the releases <iclass="fa fa-tag"></i>](https://github.com/simplefoc/Arduino-FOC/releases) ), Arduino <spanclass="simple">Simple<spanclass="foc">FOC</span>library</span> supports only in-line current sensing and implements initial support for the low-side current sensing on ESP32 boards (one motor) and on the stm32 based B_G431B_ESC1 boards.
up to this moment ( [check the releases <iclass="fa fa-tag"></i>](https://github.com/simplefoc/Arduino-FOC/releases) ), Arduino <spanclass="simple">Simple<spanclass="foc">FOC</span>library</span> supports only in-line current sensing and implements initial support for the low-side current sensing on ESP32 boards (one motor), samd21 (one motor) and on the stm32 based B_G431B_ESC1 boards (one motor).
21
24
22
25
Each one of the current sensing classes will implement all the necessary functionalities for simple and robust implementation of FOC algorithm:
23
26
- Hardware config
@@ -38,5 +41,21 @@ The current sense code will be written in a way to support as many different dri
38
41
39
42
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!
40
43
44
+
## Current sensing support per MCU architecture
45
+
46
+
MCU | In-line | Low-side | High-side
47
+
--- | --- |--- |---
48
+
Arduino (8-bit) | ✔️ | ❌ | ❌
49
+
Arduino DUE | ✔️ | ❌ | ❌
50
+
stm32 | ✔️ | ❌ | ❌
51
+
stm32 B_G431B_ESC1 | ✔️ | ✔️ (initial) | ❌
52
+
esp32 | ✔️ | ✔️ (initial) | ❌
53
+
esp8266 | ❌ | ❌ | ❌
54
+
samd21 | ✔️ | ✔️ (initial) | ❌
55
+
samd51 | ✔️ | ❌ | ❌
56
+
teensy | ✔️ | ❌ | ❌
57
+
Raspberry Pi Pico | ✔️ | ❌ | ❌
58
+
Portenta H7 | ✔️ | ❌ | ❌
59
+
41
60
## Digging deeper
42
61
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).
Low-side current sensing is probably the most common current sensing technique. The main reason why is because it does not require neither high-performance PWM rejection current sense amplifiers (as inline does) neither high-voltage supporting amplifiers (as high-side does). The shunt resistors are always placed in between low side mosfets and the ground making sure that the amplifiers always has very low voltages on its terminals. The main drawback of this approach is that since the current passing through the shunt resistors is phase current only if the corresponding low 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 low-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.
12
+
Low-side current sensing is probably the most common current sensing technique. The main reason why is because it does not require neither high-performance PWM rejection current sense amplifiers (as inline does) neither high-voltage supporting amplifiers (as high-side does). The shunt resistors are always placed in between low side mosfets and the ground making sure that the amplifiers always have very low voltages on their terminals. The main drawback of this approach is that, since the current passing through the shunt resistors is phase current only if the corresponding low 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 low-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.
13
13
14
-
Low side current sensing will be implemented soon. 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.
14
+
Low side current sensing for all the architectures is on our road-map and we are actively working on it. The main issue at the moment is very hardware specific synchronisation procedure of the PWM generation and ADC triggering. Therefore we are attacking one MCU architecture at the time. 😃
To instantiate the low-side current sensor using the <spanclass="simple">Simple<spanclass="foc">FOC</span>library</span> just create an instance of the class `LowsideCurrentSense`. 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.
33
+
34
+
<blockquoteclass="info">
35
+
Field Oriented Control algorithm can run with both 2 or 3 phase current measurements.
36
+
</blockquote>
37
+
38
+
The constructor of the `LowsideCurrentSense` class only allows you to specify one shunt resistor value and one amplification gain. If your hardware configuration has different shunt/amp values for different phases you can specify them by changing the `gain_x` attribute:
For example [AliExpress DRV8302 board](https://fr.aliexpress.com/wholesale?catId=0&initiative_id=SB_20211003032006&SearchText=bldc+drv8302) has all the current sensing phases inverted inverted. So in its case you can specify:
47
+
```cpp
48
+
// inverse current sensing gain
49
+
current_sense.gain_a *= -1;
50
+
current_sense.gain_b *= -1;
51
+
current_sense.gain_c *= -1;
52
+
```
53
+
54
+
Once the current sense has been created it can be initialised. This `init()` function configures the ADC hardware for reading and finds the zero offsets of the ADC for each channel.
55
+
```cpp
56
+
// init current sense
57
+
current_sense.init();
58
+
```
59
+
Once when your current sense has been intialised and calibrated you can start measuring the currents!
60
+
61
+
## Using the current sense with FOC algorithm
62
+
To use the `LowsideCurrentSense` with the FOC algorithm all you need to do is to add it to link it with the `BLDCMotor` you wish to use it with:
63
+
```cpp
64
+
// link motor and current sense
65
+
motor.linkCurrentSense(¤t_sense);
66
+
```
67
+
The `BLDCMotor` class in the `initFOC()` function where it aligns all the sensors, will align the `LowsideCurrentSense` with the `BLDCDriver` that is linked to the motor.
68
+
```cpp
69
+
// prepare sensors for FOC
70
+
motor.initFOC();
71
+
```
72
+
Function `initFOC()` will call two current sense class functions that are important:
Since the low-side current sensing technique requires triggering of the ADC acquisition exactly when all the low side mosfets are ON (when all the phases are grounded) the `driverSync()` synchronises the driver PWM with ADC conversion.
80
+
81
+
### Alignment with the motor phases `driverAlign(...)`
This function applies using the driver instance applies the voltage to each of the phases and checks if the measured currents correspond to the directions of the applied voltages.
88
+
This alignment procedure is able to correct for:
89
+
- Incorrect order of adc pins
90
+
- Incorrect gain sign
91
+
92
+
If [monitoring](monitoring) is enabled for the motor during the `initFOC` the monitor will display the alignment status:
93
+
-`0` - fail
94
+
-`1` - success and nothing changed
95
+
-`2` - success but pins reconfigured
96
+
-`3` - success but gains inverted
97
+
-`4` - success but pins reconfigured and gains inverted
98
+
99
+
100
+
If you are sure in your configuration and if you wish to skip the alignment procedure you can specify set the `skip_align` flag before calling `motor.initFOC()`:
101
+
```cpp
102
+
// skip alignment procedure
103
+
current_sense.skip_align = true;
104
+
```
105
+
106
+
For example [AliExpress DRV8302 board](https://fr.aliexpress.com/wholesale?catId=0&initiative_id=SB_20211003032006&SearchText=bldc+drv8302) , you would have a code similar to this:
107
+
```cpp
108
+
// invert phase b gain
109
+
current_sense.gain_a *=-1;
110
+
current_sense.gain_b *=-1;
111
+
current_sense.gain_c *=-1;
112
+
// skip alignment
113
+
current_sense.skip_align = true;
114
+
...
115
+
// align all sensors
116
+
motor.initFOC();
117
+
```
118
+
119
+
120
+
## Standalone current sense
121
+
122
+
Since the low-side current sense has to be synchornised with PWM of a driver of interest it does not make sense to use it as a stand-alone sensor.
123
+
But once when you liked the current sense with the `BLDCMotor` you can use it to get more info about your phase currents, overall current magnitude and DQ currents.
124
+
125
+
Reading the phase currents can be done by calling:
126
+
```cpp
127
+
PhaseCurrent_s current = current_sense.getPhaseCurrents();
128
+
```
129
+
This function returns the `PhaseCurrent_s` structure that which has three variables `a`, `b` and `c`. So you can print them out for example;
130
+
```cpp
131
+
Serial.println(current.a);
132
+
Serial.println(current.b);
133
+
Serial.println(current.c); // 0 if only two currents mode
134
+
```
135
+
If you are using only two phase current measurements in your `LowsideCurrentSense`, it will return the third current `current.c` equal to 0.
136
+
137
+
Sometimes the phase currents are hard to interpret, therefore this current sense class enables you to read the transformed current vector magnitude. The absolute DC current the motor is drawing.
138
+
```cpp
139
+
float current_mag = current_sense.getDCCurrent();
140
+
```
141
+
142
+
Futhermore if you have an access to the position sensor of the motor connected to the driver you can get signed value of the DC current the motor is drawing by providing it to the `getDCCurrent` method.
143
+
```cpp
144
+
float current = current_sense.getDCCurrent(motor_electrical_angle);
145
+
```
146
+
147
+
Finally if you have the access to the motor position sensor you current sense class will be able to tell you the FOC currents D and Q that your motor is drawing.
148
+
```cpp
149
+
DQCurrent_s current = current_sense.getFOCCurrents(motor_electrical_angle);
150
+
```
151
+
This function returns the `DQCurrent_s` structure which has two variables, `d` and `q`. You can print them out for example:
152
+
```cpp
153
+
Serial.println(current.d);
154
+
Serial.println(current.q);
155
+
```
156
+
157
+
### Example code
158
+
Here is a simple example of a low-side current sense using the <spanclass="simple">Simple<spanclass="foc">FOC</span>library</span> and to read the motor currents directly.
The driver code is written in a way to support as many different drivers out there as possible and in a way to be fully interchangeable.
28
29
These classes can be used as stand-alone classes and they can be used to set certain PWM value to the driver outputs, see example codes in `utils > driver_standalone_test`.
Copy file name to clipboardExpand all lines: docs/simplefoc_library/code/index.md
+4-2
Original file line number
Diff line number
Diff line change
@@ -132,9 +132,11 @@ For full documentation of the setup and all configuration parameters please visi
132
132
133
133
134
134
## Step 3. <ahref="current_sense"class="remove_dec"> Current sense setup</a>
135
-
After the position sensor and the driver we can proceed to initializing and configuring the current sense, if available of course. If current sense is not available you can skip this step. The library supports one type of current sense architecture and that is in-line current sensing `InlineCurrentSense`.
135
+
After the position sensor and the driver we can proceed to initializing and configuring the current sense, if available of course. If current sense is not available you can skip this step. The library supports two types of current sense architecture:
136
+
- in-line current sensing `InlineCurrentSense`.
137
+
- low-side current sensing `LowsideCurrentSense`.
136
138
137
-
`InlineCurrentSense`class instantiated by providing:
139
+
`InlineCurrentSense`and `LowsideCurrentSense` classes are instantiated by providing:
0 commit comments