Custom Templates

1 Templating Engine
2 Common Attributes
3 Distinct Attributes
- 3.1 Status Change
- 3.2 Heartbeat
- 3.3 User Registration

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 (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:

{
  "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

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

Message Type	Attribute	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

Custom Templates

Templating Engine

Common Attributes

Distinct Attributes

Status Change

Heartbeat

User Registration