pslockout/firmware/README.md

68 lines
2.6 KiB
Markdown

# 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.