From 962dc6ab95998245b8c2a1f0c5cad3c7af857b07 Mon Sep 17 00:00:00 2001
From: BlackMark <me@blackmark.me>
Date: Thu, 9 Jul 2020 18:52:36 +0200
Subject: [PATCH] Add readme to firmware

---
 firmware/README.md | 94 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 94 insertions(+)
 create mode 100644 firmware/README.md

diff --git a/firmware/README.md b/firmware/README.md
new file mode 100644
index 0000000..0a56e12
--- /dev/null
+++ b/firmware/README.md
@@ -0,0 +1,94 @@
+# Adaptive Brightness Firmware
+
+## Building
+
+### Prerequisites
+
+- [gcc-arm-none-eabi](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads) with C++17 support
+- make
+
+### Build instructions
+
+The gcc-arn-none-eabi compiler needs to be in the path. For example by executing `export PATH="$(pwd):$PATH"` in the `bin` directory of the toolchain.
+
+Navigate to the firmware directory and do:
+
+```console
+$ make
+```
+
+This will build the firmware in a directory called `build`. By default the firmware will be built in release mode. Change the `DEBUG` and `OPT` settings in the Makefile for a debug build like this:
+
+```Makefile
+DEBUG = 1
+OPT  = -Og
+```
+
+## Flashing
+
+The firmware can either be flashed using the built-in DFU bootloader or using the SWD (Serial Wire Debug) interface with, for example, an ST-Link v2 programmer/debugger.
+
+### DFU
+
+#### Prerequisites for DFU
+
+- [dfu-util](https://sourceforge.net/projects/dfu-util/files/)
+- [Zadig](https://zadig.akeo.ie/) (Windows only)
+
+#### Entering DFU bootloader
+
+The board has a button labeled **BOOT**, hold this button down while plugging in the device and the DFU bootloader will be executed.
+
+#### Installing correct driver (Windows only)
+
+Use Zadig to install the `WinUSB` driver for the device while it is running the bootloader. Make sure to enable the _List All Devices_ option in order to be able to select the device.
+
+This only needs to be done once. Windows will then always use the installed driver for this device.
+
+#### Flashing with dfu-util
+
+You can check if the device is recognized by executing:
+
+```console
+$ dfu-util -l
+
+Found DFU: [0483:df11] ver=2200, devnum=57, cfg=1, intf=0, path="2-13.2.2", alt=1, name="@Option Bytes  /0x1FFFF800/01*016 e", serial="FFFFFFFEFFFF"
+Found DFU: [0483:df11] ver=2200, devnum=57, cfg=1, intf=0, path="2-13.2.2", alt=0, name="@Internal Flash  /0x08000000/032*0001Kg", serial="FFFFFFFEFFFF"
+```
+
+The firmware can then be flashing using:
+
+```console
+$ dfu-util -a 0 -s 0x08000000 -D AdaptiveBrightnessFirmware.bin
+
+Invalid DFU suffix signature
+A valid DFU suffix will be required in a future dfu-util release!!!
+Opening DFU capable USB device...
+ID 0483:df11
+Run-time device DFU version 011a
+Claiming USB DFU Interface...
+Setting Alternate Setting #0 ...
+Determining device status: state = dfuERROR, status = 10
+dfuERROR, clearing status
+Determining device status: state = dfuIDLE, status = 0
+dfuIDLE, continuing
+DFU mode device DFU version 011a
+Device returned transfer size 2048
+DfuSe interface name: "Internal Flash  "
+Downloading to address = 0x08000000, size = 21256
+Download        [=========================] 100%        21256 bytes
+Download done.
+File downloaded successfully
+```
+
+You need to unplug and re-plug the device to exit the bootloader and start executing the firmware.
+
+### SWD
+
+Instructions vary depending on the SWD device and software used. As an example you could use `openocd` with an ST-Link v2 like this:
+
+```console
+$ openocd -f interface/stlink.cfg  -f target/stm32f0x.cfg -c "program build/AdaptiveBrightnessFirmware.elf verify reset exit"
+```
+
+**Note:** The `STM32 ST-LINK Utility` from ST does not issue a reset signal over the SWD interface. This makes flashing using this tool extremely difficult, as the reset line has to be manually triggered for the utility to be able to connect to the chip. `openocd` does not have this problem.