|
@@ -0,0 +1,84 @@
|
|
|
+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.
|