Add documentation for adding a board

This commit is contained in:
Daniel Fekete 2017-04-26 08:51:52 +02:00
parent 4760f3dead
commit 6c54f3d03a
6 changed files with 106 additions and 48 deletions

View File

@ -197,8 +197,6 @@
<li><a href="#8-run-the-blink-example-on-your-new-board">8. Run the blink example on your new board</a></li>
<li><a href="#9-run-the-tests-on-the-board-to-check-if-it-is-working">9. Run the tests on the board to check if it is working</a></li>
</ul>
@ -206,17 +204,51 @@
<div class="col-md-9" role="main">
<h1 id="add-your-board">Add your board:</h1>
<p>TODO explain all steps</p>
<h2 id="1-create-a-copy-of-the-stm32variantstemplate-folder-with-a-name-of-your-choice">1. Create a copy of the STM32/variants/TEMPLATE folder with a name of your choice.</h2>
<p>TODO make TEMPLATE folder</p>
<p>TODO create TEMPLATE, for now just use an existing one</p>
<h2 id="2-edit-the-ldscriptld-file">2. Edit the ldscript.ld file</h2>
<ol>
<li>Change the _estack to point to the end of RAM</li>
<li>FLASH LENGTH to be the size of RAM of the microcontroller</li>
<li>RAM LENGTH to be the size of RAM of the microcontroller</li>
</ol>
<p>TODO CCRAM? SDRAM?</p>
<h2 id="3-edit-the-varianth-file">3. Edit the variant.h file</h2>
<ol>
<li>Copy the <code>enum {</code>... from <code>system/STM32XX/stm32_chip/stm32_STM32XXXXXX.h</code> file. </li>
<li>If the board has pin name - pin number assigments (for example arduino headers), rearrange the enum accordingly.</li>
<li>Change LED_BUILTIN, MOSI, MISO... macros to point to the primary LED, primary SPI, primary I2C pins.</li>
<li>Add board specific macros if the board has extra leds, buttons, SPI CS select lines etc...</li>
</ol>
<h2 id="4-edit-the-variantcpp-file">4. Edit the variant.cpp file</h2>
<ol>
<li>Copy the <code>const stm32_port_pin_type variant_pin_list[] = {</code> from <code>system/STM32XX/stm32_chip/stm32_STM32XXXXXX.h</code> file.</li>
<li>Rearrange to be the same as <code>enum {</code> in <code>variant.h</code></li>
</ol>
<h2 id="5-edit-the-systemclock_configc-file">5. Edit the systemclock_config.c file</h2>
<ol>
<li>Run STM32CubeMX, select the chip for your board</li>
<li>If the board has external crystal, set RCC HSE to crystal. In clock configuration, set PLL Source to HSE, set HSE to the frequency of the board crystal.</li>
<li>Set some peripherals (SPI, I2C, SDIO, USB, ...), so that the clock configuration will generate extra code needed for those peripherals, and bounds check the frequencies.</li>
<li>Go to clock configuration, set everything to maximum :), let CubeMX figure out the rest.</li>
<li>Click generate. Set toolchain/IDE to SW4STM32. Clik OK</li>
<li>From the generated src/main.c, copy <code>void SystemClock_Config(void) {</code> into your <code>variant/.../systemclock_config.c</code></li>
</ol>
<h2 id="6-edit-the-boardstxt-file">6. Edit the boards.txt file</h2>
<p>TODO create template. For now, copy an existing board</p>
<ol>
<li>Rename the board</li>
<li>Change <code>build.mcu=</code> to your cortex-mX version</li>
<li>Change <code>build.series=</code> to STM32XX, where XX is the chip series</li>
<li>Change <code>build.extra_flags=-DSTM32XXXXXX</code> to be the exact chip version</li>
<li>Change <code>upload.maximum_size=</code> and <code>upload.maximum_data_size=</code> to the RAM/FLASH size of the chip</li>
<li>If the external crystal is not the board default in <code>system/STM32XX/HAL_SRC/system_stm32XXxx.c</code>, add <code>-DHSE_VALUE=8000000</code> to <code>xxx.build.extra_flags</code></li>
<li>TODO explain upload / usb / serial menu options</li>
</ol>
<h2 id="7-restart">7. Restart</h2>
<p>Restart Arduino IDE</p>
<h2 id="8-run-the-blink-example-on-your-new-board">8. Run the blink example on your new board</h2>
<h2 id="9-run-the-tests-on-the-board-to-check-if-it-is-working">9. Run the <a href="../test/">tests</a> on the board to check if it is working</h2></div>
<p>Run examples / basic / blink</p></div>
</div>
<footer class="col-md-12">

View File

@ -344,23 +344,23 @@ TODO not all implemented</p>
</tr>
<tr>
<td>MOSI</td>
<td>MOSI pin of the first <a href="arduino_libraries.md#spi">SPI</a></td>
<td>MOSI pin of the first <a href="../spi/">SPI</a></td>
</tr>
<tr>
<td>MISO</td>
<td>MISO pin of the first <a href="arduino_libraries.md#spi">SPI</a></td>
<td>MISO pin of the first <a href="../spi/">SPI</a></td>
</tr>
<tr>
<td>SCK</td>
<td>SCK pin of the first <a href="arduino_libraries.md#spi">SPI</a></td>
<td>SCK pin of the first <a href="../spi/">SPI</a></td>
</tr>
<tr>
<td>SDA</td>
<td>SDA pin of the first <a href="arduino_libraries.md#wire-i2c">I2C</a></td>
<td>SDA pin of the first <a href="../i2c/">I2C</a></td>
</tr>
<tr>
<td>SCL</td>
<td>SCL pin of the first <a href="arduino_libraries.md#wire-i2c">I2C</a></td>
<td>SCL pin of the first <a href="../i2c/">I2C</a></td>
</tr>
</tbody>
</table></div>

View File

@ -362,59 +362,54 @@
},
{
"location": "/add_board/",
"text": "Add your board:\n\n\nTODO explain all steps\n\n\n1. Create a copy of the STM32/variants/TEMPLATE folder with a name of your choice.\n\n\nTODO make TEMPLATE folder\n\n\n2. Edit the ldscript.ld file\n\n\n3. Edit the variant.h file\n\n\n4. Edit the variant.cpp file\n\n\n5. Edit the systemclock_config.c file\n\n\n6. Edit the boards.txt file\n\n\n7. Restart\n\n\n8. Run the blink example on your new board\n\n\n9. Run the \ntests\n on the board to check if it is working",
"text": "Add your board:\n\n\n1. Create a copy of the STM32/variants/TEMPLATE folder with a name of your choice.\n\n\nTODO create TEMPLATE, for now just use an existing one\n\n\n2. Edit the ldscript.ld file\n\n\n\n\nChange the _estack to point to the end of RAM\n\n\nFLASH LENGTH to be the size of RAM of the microcontroller\n\n\nRAM LENGTH to be the size of RAM of the microcontroller\n\n\n\n\nTODO CCRAM? SDRAM?\n\n\n3. Edit the variant.h file\n\n\n\n\nCopy the \nenum {\n... from \nsystem/STM32XX/stm32_chip/stm32_STM32XXXXXX.h\n file. \n\n\nIf the board has pin name - pin number assigments (for example arduino headers), rearrange the enum accordingly.\n\n\nChange LED_BUILTIN, MOSI, MISO... macros to point to the primary LED, primary SPI, primary I2C pins.\n\n\nAdd board specific macros if the board has extra leds, buttons, SPI CS select lines etc...\n\n\n\n\n4. Edit the variant.cpp file\n\n\n\n\nCopy the \nconst stm32_port_pin_type variant_pin_list[] = {\n from \nsystem/STM32XX/stm32_chip/stm32_STM32XXXXXX.h\n file.\n\n\nRearrange to be the same as \nenum {\n in \nvariant.h\n\n\n\n\n5. Edit the systemclock_config.c file\n\n\n\n\nRun STM32CubeMX, select the chip for your board\n\n\nIf the board has external crystal, set RCC HSE to crystal. In clock configuration, set PLL Source to HSE, set HSE to the frequency of the board crystal.\n\n\nSet some peripherals (SPI, I2C, SDIO, USB, ...), so that the clock configuration will generate extra code needed for those peripherals, and bounds check the frequencies.\n\n\nGo to clock configuration, set everything to maximum :), let CubeMX figure out the rest.\n\n\nClick generate. Set toolchain/IDE to SW4STM32. Clik OK\n\n\nFrom the generated src/main.c, copy \nvoid SystemClock_Config(void) {\n into your \nvariant/.../systemclock_config.c\n\n\n\n\n6. Edit the boards.txt file\n\n\nTODO create template. For now, copy an existing board\n\n\n\n\nRename the board\n\n\nChange \nbuild.mcu=\n to your cortex-mX version\n\n\nChange \nbuild.series=\n to STM32XX, where XX is the chip series\n\n\nChange \nbuild.extra_flags=-DSTM32XXXXXX\n to be the exact chip version\n\n\nChange \nupload.maximum_size=\n and \nupload.maximum_data_size=\n to the RAM/FLASH size of the chip\n\n\nIf the external crystal is not the board default in \nsystem/STM32XX/HAL_SRC/system_stm32XXxx.c\n, add \n-DHSE_VALUE=8000000\n to \nxxx.build.extra_flags\n\n\nTODO explain upload / usb / serial menu options\n\n\n\n\n7. Restart\n\n\nRestart Arduino IDE\n\n\n8. Run the blink example on your new board\n\n\nRun examples / basic / blink",
"title": "Adding a board"
},
{
"location": "/add_board/#add-your-board",
"text": "TODO explain all steps",
"text": "",
"title": "Add your board:"
},
{
"location": "/add_board/#1-create-a-copy-of-the-stm32variantstemplate-folder-with-a-name-of-your-choice",
"text": "TODO make TEMPLATE folder",
"text": "TODO create TEMPLATE, for now just use an existing one",
"title": "1. Create a copy of the STM32/variants/TEMPLATE folder with a name of your choice."
},
{
"location": "/add_board/#2-edit-the-ldscriptld-file",
"text": "",
"text": "Change the _estack to point to the end of RAM FLASH LENGTH to be the size of RAM of the microcontroller RAM LENGTH to be the size of RAM of the microcontroller TODO CCRAM? SDRAM?",
"title": "2. Edit the ldscript.ld file"
},
{
"location": "/add_board/#3-edit-the-varianth-file",
"text": "",
"text": "Copy the enum { ... from system/STM32XX/stm32_chip/stm32_STM32XXXXXX.h file. If the board has pin name - pin number assigments (for example arduino headers), rearrange the enum accordingly. Change LED_BUILTIN, MOSI, MISO... macros to point to the primary LED, primary SPI, primary I2C pins. Add board specific macros if the board has extra leds, buttons, SPI CS select lines etc...",
"title": "3. Edit the variant.h file"
},
{
"location": "/add_board/#4-edit-the-variantcpp-file",
"text": "",
"text": "Copy the const stm32_port_pin_type variant_pin_list[] = { from system/STM32XX/stm32_chip/stm32_STM32XXXXXX.h file. Rearrange to be the same as enum { in variant.h",
"title": "4. Edit the variant.cpp file"
},
{
"location": "/add_board/#5-edit-the-systemclock_configc-file",
"text": "",
"text": "Run STM32CubeMX, select the chip for your board If the board has external crystal, set RCC HSE to crystal. In clock configuration, set PLL Source to HSE, set HSE to the frequency of the board crystal. Set some peripherals (SPI, I2C, SDIO, USB, ...), so that the clock configuration will generate extra code needed for those peripherals, and bounds check the frequencies. Go to clock configuration, set everything to maximum :), let CubeMX figure out the rest. Click generate. Set toolchain/IDE to SW4STM32. Clik OK From the generated src/main.c, copy void SystemClock_Config(void) { into your variant/.../systemclock_config.c",
"title": "5. Edit the systemclock_config.c file"
},
{
"location": "/add_board/#6-edit-the-boardstxt-file",
"text": "",
"text": "TODO create template. For now, copy an existing board Rename the board Change build.mcu= to your cortex-mX version Change build.series= to STM32XX, where XX is the chip series Change build.extra_flags=-DSTM32XXXXXX to be the exact chip version Change upload.maximum_size= and upload.maximum_data_size= to the RAM/FLASH size of the chip If the external crystal is not the board default in system/STM32XX/HAL_SRC/system_stm32XXxx.c , add -DHSE_VALUE=8000000 to xxx.build.extra_flags TODO explain upload / usb / serial menu options",
"title": "6. Edit the boards.txt file"
},
{
"location": "/add_board/#7-restart",
"text": "",
"text": "Restart Arduino IDE",
"title": "7. Restart"
},
{
"location": "/add_board/#8-run-the-blink-example-on-your-new-board",
"text": "",
"text": "Run examples / basic / blink",
"title": "8. Run the blink example on your new board"
},
{
"location": "/add_board/#9-run-the-tests-on-the-board-to-check-if-it-is-working",
"text": "",
"title": "9. Run the tests on the board to check if it is working"
},
{
"location": "/test/",
"text": "Self tesing boards\n\n\nTo automatically check if the board works, there are tests in the library.\nThese work by connecting pins to \n\n\nGeneric STM32 Arduino API test\n\n\nThis test should work on almost all STM32 boards. \n\n\n\n\nFrom the arduino menu, select File/Examples/Examples for XXX/SelfTest\n\n\nConnect PA0 to PA1 to test digital/analog/read/write/interrupt\n\n\nConnect SPI MOSI to SPI MISO to test SPI\n\n\nSelect a free UART (not used for Serial) on the board, connect the RX to TX, set the SerialUartToTest macro in the sketch\n\n\nRun the sketch\n\n\n\n\nThe result should be short blink on the board LED.\nIf there was a failure, it is shown as a long LED \n\n\nThe results are also",

View File

@ -4,7 +4,7 @@
<url>
<loc>/</loc>
<lastmod>2017-04-21</lastmod>
<lastmod>2017-04-26</lastmod>
<changefreq>daily</changefreq>
</url>
@ -12,7 +12,7 @@
<url>
<loc>/upload/</loc>
<lastmod>2017-04-21</lastmod>
<lastmod>2017-04-26</lastmod>
<changefreq>daily</changefreq>
</url>
@ -21,43 +21,43 @@
<url>
<loc>/menu_options/</loc>
<lastmod>2017-04-21</lastmod>
<lastmod>2017-04-26</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>/arduino_api/</loc>
<lastmod>2017-04-21</lastmod>
<lastmod>2017-04-26</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>/spi/</loc>
<lastmod>2017-04-21</lastmod>
<lastmod>2017-04-26</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>/i2c/</loc>
<lastmod>2017-04-21</lastmod>
<lastmod>2017-04-26</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>/uart/</loc>
<lastmod>2017-04-21</lastmod>
<lastmod>2017-04-26</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>/usb_cdc/</loc>
<lastmod>2017-04-21</lastmod>
<lastmod>2017-04-26</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>/stm32_hal/</loc>
<lastmod>2017-04-21</lastmod>
<lastmod>2017-04-26</lastmod>
<changefreq>daily</changefreq>
</url>
@ -66,7 +66,7 @@
<url>
<loc>/libraries/</loc>
<lastmod>2017-04-21</lastmod>
<lastmod>2017-04-26</lastmod>
<changefreq>daily</changefreq>
</url>
@ -75,19 +75,19 @@
<url>
<loc>/boards/</loc>
<lastmod>2017-04-21</lastmod>
<lastmod>2017-04-26</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>/add_board/</loc>
<lastmod>2017-04-21</lastmod>
<lastmod>2017-04-26</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>/test/</loc>
<lastmod>2017-04-21</lastmod>
<lastmod>2017-04-26</lastmod>
<changefreq>daily</changefreq>
</url>
@ -96,7 +96,7 @@
<url>
<loc>/about/</loc>
<lastmod>2017-04-21</lastmod>
<lastmod>2017-04-26</lastmod>
<changefreq>daily</changefreq>
</url>

View File

@ -1,23 +1,54 @@
# Add your board:
TODO explain all steps
## 1. Create a copy of the STM32/variants/TEMPLATE folder with a name of your choice.
TODO make TEMPLATE folder
TODO create TEMPLATE, for now just use an existing one
## 2. Edit the ldscript.ld file
1. Change the _estack to point to the end of RAM
2. FLASH LENGTH to be the size of RAM of the microcontroller
3. RAM LENGTH to be the size of RAM of the microcontroller
TODO CCRAM? SDRAM?
## 3. Edit the variant.h file
1. Copy the `enum {`... from `system/STM32XX/stm32_chip/stm32_STM32XXXXXX.h` file.
2. If the board has pin name - pin number assigments (for example arduino headers), rearrange the enum accordingly.
3. Change LED_BUILTIN, MOSI, MISO... macros to point to the primary LED, primary SPI, primary I2C pins.
4. Add board specific macros if the board has extra leds, buttons, SPI CS select lines etc...
## 4. Edit the variant.cpp file
1. Copy the `const stm32_port_pin_type variant_pin_list[] = {` from `system/STM32XX/stm32_chip/stm32_STM32XXXXXX.h` file.
2. Rearrange to be the same as `enum {` in `variant.h`
## 5. Edit the systemclock_config.c file
1. Run STM32CubeMX, select the chip for your board
2. If the board has external crystal, set RCC HSE to crystal. In clock configuration, set PLL Source to HSE, set HSE to the frequency of the board crystal.
3. Set some peripherals (SPI, I2C, SDIO, USB, ...), so that the clock configuration will generate extra code needed for those peripherals, and bounds check the frequencies.
4. Go to clock configuration, set everything to maximum :), let CubeMX figure out the rest.
5. Click generate. Set toolchain/IDE to SW4STM32. Clik OK
6. From the generated src/main.c, copy `void SystemClock_Config(void) {` into your `variant/.../systemclock_config.c`
## 6. Edit the boards.txt file
TODO create template. For now, copy an existing board
1. Rename the board
2. Change `build.mcu=` to your cortex-mX version
3. Change `build.series=` to STM32XX, where XX is the chip series
4. Change `build.extra_flags=-DSTM32XXXXXX` to be the exact chip version
5. Change `upload.maximum_size=` and `upload.maximum_data_size=` to the RAM/FLASH size of the chip
6. If the external crystal is not the board default in `system/STM32XX/HAL_SRC/system_stm32XXxx.c`, add `-DHSE_VALUE=8000000` to `xxx.build.extra_flags`
7. TODO explain upload / usb / serial menu options
## 7. Restart
Restart Arduino IDE
## 8. Run the blink example on your new board
## 9. Run the [tests](test.md) on the board to check if it is working
Run examples / basic / blink

View File

@ -126,8 +126,8 @@ Constant | Meaning
------------------|-----------
LED_BUILTIN | The primary LED on board, if there is any
STM32_LED_BUILTIN_ACTIVE_LOW | If set, the onboard LED lights up when output is set to LOW
MOSI | MOSI pin of the first [SPI](arduino_libraries.md#spi)
MISO | MISO pin of the first [SPI](arduino_libraries.md#spi)
SCK | SCK pin of the first [SPI](arduino_libraries.md#spi)
SDA | SDA pin of the first [I2C](arduino_libraries.md#wire-i2c)
SCL | SCL pin of the first [I2C](arduino_libraries.md#wire-i2c)
MOSI | MOSI pin of the first [SPI](spi.md)
MISO | MISO pin of the first [SPI](spi.md)
SCK | SCK pin of the first [SPI](spi.md)
SDA | SDA pin of the first [I2C](i2c.md)
SCL | SCL pin of the first [I2C](i2c.md)