Merge branch 'master' of https://git.nethack.net/rob/howard

README.md

@@ -1,20 +1,59 @@
 # Overview
 
-
-Sound level monitoring via USB Benetech GM1356.
+Performs sound level monitoring using a USB Benetech GM1356 sonometer.
 
 Named after [Loud Howard](https://dilbert.com/strip/1995-04-21).
 
-Requirements:
+Big thanks to [Maciej Ciemborowicz](https://github.com/ciembor) for his work documenting the [USB protocol](https://github.com/dobra-noc/gm1356/blob/master/PROTOCOL.md) this device uses.
+
+# Requirements
  - [hidapi](https://github.com/libusb/hidapi)
  - An OS which recognises the GM1356 as a USB device (ie. not OSX Big Sur).
+ - A GM1356 sonometer (obviously)
 
 # Usage
 
-TBC
+```text
+bash$ ./howard -h
+usage:  howard [OPTIONS] outputmode1 [ outputmode2 ... ]
+
+Reads maximum noise level from a Benestar GM1356 sonometer
+over a given interval, and optionally stores result in an
+influxdb database.
+
+Valid output modes are:
+  short (single line to stdout)
+  long  (multiple lines to stdout)
+  db    (HTTP POST to influxdb, must also provide INFLUXDB OPTIONS - see below)
+
+OPTIONS:
+   -c           Run endlessly (also see -i and -w)
+   -h           Show this usage text then exit.
+   -i secs      Define time over which to get max decibels
+   -t           Test mode - just probe for sononeter then exit
+   -T           Influxdb test mode - just test influxdb connectivity then exit
+   -w secs      Define period to wait between noise level checks
+                insert will just be written to stdout.
+
+INFLUXDB OPTIONS:
+   -d dbname    Define influxdb database name
+   -H hostname  Define influxdb hostname
+   -p password  Define influxdb password
+   -u username  Define influxdb password
+   -y           Actually write to influxdb.  Without this,
+```
 
 # Screenshots
 
 TBC
 
+# Implementation Notes
+
+ - The device seems to 'hang' periodically and cause all subsequent reads to timeout.  To work around this, after two concurrent timeouts I send an `IOCTL_USBDEVFS_RESET`.
+
+ - I don't yet have configuration commands working, so the following need to be manually configured on the physical device:
+  - slow/fast exponential time averaging
+  - MAX mode
+  - dBA vs dBC units
+
 

TODO

@@ -0,0 +1,4 @@
+usage()
+tidy up output
+warn() etc to stderr
+code tidy

howard.h

@@ -26,8 +26,6 @@
 #define FLAG_RANGE_80_130  (0b00000100)
 
 // ANSI stuff
-
-
 char BOLD[BUFLENTINY];
 char ITALIC[BUFLENTINY];
 char STRIKE[BUFLENTINY];