From 0ae4e38dae641c00d958f1bfdfedabffa75c6f6b Mon Sep 17 00:00:00 2001 From: William Clark Date: Wed, 13 Dec 2023 12:07:37 +0000 Subject: [PATCH] README --- README.md | 157 ++++++++++++++++++++++++++++++++++++++-------- TODO.txt | 6 ++ rest-api-idea.txt | 133 --------------------------------------- 3 files changed, 138 insertions(+), 158 deletions(-) create mode 100644 TODO.txt delete mode 100644 rest-api-idea.txt diff --git a/README.md b/README.md index 2a40d93..d48e897 100644 --- a/README.md +++ b/README.md @@ -4,30 +4,14 @@ This software supports the following thermocouple types: -- B -- E -- J -- K -- N -- R -- S -- T - -Features not yet implemented but planned: - -- More database logging options than SQLite3 and InfluxDB -- Advanced filtering, incl. user-selectable filtering stages and sample sizes -- Several logging options at once, one local, one or more remote -- Configure any setting via API call either via RESTful JSON API or GRPC -- A terminal user interface ("TUI") that may be used to remotely monitor/access/configure a TH7 (w/ auth) -- Ability to act in headless mode -- Request dumps from filter stages for noise study -- ... and more! - -###### Note: Most thermocouples that have a coloured and a white lead, usually have the coloured one as the positive. +``` +B, E, J, K, N, R, S, T +``` ![Alt](/.gitea/webview0.png "Web view demo") +###### Note: coloured leads are positive on most thermocouples with a white and a coloured lead + ## Configuring the TH7 This program is controlled with a config file `config.toml` in which the user can configure each thermocouple channel independently, enable a web view, configure database logging, etc. @@ -69,8 +53,11 @@ type = 'U' # set thermocouple type to 'U' to just read μV type = "sqlite3" path = "/home/pi/th7.db" # where to save the database file freq = 60 # logging frequency. specified in seconds +``` -# InfluxDB example +### Using InfluxDB + +```toml [DB] type = "influxdb" host = "https://influxdb-server.com/" @@ -78,8 +65,6 @@ bucket = "my-th7-bucket" token = "cGFzc3dvcmQxMjMKcGFzc3dvcmQxMjMK" ``` -### Using InfluxDB - The `host`, `bucket` and `token` fields may be specified in the env variables, rather than in the `config.toml` file. Example: ```shell @@ -90,9 +75,131 @@ export INFLUXDB_TOKEN="cGFzc3dvcmQxMjMKcGFzc3dvcmQxMjMK" In this case, the `[DB]` field in `config.toml` can be left empty except for `type = "influxdb"` +## API + +The TH7 implements a simple REST API along with a websocket endpoint that periodically dumps data probably relevant to user logging applications. + +#### REST API + +``` +--- fetch latest measurement for a given channel id --- +GET v1/data/channel/:id -> { + "channel": { + id, + value in °C + }, + "time": current system time +} + +--- fetch latest measurements for all configured channels --- +GET v1/data/channels + +--- fetch latest "ratio table" used during signal conversion --- +GET v1/data/ratio -> { + "ratio": { + vref, + vadj, + pivdd + }, + "time": current system time +} + +--- short for all measurement data that may be wanted by a user --- +GET v1/data -> { + "channels": { ... }, + "ratio": { ... }, + "time": "..." +} + +--- fetch configuration options for a given channel id --- +GET v1/config/channel/:id -> { + "id": ..., + "thermocouple": ..., + "gain": ..., + "offset": ..., + "log" ..., + "filter": { + "sample_size": ..., + "type": ..., + }, + "time": "..." +} + +--- Fetch config options for all configured channels --- +GET v1/config/channels + +--- Fetch device config options --- +GET v1/config/device -> { + "device": { + "led": ..., + "debug": ..., + "nolog": ..., + "noweb": ... + }, + "time": "..." +} + +--- Fetch the DB config options --- +--- This can leak sensitive information so this endpoint must be --- +--- explicitly enabled in the API section of the config file. --- +GET v1/config/db + +-- +-- All POST requests are in the form: +-- $ curl -d "key=$KEY&value=$VALUE" -X POST "$URL" +-- If a request is succesful, "OK" is returned. +-- + +--- Modify a field in the device config --- +POST v1/config/device + +--- Modify a config field for a given channel --- +POST v1/config/channel/:id + +--- Modify or add a field in the database config map object --- +POST v1/config/db +``` + +#### WebSocket + +The WebSocket endpoint requires no configuration, and will dump data at a regular interval to any active client connection. The data is functionally identical to `GET v1/data`. Example: + +```json +{ + "channels": [ + { + "id": 1, + "value": -4979.418849118236 + }, + { + "id": 2, + "value": 13.239518855830024 + }, + { + "id": 3, + "value": 34.74759517361602 + }, + { + "id": 4, + "value": -21.452129020754683 + }, + { + "id": 6, + "value": 24.33195470120306 + } + ], + "ratio": { + "vref": 3.6, + "vadj": 0.9, + "pivdd": 5 + }, + "time": "Wed, 13 Dec 2023 12:00:28 GMT" +} +``` + ## Building on a Raspberry Pi -This code builds without fuss on Raspberry Pi 4 with go version go1.19.3 linux/arm +This code builds and runs without fuss on Raspberry Pi 4 with go version go1.19.3 linux/arm ```shell wget https://go.dev/dl/go1.19.3.linux-armv6l.tar.gz diff --git a/TODO.txt b/TODO.txt new file mode 100644 index 0000000..7ab65c3 --- /dev/null +++ b/TODO.txt @@ -0,0 +1,6 @@ +- More database logging options than SQLite3 and InfluxDB +- Better filtering methods +- Several logging options at once, one local, one or more remote +- A terminal user interface ("TUI") that may be used to remotely monitor/access/configure a TH7 (w/ auth) +- GUI application +- Web-based GUI (React?) diff --git a/rest-api-idea.txt b/rest-api-idea.txt deleted file mode 100644 index feaac3a..0000000 --- a/rest-api-idea.txt +++ /dev/null @@ -1,133 +0,0 @@ -To be implemented as a REST API - -========== Read data from configured channels ========== - -# i is a user-specified channel ID [1-7] -# if the channel specified is not configured, return an error -GET /data/channel/:i -> { - - return { - id, - value (in °C) - timestamp - } - -} - -# get the {id, value} of all configured channels, and a timestamp -GET /data/channels -> { - - return { - array of "/data/channel/:i" without the individual timestamp fields - timestamp - } -} - -# returns the `latest' set of Pi-specific values that are used during signal conversion -GET /data/ratio -> { - - return { - vref, - vadj, - pi_vdd, - timestamp - } - -} - -# returns all data fields that a user may want to log/access -GET /data -> { - - return { - /data/channels without timestamp - /data/ratio without timestamp - timestamp - } -} - -========== Read configuration info ========== - -# returns the config variables/options used to configure this channel -# if the channel, specified by i is not configured, an error is returned. -GET /config/channel/:i -> { - - return { - thermocouple type, - offset, - gain, - filter settings, etc. - - timestamp - } -} - -# returns an array of all configured channels -GET /config/channels -> { - - return { - array of "/config/channel/:i" without individual timestamps - timestamp - } -} - -# returns config variables/options used to set up device behaviour -GET /config/device -> { - - return { - HTTP_PORT, - WS_PORT, - debug_mode, etc. - } -} - -# returns the DB map object. -# since most DB solutions work slightly differently, the DB configuration -# is saved as just a map[string][string], and the specified DB type's associated code -# checks the map for entries it requires, upon start-up. -# This can leak secret passwords etc so this endpoint will not be reachable -# by default, and instead has to be manually enabled in the config fields -# under the [TH7] section. -GET /config/db -> { - - return { - DB map - } -} - -========== write configuration info ========== - -=== The POST request payload should be of the form: -=== { key: value } -=== $ curl -d "key=testkey&value=testvalue" -X POST "http://localhost:8080/config/device" - -# write device-specific key:value pair(s) to the device config -# returns success or error -POST /config/device -> { - - return { - success/error status of key:value change - timestamp - } -} - -# write channel-specific key:value pair(s) to the channel/:i config -# returns success or error -POST /config/channel/:i -> { - - return { - success/error status of key:value change - timestamp - } -} - -# write DB-specific key:value pair(s) to the DB config -# returns success or error -# this endpoint must be manually enabled in the device config fields -# under the [TH7] section -POST /config/db -> { - - return { - success/error status of key:value change - timestamp - } -} \ No newline at end of file