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: _dev/Add-a-new-variant-(board).md
+86-57Lines changed: 86 additions & 57 deletions
Original file line number
Diff line number
Diff line change
@@ -6,7 +6,8 @@ It is described by Arduino [here](https://arduino.github.io/arduino-cli/latest/p
6
6
>
7
7
> Variants must be placed inside the variants folder in the current architecture.
8
8
9
-
Since STM32 core release 2.0.0 [`variants` folder] contains one folder for each STM32 MCU family.
9
+
> [!NOTE]
10
+
> Since STM32 core release 2.0.0 [`variants` folder] contains one folder for each STM32 MCU family.
10
11
11
12
<details>
12
13
<summary><i>Variants folders</i></summary>
@@ -53,7 +54,16 @@ Before adding a specific board, it is a good practice to add the generic entry o
53
54
> [!NOTE]
54
55
> A folder name can reference several MCU references so several boards entry could be added. Not only the one of the specific board.
55
56
56
-
## 1 - Find the MCU folder
57
+
## 1 - Get the [Arduino_Core_STM32] git repository
58
+
59
+
> [!NOTE]
60
+
> If you do not plan to share your board, you can skip this step.
61
+
62
+
To be able to contribute and create a [Pull Requests](https://help.github.com/articles/about-pull-requests/) you should use the [Arduino_Core_STM32] git repository instead of the packaged version
63
+
64
+
See [[Using-git-repository]].
65
+
66
+
## 2 - Find the MCU folder in the core
57
67
58
68
Go to the [`variants` folder] of the STM32 core (See [[Where are sources|Where-are-sources#stm32-core-sources-files-location]]).
59
69
@@ -62,11 +72,12 @@ Go to the [`variants` folder] of the STM32 core (See [[Where are sources|Where-a
62
72
[`G0B1R(B-C-E)T_G0C1R(C-E)T`]
63
73
64
74
Several files are present as stated [here](#Generated-variant-files).
65
-
It misses only the default linker script named `ldscript.ld`.
75
+
It misses only the default linker script named `ldscript.ld` and the Generic System Clock configuration.
66
76
67
-
## 2 - Add the default linker script
77
+
> [!IMPORTANT]
78
+
> [STM32CubeMX] is used to generate them. So it have to be installed first.
68
79
69
-
It could be generated thanks [STM32CubeMX].
80
+
## 3 - Create new project with [STM32CubeMX]
70
81
71
82
1. Open [STM32CubeMX] then create a **_New Project_** and select the targeted MCU. In this example the `STM32G0B1RET`:
72
83
@@ -88,25 +99,70 @@ It could be generated thanks [STM32CubeMX].
3. Generate the code by clicking on **_ Generate Code_** button and open the folder
102
+
## 4 - System Clock configuration
103
+
104
+
`generic_clock.c` contains the default system clock configuration which is empty by default. So the default clock
105
+
at reset will be used as stated by the warning:
106
+
107
+
```c
108
+
WEAK voidSystemClock_Config(void)
109
+
{
110
+
/* SystemClock_Config can be generated by STM32CubeMX */
111
+
#warning "SystemClock_Config() is empty. Default clock at reset is used."
112
+
}
113
+
```
114
+
115
+
> [!IMPORTANT]
116
+
> For generic board the internal clock is used: mainly `HSI` or `CSI` or `MSI` depending of the series.
117
+
118
+
1. Go to **_Pinout_** tab, enable the peripherals which require specific clock configuration (not needed for peripherals clocked by `HCLKx`, or `APBx` clock).
119
+
120
+
Clock configuration means `clock mux selection` (if any) and `frequency`, see the [STM32CubeMX] user manual to
121
+
get help on the **Clock Configuration** tab and refer to the mcu documentation to get each peripheral constraints.
122
+
123
+
Usually below peripheral have to be enabled and input clock source constraint have to be checked. [STM32CubeMX] will help and warn if clock configuration is not correct else refer to the mcu documentation:
124
+
* `USB`: **48MHz** clock source.
125
+
* `SDIO` or `SDMMC`: **48MHz**
126
+
* `LPUARTx`: clock source must be in the range: **[3 x baud rate, 4096 x baud rate]** so ensure to be able to use `9600 bps`.
127
+
* `ADC` and/or `DAC`: on some series they are specific constraints.
128
+
129
+
In this example only `USB` needs to be enabled as other peripherals default clock are correct by default.
* Set `PLL Source Mux` to `HSI` if it exists else set `HSI` as `System Clock Mux`. Or any other internal clock.
139
+
* Try to set the CPU clock and `HCLK` to the maximum frequencies, [STM32CubeMX] will automatically configure the clock tree and resolve conflict if any. Sometimes due to some constraints (ex: USB) maximum frequency is not reachable.
140
+
141
+
3. Generate the code by clicking on **Generate Code** button and open the folder.
`generic_clock.c` contains the default system clock configuration which is empty by default. So the default clock
129
-
at reset will be used as stated by the warning:
183
+
## 6 - Update the default System Clock
130
184
131
-
```c
132
-
WEAK voidSystemClock_Config(void)
133
-
{
134
-
/* SystemClock_Config can be generated by STM32CubeMX */
135
-
#warning "SystemClock_Config() is empty. Default clock at reset is used."
136
-
}
137
-
```
138
-
139
-
> [!IMPORTANT]
140
-
> For generic board the internal clock is used: `HSI`.
141
-
142
-
[STM32CubeMX] is also used to generate it.
143
-
144
-
1. Go to **_Pinout_** tab, enable the desired peripherals which require specific clock configuration (not needed for peripherals clocked by `HCLKx`, or `APBx` clock): `SDIO`, `USB`, ...
145
-
In this example only `USB` needs to be enabled as other peripherals default clock are correct by default.
* Try to set the CPU clock and `HCLK` to the maximum frequencies, [STM32CubeMX] will automatically configure the clock tree and resolve conflict if any. Sometimes due to some constraints (ex: USB) maximum frequency is not reachable.
156
-
3. Generate the code by clicking on **_ Generate Code_** button and open the folder
4. In the `generic_clock.c` replace the body of the `SystemClock_Config(void)` by the one generated in `src/main.c` of the generated project.
185
+
In the `generic_clock.c` replace the body of the `SystemClock_Config(void)` by the one generated in `src/main.c` of the generated project and ensure to add each peripheral clock config available in the `stm32yyxx_hal_msp.c` file if any.
165
186
166
187
<details>
167
188
<summary><i>Example</i></summary>
@@ -229,17 +250,20 @@ In this example only `USB` needs to be enabled as other peripherals default cloc
229
250
> + RCC_ClkInitTypeDef RCC_ClkInitStruct = {};
230
251
> ```
231
252
232
-
## 4 - Declare the variant
253
+
## 7 - Declare the board
254
+
233
255
It is still to add the menu and add relevant information (Flash and SRAM sizes, ...)
234
256
235
257
> [!TIP]
236
258
> See [Arduino boards.txt specification] for further options.
237
259
238
260
Edit [`boards.txt`] file, then:
239
261
1. Find the menu part where to add the generic entry. In this example the `GenG0` menu.
240
-
2. Copy all the boards entry from the `board_entry.txt` file to this section. Pay attention to alphabetical order.
262
+
2. Copy all the boards entry from the `board_entry.txt` file to this section.
263
+
> [!WARNING]
264
+
> Pay attention to alphabetical order.
241
265
3. Check if the `build.product_line=` is correct and match the `STM32YYXXxx` MCU version.
242
-
4. Check the `upload.maximum_size=` and `upload.maximum_data_size=`
266
+
4. Check the `upload.maximum_size=` and `upload.maximum_data_size=`, sometimes not all the flash or RAM are available because they are not contiguous.
Finally, all the new reference have to be added in the [`README.md`]
321
+
Finally, all the new reference have to be added in the [`README.md`] using :yellow_heart: and set the next version. See the [milestones](https://github.com/stm32duino/Arduino_Core_STM32/milestones) to know the next version.
322
+
323
+
> [!Note]
324
+
> -:green_heart: board support is available since the specified release version.
325
+
> -:yellow_heart: board support is available in the main branch and will be available in the next release version.
298
326
299
327
<details>
300
328
<summary><i>Example</i></summary>
@@ -308,19 +336,19 @@ Finally, all the new reference have to be added in the [`README.md`]
308
336
```
309
337
</details>
310
338
311
-
## 6 - Verify your changes
312
-
After your commit has been merged, you need a way to test it since it has not been released
313
-
yet. You can do that by following
314
-
[Using a git repository](https://github.com/stm32duino/Arduino_Core_STM32/wiki/Using-git-repository).
339
+
## 9 - Verify your changes
315
340
316
341
Then verify your changes with the [CheckVariant example].
317
342
343
+
> [!Note]
344
+
> This example will print on the default `Serial` so ensure to use this one, same for the `LED_BUILTIN`.
345
+
318
346
> [!IMPORTANT]
319
347
> An issue with the Arduino IDE 2.x prevents the board to appears
320
348
> in the menu. Follow this workaround to get it working:
0 commit comments