From ba43df2856188c31e894efe88ef98c86cd6c0a3f Mon Sep 17 00:00:00 2001
From: David Arthur <mumrah@gmail.com>
Date: Sun, 17 Sep 2023 14:57:03 -0400
Subject: [PATCH] Add some documentation on firmware package

---
 firmware/Makefile  |  5 +++++
 firmware/README.md | 43 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 48 insertions(+)
 create mode 100644 firmware/README.md

diff --git a/firmware/Makefile b/firmware/Makefile
index 220cb86..395c485 100644
--- a/firmware/Makefile
+++ b/firmware/Makefile
@@ -4,6 +4,11 @@ SHELL=/bin/bash
 version:
 	./venv/bin/python setup.py --version
 
+.PHONY: init
+init: 
+	python3 -m venv venv
+	. venv/bin/activate; pip install -U platformio setuptools_scm
+
 .PHONY: build
 build: 
 	. venv/bin/activate; pio run -e ATmega328P_RPi 
diff --git a/firmware/README.md b/firmware/README.md
new file mode 100644
index 0000000..bbfc9cc
--- /dev/null
+++ b/firmware/README.md
@@ -0,0 +1,43 @@
+# TARPN BBD Firmware
+
+To build the firmware use the included Makefile. `make init` must be run once 
+prior to building
+
+```
+make init
+```
+
+Then, to build the firmware use the "clean" and "build" targets
+
+```
+make clean build
+```
+
+To produce a Python package with the firmware and bootloader bundled, use the "dist" target:
+
+```
+make dist
+```
+
+## tarpn-bbd-firmware Python package
+
+This directory contains a "virtual" Python package that is used for distributing
+the firmware. This is a Python package that does not contain any Python programs, 
+but rather contains the binary files for the BBD firmware and bootloader. A 
+"virtual" Python package was created to make it easy to manage different releases 
+of the firmware using pip.
+
+To install the latest firmware, use "pip install --upgrade"
+
+```
+pip install --upgrade --index-url https://pypi.mumrah.synology.me/simple tarpn-bbd-firmware
+```
+
+The version scheme used for this package (and the firmware) follows the PEP440
+convention: <MAJOR>.<MINOR>[.<SEGMENT>]
+
+* MAJOR version indicates the hardware compatibility version. This will rarely change
+* MINOR version indicates a normal revision of the firmware. This will change
+  often as bugs are fixed and features are releases.
+* SEGMENT is used for post-release and pre-release indicators.
+