From 9e822663cbbb841ee7636cfd169426e91d8fa643 Mon Sep 17 00:00:00 2001
From: xengineering <me@xengineering.eu>
Date: Sun, 26 Sep 2021 16:59:03 +0200
Subject: Add Helper Scripts and Documentation

---
 README.md | 34 ++++++++++++++++++++++++++++++++++
 gdb.sh    | 17 +++++++++++++++++
 ocd.sh    |  9 +++++++++
 3 files changed, 60 insertions(+)
 create mode 100755 gdb.sh
 create mode 100755 ocd.sh

diff --git a/README.md b/README.md
index 0306080..070c535 100644
--- a/README.md
+++ b/README.md
@@ -3,6 +3,40 @@
 
 A firmware project for the STM32F103C8T6 to control LED strips.
 
+## 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://gitea.xengineering.eu/xengineering/ledcontrol.git
+```
+
+Enter the repository and build the software
+```
+cd ledcontrol
+make
+```
+
+Connect your STM32F103C8T6 with an STLINK V2 debugger and flash the firmware:
+```
+bash ocd.sh
+# switch to a second terminal in the same folder
+bash gdb.sh build/ledcontrol.elf
+load
+run
+# CTRL + C will stop the execution
+# leave GDB with CTRL + D
+```
+
 ## External References
 
 - Nice [Tutorial](https://jacobmossberg.se/posts/2018/08/11/run-c-program-bare-metal-on-arm-cortex-m3.html) about C programs on bare-metal ARM chips
diff --git a/gdb.sh b/gdb.sh
new file mode 100755
index 0000000..45d36ab
--- /dev/null
+++ b/gdb.sh
@@ -0,0 +1,17 @@
+#!/bin/bash
+
+
+# Usage: bash gdb.sh path/to/my/firmware.elf  # call ocd.sh script before this
+
+
+ELF_FILE=$1
+
+
+# disable confirmation messages, connect to MCU via openocd server, reset MCU
+# and instantly stop execution
+arm-none-eabi-gdb "${ELF_FILE}" \
+	-ex 'set confirm off' \
+	-ex 'target extended-remote localhost:3333' \
+	-ex 'monitor reset halt'
+
+# now you can flash the firmware with 'load' and run it with 'run'
diff --git a/ocd.sh b/ocd.sh
new file mode 100755
index 0000000..02416fa
--- /dev/null
+++ b/ocd.sh
@@ -0,0 +1,9 @@
+#!/bin/bash
+
+
+# Usage: bash ocd.sh  # start gdb.sh script afterwards
+
+
+# run openocd server with telnet interface on localhost:4444 and GDB interface
+# on localhost:3333
+openocd -f interface/stlink-v2.cfg -f target/stm32f1x.cfg
-- 
cgit v1.2.3-70-g09d2