contrib-munin/plugins/luftdaten/feinstaubsensor

#!/usr/bin/env python3
"""

=head1 NAME

feinstaubsensor - Plugin to monitor one or more environmental sensors


=head1 APPLICABLE SYSTEMS

The "Feinstaubsensor" was developed by the OK Lab Stuttgart and is part of the
Citizen Science Project "luftdaten.info" (http://luftdaten.info).

Data is retrieved via HTTP requests from the sensors itself.


=head1 CONFIGURATION

Place a configuration entry somewhere below /etc/munin/plugin-conf.d/:

      [feinstaubsensor]
      env.sensor_hosts foo=192.168.1.4 [fe80::1:2:3:4%eth0] bar=sensor2.lan

The <sensor_hosts> environment variable is a space separated list of <token>.
Each <token> can be either a <host> or a combination of label and <host> (separated by the
character "=").
A <host> may be an IPv4 address, an IPv6 address (enclosed in square brackets) or a name to be
resolved via DNS.

Examples for <token>:
  * 192.168.1.4
  * foo=192.168.1.4
  * [fe80::1a:2b:3c:cafe]
  * bar=[fe80::1a:2b:3c:cafe]
  * feinstaubsensor-12345.local
  * baz=feinstaubsensor-12345.local


=head1 AUTHOR

  Lars Kruse <devel@sumpfralle.de>


=head1 LICENSE

  GPLv3


=head1 MAGIC MARKERS

  #%# family=manual

"""

import collections
import functools
import json
import os
import re
import sys
import urllib.request


graphs = [
    {
        "name": "wireless_signal",
        "graph_title": "Feinstaub Wifi Signal",
        "graph_vlabel": "%",
        "graph_args": "-l 0",
        "graph_info": "Wifi signal strength",
        "api_value_name": "signal",
        "value_type": "GAUGE",
    }, {
        "name": "feinstaub_samples",
        "graph_title": "Feinstaub Sample Count",
        "graph_vlabel": "#",
        "graph_info": "Number of samples since bootup",
        "api_value_name": "samples",
        "value_type": "DERIVE",
    }, {
        "name": "feinstaub_humidity",
        "graph_title": "Feinstaub Humidity",
        "graph_vlabel": "% humidity",
        "graph_info": "Weather information: air humidity",
        "api_value_name": "humidity",
        "value_type": "GAUGE",
    }, {
        "name": "feinstaub_temperature",
        "graph_title": "Feinstaub Temperature",
        "graph_vlabel": "°C",
        "graph_info": "Weather information: temperature",
        "api_value_name": "temperature",
        "value_type": "GAUGE",
    }, {
        "name": "feinstaub_particles_pm10",
        "graph_title": "Feinstaub Particle Measurement P10",
        "graph_vlabel": "µg / m³",
        "graph_info": "Concentration of particles with a size between 2.5µm and 10µm",
        "api_value_name": "SDS_P1",
        "value_type": "GAUGE",
    }, {
        "name": "feinstaub_particles_pm2_5",
        "graph_title": "Feinstaub Particle Measurement P2.5",
        "graph_vlabel": "µg / m³",
        "graph_info": "Concentration of particles with a size up to 2.5µm",
        "api_value_name": "SDS_P2",
        "value_type": "GAUGE",
    }]


SensorHost = collections.namedtuple("SensorHost", ("host", "label", "fieldname"))


def clean_fieldname(text):
    if text == "root":
        # "root" is a magic (forbidden) word
        return "_root"
    else:
        return re.sub(r"(^[^A-Za-z_]|[^A-Za-z0-9_])", "_", text)


def parse_sensor_hosts_from_description(hosts_description):
    """ parse sensor list from the environment variable 'sensor_hosts' and retrieve their data """
    sensors = []
    for token in hosts_description.split():
        if "=" in token:
            label, host = token.strip().split("=", 1)
        else:
            host = token.strip()
            label = host
        fieldname = clean_fieldname("value_" + host)
        sensors.append(SensorHost(host, label, fieldname))
    sensors.sort(key=lambda item: item.fieldname)
    return sensors


@functools.lru_cache()
def get_sensor_data(host):
    """ request the data from a sensor and return a dict (value_type -> value)

    The result is cached - thus we do not need to take care for efficiency.

    Example dataset returned by the sensor:
        {"software_version": "NRZ-2017-099", "age":"88", "sensordatavalues":[
        {"value_type":"SDS_P1","value":"27.37"},{"value_type":"SDS_P2","value":"13.53"},
        {"value_type":"temperature","value":"23.70"},{"value_type":"humidity","value":"69.20"},
        {"value_type":"samples","value":"626964"},{"value_type":"min_micro","value":"225"},
        {"value_type":"max_micro","value":"887641"},{"value_type":"signal","value":"-47"}]}

    """
    try:
        with urllib.request.urlopen("http://{}/data.json".format(host)) as request:
            body = request.read()
    except IOError as exc:
        print("Failed to retrieve data from '{}': {}".format(host, exc), file=sys.stderr)
        return None
    try:
        data = json.loads(body.decode("utf-8"))
    except ValueError as exc:
        print("Failed to parse data from '{}': {}".format(host, exc), file=sys.stderr)
        return None
    return {item["value_type"]: item["value"] for item in data["sensordatavalues"]}


def print_graph_section(graph_description, hosts, include_config, include_values):
    print("multigraph {}".format(graph_description["name"]))
    if include_config:
        # graph configuration
        print("graph_category sensors")
        for key in ("graph_title", "graph_vlabel", "graph_args", "graph_info"):
            if key in graph_description:
                print("{} {}".format(key, graph_description[key]))
        for host_info in hosts:
            print("{}.label {}".format(host_info.fieldname, host_info.label))
            print("{}.type {}".format(host_info.fieldname, graph_description["value_type"]))
    if include_values:
        for host_info in hosts:
            # We cannot distinguish between fields that are not supported by the sensor (most are
            # optional) and missing data. Thus we cannot handle online/offline sensor data fields,
            # too.
            data = get_sensor_data(host_info.host)
            if data is not None:
                value = data.get(graph_description["api_value_name"])
                if value is not None:
                    print("{}.value {}".format(host_info.fieldname, value))
    print()


action = sys.argv[1] if (len(sys.argv) > 1) else ""
sensor_hosts = parse_sensor_hosts_from_description(os.getenv("sensor_hosts", ""))
if not sensor_hosts:
    print("ERROR: undefined or empty environment variable 'sensor_hosts'.", file=sys.stderr)
    sys.exit(1)


if action == "config":
    is_dirty_config = (os.getenv("MUNIN_CAP_DIRTYCONFIG") == "1")
    for graph in graphs:
        print_graph_section(graph, sensor_hosts, True, is_dirty_config)
elif action == "":
    for graph in graphs:
        print_graph_section(graph, sensor_hosts, False, True)
else:
    print("ERROR: unsupported action requested ('{}')".format(action), file=sys.stderr)
    sys.exit(2)