labrat_project 0.5.1

No project description provided

🐀 Labrat Sensor Logger

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

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

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

---

Quick Start

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

[CONNECTIONS]

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

then run the setup wizard.

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

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

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 🧙

---

Setup & First Run

1. Create a Secrets File

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

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

These sections are then further broken up

[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
            "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
            "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 per route
   "KEY" = "" # The key to connect to http logging
   "LOCAL_ON" = true  # Whether to run the routes through Flask, only safe on a local network
       [CONNECTIONS.FLASK.HTTP] # Route information for the HTTP server
       "ROUTE" = "/datalog" # The route to the HTTP logging server
   
       [CONNECTIONS.FLASK.DASH] # Route information for the display dashboard 
       "ROUTE" = "/dash"  # The route to the display dashboard

       [CONNECTIONS.FLASK.SETUP]  # Route information for the quick set up page
       "ROUTE" = "/setup" # The route to the quick setup page

All connections methods can run in parallel

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 file in the options in the settings/secrets file for what you want to do 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

---

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