influxDB

influxDB is a fast open-source time-series database package. It can run on a variety of platforms and is also available as a managed, fully hosted service, from several vendors. As part of their "TICK" stack, InfluxData provides tools to facilitate collecting data from a variety of sources, as well as tools for infrastructure monitoring, alert management, data visualization, and database management. The popular grafana visualization tools also work well with influxDB.

eMon Energy fully supports the influxDB HTTP API for sending data to influxDB at a specific interval of 5 seconds to one hour. Like other similar eMon Energy services, continuity of updates is maintained despite outages that may interrupt the communications.

This tutorial assumes you have established your own instance of influxDB or subscribed to a hosted service. It does not attempt to explain how to install or use influx or any of the related visualization tools. There's a whole universe of enthusiastic users at the influxData forum, where you can get help with anything and everything.

Configure eMon Energy

To configure the influxDB upload service in eMon Energy, Hover over **Setup button** and click **Web Server** from the dropdown menu.

**Setup Menu**

Choose influxDB.

**Select influxDB**

Here you specify what you want eMon Energy to upload.

**Select influxDB**
post interval

Number of seconds that each data point will represent. The trade-off is between higher resolution (small interval) and minimizing the storage requirement of the data over time (larger interval). eMon Energy accepts any value from 5 seconds to 3600 seconds (1 hour), in 5 second increments. Although not a strict requirement, it's best to use a number that is an even factor or multiple of one minute: 5, 10, 15, 20, 30, 60, 120, etc.

bulk send

Number of interval postings to aggregate into a single HTTP request. Specifying 1 will send a data packet to influxDB at each interval. If your interval is 5 or 10, it will send a packet every 5 or 10 seconds. That's fairly inefficient and can be problematic when there are internet connectivity issues. By specifying a larger bulk send, eMon Energy will aggregate the posting data for the specified number of intervals and send the data in one packet. For instance if your interval is 10 seconds, specifying bulk send = 6 will cause data to be sent every 60 seconds. Large bulk send values will cause any real-time dashboards to update less frequently, so you should strike a balance. eMon Energy keeps all of the data in the SD data log, so there is no risk of losing data by using this feature. Should there be any failure to deliver, eMon Energy will pick up with the last successful posting when the problem is resolved.

server URL

URL of the influxDB server. The URL must begin with http:// (not https://). The url may contain a domain name or an IP address. The :port number is optional and defaults to the influxDB default of :8086.

database

Name of the influxDB database that you have created to be the repository for the eMon Energy data.

retention policy

Optional name of the influxDB retention policy that you want to associate with the measurements that are written to influxDB. If not specified influx will use the default policy. If you specify a retention policy, it must be defined to influxDB before data can be written.

username/password

Optional security credentials. If specified, eMon Energy will use standard authorization headers with these credentials.

upload history from

Specify the starting date that eMon Energy will use to upload history to a new set of measurements. When the influxDBService starts, a query is made to determine the date/time of the last data written, qualified by the first tag-set. Data upload is initiated as follows:

Condition

begin date specified

begin date not specified

new measurement set

begin date 00:00

current date/time

existing measurement set

greater of last entry date/time or begin date

last entry date/time

measurement

Name that you assign to the measurements that eMon Energy will be posting. The specification can be a constant string, or can include variables as explained below under variables. Note that if not specified, the variable $name will be used.

tag-set

tag-set

A collection of optional user specified tag-key/tag-value pairs that will be included as part of each measurement. The influx documentation somewhat explains them here. Basically, these tags each produce a table index that can be helpful in increasing the performance of data retrieval. The first tag-set is a special case for eMon Energy, and if specified, is used to uniquely identify the measurement subset from this device so that upload can resume seamlessly. If this is not the only device that will be posting to the database, a unique identifier for this device should be included as the first entry in a tag-set. tag-values can be a constant string or can include variables as explained below under variables

edit an existing tag by clicking on it's associated edit button, or add a new one with the add button. add tag-set

**Influx tag-set**
field-key

Each measurement contains a field key and field value. The field value is always the value specified in the "calculator" function. The field key to be used is specified here. It can be a constant string or can include variables as explained below under variables. If not specified, the default field key in each measurement is the string 'value'.

measurements

measurements

The set of *measurement*s that will be sent at each interval. The editor uses the "calculator" interface to create scripts to generate data using the various eMon Energy inputs. Each entry will generate a measurement using the influx line protocol:

<measurement>[,tag-key1=tag-value1[,tag-key2=tag-value2...]] field-key=field-value time

Note that measurement, tag-value, and field-key are specified above and can be fixed strings or can be or contain variables. Some examples of the various ways this can be used to create different types of measurement specifications are given below.

As each measurement is written the $name and $units variables are assigned the value specified in the individual measurement specification.

The units of the field set defaults to watts. While Watts is the typical unit reported, the following additional units are available.

  • watts

  • volts

  • VA

  • pf

  • Hz

  • kW

  • wH

  • kWh

Once configured, a new influx service will be created. The current state of the service and the date/time of last update will be displayed under the influxDB tab in the status display.

influx status bar

The service can be started and stopped using the start/stop button. When a running influx service is changed, the service is automatically stopped and restarted.

Variables

Variables provide a way to further customize the way data is organized in your influxDB database. This tutorial will not get into the implications of different conventions, except to say that future generic visualization templates may be based on using the default specifications for measurement and field key.

There are three variables defined:

  • $device - The name assigned to this eMon Energy device in the device configuration section.

  • $name - The name specified for the current measurement

  • $units - The units specified for the current measurement

When these variables appear as all or part of the string specified for measurement field key or a tag value, the instance of the variable name is replaced by it's value. Evaluation proceeds left to right in a string.

So as an example, when generating a measurement configured as:

**Influx Solar Output**

with a device name of eMonHome and the current value of the input solar of 2944.6, the following different measurements could be generated:

measurement

tag-value

field-key

measurement sent to influxDB

$name

value

solar value=2944.6 1523810195 (This is the default)

$units

$device

$name

kWh,tag1=eMonHome solar=2944.6 1523810195

$device

$name

$units

eMon,tag1=solar kWh=2944.6 1523810195

$name.$units

value

solar.kWh value=2944.6 1523810195

power

&device.01

$name

power,tag1=eMon.01 solar=2944.6 1523810195