add firmware template description

This commit is contained in:
King Kévin 2016-01-29 12:12:04 +01:00
parent 5b4df1bc8a
commit db26607b2d
1 changed files with 100 additions and 0 deletions

100
README.md Normal file
View File

@ -0,0 +1,100 @@
this firmware template is designed for development boards based around [STM32 F1 series micro-controller](http://www.st.com/web/en/catalog/mmc/FM141/SC1169/SS1031).
dependencies
============
the source code uses the [libopencm3 library](http://libopencm3.org/), designed for such micro-controllers.
it also uses the [STM32duino-bootloader](https://github.com/rogerclarkmelbourne/STM32duino-bootloader) for easier flashing
both project are already git submodules.
to initialize and get them you just need to run once:
```bash
git submodule init
git submodule update
```
board
=====
currently the following development boards are supported:
- [Maple Mini](http://leaflabs.com/docs/hardware/maple-mini.html), based on a STM32F103CBT6
- [System Board](http://www.aliexpress.com/item/stm32f103c8t6-stm32f103-stm32f1-stm32-system-board-learning-board-evaluation-kit-development-board/2042654667.html), based on a STM32F103C8T6
**you need to define which board you are using in the Makefile**
this is required:
- for the linker script to know the memory layout (flash and RAM)
- to flash the corresponding bootloader
- map the user LEDs and buttons provided on the board
flash
=====
the `Makefile` offers two ways of flashing the firmware on the board:
- over the SWD port (Serial Wire Debug)
- using the USB DFU interface (Device Firmware Upgrade)
the default mechanism `make flash` uses DFU.
SWD
---
to flash over SWD you need an SWD adapter.
the `Makefile` uses a ST-Link V2 (clone), along with the OpenOCD software.
the main firmware will be placed after the bootloader.
thus you first need to flash the bootloader first (see below), else the main firmware will not be started.
SWD is nice because it will always work, even is USB is buggy, or the code on the board is stuck.
it also does not require to press on any reset button.
to flash using SWD run `make flash-swd`
DFU
---
to flash using DFU you just need to connect the USB port.
when booting the micro-controller will start the STM32duino-bootloader bootloader.
this configures the USB to accept firmware updates.
after a short timeout (<1s) it will start the main firmware.
the main firmware will not be started if the bootloader is missing.
you only have to flash the bootloader once, using the SWD method.
to flash the bootloader run `make bootloader`.
to then flash using DFU run `make flash-dfu`.
this will try to reset the board to start the bootloader.
else you will need to reset the board manually using the reset button.
firmware
========
the firmware provides basic example code for various peripherals.
button
------
if a button is present on the board, pressing it will toggle the LED.
UART
-----
whatever you send over UART (USART1) will be echoed back (also over USB).
USB
---
the firmware also offer serial communication over USB using the CDC ACM device class.
since the micro-controller first starts the bootloader, it is recognised a DFU device.
to provide the CDC ACM interface the host needs to re-enumerate the USB device.
for this a disconnect disconnect is simulated by pulling USB D+ low for a short time (in software or using a dedicated circuit).
then the host will re-enumerate the USB device and see the CDC ACM interface.
whatever you send over USB (CDC ACM) will be echoed back (also over UART).
additionally you can reset the board by setting the serial width to 5 bits.
this allows to restart the bootloader and flash new firmware using DFU.
to reset the board run `make reset`.
this only works if the USB CDC ACM run correctly and the micro-controller isn't stuck.