HTTP Templates

HTTP Template is a rule of building an outgoing HTTP request. A template specified a rule of building request method, URL, HTTP headers, and request body. A template is applied to an incoming message from devices, which has been parsed and enriched by information about the device. For the convenient building of templates, Nwave created a special template language which will be explained further in this document.

HTTP template may be applied to all messages coming from a device or only to one type of message. Nwave supports the following messages types:

• All - apply a template to all types of messages;

• Status Change - status change message is sent from a sensor when its value has been changed (occupancy state for parking sensor or number of detected cars for car counters);

• Heartbeat - heartbeat message is sent after every constant time period of unchanging sensor state;

• Calibration - this type of message is sent after a sensor calibration performed using Nwave mobile apps;

• User Registration - user registration message is sent when a user is authorized on the sensor using a Bluetooth-tag;

• Error - this type of message is sent only by car counters when some hardware, software or environment problem has been detected by a sensor;

• General - general type is used for data coming from devices flashed by custom firmware.

HTTP request source data

HTTP request service builds requests based on a user-defined template and incoming data which contains the following fields:

• message_trace_id - a message trace id;

• message_time - a time of receiving a message from a base station;

• received_time - a time of receiving a message by the Nwave cloud;

• device_id - a device ID in hex format;

• device_id_dec - a device ID in decimal format;

• signal - a message signal level;

• data - a raw message payload in hex format;

• station_id - an ID of a station that got the message;

• custom_id - a bound position custom ID or '?' if a custom ID was not set;

• latitude - a latitude parameter of a position;

• longitude - a longitude parameter of a position;

• level - position's level (e.g. ground, 1st);

• network_id - a network ID of a position;

• zone_id - a decimal zone ID of a position;

• group_id - a decimal group ID of a position;

• group_name - a group name which a position belongs to;

• group_inner_id - an inner ID of a position in a group;

• parsed - a parsed message. It contains different data, depending on device type, firmware type, and message type.

Parking sensor parsed message objects

Status Change

• voltage_V - device’s battery voltage;

• parking_session_iterator - a number which is incremented after every occupancy;

• occupation_status - “true” if a sensor is occupied, otherwise - “false”;

• previous_occupancy_status_duration_min - duration of a sensor previous state, this field can help if the previous message was not received by any station.

Heartbeat

• voltage_V - device’s battery voltage;

• parking_session_iterator - a number which is incremented after every occupancy;

• occupation_status - “true” if a sensor is occupied, otherwise - “false”;

• heartbeat_message_counter - number of heartbeat messages sent during an unchanged occupancy state.

Calibration

• voltage_V - device’s battery voltage;

• hardware_reset - “true” if a message caused by a device’s periodical self-reset;

• noisy_environment - “true” if an environment is too noisy for the calibration process

User Registration

• voltage_V - device’s battery voltage;

• parking_session_iterator - a number which is incremented after every occupancy;

• occupation_status - “true” if a sensor is occupied, otherwise - “false”;

• user_ID - an ID of Bluetooth tag which was used for authorization.

Car Counter parsed message object

Status Change

• voltage_V - device’s battery voltage;

• car_counter - number of detected cars.

Error

• voltage_V - device’s battery voltage;

• first_calibration - “true” if a message is caused by calibration via mobile app;

• magnetometer_calibration_error - an error while magnetometer calibration or self-calibration;

• magnetometer_calibration_timeout - “true” if hardware error occured;

• reading_error - “true” if there are some problems with onboard sensor's data reading;

• sensor_power_supply_too_low - “true” if battery level is too low;

• hardware_reset - “true” if a message caused by a device periodical self-reset.

HTTP template language

The HTTP template language is a language of transforming data based on the python 3 language syntax.

There are two main functions of a template language:

• getting the source data field values;

• operations over the source data field values.

For retrieving a value of any field from source data you need to use source data field name surrounded by braces. This rule works for all fields except for parsed data fields. For retrieving any value from parsed data you need to use the following format: {parsed['<field name>']}.

Examples:

• {modem_id} - gets device ID hex;

• {data} - gets full raw message;

• {message_time} - gets a UNIX timestamp;

• {parsed['voltage_V']} - gets battery voltage information.

More complex example:

This URL template creates a URL that contains a position’s network ID and occupancy status:

http://example.com/parking?id={network_id}&occupied={parsed['occupation_status']}

Nwave supports some operations over the source data values if pure values are not usable or can be converted to a more convenient format.

Operations:

• IF-THEN-ELSE operator in Python style {<result if true> if <condition> else <result if false>};

• pow(a, b) - returns a value of x to the power of y (x^y);

• str(obj) - stringifies an object;

• hex(int) - returns a hexadecimal representation of an integer value;

• int(str, base) - returns an integer representation of a string;

• len(str) - returns the length of a string argument;

• iso8601(ts) - returns ISO8601 representation of a timestamp;

• <obj>[index] - accesses string characters by index;

• obj[a:b:c] - slice operator which works the same as the Pyhton language;

• +, I, *, /, *, //, **, % - standard Python language operators.

Example:

This body example returns JSON which contains a position network id, occupation status in the format “occupied”/”free” and message receiving timestamp in ISO8601 format:

Using the template functionality, you can even create custom formatting request, where the format is changed depends on source data values. The following snippet shows how to create an empty request if a raw message is too short, but if the data is too long, the template will add a message payload tail as a query argument:

http://example.com{(('?tail=%s' % data[6:]) if (len(data) >= 6) else '')}

You can use templates in URLs and request bodies.

For more examples, you can read Standard Templates and other standard protocols.

HTTP Template suites

HTTP template suites are used for uniting HTTP templates, which are applied to different (or the same) message types. Also, HTTP Template Suites are data routing entities. You can configure data routing from a device’s zone or a group only to an HTTP Template Suite, but not to an individual HTTP Template.