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? ↩