Skip to content

InfluxDB Feed Plugin

The InfluxFeed plugin, when installed and enabled, will export entity data from Reactor into InfluxDB, a database that is particularly well-suited to time-series data, and adds data visualization capabilities to your Reactor environment. InfluxDB 1.8+ and 2.x are supported (as of April 2023, version 2.7 is recommended).

Installation of InfluxDB is off-topic for this documentation. Follow the installation instructions for those particular projects and make sure your InfluxDB service is up and running, and you've created a new database, before configuring it in Reactor. Make sure your InfluxDB service starts at boot (and ideally before Reactor, for example, by listing InfluxDB as a dependency in the service configuration file if you are using systemd).

Installation

At the moment, InfluxFeed is included in all Reactor distributions. In a future release, it will be a separately-installed component.

Configuration

InfluxFeed (like all plugins) is configured in the plugins section of your reactor.yaml file. The structure of this section is similar to that of the controllers section (Controllers are actually a special case of Plugins). There is a prototype configuration in dist-config/reactor.yaml that you can copy-paste as a starting point. The id must be unique to each plugin instance. The implementation value must be exactly InfluxFeed. The name can be anything you wish, and the enabled value must be true if you want the plugin to run.

In the config subsection for the instance, the details of the database connection and what is to be exported are defined. Database configuration is somewhat different for InfluxDB 1.x vs 2.0, so please follow the configuration instructions for the version you are using.

Configuration for InfluxDB 1.x

If InfluxDB is running on the same host as Reactor, then the only configuration values you need to supply to get started are influx_database, influx_username and influx_password in the config subsection. Here's such a minimal configuration:

plugins:
  - id: influx
    name: InfluxDB 1.x Feed
    enabled: true
    implementation: InfluxFeed
    config:
      influx_url: http://influx-ip-or-hostname:8086
      influx_database: reactor
      influx_username: someuser
      influx_password: "I'm a little teapot"  # note use of quotes

If your InfluxDB server is running on the same host as Reactor, you can (and should) omit influx_url (comment it out or delete the line); otherwise, it should be set with the IP and port of your InfluxDB service.

The influx_retention_policy value sets a retention policy for data sent (default is database's configured policy).

Configuration for InfluxDB 2.0

For InfluxDB 2.x, only the influx_token, influx_org and influx_bucket keys are required. You can create the token in the InfluxDB UI.

plugins:
  - id: influx
    name: InfluxDB 2.0 Feed
    enabled: true
    implementation: InfluxFeed
    config:
      influx_url: http://influx-ip-or-hostname:8086
      influx_token: j3ky2IbsCbl83Lff82W-yWs2QC7_MwzvrNL6ZCqK0fqXlMWjRALvOYhQJ0GRTe-lsxVaANTWW4TKhcZPRwIPxg==
      influx_org: myhome
      influx_bucket: reactor

If your InfluxDB server is running on the same host as Reactor, you can (and should) omit influx_url (comment it out or delete the line); otherwise, it should be set with the IP and port of your InfluxDB service.

The influx_retention_policy value sets a retention policy for data sent (default is database's configured policy).

Selecting Capabilities for Export

By default, InfluxFeed will export data for all entities having the following capabilities: power_switch, dimming, binary_sensor, motion_sensor, leak_detector, temperature_sensor, humidity_sensor, battery_power, and wx (attributes temperature and humidity only). If you want to select additional capabilities/attributes, or eliminate some of the defaults, the following configuration keys apply:

  • select_capabilities - (object) optional, capabilities to be exported (see details below);
  • select_entities - (array of strings) optional, strings to match canonical IDs for those entities that should be exported; if not supplied, all entities that have a capability eligible for export will be exported. See details below.
  • filter_entities - (array of strings) optional, strings to match canonical IDs for those entities that should not be exported, even if they have a matching capability and/or are matched by select_entities. See details below.

The select_capabilities config value, when supplied, must be an object that names which capabilities are to be exported. The general form is this:

plugin:
  - id: influx
    # this example heavily abbreviated for simplicity.
    config:
      select_capabilities:
        light_sensor: true
        power_sensor: true
        dimming: false

In the example above, the capabilities light_sensor and power_sensor will be exported in addition to the default exported capabilities (listed earlier). Export of the dimming capability is being disabled by the use of false as the value.

For some capabilities, there are attributes that may be undesirable, for one reason or another, to export, for example, long strings that rarely or never change, or any value you're not at all interested in that would waste space in the database. To limit the exported attributes for a capability, we'll add to the previous example config:

plugin:
  - id: influx
    # this example heavily abbreviated for simplicity.
    config:
      select_capabilities:
        light_sensor: true
        power_sensor: true
        dimming: false
        x_hubitat_sys_mode:
          attributes:
            mode_id: true
            mode_name: true

In this example, the x_hubitat_sys_mode capability will be exported, but only the mode_id and mode_name attributes; all other attributes defined for the capability are ignored (not exported). If you don't specify which attributes are to be exported (as shown above for light_sensor, power_sensor, and dimming), then all attributes of the named capability are exported.

Exporting Extended Attributes

Extended attributes (those in extension capabilities, i.e. beginning x_hubname...) do not have guaranteed data types — the data type is whatever the hub provides, at the time it provides it. It is therefore possible that a change in the hub firmware or behavior can cause a change in the data type of the exported value at any time, which InfluxDB will not accept (the data type for the field in InfluxDB is determined by the first insert and must remain consistent thereafter). If you are exporting extended attributes, you must use Advanced Attribute Handling (below) to force the expected data type for each extended attribute exported. Alternately, if the extended attribute value is mapped into a Reactor capability/attribute, use that instead (Reactor attribute value types are guaranteed).

See Advanced Attribute Handling below for additional special configuration for attributes.

Selecting Exported Entities

If select_entities and filter_entities are not specified in the configuration, then all entities having a capability that is eligible for export are selected for export. The select_entities and filter_entities values are two ways to limit the list of entities exported if necessary. They can be used individually or together.

Each value must be an array containing strings. The strings can be one of the following (quoting these strings is recommended):

  • A literal string that exactly matches the canonical ID or name of an entity (e.g. "hubitat>76", "Living Room Lamp"); name matches are case-insensitive;
  • The string "controllerid>*" where controllerid is the ID of one of the configured controllers; in this case, all entities from that controller are matched;
  • A string of the form "/regexp/", where regexp is a regular expression used to match the entity's canonical ID or name. Note that no regular expression flags are permitted after the trailing /; the pattern is always case-insensitive.

If select_entities is not specified, then all entities are exported; but if select_entities is specified, only those entities matching its listed values are exported.

The filter_entities list is identical in form to select_entities, but has the opposite effect: it filters out any matching entities. Filtering is applied after selecting (that is, select_entities is processed before filter_entities).

Advanced Attribute Handling

Reactor has an enhanced form of the select_capabilities configuration that allows finer control over which attributes are exported, their data type, field name, and value. This is necessary because some hubs (e.g. Vera) handle all attributes as strings, complicating data handling within InfluxDB and Grafana.

The following is the advanced form for attributes control in select_capabilities configuration (this shows all options, most are optional and have reasonable defaults):

    config:
      # your other configuration above this line
      select_capabilities:
        capability_name:
          include_all_attributes: true | false
          attributes:
            attribute_name:
              include: true | false
              name: "new_field_name"
              type: "number" | "boolean" | "string"
              map:
                "value1": "new_value1"
                "value2": "new_value2"
                "value3": "new_value3"
              map_default: "default_value"
              expr: "expression"
              skip_null: false
            next_attribute_name:
              # more
        next_capability_name:
          # etc.

Within each capability, the attributes key lists the names of each attribute to be exported; attributes not mentioned are not exported, so this requires that you name all attributes you need to export with this form or the simple attribute_name: true form.

If include_all_attributes is not specified or is false, only attributes specifically listed in attributes will be exported. If true, all attributes of the capability will be exported unless the attribute is listed with include: false as further described below.

The attributes key then provides specific information about each attribute, under which the following keys are supported (all are optional):

include

This is a convenience value that lets you quickly include/exclude an attribute. If the value is true (the default if this key is not given), the attribute is exported; if false, it is not exported.

name

Allows you to change the name of the field to which the attribute value is exported. By default, the field name is the same as the attribute name. In some cases, it may be desirable to change the name, particularly when changing the data type of a field: InfluxDB does not currently allow you to write data to an existing field of a type other than the type it already contains. Overriding the name to create a new field quickly works around this limitation1.

type

Allows you to change the data type of the exported value. Valid types are number, string and boolean. The plugin will attempt to convert the attribute value to the data type specified; if the data type cannot be converted, a null results.

map

Processed before type (if present), the map is an object/dictionary that converts a matching input value to an output value. The map_default value, if present, will be used if the attribute value does not match any in the given dictionary; if map_default is not provided and there is no dictionary match, the result is null. This is intended only for use with string attribute values; do not, for example, attempt to convert booleans to 0 or 1; type: number will do that correctly.

expr

Warning: Experimental Allows you to modify the value by passing it through an expression of your choosing. The local variable value will contain the current value of the attribute (after applying map and type). For example, to convert an attribute value in bytes to megabytes with two decimals, one might use expr: math.round( value / 1048576, 2 ). The expression is tokenized at startup to improve performance. If the expression contains a syntax error and cannot be tokenized, and error is written to the log file and the field will not be output. If the expression fails evaluation (i.e. it compiles but doesn't run), null is output (and error messages are output to the logs). You must inspect the logs when setting up this feature; if your expression fails to evaluate, it will log a lot of errors every time it is used (each time the plugin tries to export the attribute).

skip_null

If skip_null: true is present, null values will not be exported for this attribute to InfluxDB.

To reiterate, the order of processing is map..type..expr..skip_null. After these steps, the value must be a primitive value (string, number, boolean, or null). If it is not, the attribute is not exported. You cannot export array or object data to InfluxDB.

Exporting Global Variables

Global variable values can also be exported to InfluxDB. The additional configuration array export_globals, when present, defines which global variables are exported. All exported global variables are fields of the globals measurement in InfluxDB.

The following is an example configuration:

    config:
      # (InfluxDB server and other configuration redacted for clarity)
      export_globals:
        - livingRoomAverageHumidity     # simple, by name only
        - name: livingRoomAverageTemp   # detailed, more directives to control value logged
          type: number
          expr: (value - 32) / 1.8      # convert F temp to C (for example)

In this example, a global variable named livingRoomAverageHumidity is exported. Its type will be inferred from the value first seen when Reactor starts, and its values are written without modification. The variable livingRoomAverageTemp has a somewhat more complex configuration, where its type is specifically declared to be a number (so the plugin will try to coerce the value to a number before exporting it), and an expression is used to rescale the value before sending it to InfluxDB.

Global variable export configuration, when done using the detailed syntax, supports the following keys (with their same meaning) as those used for entity attributes: map, type, expr, and skip_null (see above). With detailed syntax, name and type are always required.

Like attribute values, only primitive values (strings, numbers, booleans, and null) can be logged by InfluxDB.

Updated: 2024-Mar-28

  1. See InfluxDB FAQ: Can I change a field's data type? ↩