labrat_project 0.8.1

No project description provided

Labrat Laboratory Monitoring

Connect sensors and log data to a database, file, or both.

Display the data from this database in a dashboard

Current connection modes available:

Connection	Description
MQTT	Subscribe to an MQTT broker
serial	Read from a wired serial port
http	Receive data via a Flask API

Table of Contents

• Requirements
• Quick Start
• All Options
• Setup & First Run
  • 1. Create a Secrets File
  • 2. Set Up Database Contents
  • 3. Run
• Running as a Daemon

---

Requirements

To run LabRat you need to have python installed. Please install via your preferred method, we advise creating an environment.

LabRat can be installed using poetry, pip or conda.

In the installation folder can be found a conda environment.yml file and a pip requirements.txt file.

Quick Start

Not sure where to begin? There are two options: Create a Secrets File. The minimum secrets file is:

VERSION = 1.0

[CONFIG]
    "AUTOBROW" = true
    "ALLOW_SETUP" = true

[CONNECTIONS]

   [CONNECTIONS.FLASK]
   "KEY" = "" # this can be filled with anything for this step.
       [CONNECTIONS.FLASK.SETUP]
       "ROUTE" = "/setup"

A copy of this is in the installation folder

then run the setup wizard.

python labrat_log.py -secrets "mypath/secrets.toml" -quick_start

or run this command

 python labrat_log.py -quick_start --config $'VERSION = 1.0\n\n[CONFIG]\nAUTOBROW = true\nALLOW_SETUP = true\n[CONNECTIONS]\n[CONNECTIONS.FLASK]\nKEY = "secret"\nLOCAL_ON = true\n[CONNECTIONS.FLASK.SETUP]\nROUTE = "/setup"'

This will open a browser window in which you can give a name for the database and add inator devices.

This can be used to create a database or to add devices to an existing database

When you have finished close the browser window and then turn off the flask server

ctl+c

---

All Options

usage: labrat_log.py [-h] [-sql SQL] [-secrets SECRETS] [-quick_start]

Flag	Description
-secrets SECRETS	Path to the TOML secrets file (logins, broker details, etc.)
-quick_start	Run the quick start wizard 🧙

---

First Run

1. Create a Secrets File

Once you have run the quick start to create a database and add a device, then move on to the following:

Create a .toml file with your credentials and connection details: This has the following main sections which have their own sub-sections

[CONFIG]
[LOGGING] # Options to control logging
[CONNECTIONS] # Options to control the connections

These sections are then further broken up

Config TOML options

[CONFIG]
    "AUTOBROW" = false # Whether to automatically open the browser or not
    "ALLOW_SETUP" = false # Whether to allow database set up and addition of devices or not
    "COMMAND_QUEUE" = false # whether to allow a command COMMAND_QUEUE to run

[LOGGING]
    [LOGGING.SQLITE] # Settings for logging to SQLite database 
    "FILE" = "" # The path to sql database file
    "CREATE" = false # Whether to create the DB or not (true for quick set up)

    [LOGGING.FILE]  # Settings for logging to a text file
    "FILE" = "" # Path for the file
    "CREATE" = false # Whether to create the file or append

    [LOGGING.ELN] #Settings for connecting to an Electronic Laboratory notebook
    "NAME" = "RSpace" # Name of the ELN
    "KEY" = ""  # If required a key to logging to the ELN

[CONNECTIONS]
    [CONNECTIONS.MQTT] # MQTT connection details
        [CONNECTIONS.MQTT.NAME] # Details of a MQTT connection NAME should be changed and be unique
            "VERB" = "false" # If set to true will print whatever is recieved by connection
            "USERNAME" = "" # Any user names needed by broker
            "KEY" = ""  # Key needed to connect to broker
            "BROKER" = "" # Address of the broker
            "PORT" = 1883 # The port number of the broker, 8883 is traditional
            "TOPIC" = ""  # The Topic to subscribe to, adding # is normally useful
            "TLS" = true  # Whether the MQTT broker is using a TLS connection, i.e is encrypted. true or false
    
    [CONNECTIONS.SERIAL]  # Serial connection details
        [CONNECTIONS.SERIAL.NAME] # Details of a Serial connection NAME should be changed and be unique
            "VERB" = "false" # If set to true will print whatever is recieved by connection
            "PORT" = "" # The name of the serial port
            "BAUD" = "" # The baud rate for the port

   [CONNECTIONS.FLASK]  # Flask server connection details
   # Due to its nature Flask is treated differently to other connections, only one server for all routes
   "KEY" = "" # The key to connect to http logging, see below for how to generate*
   "LOCAL_ON" = true  # Whether to run the routes through Flask, only safe on a local network
   "HOST" = ""  # Host address to use
   "PORT" =   # Port number to use
      [CONNECTIONS.FLASK.HTTP] # Route information for the HTTP server
        "ROUTE" = "/datalog" # The route to the HTTP logging server
        "KEY" = "" # The key to connect to this route, if different from main key, see below for how to generate*
      [CONNECTIONS.FLASK.DASH] # Route information for the display dashboard 
        "ROUTE" = "/dash"  # The route to the display dashboard
        "KEY" = "" # The key to connect to this route, if different from main key, see below for how to generate*
      [CONNECTIONS.FLASK.SETUP]  # Route information for the quick set up page
        "ROUTE" = "/setup" # The route to the quick setup page
        "KEY" = "" # The key to connect to this route, if different from main key, see below for how to generate*
      # API routes - no html page
      [CONNECTIONS.FLASK.DEVICES] # Route to the add devices api
        "ROUTE" = "/api/devices"  # The route for the add devices
        "KEY" = "" # The key to connect to this route, if different from main key, see below for how to generate*
      [CONNECTIONS.FLASK.UPDATE_CONNS] # Route information for Connections control api
        "ROUTE" = "api/conns" # The route for the connections control
        "KEY" = "" # The key to connect to this route, if different from main key, see below for how to generate*
      [CONNECTIONS.FLASK.PUBLISH_API]
        "ROUTE" = "api/publish" # The route for publishing via a connection
        "KEY" = "" # The key to connect to this route, if different from main key, see below for how to generate*

These options can be given as a toml string on the cli, any values given on the cli will overwrite those from the config file

All connection methods can run in parallel

* To generate a key use the following python code:

import secrets

print(secrets.token_urlsafe(32))

or directly on the command line

python -c 'import secrets; print(secrets.token_urlsafe(32))'

2. Set Up Database Contents

Add devices to the database.

The device file must conform to the Inator DB schema. This can be done using the quick start page

Device file JSON schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "devices": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "device_name":     { "type": "string" },
          "device_guid":     { "type": "string" },
          "num_sensors":     { "type": "integer" },
          "device_info":     { "type": "string" },
          "device_type":     { "type": "string" },
          "device_location": { "type": "string" },
          "device_active":   { "type": "integer" },
          "connection": {
            "type": "string",
            "enum": ["Serial", "MQTT", "Other"]
          },
          "sensors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "sens_name": { "type": "string" },
                "measures":  { "type": "string" },
                "returns":   { "type": "string" },
                "calib":     { "type": "string" },
                "range":     { "type": "string" },
                "info":      { "type": "string" },
                "comments":  { "type": "string" }
              },
              "required": ["sens_name", "measures", "returns", "calib", "range", "info", "comments"]
            }
          }
        },
        "required": [
          "device_name", "device_guid", "num_sensors", "device_info",
          "device_type", "device_location", "device_active", "connection", "sensors"
        ]
      }
    }
  },
  "required": ["devices"]
}

3. Run

To run LabRat put the options in the settings/secrets file for what logging, connections and displays you need.

Then depending on your installationn method run using:

python labrat_log.py -secrets path/to/secrets.toml

or

poetry run python labrat_log.py -secrets path/to/secrets.toml

---

Data from a device

Once connections are set up and a device is registered in the database then any data sent on the connection will be logged.

The format is simple and extendable. A JSON string is sent (i.e has {} around the contents) in this format

{
  "inator": "name",  # the name of the device, must match name added to database
  "<sensor1>": "value", the value from the sensor, name must match name used in database for the sensor
  "<sensor2>": "value",
  "<sensor3>": "value",
  .
  .
  .
  "<sensorN>": "value",
}

As long as the names used match those entered into the database the logging will work

---

Running as a Daemon

Run the logger as a persistent background service using Supervisor.

1. Install

sudo apt update && sudo apt install supervisor

2. Configure

Edit the provided supervisord.conf file, updating these fields:

Field	What to set
command=	Full command with all required paths and flags
user=	System user to run the process as
stdout_logfile=	Absolute path and filename for log output
directory=	Working directory (home directory for MQTT)

3. Start

supervisord -c /path/to/supervisord.conf

4. Monitor & Control

Use supervisorctl to manage the process:

supervisorctl status          # check if running
supervisorctl restart labrat  # restart the service
supervisorctl stop labrat     # stop the service