Skip to content

InfluxDB Feed Plugin

The InfluxFeed plugin, when installed and enabled, will export entity data from Reactor into InfluxDB 1.8+ or 2.0. InfluxDB is a database that is particularly well-suited to time-series data, and adds data visualization capabilities to your Reactor environment.

InfluxFeed supports version 1.8 and higher InfluxDB. 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.0, 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).

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 22039 introduced additional behaviors in the select_capabilities configuration for attributes to allow better control over data types and values. 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 in select_capabilities configuration (all keys are optional):

  # your other configuration above this line
  select_capabilities:
    capability_name:
      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"
    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.

Within each attribute, 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 of a different type for an existing field than the type it already contains. Overriding the name to create a new field quickly bypasses this limitation1.

type

Allows you to change the type of 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 is output.

map

Processed before type handling, 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 dictionary; if not provided, the output 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.

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).

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

Updated: 2022-Mar-27