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.
IoTaWatt fully supports the influxDB HTTP API for sending data to influxDB at a specific interval of 5 seconds to one hour. Like other similar IoTaWatt 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.
Here you specify what you want IoTaWatt to upload.
- 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). IoTaWatt 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, IoTaWatt 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. IoTaWatt 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, IoTaWatt 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.
- Name of the influxDB database that you have created to be the repository for the IoTaWatt 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.
- Optional security credentials. If specified, IoTaWatt will use standard authorization headers with these credentials.
- upload history from
Specify the starting date that IoTaWatt 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
- Name that you assign to the measurements that IoTaWatt 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.
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 IoTaWatt, 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
- 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'.
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 IoTaWatt 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.
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 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 IoTaWatt 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:
with a device name of IotaHome 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=IotaHome solar=2944.6 1523810195|
|$device||$name||$units||IotaWatt,tag1=solar kWh=2944.6 1523810195|
|$name.$units||value||solar.kWh value=2944.6 1523810195|
|power||&device.01||$name||power,tag1=IotaWatt.01 solar=2944.6 1523810195|