add firmware template description

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.
+
+