From: Nathaniel Wesley Filardo Date: Sat, 29 Jun 2019 13:10:11 +0000 (+0100) Subject: Rework docs X-Git-Url: https://hydra-www.ietfng.org/gitweb/?a=commitdiff_plain;h=2f0d9affa54059a733964fc2595b6d9aa2eac74d;p=acmetensortoys-esp-lua_ctfws Rework docs --- diff --git a/README-flashing.rst b/README-flashing.rst index b6d9aeb..aaad4e5 100644 --- a/README-flashing.rst +++ b/README-flashing.rst @@ -1,9 +1,51 @@ Prepare the Firmware #################### -Not yet really documented; build a NodeMCU firmware with the modules listed in -``README.rst``. Ensure that ``./firm`` points to your firmware build directory, -as we're going to pull ``luac.cross`` and the firmware ``.bin`` therefrom. +Not yet really documented; build a NodeMCU firmware with the modules listed +below. Ensure that ``./firm`` points to your firmware build directory, as +we're going to pull ``luac.cross`` and the firmware ``.bin`` therefrom. + +You'll want to run the following to build the CtFwS-specific LFS image for +NodeMCU:: + + LUACROSS=$(readlink -f ./firm/luac.cross.int) ./mklfs.sh + +NodeMCU modules used +==================== + +Please ensure that your build of NodeMCU supports LFS and the following +modules: + +* ``bit`` (for LCD) +* ``cron`` +* ``file`` +* ``i2c`` (for LCD) +* ``mqtt`` +* ``net`` +* ``node`` +* ``rtctime`` +* ``sjson`` +* ``sntp`` +* ``tmr`` +* ``wifi`` + +Additionally, + +* If you are developing on this software, the ``mDNS`` module may be a good + idea, too; the emergency telnet server can be reached with a more friendly + name. + +* This has only been tested with integer builds. + +Configuration Files +################### + +* ``nwfnet.conf`` has details of how to get connectivity to the network. +* ``nwfnet.conf2`` sets the SNTP server to use +* ``nwfmqtt.conf`` sets the MQTT server and credentials; it is derived from + ``nwfmqtt.conf.in`` via ``rewrites.sed`` in the configuration directories; + note that the latter of which is deliberately not checked in. +* ``ctfws-misc.conf`` can be used to assign the LCD I2C address Flashing ######## diff --git a/README-hardware.rst b/README-hardware.rst new file mode 100644 index 0000000..907305d --- /dev/null +++ b/README-hardware.rst @@ -0,0 +1,87 @@ +Jail Glyph Timers +################# + +At each jail glyph, we install a device consisting of + +* an ESP8266 module +* a beeper +* a 4x20 text LCD +* a small lipo battery + +This device is not intended to be interactive in any way; turn it on and let +it do its thing. + +The device joins CMU's wireless network, performs SNTP to get an +accurate clock, and connects to a MQTT server managed by the KGB to +receive updates about the game for display, namely: + +* game configuration (setup duration, N rounds M seconds long) +* game start time +* team scores / flag capture counts +* game over + +The devices heartbeat into their own MQTT topics as well, so judges can know +they are still running and, as a test, include in the heartbeat message which +AP they're associated with. + +BOM +=== + +The first instantiation, just as a baseline: + ++---+-------------------------------------------------------------+-------+ +| 1 | NodeMCU board (ESP8266+USB serial) | 4.00 | ++---+-------------------------------------------------------------+-------+ +| 1 | 2.5Ah USB power stick | 5.50 | ++---+-------------------------------------------------------------+-------+ +| 1 | 4x20 LCD display | 4.50 | ++---+-------------------------------------------------------------+-------+ +| 1 | Buzzer | 0.20 | ++---+-------------------------------------------------------------+-------+ +| 1 | Small breadboard | 0.80 | ++---+-------------------------------------------------------------+-------+ +| | Jumper wire, double-stick tape, twist-ties | 0.50 | ++---+-------------------------------------------------------------+-------+ +| | TOTAL | 15.50 | ++---+-------------------------------------------------------------+-------+ + +We have found it necessary, on occasion, to add a 100-ohm resistor between +power and ground to keep the USB power sticks from automagically turning +off due to low draw. It's not great, but it works. + +NodeMCU Pinout +============== + ++------+--------------------------------------+ +| GPIO | Purpose | ++------+--------------------------------------+ +| 0 | FLASH (button) | ++------+--------------------------------------+ +| 1 | Reserved for Lua console TX via USB | ++------+--------------------------------------+ +| 2 | Free for good use | ++------+--------------------------------------+ +| 3 | Reserved for Lua console RX via USB | ++------+--------------------------------------+ +| 4 | I2C SDA for LCD-driving I/O expander | ++------+--------------------------------------+ +| 5 | I2C SCL for LCD-driving I/O expander | ++------+--------------------------------------+ +| 9 | Free for good use | ++------+--------------------------------------+ +| 10 | Free for good use | ++------+--------------------------------------+ +| 12 | free for good use | ++------+--------------------------------------+ +| 13 | free for good use | ++------+--------------------------------------+ +| 14 | beeper active-low | ++------+--------------------------------------+ +| 15 | free for good use | ++------+--------------------------------------+ +| 16 | ESP8266 WAKE; free for good use | ++------+--------------------------------------+ + +* ADC0 is also free at the moment. + +* I2C is, of course, a multi-tap (and multi-master...) bus. diff --git a/README.rst b/README.rst index fdcdc10..d5b86d1 100644 --- a/README.rst +++ b/README.rst @@ -6,143 +6,17 @@ This is a hardware device designed to assist the `CMU KGB `_ game of `Capture The Flag With Stuff `_. -Protocol -######## +The device functions more or less as a glorified stopwatch under centralized +control; see +https://github.com/cmukgb/ctfws-timer-host/blob/master/protocol/protocol.rst +for the gory details. Almost surely, though, you'll be interacting with these +via http://timer.cmukgb.org/judge (a deployment of +https://github.com/cmukgb/ctfws-timer-web). -The protocol documentation has been moved to a more central location, -namely http://www.ietfng.org/nwf/ee/ctfws-iot.html +Character Display Examples +########################## -.. note:: - - Due to a bug in nodemcu (https://github.com/nodemcu/nodemcu-firmware/issues/1773), - do not send empty messages or messages with QoS 2; stick to QoS 1 and it - appears to work. - - -Jail Glyph Timers -################# - -At each jail glyph, we would install a device consisting of - -* an ESP8266 module -* a beeper -* a LCD (probably a small I2C graphics display or 4x20 text or similar) -* a small lipo battery (and charging circuitry, likely) - -This device is not intended to be interactive in any way; turn it on and let -it do its thing. - -The device would join CMU's wireless network, perform SNTP to get an -accurate clock, and associate with a MQTT server managed by the KGB to -receive updates about the game for display, namely: - -* game configuration (setup duration, N rounds M seconds long) -* game start time -* team scores / flag capture counts -* game over - -It's likely beneficial (or at least, not harmful) for the devices to -heartbeat into their own MQTT topics as well, and may wish to announce which -AP they're associated with. - -The device should otherwise function more or less as a glorified stopwatch -under centralized control. - -NodeMCU modules used -==================== - -Please ensure that your build of NodeMCU supports LFS and the following modules: - -* ``bit`` (for LCD) -* ``cron`` -* ``file`` -* ``i2c`` (for LCD) -* ``mqtt`` -* ``net`` -* ``node`` -* ``rtctime`` -* ``sjson`` -* ``sntp`` -* ``tmr`` -* ``wifi`` - -Additionally, - -* ``mDNS`` may be a good idea, too, if you want to talk to your device over, - e.g. telnet, and want it to have a somewhat friendly name. - -* ``rtcmem`` may be useful if you wish to stash a little bit of state - frequently and don't want to write to flash. - -* ``uart`` is in most default builds but is not necessary, if you need space. - -This has only been tested with integer builds. - -BOM -=== - -One possible instantiation, just as a baseline: - -+---+-------------------------------------------------------------+-------+ -| 1 | NodeMCU board (ESP8266+USB serial) | 4.00 | -+---+-------------------------------------------------------------+-------+ -| 1 | 2.5Ah USB power stick | 5.50 | -+---+-------------------------------------------------------------+-------+ -| 1 | 4x20 LCD display | 4.50 | -+---+-------------------------------------------------------------+-------+ -| 1 | Buzzer | 0.20 | -+---+-------------------------------------------------------------+-------+ -| 1 | Small breadboard | 0.80 | -+---+-------------------------------------------------------------+-------+ -| | Jumper wire | 0.50 | -+---+-------------------------------------------------------------+-------+ -| | TOTAL | 15.50 | -+---+-------------------------------------------------------------+-------+ - -We have found it necessary, on occasion, to add a 100-ohm resistor between -power and ground to keep the USB power sticks from automagically turning -off due to low draw. It's not great, but it works. - -NodeMCU Pinout -============== - -+------+--------------------------------------+ -| GPIO | Purpose | -+------+--------------------------------------+ -| 0 | FLASH (button) | -+------+--------------------------------------+ -| 1 | Reserved for Lua console TX via USB | -+------+--------------------------------------+ -| 2 | Free for good use | -+------+--------------------------------------+ -| 3 | Reserved for Lua console RX via USB | -+------+--------------------------------------+ -| 4 | I2C SDA for LCD-driving I/O expander | -+------+--------------------------------------+ -| 5 | I2C SCL for LCD-driving I/O expander | -+------+--------------------------------------+ -| 9 | Free for good use | -+------+--------------------------------------+ -| 10 | Free for good use | -+------+--------------------------------------+ -| 12 | free for good use | -+------+--------------------------------------+ -| 13 | free for good use | -+------+--------------------------------------+ -| 14 | beeper active-low | -+------+--------------------------------------+ -| 15 | free for good use | -+------+--------------------------------------+ -| 16 | ESP8266 WAKE; free for good use | -+------+--------------------------------------+ - -* ADC0 is also free at the moment. - - -Character Display -================= - -Setup time display:: +* Setup time display:: 0 1 01234567890123456789 @@ -151,7 +25,7 @@ Setup time display:: messagemessagemessag START IN : MM:SS.s -Steady state display:: +* Steady state display:: 0 1 01234567890123456789 @@ -160,7 +34,7 @@ Steady state display:: messagemessagemessag JB# n/N : MM:SS.s -Last round display:: +* Last round display:: 0 1 01234567890123456789 @@ -169,7 +43,7 @@ Last round display:: messagemessagemessag GAME END : MM:SS.s -Game over:: +* Game over:: 0 1 01234567890123456789 @@ -178,7 +52,7 @@ Game over:: messagemessagemessag GAME OVER @ MM:SS -Game not configured:: +* Game not configured:: 0 1 01234567890123456789 @@ -187,12 +61,4 @@ Game not configured:: messagemessagemessag GAME NOT CONFIGURED -Configuration Files -=================== -* ``nwfnet.conf`` has details of how to get connectivity to the network. -* ``nwfnet.conf2`` sets the SNTP server to use -* ``nwfmqtt.conf`` sets the MQTT server and credentials; it is derived from - ``nwfmqtt.conf.in`` via ``rewrites.sed`` in the configuration directories; - note that the latter of which is deliberately not checked in. -* ``ctfws-misc.conf`` can be used to assign the LCD I2C address