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
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.
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.
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
.
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.
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.
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.
-
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 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.
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.
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').
See FULL_CONFIGURATION.
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.
If you'd like to chat with the esphome-influxdb_v2_oss community, join us on Matrix!