About
============

Receive monitoring data from a [squeow]() AM transmitter.


read.py will (using decoder.py) connect to a serial port, print values to stdout, and send values to a
webserver

webserver.py is such a webserver. It provides an authenticated API for receiving values (most likely by
read.py) and an unauthenticated API to get values.

Howto
------------

### Dependencies

```sh
apt install python3-fastapi python3-serial python3-requests
```

### Run

```sh
./read.py -v --baudrate 115200 --wait --device /dev/pts/17 --http-endpoint http://127.0.0.1:8000 --http-auth-file password.txt
```

```
uvicorn webserver:app
```

Serial protocol
--------------------

### Goals

#### receive-only

if you only want to receive data, you shouldn't need to *ask* for data. This makes it possible to connect a
serial port to multiple receivers!

#### machine and human-readable

this software will parse messages, but even if you don't have it around, you should be able to read messages
just opening `minicom`.

### High level description

Messages are started by the 0x01 ascii character (SOH start of heading) and ended by 0x0A ("\n", NL, new
line). A messages needs to be entirely ascii.

There are two types of messages:
 - log messages
 - dump messages

### Dump messages

Example: ```DMP freq=1234567 temp1=78 temp2=50 alm_temp=0 ros=4095 alm_ros=1```

DMP is just a prefix to indicate the kind of message. Follows a space-separated sequence of key-values. A
value is any string (including numbers, but no spaces). Please only use lowercase letters, numbers, and
underscore (`[a-z0-9_]`).
Values can only be integral positive numbers. Booleans don't have any specific form of support.

It is allowed to send dump messages which only inform the receiver about a part of the state, and not all of
it. It's the receiver's responsibility to keep track of the whole state, and updating it whenever a new dump
message arrives.

### Log messages

Examples :

```
LOG I starting
LOG E overcurrent protection
```

`LOG` is just a prefix.
Then a space
Then a single capital letter indicating the severity of the message.
Then a space.
Whatever follows is the actual message

This makes it possible for debug messages to be sent.