Skip to content

Commit 1ebf74d

Browse files
askuricaskuric
committed
added the adc choosing guide
1 parent ead1190 commit 1ebf74d

File tree

5 files changed

+138
-18
lines changed

5 files changed

+138
-18
lines changed

‎docs/simplefoc_library/code/current_sense/low_side.md‎

Lines changed: 8 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ Low side current sensing for all the architectures is on our road-map and we are
2121

2222
## Current sensing support per MCU architecture
2323

24-
Low side current sensing is currently supported for several MCU architectures supported by the <span class="simple">Simple<span class="foc">FOC</span>library</span>. ESP32 architecture has the most generic support, supporting multiple motors per chip. Stm32 families f1, f4 and g4 are initially supported and support low-side sensing for only one motor. A special case of the STM32 board is the B-G431-ESC1 development kit which has very specific low-side implementation for its hardware configuration, and it is fully supported by the library. Samd21 architecture is under development, it has an initial support for only one motor, but for now as it has not been extensively tested, we suggest not to rely on our implementation.
24+
Low side current sensing is currently supported for several MCU architectures supported by the <span class="simple">Simple<span class="foc">FOC</span>library</span>. ESP32 architecture has the most generic support, supporting multiple motors per chip. Stm32 families f1, f4, l4, g4 and f7 are supported and support low-side sensing for only one motor. A special case of the STM32 board is the B-G431-ESC1 development kit which has very specific low-side implementation for its hardware configuration, and it is fully supported by the library. Samd21 architecture is under development, it has an initial support for only one motor, but for now as it has not been extensively tested, we suggest not to rely on our implementation. Teensy4 has an initial support for low-side sensing for one motor as well.
2525

2626
MCU | Low-side Current sensing
2727
--- | ---
@@ -49,7 +49,7 @@ Renesas (UNO R4) | ❌ (TBD)
4949

5050
Low-side current sensing requires very high synchronisation of the PWM generated by the `driver` and the ADC triggering. There are two main considerations to have in mind when choosing your `driver` parameters:
5151
1. PWM frequency considerations
52-
2. PWM pins
52+
2. Appropriate PWM and ADC pin considerations
5353

5454

5555
See more info about driver paramers in the [driver docs](drivers_config)!
@@ -69,17 +69,15 @@ driver.pwm_frequency = 20000;
6969
</code>
7070
</blockquote>
7171

72-
####  2. PWM pin considerations
73-
74-
As ADC conversion has to be synchronised with the PWM generated on ALL the phases, it is important that all the PWM generated for all the phases have aligned PWM. Since the microcontrollers usually have more than one timer for PWM generation on its pins, different architectures of microcontrollers have different degrees of alignment in between the PWM generated from different timers.
72+
####  2. Appropriate PWM and ADC pin considerations
7573

74+
As ADC conversion has to be synchronised with the PWM generated on ALL the phases, it is important that all the PWM generated for all the phases have aligned PWM and that it supports triggering of the ADC conversion. Since the microcontrollers usually have more than one timer for PWM generation and more than one ADC for reading the analog values it is important to choose the right pins for the right phase.
7675

7776
<blockquote class="info">
78-
<p class="heading">RULE OF THUMB: PWM timer pins</p>
79-
In order to maximise your chances for the low-side current sensing to work well we suggest to make sure that the PWM pins chosen for your driver all belong to the same Timer.
80-
81-
Finding out which pins belong to different timers might require some time to be spent in the MCU datasheet 😄
82-
You can also always ask the community for help - <a href="https://community.simplefoc.com/">community link</a>!
77+
<p class="heading">RULE OF THUMB: PWM timer and ADC pins</p>
78+
In order to maximise your chances for the low-side current sensing to work well we suggest to make sure that the PWM pins chosen for your driver all belong to the same Timer, and the ADC pins chosen for your current sense all belong to the same ADC.<br>
79+
📢 Here is a quick guide to choosing appropriate PWM pins for different MCU architectures <a href="choosing_pwm_pins">see in docs</a>.<br>
80+
📢 Here is a quick guide to choosing appropriate ADC pins for different MCU architectures <a href="choosing_adc_pins">see in docs</a>.
8381
</blockquote>
8482

8583

‎docs/simplefoc_library/digging_deeper/practical/choosing_pins.md‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -122,9 +122,10 @@ ESP32 | ✔️
122122
ESP32-S2| ❌
123123
ESP32-S3| ✔️
124124
ESP32-C3 | ❌
125-
ESP32-C6 | ✔️
126-
ESP32-H2 | ✔️
127-
ESP32-P4 | ✔️
125+
126+
<!-- ESP32-C6 | ?
127+
ESP32-H2 | ?
128+
ESP32-P4 | ? -->
128129

129130
All the esp32 architecture that have the `MCPWM` will by default use `MCPWM` for motor control.
130131

@@ -139,9 +140,10 @@ ESP32 | 16
139140
ESP32-S2|8
140141
ESP32-S3|8
141142
ESP32-C3|6
142-
ESP32-C6|6
143-
ESP32-H2|6
144-
ESP32-P4|8
143+
144+
<!-- ESP32-C6|6 (no arduino support yet)
145+
ESP32-H2|6 (no arduino support yet)
146+
ESP32-P4|8 (no arduino support yet) -->
145147

146148
If the user wants to force using the `LEDC` driver for the boards that support `MCPRM` he has to set the `SIMPLEFOC_ESP32_USELEDC`.
147149

@@ -359,3 +361,4 @@ FlexTimer | submodule | A | B | X
359361
`FlexPWM4`|2| 2 | 3 | -
360362

361363
</div>
364+

‎docs/simplefoc_library/digging_deeper/practical/choosing_pins_adc.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
---
2+
layout: default
3+
title: Choosing ADC pins
4+
nav_order: 4
5+
description: "Arduino Simple Field Oriented Control (FOC) library ."
6+
permalink: /choosing_adc_pins
7+
parent: Practical guides
8+
grand_parent: Digging deeper
9+
grand_grand_parent: Arduino <span class="simple">Simple<span class="foc">FOC</span>library</span>
10+
---
11+
12+
# A short guide to choosing Analog pins for your application
13+
14+
When it comes to choosing pins for your application, there are a few things to consider. The most important thing is to make sure that the pins you choose are compatible with the hardware you are using.
15+
Make sure to check that your microcontroller family and SimpleFOC supports the necessary PWM generation, position sensor and current sensing technique. You can find this info in our docs [here](microcontrollers).
16+
17+
Once you are sure that you microcontroller is apt to the application, it is time to consider which pins to use. There are three main questions:
18+
1. Which pins to use for PWM generation?
19+
2. Which pins to use for the position sensor?
20+
3. Which pins to use for current sensing?
21+
22+
In this guide we will focus on the first question: **Which analog pins to use for current sensing?**
23+
24+
The answer to these questions depends on the microcontroller you are using and the hardware you have. Here is the list of microcontroller families supported by SimpleFOC and the PWM generation modes supported by each of them:
25+
26+
MCU | In-line | Low-side | High-side
27+
--- | --- |--- |---
28+
Arduino AVR (8-bit) | ✔️ | ❌ | ❌
29+
Arduino DUE | ✔️ | ❌ | ❌
30+
stm32 (in general) | ✔️ | ❌ | ❌
31+
stm32f1 family | ✔️ | ✔️ (one motor) | ❌
32+
stm32f4 family | ✔️ | ✔️ (one motor) | ❌
33+
stm32g4 family | ✔️ | ✔️ (one motor) | ❌
34+
stm32l4 family | ✔️ | ✔️ (one motor) | ❌
35+
stm32f7 family | ✔️ | ✔️ (initial) | ❌
36+
stm32 B_G431B_ESC1 | ❌ | ✔️ (one motor) | ❌
37+
esp32/esp32s3 | ✔️ | ✔️ | ❌
38+
esp32s2/esp32c3 | ✔️ | ❌ | ❌
39+
esp8266 | ❌ | ❌ | ❌
40+
samd21 | ✔️ | ✔️ (one motor) | ❌
41+
samd51 | ✔️ | ❌ | ❌
42+
teensy3 | ✔️ | ❌ | ❌
43+
teensy4 | ✔️ | ✔️(one motor) | ❌
44+
Raspberry Pi Pico | ✔️ | ❌ | ❌
45+
Portenta H7 | ✔️ | ❌ | ❌
46+
nRF52 | ✔️ | ❌ | ❌
47+
Renesas (UNO R4 Minima) | ❌ | ❌ | ❌
48+
49+
### In-line current sensing
50+
What is important to see is that most of the the microcontroller families, except esp8266 and Arduino UNO R4, can be used with in-line current sensing. For this current sensing technique, you can use any of the analog pins, as no synchronization between the PWM signals and the current sensing is necessary.
51+
52+
### Low-side current sensing
53+
When it comes to using the low-side current sensing, a precise synchronisation between the PWM signals and the current sensing is necessary ([read more here](low_side_current_sense)).
54+
SimpleFOC aims to support low-side current sensing for all the microcontroller families that have the capability to synchronise the ADC conversion with the PWM signals.
55+
For the moment, the low-side current sensing is supported for the following microcontroller families: stm32, esp32, teensy4 and samd21.
56+
57+
58+
<blockquote class="info" markdown="1"><p class="heading">What about high-side current sensing?</p>
59+
High-side current sensing is not supported by SimpleFOC at the moment. This is mostly because the high-side sensing is very rare in practice. Most of the mcu families that can support low-side sensing could support the high side as well, but as of now there is no support for it in the library. If you are interested in this feature, please let us know on our community forum.
60+
</blockquote>
61+
62+
When it comes to choosing the analog pins for the low-side current sensing, as there is a need for the synchronization between the PWM signals (belonging to one or more timers) and the ADC conversion, the choice of the pins is more limited. **As a rule of thumb, it is recommended to use the pins that belong to the same ADC.** This comes form the fact that in the PWM synchronization process, timers often can trigger only one ADC at a time.
63+
64+
The information about the ADC associated with the pins is sometimes hard to obtain, especially for less experienced users. So in the next few sections we will provide some information on how to find the ADC pins for some of the most popular microcontroller families supporting the low-side current sensing.
65+
66+
- [ESP32 boards](#esp32-boards)
67+
- [STM32 boards](#stm32-boards)
68+
- [Teensy4 boards](#teensy4-boards)
69+
70+
## ESP32 boards
71+
72+
Esp32 boards have two ADCs that can be used for the low-side current sensing. The ADCs are associated with the pins in the following way (info from the [espressif docs](https://docs.espressif.com/projects/esp-idf/en/v4.4/esp32/api-reference/peripherals/adc.html)):
73+
74+
75+
ESP32 SoC |`ADC1` pins | `ADC2` pins
76+
--- | --- |---
77+
ESP32 | GPIO32 - GPIO39 | GPIO0, GPIO2, GPIO4, GPIO12 - GPIO15, GOIO25 - GPIO27
78+
ESP32-S2| GPIO1 - GPIO10 | GPIO11 - GPIO20
79+
ESP32-S3| GPIO1 - GPIO10 | GPIO11 - GPIO20
80+
ESP32-C3 | GPIO0 - GPIO4 | GPIO5
81+
82+
<blockquote class="info" markdown="1"><p class="heading">Important</p>
83+
Esp32 has a very flexible ADC configuration, so you can use any of the pins listed above for the low-side current sensing. However, it is recommended to use the pins that belong to the same `ADC`.
84+
</blockquote>
85+
86+
87+
## STM32 boards
88+
89+
Stm32 is the most powerful family of microcontrollers supported by SimpleFOC, at least in terms of motor control capabilities. SimpleFOC supports many of the STM32 families such as stm32f1, stm32f4, stm32g4, stm32l4, stm32f7, and all of them can be used in low-side current sensing mode.
90+
91+
<blockquote class="info" markdown="1"><p class="heading">Important</p>
92+
For low-side current sensing with stm32 boards, it is required to use the analog pins that belong to the same `ADC`.
93+
</blockquote>
94+
95+
Once you provide the SimpleFOC current sense object with a set of pins, the library will automatically associate the pins with the appropriate ADC and channels and will take care of the synchronization between the PWM signals and the ADC conversion. If the pins do not belong to the same ADC, the library will throw an error.
96+
97+
Finding the pins that belong to the same ADC is not an easy task, especially for less experienced users. Therefore, we've created a website that enables a relatively easy navigation of the pins and timers for the most popular stm32 boards.
98+
99+
<a href ="https://docs.simplefoc.com/stm32pinouts/" class="btn btn-primary"><i class="fa fa-github"></i> Open stm32 pinout helper</a>
100+
101+
## Teensy4 boards
102+
103+
Teensy4 boards are very powerful and have a lot of analog pins that can be used for with both of their ADCs. The pins that belong to the ADCs are listed in the table below. For more info see the awesome github repo [TeensyDocuments](https://github.com/KurtE/TeensyDocuments/blob/master/Teensy4%20Pins.pdf)
104+
105+
Board | `ADC1` pins only | `ADC2` pins only | Both ADCs
106+
---| ---- | ---- | ----
107+
Teensy 4 | 24, 25 | 26, 27 | 14, 15,..., 22, 23, 40, 41
108+
Teensy 4.1 | 24, 25 | 26, 27, 38, 39 | 14, 15,..., 22,23
109+
110+
111+
<blockquote class="info" markdown="1"><p class="heading">Important</p>
112+
For low-side current sensing with Teensy4 boards, it is required to use the analog pins that belong to the `ADC1`.
113+
</blockquote>

‎docs/simplefoc_library/digging_deeper/practical/index.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,12 @@ Additionally, there are many different useful practical information already avai
2828
<a href="choosing_pwm_pins">
2929
<h3 style="color:inherit"> <i class="fa fa-lg fa-wrench" style="padding:10px"></i> Choosing PWM pins for you application</h3>
3030
</a>
31-
<p> A short guide to choosing appropriate pins for your application </p>
31+
<p> A short guide to choosing appropriate PWM pins for your application </p>
32+
</div>
33+
<div >
34+
<a href="choosing_adc_pins">
35+
<h3 style="color:inherit"> <i class="fa fa-lg fa-wrench" style="padding:10px"></i> Choosing Analog pins for you application</h3>
36+
</a>
37+
<p> A short guide to choosing appropriate analog pins for your application </p>
3238
</div>
3339
<div>

‎docs/simplefoc_library/hardware/mcus/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,7 @@ The current sensing support for all the architectures is shown in the table belo
7373

7474
MCU | In-line | Low-side | High-side
7575
--- | --- |--- |---
76-
Arduino (8-bit) | ✔️ | ❌ | ❌
76+
Arduino AVR (8-bit) | ✔️ | ❌ | ❌
7777
Arduino DUE | ✔️ | ❌ | ❌
7878
stm32 (in general) | ✔️ | ❌ | ❌
7979
stm32f1 family | ✔️ | ✔️ (one motor) | ❌

0 commit comments

Comments
 (0)