pslockout/firmware

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.