From 3338b694f441ca5bd6944fbb0089099fb65ddfe5 Mon Sep 17 00:00:00 2001
From: dakkar <dakkar@thenautilus.net>
Date: Sat, 2 Apr 2022 13:55:36 +0100
Subject: serial protocol: helper program & docs

---
 Makefile       |  4 ++++
 README.md      | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 utils/get-data | 28 ++++++++++++++++++++++++++++
 3 files changed, 86 insertions(+)
 create mode 100644 utils/get-data

diff --git a/Makefile b/Makefile
index 0ddaa03..0d08a1b 100644
--- a/Makefile
+++ b/Makefile
@@ -1,6 +1,10 @@
 SKETCH = main.ino
 LIBS = $(abspath arduino-core arduino-i2c-scd4x arduino-sps GxEPD Adafruit-GFX-Library Adafruit_BusIO esp32-micro-sdcard)
 
+# makeESPArduino defaults this to `--rts=0 --dtr=0` which makes the
+# board reset; we don't really want that
+MONITOR_PAR=
+
 UPLOAD_PORT = /dev/ttyUSB0
 # maybe board with eink?
 BOARD = ttgo-t1
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.
diff --git a/utils/get-data b/utils/get-data
new file mode 100644
index 0000000..f4309cd
--- /dev/null
+++ b/utils/get-data
@@ -0,0 +1,28 @@
+#!/usr/bin/env perl
+use strict;
+use warnings;
+use Path::Tiny;
+use IO::Termios;
+
+my $makefile = path(__FILE__)->parent(2)->child('Makefile');
+my ($port) = $makefile->slurp() =~ /^UPLOAD_PORT\s*=\s*(\S+)/sm;
+
+my $fh = IO::Termios->open($port, '115200,8,n,1')
+    or die "Can't open $port: $!\n";
+
+$fh->cfmakeraw();
+
+print $fh "xx logcat\n"
+    or die "Can't write: $!";
+my $in_log=0;
+while (<$fh>) {
+    if (/^xx end\b/) {
+        last;
+    }
+    elsif ($in_log) {
+        print;
+    }
+    elsif (/^xx begin\b/) {
+        $in_log=1;
+    }
+}
-- 
cgit v1.2.3