Status streams using cURL
This tutorial will show how to send status streams to Carriots with cURL and understand the response.
Status streams are technically equivalent to data streams except for the data payload treatment and response. Status streams may be used to communicate that a device is still alive, to inform about its signal coverage, battery level or some other management info and for software management.
This last use is what will be slightly covered in this tutorial. Please note that sending status streams is explained here using cURL but can be done with any other client.
To begin with, we need to know what we want to send and how to send it to Carriots REST API. You need:
- A device in Carriots
- A valid Apikey
- Your payload (data to send)
- A REST client
Before diving into more details. A brief explanation about how files can be associated to a device.
In Carriots, devices can have associated text files for its software management. For example, a device can have a dynamic configuration file holding parameters that can be replaced in execution time, without rebooting the device. It can also have a static configuration file with parameters that are loaded at boot time and a firmware configuration file containing scripts and algorithms that changes devices behaviour.
In this tutorial our device, lets take test@carriots, will have the following associated files:
- dynamic_conf - version 1.3
- static_conf - version 1.0
- firmware - version 1.0
Versions are important to know when a device has a file with a different version number and should be updated.
Files are created under the "Files" tab in the control panel devices screen.
If youre registered in Carriots, you have a default device already created for you.
Check your control panel and see what it looks like.
Basically you need the device id_developer that might be something like defaultDevice@myusername.
Now, go to your control panel “My account menu” and check your Apikey.
Its a big alphanumeric token like 98346673a6377ef1fde2357ebdcb0da582b150b00cabcd5a0d83045425407ab4.
Now we define the data. Here comes the difference from data streams.
Keys can be devices file names with a version number as value. When a key matches a devices file name, Carriots will compare its version and will return a 0 if version match (0 means no update needed) or 1 if version does not match, which means that for that file versions are different.
If a key doesnt correspond to a devices file, nothing will be returned (0 nor 1).
In this tutorial we will send this data:
Finally we need a REST client. This client can be whatever you want that can create full HTTP request including headers, verbs and so on.
In this tutorial we will use cURL. If you are not familiar with cURL you might want to check the official page: http://curl.haxx.se/ for installation instructions and documentation. We will assume you will have it installed and running. You can also follow this tutorial with other REST clients such as hurl (http://www.hurl.it/) or Poster plugin (https://addons.mozilla.org/en-us/firefox/addon/poster/)
Your payload, the stream to send to Carriots, will be:
Protocol will be used in future versions of Carriots along with checksum. Let it be v1 or whatever for the protocol and leave it blank for the checksum. Both will be ignored for the actual REST API version.
The at field is the epoch timestamp (Unix UTC) for the stream. You can run date +%s to get it in Unix/Linux shell or go to http://www.epochconverter.com/ hre and grab one. data field contains your data. Or you can use "now" reserved word and Carriots will fill the value with the receive date timestamp automatically.
Create a file containing the payload: payload.txt
The target URL is: http://api.carriots.com/status/
Lets send it to Carriots!
Type the cURL command:
This command send a POST request to Carriots REST API including the data from payload.txt file. The corresponding apiKey
--verbose is there because you like to see it all.
Your response must be something like:
This response means that dynamic_conf is 1 (update needed), static_conf is 0 (no update needed) and firmware is 1 (update needed).
battery_level is ignored in the response because it does not match any devices file.
Now you can check your stream listed in the control panel status stream list. Go to “Data management” → “Status streams” and you will see your data!
Ok, now we know which configuration files are not up to date. How to download them?
First step is locating the version identifier for the files to be updated by accessing the device configurations in the following URL:
The response will be something like:
So the version for "firmware" file is 1.0. The URL to download "firmware" file content is:
Generic file download URLs are like this one:
http://api.carriots.com/devices/--DEVICE ID_DEVELOPER--/deviceconfigs/--FILE NAME--/--FILE VERSION--/
If you want to know more about device config, see this link.