Custom Templates
Custom Templates are possible for Direct Message Types. You can read more about message types and standard templates here. If you need more data than provides a standard template, you are able to create your own template. For doing this you need to use a special Templating Language, which is being processed by Templating Engine.
Templating Engine
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 attribute values;
operations over the source data attribute values.
For retrieving a value of any attribute from source data you need to use the source data attribute 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 (xy);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:
{
"timestamp": "{iso8601(message_time)}",
"space_network_address": "{network_id}",
"new_status": "{"occupied" if parsed["occupation_status"] is True else "free"}"
}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.
Common Attributes
The following attributes are available for all message types:
String attributes should be wrapped in quotes.
Attribute | Template Usage | Type | Description |
|---|---|---|---|
message_trace_id | "{message_trace_id}" | str | message trace id UUID format |
message_time | "{message_time}" | str | time of receiving a message from a base station |
received_time | str | time of receiving a message by the Nwave cloud | |
device_id | str | device ID in hex format | |
device_id_dec | int | device ID in decimal format | |
signal | float | message signal level | |
data | str | raw message payload in hex format | |
station_id | int | ID of a station that got the message | |
custom_id | str | bound position custom ID or '?' if a custom ID was not set | |
latitude | float | latitude parameter of a position | |
longitude | float | longitude parameter of a position | |
floor_number | int | position's floor number | |
network_id | str | network ID of a position | |
zone_id | int | decimal zone ID of a position | |
group_id | int | decimal group ID of a position | |
group_name | str | group name which a position belongs to | |
group_inner_id | int | inner ID of a position in a group |
Distinct Attributes
Attributes that are different for each message type are accessible under the parsed key.
Message Type | Attribute | Template Usage | Type | Description |
|---|---|---|---|---|
Status Change | voltage_V | float | device’s battery voltage | |
parking_session_iterator | int | a number which is incremented after every occupancy Not available for LoRa sensors | ||
occupation_status | boolean | “true” if a sensor is occupied, otherwise - “false” | ||
previous_occupancy_status_duration_min | int | duration of a sensor previous state, this field can help if the previous message was not received by any station | ||
Heartbeat | voltage_V | float | device’s battery voltage | |
parking_session_iterator | int | a number which is incremented after every occupancy Not available for LoRa sensors | ||
occupation_status | boolean | “true” if a sensor is occupied, otherwise - “false” | ||
heartbeat_message_counter | int | number of heartbeat messages sent during an unchanged occupancy state | ||
User Registration | voltage_V | float | device’s battery voltage | |
parking_session_iterator | int | a number which is incremented after every occupancy Not available for LoRa sensors | ||
occupation_status | boolean | “true” if a sensor is occupied, otherwise - “false” | ||
user_ID | str | an ID of Bluetooth tag which was used for authorization |