stm32f1/README.md

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
- [blue pill](http://www.aliexpress.com/item/1pcs-STM32F103C8T6-ARM-STM32-Minimum-System-Development-Board-Module-For-arduino/32478120209.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, 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.
to flash the bootloader run `make bootloader`.

SWD is nice because it will always work, even if 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`

SWD also allows you to debug the code running on the micro-controller using GDB.
to start the debugging session use `make debug`.

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.

to compile the firmware run `make`

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.