From db26607b2d8c4db56e07a22215cbb978a1c1707b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?King=20K=C3=A9vin?= Date: Fri, 29 Jan 2016 12:12:04 +0100 Subject: [PATCH] add firmware template description --- README.md | 100 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..55d6deb --- /dev/null +++ b/README.md @@ -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. + +