th7/README.md

# TH7

### Seven-channel multiple thermocouple reader and logger HAT for the Raspberry Pi.

This software supports the following thermocouple types:

```
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.
The TH7 software uses sane default values where possible.

```toml
# EXAMPLE TH7 CONFIG
[TH7]
port = 9090   # port used by the web view
LED = true    # enable the blinking lights on the Raspberry Pi Hat
debug = false # if true, the software will use a simulated TH7
nolog = false # debug variable, will simulate a DB
noweb = false # set to true to disable web view and the REST API

# Configure channel 1
[Channel_1]
type = 'K'    # set type to K-type thermocouple
gain = 106.8  # gain is used during signal conversion
offset = -5.6 # offset is added to the final converted value (in °C)
filter.samples = 50 # samples for the filter function
filter.type = 0     # integer representing the filter function type
log = false # do not log this channel to DB (if applicable)

# Filter functions:
# 0: simple alpha-beta filter (default)
# 1: lag filter: old * 0.90 + new * 0.10
# 2: lag filter: old * 0.95 + new * 0.05
# 3: lag filter: old * 0.99 + new * 0.01

# Configure channel 2 to read μV
# this example uses default values for gain, offset and filter.
[Channel_2]
type = 'U' # set thermocouple type to 'U' to just read μV

# Database
# Each database type requires its own set of values
# Below is an example for SQLite3
[DB]
type = "sqlite3"
path = "/home/pi/th7.db" # where to save the database file
freq = 60 # logging frequency. specified in seconds
```

### Using InfluxDB

```toml
[DB]
type = "influxdb"
host = "https://influxdb-server.com/"
bucket = "my-th7-bucket"
token = "cGFzc3dvcmQxMjMKcGFzc3dvcmQxMjMK"
```

The `host`, `bucket` and `token` fields may be specified in the env variables, rather than in the `config.toml` file. Example:

```shell
export INFLUXDB_HOST="https://influxdb-server.com/"
export INFLUXDB_BUCKET="my-th7-bucket"
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 -> {
    "channel": {
        "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 -> {
    "db": { ... },
    "time": "..."
}

--
-- 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 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
sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go1.19.3.linux-armv6l.tar.gz
```

edit $HOME/.profile and add the following, if not already there:

```shell
export PATH=$PATH:/usr/local/go/bin
```

source new profile

```shell
. $HOME/.profile
```

then try to build

```shell
make
```