From d2cb012e1e4d71815613b1c411fda41211f647a2 Mon Sep 17 00:00:00 2001
From: Tanner Collin <git@tannercollin.com>
Date: Mon, 18 Feb 2019 00:42:03 -0700
Subject: [PATCH] Update firmware readme

---
 firmware/README.md  | 67 +++++++++++++++++++++++++++++++++++++++++++++
 firmware/README.txt | 20 --------------
 2 files changed, 67 insertions(+), 20 deletions(-)
 create mode 100644 firmware/README.md
 delete mode 100644 firmware/README.txt

diff --git a/firmware/README.md b/firmware/README.md
new file mode 100644
index 0000000..6f956b5
--- /dev/null
+++ b/firmware/README.md
@@ -0,0 +1,67 @@
+# Protospace lockout firmware
+
+Runs on the Wemos D1 Mini in each lockout.
+
+## Building
+
+Open `firmware.ino` in the Arduino IDE.
+
+### Dependencies
+
+- ESP8266 Core version 2.5.0
+- ArduinoJson 5.13.3
+
+Open File > Preferences > Additional Boards Manager URLs. Add `http://arduino.esp8266.com/stable/package_esp8266com_index.json`.
+
+Open Tools > Board > Boards Manager. Filter for `esp8266`. Select version 2.5.0 and install.
+
+Open Sketch > Include Library > Manage Libraries. Filter for `arduinojson`. Select version 5.13.3 and install.
+
+Open Tools > Board. Select `LOLIN(WEMOS) D1 R2 & mini` from the ESP8266 section. Leave the rest of the settings alone.
+
+### Deployment
+
+#### Over USB
+
+Leave the number in `LOCKOUT_FIRMWARE_VERSION` alone or else the lockout will update itself.
+
+Unplug the Wemos from the socket inside the lockout (important). Attach via USB to your computer.
+
+Open Tools > Port. Select the USB port.
+
+Open Sketch > Upload.
+
+#### Over the air
+
+Increment the number in `LOCKOUT_FIRMWARE_VERSION`. Leave `MRWIZARD` alone, it's needed to extract the version.
+
+Open Sketch > Export Compiled Binary. The firmware should now build.
+
+Login to http://tools-auth.protospace.ca/firmware/ and upload the output `firmware.ino.d1_mini`. Select the deployment group carefully.
+
+## Folder structure
+
+- `firmware.ino` string constants, global variables, main setup, interrupt loop, main loop
+- `utils.cpp` helper functions: hardware abstraction, card checking functions, json (de)serializers
+- `logging.cpp` log functions: add and remove log records
+
+- `comm.cpp` communication to webserver and authserver, HTTP POST and GET functions
+- `leds.cpp` LED control state machine for off, armed, on, and error
+- `lock.cpp` lockout relay control state machine, deal with button presses
+- `wifi.cpp` Wi-Fi control state machine for reconnecting when needed
+
+- `*.h` system settings such as delay times, pins, state machine enum definitions
+
+## Contributing
+
+This is the most critical part of the lockouts so please run your changes through code review.
+
+Keep features limited and simple so there's fewer chances for bugs and less code to review. Safety is more important here than convenience or bells and whistles.
+
+### Coding Style
+
+Tabs not spaces. variableNames, DEFINE\_CONSTANTS. Put {} braces on the same line except for with functions. No typedefs.
+
+Continue the current coding style. Don't make code complicated to reduce lines of code, reduce features instead. Aim for readability over elegance. Make the code self-documenting and use comments only when needed.
+
+Style guide: https://www.kernel.org/doc/html/v4.10/process/coding-style.html except for perhaps the 3 indentation and 80 column limit.
diff --git a/firmware/README.txt b/firmware/README.txt
deleted file mode 100644
index b861428..0000000
--- a/firmware/README.txt
+++ /dev/null
@@ -1,20 +0,0 @@
-Protospace lockout firmware
-===========================
-
-
-Code Structure
---------------
-
-- Declarations
-- State definitions
-- Initializations
-- State machines
-  - States
-    - State actions
-    - Conditions that change the state
-
-
-Dependencies
-------------
-
-Uses ArduinoJson Version 5.x.x