Setting up influxdb for VSCP use

Setting up influxdb for VSCP use

This is a simple step by step guide on how to setup influxdb for use with a VSCP system. It concentrate on the >2 version only. There is plenty of information available about the earlier versions.

The instructions is for a Debian based (or derived) system. Links are provided to relevant parts that can used for other setups.

Step 1 - Install

Full install instructions are here.

influxdb needs curl so install it first. You do this with

sudo apt install curl

Now get the latest version of influxdb with

wget https://dl.influxdata.com/influxdb/releases/influxdb2-2.0.8-amd64.deb

Install with

sudo sudo dpkg -i influxdb2-2.0.8-amd64.deb

After the install is finished verify that the influxdb server is running with

sudo service influxdb status

You can read more about controlling (start/stop/restart) the systemd service here

Step 2 - Configure the server

When the server is running it exports a web interface at http://localhost:8086. Setup your admin server account in this interface the first thing you do. Username, password, organisation name and a default bucket is what you enter here. The official docs describe the process here.

Note your token and your organisation

and on the command line issue

influx config create --active -n config-name -u http://localhost:8086 -t mySuP3rS3cr3tT0keN -o example-org

where mySuP3rS3cr3tT0keN is your token and example-org is your organisation.

This sets up a configuration profile. This lets you avoid having to pass your InfluxDB API token with each influx command.

Note that the web interface is open and unsecure at this moment. We recommend that you get a letsencrypt certificate for your server and follow the steps described here to secure your server. This is entirely optional of course.

Step 3 - Set environment variable

export INFLUX_TOKEN=mySuP3rS3cr3tT0keN

where mySuP3rS3cr3tT0keN is your personal token from above. Doing this lets you omit the token when you issue commands.

Step 4 - Create a bucket

Create a bucket vscptest we can use for some testing. You will delete it later on in this guide. We add it with

influx bucket create -n vscptest -o "your organisation" -r 72h

The full format is

influx bucket create -n <bucket-name> -o <org-name> -r <retention-period-duration>

retention-period-duration is the time the data is kept. In this sample this time is set to 72 hours.

You can also create buckets in the web interface. Read more about that here

If you want to view defined buckets issue

influx bucket list

Step 5 - Add some (VSCP) data

Full info about adding data to influx is here and here

Before we can do anything useful we need to add some VSCP data to the bucket we created above. There are different formats you can enter data. One is the line protocol. Flux is another way.

The line format is simple to understand it is built like this

measurement,tag-pair,tag-pair... field-pair,field-par,field-par timestamp

Tags are value pairs that are indexed and therefore suitable for selection and search. Field are data belonging to a record. You can search on fields also but the search is much less efficient then on tags.

For a VSCP measurement we can construct a line protocol item like this

temp_garage,guid=FF:FF:FF:FF:FF:FF:FF:F5:11:00:00:00:00:00:00:03,sensorindex=0,unit=1 value=22.52,zone=0,subzone=0

• temp_garage is the measurement. We put one or many measurement sin a bucket.
• guid=FF:FF:FF:FF:FF:FF:FF:F5:11:00:00:00:00:00:00:03 is the first tag. We want to select a measurement from which sensor it originates from. A sensor is defined by it's guid and it sensorid. The measurement name can be seen as a textual description of the two. Note that tags always is stored as strings. No quotation marks needed.
• sensorindex The sensor index identifies a specific sensor in a device identified by it's GUID.
• unit Tells what unit the measurement is in. Zero for the default unit. It is a tag because we may want to select a specific unit when we present data.
• value is the measurement value. It is a floating point value.
• zone Is the zone this sensor is located in.
• subzone Is the subzone this sensor is located in.

You can use the CLI to

influx write \
  -b bucketName \
  -o orgName \
  -p ns \
  --format=lp
  -f /path/to/myLineProtocolData.txt

All you need to use influx write is to specify your bucket name -b, your org name -o, and your timestamp precision -o, the format of your file. In our example, our file is in line protocol or --format=lp, and the path to your file. csv (comma separated values) is the other format.

Step 6 - Query data

Full influx query info is here and here

Show guid,value and unit for the temperature bucket in the last 10 minutes

from(bucket: "temperatures")
  |> range(start: -10m)
  |> keep(columns: ["guid","_value","unit"])

Data for all sensors will be displays. With

from(bucket: "temperatures")
  |> range(start: -10m)
  |> keep(columns: ["guid","sensorindex","value"])
  |> filter(fn: (r) =>
    r.guid == "25:00:00:00:00:00:00:00:00:00:00:00:05:01:00:02" 
  )

we will only get values for device 25:00:00:00:00:00:00:00:00:00:00:00:05:01:00:02. If it have several sensors (with different sensorindex) we will get all of them.

from(bucket: "temperatures")
  |> range(start: -10m)
  |> keep(columns: ["guid","sensorindex","value"])
  |> filter(fn: (r) =>
    r.guid == "25:00:00:00:00:00:00:00:00:00:00:00:05:01:00:02" and
    r.sensorindex == "4"
  )

will also specify the sensor of the device which we want values from.

Step 7 - Delete the test bucket

Remove the test bucket with

influx bucket delete -n vscptest -o "your organisation" 

You can delete buckets also in the web interface. Full info about deleting buckets is here

to be continued ....