Rework docs

diff --git a/README-flashing.rst b/README-flashing.rst
index b6d9aeba54cd6f08f1f935a768283e2c0c42b825..aaad4e590c92d5372443465b83f50ebb948bd5c1 100644 (file)
--- a/README-flashing.rst
+++ b/README-flashing.rst
@@ -1,9 +1,51 @@
 Prepare the Firmware
 ####################
 
 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
 ########
 
 Flashing
 ########

diff --git a/README-hardware.rst b/README-hardware.rst
new file mode 100644 (file)
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 fdcdc10876ae75804df8a6eba294e94e8e55bca3..d5b86d14da75a591b34376eda3f001a14e401ef3 100644 (file)
--- a/README.rst
+++ b/README.rst
@@ -6,143 +6,17 @@ This is a hardware device designed to assist the `CMU KGB
 <http://www.cmukgb.org/>`_ game of `Capture The Flag With Stuff
 <http://www.cmukgb.org/activities/ctfws.php>`_.
 
 <http://www.cmukgb.org/>`_ game of `Capture The Flag With Stuff
 <http://www.cmukgb.org/activities/ctfws.php>`_.
 

-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
 
     0         1         
     01234567890123456789


@@ -151,7 +25,7 @@ Setup time display::
     messagemessagemessag
     START IN :   MM:SS.s
 
     messagemessagemessag
     START IN :   MM:SS.s
 

-Steady state display::
+* Steady state display::

 
     0         1         
     01234567890123456789
 
     0         1         
     01234567890123456789


@@ -160,7 +34,7 @@ Steady state display::
     messagemessagemessag
     JB#   n/N :  MM:SS.s
 
     messagemessagemessag
     JB#   n/N :  MM:SS.s
 

-Last round display::
+* Last round display::

 
     0         1         
     01234567890123456789
 
     0         1         
     01234567890123456789


@@ -169,7 +43,7 @@ Last round display::
     messagemessagemessag
     GAME END  :  MM:SS.s
 
     messagemessagemessag
     GAME END  :  MM:SS.s
 

-Game over::
+* Game over::

 
     0         1         
     01234567890123456789
 
     0         1         
     01234567890123456789


@@ -178,7 +52,7 @@ Game over::
     messagemessagemessag
      GAME OVER @ MM:SS
 
     messagemessagemessag
      GAME OVER @ MM:SS
 

-Game not configured::
+* Game not configured::

 
     0         1         
     01234567890123456789
 
     0         1         
     01234567890123456789


@@ -187,12 +61,4 @@ Game not configured::
     messagemessagemessag
      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