---------------------
ledcontrol / firmware
---------------------

This folder contains the firmware for the ledcontrol project. It assumes a
STM32F103C8T6 microcontroller.


Usage
-----

Install the necessary software. For Arch Linux this works like this:

	sudo pacman -S \
		base-devel \
		arm-none-eabi-binutils \
		arm-none-eabi-gcc \
		arm-none-eabi-gdb \
		arm-none-eabi-newlib

Clone this repository with all Git submodules:

	git clone --recurse-submodules https://cgit.xengineering.eu/ledcontrol

Enter the repository and build the software:

	cd ledcontrol/firmware
	make

Connect your STM32F103C8T6 with an STLINK V2 debugger and flash the firmware:

	./ocd.sh
	# switch to a second terminal in the same folder
	./gdb.sh build/ledcontrol.elf
	load
	run
	# CTRL + C will stop the execution
	# leave GDB with CTRL + D

Mention that you do not have to quit GDB to upload new compiled firmware. Just
call `load` and `run` again.


Upload firmware via serial bootloader
-------------------------------------

STM32 microcontrollers have a built-in serial bootloader to flash firmware. It
is activated if pin BOOT0 is pulled to 3.3 V, BOOT1 to 0 V (GND) and the
microcontroller is restarted. In this state it is possible to flash firmware
with just a USB to serial adapter via USART1 (PA9 and PA10). This works with a
FTDI USB to UART adapter (3.3 V TTL logic and 5 V VCC).

To upload a *.bin firmware to the MCU just follow these steps. You will need to
install the stm32flash utility (maybe via AUR):

- connect:
	- GND (UART adapter) to GND (MCU)
	- RX (UART adapter, yellow in my case) to PA9 (MCU)
	- TX (UART adapter, orange in my case) to PA10 (MCU)
	- VCC (UART adapter) to VCC (MCU) just if no other power source is
	  connected!
- set BOOT0 to 1 (3.3 V) and BOOT1 to 0 (GND)
- reboot MCU
- flash firmware with stm32flash

To flash and verify `firmware.bin` via `/dev/ttyUSB0` use this command:

	stm32flash -w firmware.bin -v /dev/ttyUSB0

It can then be started with:

	stm32flash -g 0x0 /dev/ttyUSB0

For further details run `man stm32flash`.


External References
-------------------

- tutorial about C programs on bare-metal ARM chips:
  https://jacobmossberg.se/posts/2018/08/11/run-c-program-bare-metal-on-arm-cortex-m3.html
- tutorial about STM32 programming with libopencm3:
  https://www.rhye.org/post/stm32-with-opencm3-0-compiling-and-uploading/
- PWM example from the libopencm3 project:
  https://github.com/libopencm3/libopencm3-examples/blob/master/examples/stm32/f1/obldc/pwmleds/pwmleds.c