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_database: reactor
      influx_username: someuser
      influx_password: "I'm a little teapot"  # note use of quotes

Optionally, you can set influx_url to the URL of your InfluxDB server; 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_token: j3ky2IbsCbl83Lff82W-yWs2QC7_MwzvrNL6ZCqK0fqXlMWjRALvOYhQJ0GRTe-lsxVaANTWW4TKhcZPRwIPxg==
      influx_org: myhome
      influx_bucket: reactor

Optionally, you can set influx_url to the URL of your InfluxDB server; 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
            - mode_name

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

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

Updated: 2021-Oct-13