Sensorlogger
Config file structure
Further below you will find a complete example configuration. Any Sensorlogger configuration file must be a JSON structure. It can contain the following sections, but not all of them are required.
- general is meant for general settings and remarks (you can add your own). Currently, it only specifies the global event log file for errors and warnings.
- tinkerforge contains the parameters for the connection to the Brick Daemon.
- mqtt contains the parameters for connections to MQTT brokers.
- homematic contains the parameters for the connection to the XML-API of a HomeMatic CCU.
- sensors contains a description of all sensors from which data should be read. This is a JSON array that can contain an arbitrary number of sensor definition objects.
- logbooks defines logbook files and associated columns. It is also a JSON array that can contain an arbitrary number of logbook definitions and their proper columns.
Generally, a configuration file must only contain the parameters and sections that you actually need. Irrelevant parameters can be omitted; if necessary, their standard values will be used. The standard values are presented in descriptions in the following sections.
Hint: you can use Firefox to open JSON files and make their tree structure visible. This can help you understand how JSON files work, and any errors in your file will be shown.
General settings
The "general" section of the configuration file may contain the following settings."general": { "logfile": "/home/username/sensorlogger.log", "loglevel": "info", "http_timeout": 20, "default_rest_period": {"value": 60, "unit": "s"}, "default_retry_time": {"value": 10, "unit": "s"} }
"logfile": Path to a log file for status and error messages. Can be left blank or set to null if no log file is desired.
Standard value: null
"loglevel": Type of events that are logged. Can be any of the following:
- "error" — Only log error messages.
- "warning" — Log errors and warnings.
- "info" — Log errors, warnings and info messages.
- "debug" — Log errors, warnings, info and debug messages.
Standard value: "info"
"http_timeout": Timeout (in seconds) for HTTP requests.
Standard value: 10
"default_rest_period": Default rest period for any sensor that doesn’t specify its own rest period. The rest period is generally the time between two readouts of the same sensor. See specific sensor documentations for details. The numerical part for this parameter is set under "value", its unit under "unit". The following units are allowed: "ms", "s", "min", "h", "d".
Standard value: 60 s
"default_retry_time": Default retry time for any sensor that doesn’t specify its own retry time. When a sensor reading fails, the following attempt to read the sensor is made after the retry time (if it is shorter than the sensor’s rest period). The numerical part for this parameter is set under "value", its unit under "unit". The following units are allowed: "ms", "s", "min", "h", "d".
Standard value: 5 min
Example configuration
Shown below is an example configuration file for the following scenario.
- An outside weather station has two Tinkerforge sensors: one for temperature, another one for wind. A Temperature Bricklet is used for the temperature measurement. The wind anemometer is connected to an IO Bricklet at channel 0 and Sensorlogger is used to count digital events (whenever a low state is reached).
- In the living room we have a different temperature sensor that sends its measurements to an MQTT broker. Sensorlogger subscribes to its topic. Additionally, there is a HomeMatic humidity sensor in the living room. Sensorlogger reads its datapoint values every two minutes via the XML-API from the HomeMatic CCU.
- The solar generator is monitored by another application and its current state is reported in a local JSON file. The value for the currently produced electric power is read by Sensorlogger from its configured key sequence in the JSON tree.
- Two logbooks are defined: one for the weather station and another one for the house. The weather logbook contains one line every five minutes. In two columns, it contains the mean temperature for the last 15 minutes and the wind anemometer’s rotation frequency for the last five minutes (which is the logbook’s cycle time). The logbook for the house contains two columns for the mean living room temperature and humidity of the last 15 minutes (again, the cycle time) and two more columns for the mean and maximum electric power produced during the past 60 minutes.
- Both the current sensor values as well as the statistical results for the logbook columns are sent to the MQTT broker using their own topics, as well as to the HomeMatic CCU using the ISE IDs for special system variables.
{ "general": { "logfile": "/home/username/sensorlogger.log", "loglevel": "info", "http_timeout": 20, "default_rest_period": {"value": 60, "unit": "s"}, "default_retry_time": {"value": 10, "unit": "s"} }, "tinkerforge": { "comment": "Connecting to the Brick Daemon, and error management.", "host": "192.168.1.2", "port": 4223, "max_bricklet_read_failures": 2, "max_brickd_restart_attempts": 3, "brickd_restart_command": null, "system_restart_command": null }, "mqtt": [ { "comment": "Connecting and communicating with the MQTT broker.", "host": "192.168.1.3", "port": 1883, "qos": 1, "retained": false, "connected_topic": "Sensorlogger/status", "connected_message": "online", "lwt_topic": "Sensorlogger/status", "lwt_message": "offline", "enable_publish": true, "enable_subscribe": true, "topic_domain": "" } ], "homematic": { "comment": "URL of your HomeMatic's XML API", "xmlapi_url": "http://192.168.1.4/config/xmlapi" }, "sensors": [ { "comment": "Tinkerforge sensor for outside temperature.", "sensor_id": "Weather/Temperature", "tinkerforge_uid": "z3L", "channel": 0, "factor": 1, "offset": -4, "counter": false, "trigger": "periodic", "rest_period": {"value": 60, "unit": "s"}, "retry_time": {"value": 30, "unit": "s"}, "mqtt_publish": "Weather/Temperature/current", "homematic_publish": "25484" }, { "comment": "Tinkerforge IO bricklet triggers count events whenever getting to low state.", "sensor_id": "Weather/Wind", "tinkerforge_uid": "9Ws", "channel": 0, "counter": true, "trigger": "low", "rest_period": {"value": 8, "unit": "ms"}, "io_debounce": {"value": 8, "unit": "ms"} }, { "comment": "MQTT sensor for the living room temperature.", "sensor_id": "House/Living_Room/Temperature", "mqtt_subscribe": "House/Living_Room/Temperature/current", "factor": 1, "offset": 0, "counter": false, "trigger": "periodic", "rest_period": {"value": 2, "unit": "min"}, "homematic_publish": "74633" }, { "comment": "HomeMatic sensor for the living room humidity.", "sensor_id": "House/Living_Room/Humidity", "homematic_subscribe": "94836", "factor": 1, "offset": 0, "counter": false, "trigger": "periodic", "rest_period": {"value": 2, "unit": "min"}, "retry_time": {"value": 30, "unit": "s"}, "mqtt_publish": "House/Living_Room/Humidity/current" }, { "comment": "Current solar power from local JSON file.", "sensor_id": "House/Solar/Power", "json_file": "/var/log/solar.json", "json_key": ["solar", "creation", "power"], "factor": 1, "offset": 0, "trigger": "periodic", "rest_period": {"value": 5, "unit": "s"}, "retry_time": {"value": 2, "unit": "s"}, "mqtt_publish": "House/Solar/Power/current", "homematic_publish": "23674" } ], "logbooks": [ { "filename": "weather.txt", "cycle_time": {"value": 5, "unit": "min"}, "max_entries": 288, "missing_data": "-", "columns": [ { "title": "Temperature 15 minute average", "unit": "°C", "sensor_id": "Weather/Temperature", "operation": "mean", "evaluation_period": {"value": 15, "unit": "min"}, "mqtt_publish": "Weather/Temperature/average15min", "homematic_publish": "83472" }, { "title": "Wind sensor rotation frequency", "unit": "Hz", "sensor_id": "Weather/Wind", "operation": "freq", "mqtt_publish": "Weather/Wind/average15min", "homematic_publish": "75653" } ] }, { "filename": "house.txt", "cycle_time": {"value": 15, "unit": "min"}, "max_entries": 48, "missing_data": "-", "columns": [ { "title": "Living room temperature", "unit": "°C", "sensor_id": "House/Living_Room/Temperature", "operation": "mean", "mqtt_publish": "House/Living_Room/Temperature/average15min", "homematic_publish": "23545" }, { "title": "Living room humidity", "unit": "%rel.", "sensor_id": "House/Living_Room/Humidity", "operation": "mean", "mqtt_publish": "House/Living_Room/Humidity/average15min", "homematic_publish": "12736" }, { "title": "Mean solar power (last 60 minutes)", "unit": "W", "sensor_id": "House/Solar/Power", "operation": "mean", "evaluation_period": {"value": 1, "unit": "h"}, "mqtt_publish": "House/Solar/Power/mean", "homematic_publish": "34653" }, { "title": "Peak solar power (last 60 minutes)", "unit": "W", "sensor_id": "House/Solar/Power", "operation": "max", "evaluation_period": {"value": 1, "unit": "h"}, "mqtt_publish": "House/Solar/Power/peak", "homematic_publish": "34654" } ] } ] }