Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/kpfleming/esphome-influxdb_v2_oss

An ESPHome component for publishing measurements to InfluxDB OSS (version 2 or later).
https://github.com/kpfleming/esphome-influxdb_v2_oss

Last synced: about 1 month ago
JSON representation

An ESPHome component for publishing measurements to InfluxDB OSS (version 2 or later).

Awesome Lists containing this project

README 

        
# esphome-influxdb_v2_oss



Open Source Initiative Approved License logo

[![License - GNU GPL v3.0+](https://img.shields.io/badge/License-GNU%20GPL%203.0%2b-9400d3.svg)](https://spdx.org/licenses/GPL-3.0-or-later.html)



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](https://spdx.org/licenses/GPL-3.0-or-later.html)



##  



## Features



### Measurement Composition



This component allows composition of

[measurements](#influxdb-data-structure) 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](https://www.home-assistant.io/integrations/influxdb/)

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](examples/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.



```yaml

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.



```yaml

external_components:

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

```



This configuration requires one external component,

esphome-influxdb_v2_oss.



```yaml

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



```yaml

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.



```yaml

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.



```yaml

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](FULL_CONFIGURATION.md).



## Issues, Feature Requests, Discussions



If you need to report an issue, or suggest a new feature, please do so

in the

['Issues'](https://github.com/kpfleming/esphome-influxdb_v2_oss/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'](https://github.com/kpfleming/esphome-influxdb_v2_oss/discussions)

area of this repository.



## Chat



If you'd like to chat with the esphome-influxdb_v2_oss community, join

us on [Matrix](https://matrix.to/#/#esphome-influxdb:km6g.us)!