serial protocol: helper program & docs

1 files changed, 54 insertions, 0 deletions

diff --git a/README.md b/README.md
index 70611ff..0bbe5af 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,4 @@
+
 # Environmental sensor
 
 ## Components
@@ -53,6 +54,59 @@ You'll probably need to adjust some paths in the
 [`Makefile`](Makefile), then you can `make flash` to build and flash
 the software.
 
+### Serial protocol
+
+`make monitor` (or `make run` if you want to build+flash+monitor)
+lets you interact with the serial line.
+
+Lines starting with `#` are debug information, lines starting with `!`
+are errors / warnings.
+
+You can send tagged commands, and get tagged responses. For example,
+you write:
+
+    1 logwipe
+
+and you get back:
+
+    # reading
+    # 1 logwipe
+    # <1|logwipe>
+    # file: quality.csv
+    1 wiped
+
+and the logged data has been removed from the SD card.
+
+Then you write:
+
+    2 logcat
+
+and get:
+
+    # reading
+    # 2 logcat
+    # <2|logcat>
+    2 begin
+      secs,  co2,  temp, humid,    pm1,  pm2.5,    pm4,   pm10, batt
+       162,  639,  18.1,  33.7,    1.1,    0.1,    0.0,    0.0, 4.26
+       168,  637,  17.8,  34.2,    1.1,    0.1,    0.0,    0.0, 4.26
+       174,  637,  17.8,  34.2,    1.1,    0.1,    0.0,    0.0, 4.26
+       180,  637,  17.8,  34.2,    1.1,    0.1,    0.0,    0.0, 4.26
+       187,  637,  17.8,  34.2,    1.1,    0.1,    0.0,    0.0, 4.26
+       193,  637,  17.8,  34.2,    1.1,    0.1,    0.0,    0.0, 4.26
+    2 end
+
+which is the whole contents of the data log from the SD card.
+
+There's also `setco $int`, to force-calibrate the CO₂ sensor, but I
+haven't tested it yet.
+
+#### Helper programs
+
+If you install `Path::Tiny` and `IO::Termios` on your Perl, you can
+use [`utils/get-data`](utils/get-data) to get the logged data off the
+sensor.
+
 ## Enclosure
 
 Render with [OpenSCAD](https://openscad.org/), then print.