esphome-influxdb_v2_oss

This repo contains an ESPHome component for publishing data to InfluxDB V2 (OSS version, not Cloud).

Open Source software: GNU General Public License v3.0 or later

Features

Measurement Composition

This component allows composition of measurements from any number of sensors (numeric, text, and binary). Organizing sensors in this way ensures that all of their values are recorded with the same timestamp, which enables summarization and comparison in a reliable fashion.

Batch Timestamps

Multiple measurements can be published in a batch, ensuring that they all have the same timestamp if timestamping is enabled in the component. This permits summarizaton and comparison across measurements without having to manipulate the timestamps (e.g. truncation) in the database query or reporting tool.

Backlog Queueing

If a time server is available, local timestamping of measurements is permitted, and the component can queue measurements if the InfluxDB server is unreachable or unavailable. Each time the publish operation is invoked, an attempt will be made to connect to the server, and if it is successful then that measurement will be published along with some (or all) of the queued measurements.

Field Naming and Type Overrides

When sensors are added to a measurement as fields, the component will use the sensor's ID as the field name by default; the configuration can provide an alternative name to be used instead.

Numeric sensors default to 'float' format when published, but the configuration can override the type to 'integer' or 'unsigned integer' if desired.

Raw or Filtered Sensor Values

When a field is published, its value can be either the raw sensor value, or the filtered value if the sensor configuration includes filters. This allows the Home Assistant dashboards to include values that have been transformed for display, but InfluxDB to receive the raw values, without having to use the copy component to make both values available.

Comparison to Home Assistant's InfluxDB integration

Home Assistant includes an InfluxDB integration which can publish state changes (from all Home Assistant entities) and also import data to make it available for use in automations.

The integration does not have the composition flexibility offered by this component, and does not offer any form of batching or timestamping; as a result, controlling the organization of the published data is difficult, which makes the creation of database queries and external dashboards more complex.

In addition, dependence on Home Assistant for data recording means that any time the Home Assistant installation is upgraded or otherwise unavailable the data publication will be disrupted, and data could be lost. In applications where the data is being used for long-term reporting, elimination of the 'middle step' (passing the data through Home Assistant) reduces the chances of data loss.

Requirements

An InfluxDB V2 (OSS, not Cloud) server, with an API token that grants (at least) 'write' permission to the buckets where the measurements will be written.
A time server (Home Assistant or SNTP) if the measurements will be locally timestamped before publication (also necessary for backlog support).

InfluxDB Data Structure

InfluxDB stores data as measurements; they have names, contain fields (named values), and optionally contain tags (named discriminators). Measurements also have timestamps, which can either be generated by InfluxDB when the measurement is received, or included in the measurement by its sender.

Measurements are stored in buckets, and buckets belong to organizations.

When configuring this component you will need to know the organization and bucket names that exist on the server (which will receive the measurements), but you will decide how to name the measurements and fields, and which tags to include.

Configuration

The ESPHome 'logger' defaults to debug level; while this can be useful for troubleshooting ESPHome configurations, it can also cause warnings to be generated which don't correspond to actual problems. If you have the level set to debug, you may see a warning for the http_request component, since it will block ESPHome activities for some time while it waits for a response from the InfluxDB server. The warning will indicate that component http_request took too much time to do its work.

Minimal Example

This section is a walkthrough of minimal.yml from the examples directory. It is the most basic configuration needed to support the reporting device information (uptime and WiFi RSSI) to InfluxDB.

esphome:
  name: influxdb-minimal
  friendly_name: Minimal InfluxDB Example

esp32:
  board: esp32dev
  framework:
    type: esp-idf

wifi:
  networks:
    - ssid: example-network
      password: network-password

api:

This section fulfills basic ESPHome requirements: node information, board selection, and WiFi/API connectivity.

external_components:
  - source: github://kpfleming/esphome-influxdb_v2_oss

This configuration requires one external component, esphome-influxdb_v2_oss.

time:
  - platform: homeassistant
    timezone: EST5EDT,M3.2.0,M11.1.0

This section configures time synchronization with a Home Assistant installation (time sync will be achieved once Home Assistant connects to the ESPHome API on this device).

sensor:
  - id: _uptime
    platform: uptime
    name: ${node_name} Uptime
    on_value:
      then:
        - if:
            condition:
              time.has_time:
            then:
              - influxdb.publish: _device_info

  - id: _wifi_rssi
    platform: wifi_signal
    name: ${node_name} WiFi Signal

This section configures two sensors, device uptime and the WiFi RSSI (signal strength).

In addition, the configuration triggers publication to InfluxDB each time the 'uptime' sensor has a new value (once per second), but only if the 'time' component has achieved time synchronization. As noted below, this is required for the InfluxDB component to be able to generate timestamps, and also for the ability to queue measurements for later publication if connectivity to the InfluxDB server is interrupted.

http_request:
  useragent: esphome/influxdb
  timeout: 15s
  watchdog_timeout: 15s

This section configures the http_request component, which is used by the InfluxDB component to publish measurements to the server.

influxdb_v2_oss:
  url: http://influxdb.example.com:8086
  organization: example
  token: influxdb-token
  backlog_max_depth: 60
  backlog_drain_batch: 10
  tags:
    device: ${node_name}
  measurements:
    - id: _device_info
      bucket: iot_devices
      name: info
      sensors:
        - sensor_id: _uptime
          name: uptime
        - sensor_id: _wifi_rssi
          name: rssi

This final section configures the InfluxDB component itself.

First, the basic details required to connect to the InfluxDB server: URL, organization, and token.

The backlog_max_depth and backlog_drain_batch items control the maximum number of measurements which can be stored in memory while waiting for the InfluxDB server to be reachable, and the maximum number of queued measurements which can be submitted in a single batch. It is important to keep that number relatively low so that the ESPHome device won't appear to 'lock up' when draining a large number of queued measurements when the InfluxDB server becomes reachable after a period of unreachability.

The 'tags' section configures tags (keys and values) which will be added to all measurements published by the component. In this case a tag named device will be sent containing the ESPHome node_name.

Finally a single measurement is configured. It has an ID which can be supplied to the influxdb.publish action to trigger publication, a bucket name to receive the measurement, and a name ('info'). The measurement will contain values from two sensors (specified by their IDs), with names supplied to override the default names ('uptime' instead of '_uptime' and 'rssi' instead of '_wifi_rssi').

Full Featured

See FULL_CONFIGURATION.

Issues, Feature Requests, Discussions

If you need to report an issue, or suggest a new feature, please do so in the 'Issues' area of this repository.

If you'd like to discuss usage of these components, or ask for help with them (but not with ESPHome itself or InfluxDB), please do so in the 'Discussions' area of this repository.

Chat

If you'd like to chat with the esphome-influxdb_v2_oss community, join us on Matrix!