• Deutsch

Sensorlogger

1. Overview
2. Download, Installation & Startup
3. Configuration & complete example
• Tinkerforge
• MQTT
• HomeMatic
• JSON values
• Statistics & Logbooks

Tinkerforge settings

Connection to the Brick Daemon

The general tinkerforge section is used to configure the connection parameters to the Brick Daemon.

"tinkerforge": {
    "host": "localhost",
    "port": 4223,
    "max_bricklet_read_failures":  8,
    "max_brickd_restart_attempts": 3,
    "brickd_restart_command": "sudo /bin/systemctl restart brickd",
    "system_restart_command": "sudo /bin/systemctl --force reboot"  
}

• "host": Hostname or IP address where the Tinkerforge Brick Daemon can be reached. May be omitted or set to null if you don’t want to configure any Tinkerforge sensors.

  Standard value: null

• "port": Port on the host to connect to the Brick Daemon.

• "max_bricklet_read_failures": Sets a first limit for a maximum number of subsequent readout failures for Bricklets that are polled periodically. If the limit is reached, it is reported in the global log file and brickd_restart_command is executed (if defined).

  Standard value: 7

• "max_brickd_restart_attempts": The maximum number of subsequent attempts to restart the Brick Daemon to solve readout failures. If this limit is reached, it is reported in the global log file and system_restart_command is executed (if defined).

  Standard value: 3

• "brickd_restart_command": Command to be executed when the maximum number of subsequent Bricklet readout failures is reached. The intention is to issue a service restart command for the Brick Daemon on the command line in order to solve readout hiccups. Sometimes, this helps. Please note that if you issue any sudo command, the user that runs Sensorlogger must be allowed to execute this command without entering a password. This can be set up accordingly in the sudoers file.

  Standard value: null

• "system_restart_command": Command to be executed when the maximum number of subsequent Brick Daemon restarts is reached and did not solve the sensor readout failures. The intention is to issue a command to restart the entire system. In my experience, this can be of temporary help under very bad conditions (like in a weather station), but it should only be used when such drastic measures are really necessary and a restart does not disrupt any other services. Please note that if you issue any sudo command, the user that runs Sensorlogger must be allowed to execute this command without entering a password. This can be set up accordingly in the sudoers file.

  Standard value: null

On any normally running system, you should not use the restart parameters and instead omit them or set them to null. Please only use them if you are fully aware of what you’re doing.

"brickd_restart_command": null,
"system_restart_command": null

Tinkerforge sensors

Polling in specific time intervals

"sensors": [
    ...
    {
        "sensor_id": "Weather/Temperature",
        "tinkerforge_uid": "z3L",
        "factor": 1,
        "offset": -4.5,
        "channel": 0,
        "mqtt_publish": "House/Weather/Temperature/current",
        "homematic_publish": "12345",
        "counter": false,
        "trigger": "periodic",
        "rest_period": {"value": 60, "unit": "s"},
        "retry_time":  {"value": 30, "unit": "s"}
    },
    ...
]

• "sensor_id": General, unique ID for the sensor that will later be referenced when defining statistics and logbooks.

• "tinkerforge_uid": UID of the Tinkerforge Bricklet, as displayed e.g. in the Brick Viewer.

• "factor": Correction factor, see next point.

  Standard value: 1

• "offset": Correction offset. The resulting sensor value is then calculated from factor·(measurement+offset).

  Standard value: 0

• "channel": Channel that is supposed to be polled. Only relevant for Bricklets with multiple channels or measurement options. See: Supported Bricklets & Channels at the bottom of this page.

  Standard value: 0

• "io_port": If an IO-16 Bricklet is used, this parameter specifies the port "a" or "b".

  Standard value: "a"

• "mqtt_publish": Topic that is used to publish the polled and possibly corrected sensor value via MQTT.

  Standard value: null

• "homematic_publish": ISE ID of the HomeMatic system variable that should be set to the polled and possibly corrected sensor value.

  Standard value: null

• "counter": Specifies if this sensor is a pure counter. In this case, the variable must be set to true. This means that no measurement value is kept in the data storage, but all messages are counted. For logbook statistics, it will only be possible to evaluate the number of measurements and their frequency, but none of the other statistical operations (such as mean) will give any meaningful results. If a sensor is polled very often, it can save memory not to keep all measurements of a measurement cycle if the intention is for example to only forward them via MQTT, or if this sensor acts as an event counter (see next section).

  Note that measurements are always counted, irrespective of this configuration parameter. You will always be able to evaluate count and frequency when running the statistical analysis.

  Standard value: false

• "trigger": Defines how a measurement is triggered. In case of periodically polled sensors, this parameter must be set to "periodic". For external triggers, see the next section.

  Standard value: "periodic"

• "rest_period": Time for the sensor to rest between two measurements. The sensor is polled again after the rest period has passed. 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: default_rest_period, minimum: 100 ms

• "retry_time": When the 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: default_retry_time, minimum: 100 ms

External triggers

Only Tinkerforge IO Bricklets are currently supported as external triggers.

"sensors": [
    ...
    {
        "sensor_id": "Weather/Wind",
        "tinkerforge_uid": "9Ws",
        "channel": 0,
        "io_port": "a",
        "factor": 0.5,
        "offset": 0,
        "mqtt_publish": "House/Weather/Wind/last-pulse",
        "counter": true,
        "trigger": "low",
        "rest_period": {"value": 7, "unit": "ms"},
        "io_debounce": {"value": 7, "unit": "ms"}
    },
    ...
]

• "sensor_id": General, unique ID for the sensor that will later be referenced when defining statistics and logbooks.

• "tinkerforge_uid": UID of the Tinkerforge Bricklet, as displayed e.g. in the Brick Viewer.

• "channel": Channel of the IO Bricklet that should trigger the interrupt. Note that the channel numbers start at zero.

  Standard value: 0

• "io_port": If an IO-16 Bricklet is used, this parameter specifies the port "a" or "b".

  Standard value: "a"

• "factor": Correction factor, see next point.

  Standard value: 1

• "offset": Correction offset. The resulting sensor value is then calculated from factor·(measurement+offset). For digital sensors such as the IO Bricklets the measurement value is always 0 (low) or 1 (high) and can be weighted or shifted by the factor and offset parameters.

  Standard value: 0

• "mqtt_publish": Topic that is used to publish the received and possibly corrected sensor value via MQTT.

  Standard value: null

• "homematic_publish": ISE ID of the HomeMatic system variable that should be set to the received and possibly corrected sensor value.

• "counter": Specifies if this sensor is a pure counter. In this case, the variable must be set to true. This means that no measurement value is kept in the data storage, but all messages are counted. For logbook statistics, it will only be possible to evaluate the number of triggered events and their frequency, but none of the other statistical operations (such as mean) will give any meaningful results. If a sensor triggers very often, it can save memory not to keep all the events of a measurement cycle if this sensor only acts as an event counter.

  Note that measurements are always counted, irrespective of this configuration parameter. You will always be able to evaluate count and frequency when running the statistical analysis.

  Standard value: false

• "trigger": Specifies which events trigger a measurement. Currently, only Tinkerforge IO Bricklets are supported. For those, the following keywords can be used:

  • "low" — Measurement is triggered when the level falls to low.
  • "high" — Measurement is triggered when the level rises to high.
  • "high_or_low" — Measurement is triggered when the level changes its state from low to high or the other way around.
  • "periodic" — Periodically polled sensor. See previous section.

  Standard value: "periodic" (see previous section)

• "rest_period": Time for the sensor to rest between two measurements. In case of an externally triggered sensor, this is the minimum time that must pass between two measurements. Any measurements arriving within a shorter time period are rejected and not recorded.

  If a Bricklet triggers a lot of events, this parameter can serve as a debounce time at the receiving end of the Sensorlogger. The Brick Daemon can get its own debounce time using the parameter shown under the next point. The "rest_period" parameter becomes important if you want to avoid a flood of events that are only due to latencies in the connection between Brick Daemon and Sensorlogger. Latencies can have bad effects on frequency evaluation (especially the maximum frequency), because events can only be time-tagged once they arrive at the Sensorlogger.

  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: default_rest_period

• "io_debounce": Debounce time for the Brick Daemon to avoid multiple events from bouncing at the digital input of the IO Bricklet. The value is passed to the Brick Daemon upon Callback registration. 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: 7 ms

Supported Bricklets & Channels

Currently, version 2.1.33 (2022-05-11) of the Tinkerforge C/C++ bindings are used. The following Tinkerforge Bricklets are supported. The table also lists the channel IDs if a Bricklet supports different types of measurements.

Bricklet and Versions	Channels
Air Quality	0: Indoor air quality (IAQ) index 1: Temperature 2: Relative humidity 3: Air pressure
Ambient Light ver. 1, 2, 3
Analog In ver. 1, 2, 3
Barometer ver. 1, 2
CO2
CO2 2.0	0: CO2 concentration 1: Temperature 2: Relative humidity
Current12
Current25
Distance IR ver. 1, 2
Distance US ver. 1, 2
Dust
Energy Monitor	0: Voltage 1: Current 2: Energy 3: Real power 4: Apparent power 5: Reactive power 6: Power factor 7: Frequency
GPS ver. 1	0: Latitude 1: Longitude 6: PDOP 7: HDOP 8: VDOP 9: EPE
GPS ver. 2, 3	0: Latitude 1: Longitude 2: Altitude (m) 3: Geoidal separation (m) 4: Speed (km/h) 5: Course (°) 6: PDOP 7: HDOP 8: VDOP
Hall Effect ver. 2
Humidity ver. 1, 2
Industrial Digital In 4 ver. 1, 2	0 to 3
Industrial Dual 0-20mA ver. 1, 2	0 to 1
Industrial Dual Analog In ver. 1, 2	0 to 1
IO4 ver. 1, 2	0 to 3, also as a pulse counter
IO16 ver. 1, 2	0 to 15, also as a pulse counter
Laser Range Finder ver. 1, 2
Line
Load Cell ver. 1, 2
Moisture
Particulate Matter	1 or 10: PM1.0 2 or 25: PM2.5 3 or 100: PM10
PTC Temperature ver. 1, 2
Sound Intensity
Sound Pressure Level
Temperature ver. 1, 2
Temperature IR ver. 1, 2	0: Ambient 1: Object
UV Light ver. 1, 2
Voltage
Voltage/Current ver. 1, 2	0: Voltage 1: Current

MQTT