68 lines
2.6 KiB
Markdown
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.
|