Posting Custom Messages to the Aretas Cloud (Basic Method)

You are here:
< Back

The message format to post to the Aretas API was kept intentionally simple. There are two facets to the Aretas Cloud Web Services, the ingest portion and the standard web service for applications and application developers. The ingest portion maintains a proprietary authorization mechanism for posting sensor messages while maintaining an ultra simplistic API for “dumb” sensors that cannot support SSL/TLS and other complicated auth mechanisms (some IoT MCUs have less than 2K of memory and still need to run a networking stack). Posting sensor messages requires that you have already provisioned the sensor device in your account before posting. Once the sensor device has been added to your account, it may take up to 5 minutes to propagate the auth criteria to the various ingest end points.

API URL

http://api.aretas.ca/SensorAPI The API URL takes sensor sensor data via http mechanism in an ultra simplistic REST-style format. All the payload data is contained in the GET request key/value pairs. The various API functions are denoted by the *actiontype* key/value pair All values posted to the API must be parseable base 10 format integers or longs.

For instance, the sensor type must be converted to an unsigned integer then into a base 10 string for the query URL. You cannot post “0xF8” or convert it to a signed integer and output it in base 10 notation (since the resulting number would be negative). The obvious exception is the data which needs to be in a base 10 notation suitable for parsing into a 32-bit IEE floating point number. e.g. 0.01 or 18.340 or -12.2 etc.

Currently the only exposed actiontype for remote clients using basic posting method is the POSTDATA request. A sample GET request will look like: http://api.aretas.ca/SensorAPI?a=1&m=343125563&st=248&t=1312569434&d=29.3key / value pairs are as follows

a = actiontype

actiontype will be an usigned integer specifying the API actiontype currently there is one exposed actiontype: POSTDATA = 0x01 therefore GET requests should contain a=1

m = macaddress

mac address will need to be a 32-48-bit unique ID. Certain sensor clients as specified by us will require their macs to be 32-bits in length. The MAC does not necessarily have to be an actual MAC, although device manufacturers have done a lot of the work already to provide us with a unique device ID, as such, you can usually just chop off 2 bytes of the OUI portion and be pretty much guaranteed a unique ID.

st = sensortype

the sensor value is a base 10 string representation of a short unsigned int representing one of the sensor codes from the Aretas API. This value can be arbitrary, but to accurately be mapped to a type in the charting and alerting systems, please choose an existing sensor type from the documentation

t = timestamp

the timestamp is a long timestamp (milliseconds from epoch) Please note that the timestamp must be in MILLISECONDS

d = data

the data is a string representing a float value for the data reading from the sensor the number should be parseable into a 32-bit IEE floating point number.

API Response Codes

The API will respond with a string representing a response code (similar to HTTP response codes) e.g:. 200 Client API libraries are implemented in Java to interpret the response codes however most platforms can convert the API reponse codes using something like an atoi(String) function or parseInt function and use the response code descriptions below to interpret:

200 = RESPONSE_OK //sensor data is injected into queue, everything is ok
400 = RESPONSE_ERR //there was an error processing the request (connection timeout, etc)
401 = MAC_NOT_ALLOWED //the mac address in the query was not authorized to perform the action requested
402 = INCOMPLETE_QUERY //the query parameters were incomplete
404 = UNSUPPORTED_ACTION //the actiontype was not allowed or unsupported
801 = BAD_SENSOR_TYPE //the sensor type is not allowed or unsupported
802 = BAD_DATA //the data was impossible to parse or decipher
803 = DATA_OUT_OF_RANGE //the data was out of range for the specified sensor type
1022 = UNKNOWN_ERR //an unknown internal error occurred (usually only triggered by the APIClient library)
1023 = UNKNOWN_RESPONSE //triggered by the APIClient library when the response from the server was unexpected)
Java programmers can use the SensorAPI.jar file and the com.pyropath.air.webservice.APIClient library for injecting sensor messages. There is one exposed, static method: queueSensorReport(SensorReport s) which takes a single argument com.pyropath.air.entities.SensorReport and will return one of the above response codes. Other platform developers will need to implement their own http client methods for connecting to the service.

Example Sensor Codes:

#define O3_SENSOR_TYPE 0x30 //Ozone
#define SPL_AVG_TYPE 0x31 //SPL average
#define SPL_PEAK_TYPE 0x32 //SPL peak
#define TEMP_SENSOR_TYPE 0xF6 //Temperature
#define RH_SENSOR_TYPE 0xF8 //Relative Humidity
#define CO2_SENSOR_TYPE 0xB5 //Carbon Dioxide
#define NO2_SENSOR_TYPE 0x50 //Nitrogen Dioxide
#define CO_SENSOR_TYPE 0x40 //Carbon Monoxide
#define VOC_SENSOR_TYPE 0x60 //Volatile Organic Compounds
#define PM_SENSOR_TYPE 0xD9 //Particulate Matter (consolidated)

For a complete list of sensor codes and API methods, please review the documentation or contact us directly.

Implementation notes
  1. Please ensure your system is time-synchronized and uses an accurate time source (such as NTP). If there are no public NTP servers available to you, you may use time.aretas.ca as a synchronization source although it is a high stratum server (but should be fine for most use cases)
  2. For the time being, restrict MAC addresses to 32-bit length integers.
  3. It bears repeating that all query url parameters MUST be parseable back into their native formats. All sensor types are unsigned integers (byte length), timestamps are 32-bit longs (in MILLISECOND precision), actiontypes are unsigned integers and data is IEE float format.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.