Wirepas protocol

Wirepas protocol connects Wirepas mesh network gateways to flespi over MQTT using the standard gateway-to-backend API published by Wirepas, in its protobuf encoding on the gw-event and gw-response topics or in the JSON encoding of Teltonika Gateway Wi-Fi on the json-gw-event and json-gw-response topics. Any vendor's gateway implementing this API can stream mesh data to flespi without vendor lock-in. flespi decodes received packet events and Wirepas positioning application payloads, registering separate messages for mesh tags and anchors with RSSI measurement arrays for indoor positioning, battery voltage, and mesh diagnostics such as hop count and travel time.

To connect a Teltonika Gateway Wi-Fi, create a wirepas channel and use its URI and port in the device's Config->MQTT set up. Both JSON and Protobuf data encodings are supported: the encoding is recognised from the topics the gateway publishes on, and commands and settings are sent back in the same encoding.

Messages are registered per mesh node, not per gateway: each node's message uses its Wirepas network address as the ident and carries the relaying gateway's identifier in the gateway.id parameter and its sink in sink.id, while every anchor that saw the node additionally receives its own message with the observed asset and RSSI in the tags array. Nodes are automatically classified as tags or anchors by the type of RSSI measurement they report, and message timestamps come from the event generation time reported by the gateway. Every node message names the Wirepas endpoint it was received on in message.type.enum and its family in message.type: positioning, status or sensors.

There are 4 device types available for the protocol:

Wirepas Mesh Gateway device type is identified by the gateway serial number (e.g. BTGW-00000000deadbeef). It stores the gateway status events and the gateway answers to requests, with event.payload holding the copy of the JSON object received as MQTT payload from a JSON gateway and payload.hex the raw bytes received from a protobuf gateway. The commands and the settings of the protocol are sent to the gateway device: tag reporting periods and tag led are written into the application configuration of the sink, the diagnostics interval of the mesh is a setting, and the OTAP commands upload a firmware scratchpad to the sink and control its rollout.

Wirepas Mesh Tag device type is the virtual representation of the moving tag, it is identified by the 10 digit Wirepas network address (e.g. 1234567890) and stores the array parameter "anchors" that looks like [{"id":"1234567","rssi":-104},{"id":"7654321","rssi":-73}] that displays the list of anchors seen by the tag and the signal strength to it. Tag data is transmitted to the gateway over the anchor's mesh network, thus the tag also has parameters the signal.hop.count (number of the nodes in the Mesh network used to transfer the signal to the gateway) and signal.travel.time, together with the standard parameters like message.seqnum and battery.voltage. The positioning report also carries device.static.status, true while the tag runs its static reporting period, and the sensors report of a Teltonika EYE Sensor Mesh tag adds temperature, humidity, movement, magnet and other sensor values.

Wirepas Mesh Anchor device type is used to track the anchor devices to effectively answer the question "which tags were seen by the specific anchor device". It is identified by the 7-digit Wirepas network address (e.g. 1234567) and it stores the array parameter "tags" that looks like [{"id":"1234567890","rssi":-104}].

ELA Wirepas Mesh Tag device type is for the tags of ELA Innovation. Their 11/11 endpoint carries the battery voltage in the same 4 byte frame a Teltonika EYE tag uses for its sensors, so an ELA node must be registered with this device type to be decoded correctly; everything else, including its role and its sensor endpoints 100 to 200, is recognised automatically.