Using Helium Commander to Export Sensor Data
The Helium API offers a comprehensive set of options to fetch time-series data from your sensors.
Time-series API endpoints are available for sensors, elements and at the organization level. Each of these has the set of APIs but offers up different readings since they play different roles.
Helium-commander, commander in the below, is a command line interface (CLI) that makes it easier to use the Helium API from the command line. It offers a number of commands and sub-commands to interact with the Helium API.
Let’s explore how we fetch readings for a sensor and label of sensors.
In order to retrieve readings we need to have the ID of a resource that supports the timeseries endpoints. At the time of this writing commander supports the following timeseries related commands:
- Sensor - timeseries, dump
- Label - dump
- Organization - timeseries, dump
- Element - timeseries, dump
The format for the timeseries and dump commands is consistent across each of these, so we’re only going to cover the sensor case. The notable exception is organization which does not require an ID since the command applies to the authorized organization, i.e. the organization your API key is a part of.
In order to get an ID for a sensor we use the following:
The short form of the UUID in the first column can be used in all commands that need a sensor ID. (Note: you can get the full UUID if needed by passing --uuid flag.)
To fetch a page of readings for a given sensor use the following:
This shows the ID for each reading, the timestamp the reading was taken, the port of the reading and the actual value. The port of a reading indicates the kind of reading it is and what the units are. While any string can be a valid port, the sensors that Helium ships use documented ports.
The amount of data in the timeseries list command can be controlled using the --page-size argument. The default page size is 20 but can be set up to a server-controlled maximum. The current maximum is 10,000 readings. After that the page links in the API response should be used to page through the results on a page by page basis.
For example to return just 5 readings in the result instead of 20:
You can filter the returned readings by passing in --port with a comma separated list of ports to include in the result. For example, to retrieve a page of just temperature readings:
In order to fetch readings within a certain date and time range use the --start and --end arguments to set a start and end date time.
For example, to retrieve temperature readings for a given day:
The default output format is the visual tabular format shown in the examples above. You can have commander report more machine friendly versions of the data by using --format. The supported format values as of this writing are tabular, csv or json.
For example, the below retrieves a page of temperature readings in csv format:
In order to pipe the output of the above to a file called out.csv use the unix re-direct operator:
$ helium --format csv sensor timeseries list 3df4e2e0 --page-size 5 > out.csv
In order to get more than the maximum readings in a page use the dump command. The readings are dumped to a file that is named after the complete UUID for the sensor.
The default output format for dumped readings is csv but json is also supported.
Note that all the above port and date filters can be used in the dump command.
Since there can be a lot of readings exported the dump command can take a long time to complete and may generate very large files with the exported readings.
For example to dump all readings for a sensor:
$ helium sensor dump 3df4e2e0
To dump readings for all sensors in a label. A file named after the sensor UUID will be created for each sensor in the given label:
$ helium label dump 364779e
To dump all readings for every sensor in your organization. A file named after the sensor UUID will be created for each sensor:
$ helium organization dump
That covers the basics of accessing and dumping Helium time-series readings. helium-commander offers a lot of help information that is displayed by using --help at each level of commands and sub-commands. Happy time-series and commander exploring!