# About

Receive monitoring data from a [squeow](https://repo.esiliati.org/cesco/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.


# Monitoring


None of the software provided will include monitoring functionalities. However, it will be easy to integrate
with an existing monitoring service:

### Nagios

This check will verify whether the alarm for temp1 is off

    /usr/lib/nagios/plugins/check_http --regex '^0$' -I 127.0.0.1 -p 8000 --url=/variables/alm_temp1

If you want to check whether the squeow microcontroller is still alive, this will check that the last message
was received from the microcontroller less than 100s ago.

    /usr/lib/nagios/plugins/check_http --regex '^squeow_time_since_last_seen [0-9][0-9]?$' -I 127.0.0.1 -p 8000 --url=/metrics

### Prometheus

a `/metrics` endpoint is exposed with the common `metric=value` format, which is easily to integrate into your
prometheus instance.

Adding something like this at the end of the `scrape_configs` section of your `prometheus.yml` could be
enough:

    - job_name: 'squeow'
  
      # Override the global default and scrape targets from this job every 5 seconds.
      scrape_interval: 5s
      scrape_timeout: 5s
  
      # metrics_path defaults to '/metrics'
      # scheme defaults to 'http'.
  
      static_configs:
        - targets: ['localhost:8000']

# Development

## Simulate a serial port

you might want to avoid developing with the squeow microcontroller actually connected to your computer, and
just simulate it.

if you want to do so, run:

```
socat -d -d pty,raw,echo=0 pty,raw,echo=0
```

Now, read the output; the first two lines would be sth like


```
2013/11/01 13:47:27 socat[2506] N PTY is /dev/pts/2
2013/11/01 13:47:27 socat[2506] N PTY is /dev/pts/3
```

This means that your `read.py` must use `--device /dev/pts/2`.

To simulate the reception of a message from the microcontroller, do this

```
echo -e '\x01DMP freq=1234567 temp1=78 temp2=50 alm_temp=0 ros=4095 alm_ros=1' > /dev/pts/3
```