Status | Date | Doc Version | Doc Number | Applicable | Confidentiality |
RELEASED | v3.0A | WP-RM-129 | Backend v3 | PUBLIC |
Version | Description |
1.6 | Initial version |
1.7 | Updated for WNT 1.7
|
2.0 | Updated for WNT 2.0
|
3.0 | Updated for WNT 3.0
|
Introduction
This document describes the Wirepas Network Tool (WNT) server backend API and is intended for Wirepas licensee to implement own services on top of the WNT server. Prerequisites include overall knowledge of Wirepas Mesh (WM) and WNT client. APIs are implemented on top of web sockets and HTTP connections using JSON and Protocol Buffers (version 2) data encoding.
This document is compliant with WNT backend version 3.0.
Backend interface components
Backend client interface consists of four individual components which all use secure versions of the protocols (WSS, HTTPS).
Figure 1 Simplified architecture
Table 1: Components
Component | Protocol | Port | Data encoding |
Authentication | Web socket | 8813 | JSON |
Metadata | Web socket | 8812 | JSON |
Real time situation | Web socket | 8811 | Protocol Buffers * |
Time series | HTTP | 8886 | JSON ** |
*Authentication is done by using JSON
**Queries are sent via HTTP GET
The MQTT connection between the gateway and WNT backend is described in document: WP-RM-128 - API between a Gateway and Wirepas Backends.
Authentication service
The service handles user management and access to metadata and real time situation service. The time series service shares the same credentials as the authentication service. Any credentials changes made through authentication service are propagated automatically to the time series service. Credentials can only be changed via authentication service. Other clients are notified about the users related changes (except password changes) via real time situation connection.
Metadata service
Metadata service provides access to:
- node metadata
- buildings
- floor plans
- areas
- network information
- downlink communication with the nodes
The clients are notified about the metadata changes via real time situation connection.
Real time situation service
The real time information of all the nodes and changes to metadata are available from the real time situation service. After the connection is established, and authentication has succeeded, the service will send all real time information via the connection. When the service receives new information from the nodes it forwards only the data that has changed to the client connections.
Time series service
Time series service contains diagnostics - and auxiliary data. It is implemented as direct access to the Influx database version 1.7. For more information please see Section “Time series service data”.
Protocol version
Authentication, metadata and real time situation (authentication) messages contain protocol version field. This field needs to match the correct protocol version supported by the WNT backend. At the moment the backend cannot handle messages of older protocol version.
Table 2: Protocol versions
Protocol version | Backend version |
2 | 1.6, 1.7 |
3 | 2.0 |
4 | 3.0 |
Authentication service messages
Authentication service works in request / response principle. User is automatically logged out when the connection is closed, and session id received via login message cannot be used later. Authenticated real time situation connection will work after the authentication service connection is closed. Access to methods depends on user's role.
Table 3: Roles
Role | Number |
Administrator | 1 |
Operator | 2 |
Simple rule between the roles is that operator can only query data, but administrator can also make changes.
All requests have common version field which denotes the protocol version and distinct type field per message type.
Table 4: Message types
Message | Type | Role |
Login | 1 | All |
Get users | 11 | Administrator |
Create user | 12 | Administrator |
Update user | 13 | Administrator |
Delete user | 14 | Administrator |
Due to possibility that the information about the change comes earlier from the real time situation connection than the response from the authentication service, some methods contain an originator_token field which can be used to check if the change was originated from the current client. The token can be e.g. UUID (version 1 / 4) as string.
Responses contains result field which contains information if any error occurred.
Table 5: Result codes
Message | Code |
Ok | 1 |
Generic error | 2 |
Invalid credentials while logging in | 3 |
Wrong protocol version | 4 |
User does not have rights to perform the action | 5 |
Invalid user id | 6 |
User which was tried to create already exists | 7 |
Received message was invalid | 8 |
Invalid session id | 9 |
User information fields have minimum and maximum lengths in characters.
Table 6: Minimum and maximum lengths
Field | Minimum | Maximum |
username | 1 | 63 |
password | 6 | 255 |
full_name | 1 | 255 |
Login
Login message is used to login to the services and it returns a session id that is used to authenticate to the metadata and real time situation services.
Table 7: Login message
Request | Response |
{ | { |
Get users
Message returns list of users and users' information.
Table 8:Get users message
Request | Example response |
{ | { |
Create user
New user can be created with create user message. Only a single user can be created with the message although users field is an array.
Updates are sent to clients via real time situation connection using metadata_update_message -> added_or_changed_users message.
Table 9: Create user message
Request | Response |
{ | { |
Update user
User can be updated with update user message. Only a single user can be updated with the message although users field is an array. In user data only username field is required.
Updates are sent to clients via real time situation connection using metadata_update_message -> added_or_changed_users message.
Table 10: Update user message
Request | Response |
{ | { |
Delete user
User can be deleted with delete user message. Only a single user can be deleted with the message although users field is an array.
Updates are sent to clients via real time situation connection using metadata_update_message -> deleted_users message.
Table 11: Delete user message
Request | Response |
{ | { |
Metadata service messages
Metadata service works in request / response principle. All the messages require session id, which can be get from authentication service.
All requests have a common version field which denotes the protocol version and distinct type field per message type.
Table 12: Message types
Message | Type | Role |
Get buildings | 1001 | All |
Create building | 1002 | Administrator |
Update building | 1003 | Administrator |
Delete building | 1004 | Administrator |
Get building's floor plans | 1011 | All |
Create floor plan | 1012 | Administrator |
Update floor plan | 1013 | Administrator |
Delete floor plan | 1014 | Administrator |
Get floor plan image data | 1021 | All |
Set floor plan image data | 1022 | Administrator |
Get map areas | 1031 | All |
Create map area | 1032 | Administrator |
Update map area | 1033 | Administrator |
Delete map area | 1034 | Administrator |
Get networks | 1041 | All |
Create network | 1042 | Administrator |
Update network | 1043 | Administrator |
Delete network | 1044 | Administrator |
Add node to floor plan | 1051 | Administrator |
Remove node from floor plan | 1052 | Administrator |
Set node metadata | 1061 | Administrator |
Change node id and / or network id * | 1062 | Administrator |
Delete node | 1063 | Administrator |
Set network data | 1071 | Administrator |
Send Remote API request * | 1072 | Administrator |
Send data message | 1073 | Administrator |
Get scratchpad status | 1074 | Administrator |
Load scratchpad * | 1075 | Administrator |
Get components information | 1081 | All |
*Message will be documented later
Due to possibility that the information about the change comes earlier from the real time situation connection than the response from the metadata service, some methods contain an originator_token field which can be used to check if the change was originated from the current client. The token can be e.g. UUID (version 1 / 4) as string.
Responses contains result field which contains information if any error occurred.
Table 13: Result codes
Message | Code |
Ok | 1 |
Generic error | 2 |
Wrong protocol version | 4 |
User does not have rights to perform the action | 5 |
Invalid id (building, floor plan, area etc.) | 6 |
Received message was invalid | 8 |
Invalid session id | 9 |
Get buildings
The message returns name and id of all the buildings.
Table 14: Get buildings message
Request | Example response |
{ | { |
Create building
New building can be created with create building message which returns building id that can be used later to reference the building. Only a single building can be created with the message although buildings field is an array.
Updates are sent to clients via real time situation connection using metadata_update_message -> added_or_changed_buildings message.
Table 15: Create building message
Request | Response |
{ | { |
Update building
Building name can be updated with update building message. Only a single building can be updated with the message although buildings field is an array.
Updates are sent to clients via real time situation connection using metadata_update_message -> added_or_changed_buildings message.
Table 16: Update building message
Request | Response |
{ | { |
Delete building
Building can be deleted with delete building message. Only a single building can be deleted with the message although buildings field is an array.
Updates are sent to clients via real time situation connection using metadata_update_message -> deleted_buildings message.
Table 17: Delete building message
Request | Response |
{ | { |
Get building's floor plans
The message returns information about the floor plans in a building. Only a single building's floor plans can be fetched with the message although buildings field is an array.
The rotation_matrix, offset_ecef_to_local, offset_local_to_ecef and pixels_per_meter fields are used for mapping between WGS84 and pixel coordinates. For more information please see Section “Coordinate conversions”.
Table 18: Get building's floor plans message
Request | Example response (only one floor plan) |
{ | { |
Create floor plan
New floor plan can be created with create floor plan message which returns floor plan id that can be used later to reference the floor plan. It is recommended to use the values defined below when creating a new floor plan. Only a single floor plan can be created to a single building with the message although buildings and floor_plans fields are arrays.
The rotation_matrix, offset_ecef_to_local, offset_local_to_ecef and pixels_per_meter fields are used for mapping between WGS84 and pixel coordinates. For more information please see Section “Coordinate conversions”.
Updates are sent to clients via real time situation connection using metadata_update_message -> added_or_changed_floor_plans message.
Table 19: Create floor plan message
Request | Response |
{ | { |
Update floor plan
Floor plan information can be updated with update floor plan message. Only a single floor plan in single building can be updated with the message although buildings and floor_plans fields are arrays. Request below shows how a floor plan image and thumbnail are bound to the floor plan.
The rotation_matrix, offset_ecef_to_local, offset_local_to_ecef and pixels_per_meter fields are used for mapping between WGS84 and pixel coordinates. For more information please see Section “Coordinate conversions”.
Updates are sent to clients via real time situation connection using metadata_update_message -> added_or_changed_floor_plans message.
Table 20: Update floor plan message
Example request | Response |
{ | { “data”: { |
Delete floor plan
Floor plan can be deleted with delete floor plan message. Only a single floor plan in single building can be deleted with the message although buildings and floor_plans fields are arrays.
Updates are sent to clients via real time situation connection metadata_update_message -> deleted_floor_plans message.
Table 21: Delete floor plan message
Request | Response |
{ | { |
Get floor plan image data
The method can be used to fetch floor plan image or thumbnail data. The image binary data is encoded using Base64 (RFC 3548) encoding.
Table 22: Get floor plan image data message
Request | Response |
{ | { |
Set floor plan image data
The method can be used to upload floor plan image or thumbnail data. The image binary data needs to be encoded using Base64 (RFC 3548) encoding. The method returns image id which can be used to reference the image later. Supported image formats are BMP, TIFF, JPEG, GIF, PNG and JPEG XR.
Table 23: Set floor plan image data message
Request | Response |
{ | { |
Get areas
The message returns areas for given floor plan id. Only a single floor plan's areas in a single building can be queried with the message although buildings and floor_plans fields are arrays. Area color values (alpha, red, green and blue) are integers between 0…255. llas is an array of area corner points' coordinates in WGS84 format and can contain 3…n items. altitude is in meters.
Table 24: Get areas message
Request | Response |
{ | { |
Create area
New area can be created with create area message which returns area id that can be used later to reference the area. Only a single area in a single floor plan and single building can be created with the message although buildings, floor_plans and areas fields are arrays. Area color values (alpha, red, green and blue) are integers between 0…255. llas is an array of area corner points' coordinates in WGS84 format and can contain 3…n items. altitude is in meters.
Updates are sent to clients via real time situation connection using metadata_update_message -> added_or_changed_areas message.
Table 25: Create area message
Request | Response |
{ | { |
Update area
Existing area can be updated with update area message. Area color values (alpha, red, green and blue) are integers between 0…255. llas is an array of area corner points' coordinates in WGS84 format and can contain 3…n items. altitude is in meters.
Updates are sent to clients via real time situation connection using metadata_update_message -> added_or_changed_areas message.
Table 26: Update area message
Request | Response |
{ | { |
Delete area
Area can be deleted with delete building message. Only a single area can be deleted with the message although buildings, floor_plans and areas fields are arrays.
Updates are sent to clients via real time situation connection using metadata_update_message -> deleted_areas message.
Table 27: Delete building message
Request | Response |
{ | { |
Get networks
The message returns network id and name mappings.
Table 28: Get networks message
Request | Example response |
{ | { |
Create network
The message is used to create a new network id to name mapping. Only a single network mapping can be created with the message although networks field is an array.
Updates are sent to clients via real time situation connection using metadata_update_message -> added_or_changed_networks message.
Table 29: Create network message
Request | Response |
{ | { |
Update network
Network name can be updated with update network message. Only a single network can be updated with the message although networks field is an array.
Updates are sent to clients via real time situation connection using metadata_update_message -> added_or_changed_networks message.
Table 30: Update network message
Request | Response |
{ | { |
Delete network
Network id to name mapping can be deleted with delete network message. Only a single network can be deleted with the message although networks field is an array.
Updates are sent to clients via real time situation connection using metadata_update_message -> deleted_networks message.
Table 31: Delete network message
Request | Response |
{ | { |
Add node to floor plan
Node can be bound to floor plan with add node to floor plan message. Only a single node can be added with the message although nodes field is an array. In order to see node in the floor plan the node needs to be approved with valid location information with set node metadata message.
Updates are sent to clients via real time situation connection using node_metadata message.
Table 32: Add node to floor plan message
Request | Response |
{ | { |
Remove node from floor plan
Node can be removed from floor plan with remove node from floor plan message. Only a single node can be removed with the message although nodes field is an array.
Updates are sent to clients via real time situation connection using node_metadata message.
Table 33: Remove node from floor plan message
Request | Response |
{ | { |
Set node metadata
The method is used set node related metadata. is_virtual denotes the planning node feature in WNT client [2].
Updates are sent to clients via real time situation connection using node_metadata message.
Table 34: Set node metadata message
Example request | Response |
{ | { |
Delete node
The method is used to delete node real time situation and metadata. Only a single node's data can be deleted with the message although nodes field is an array. Note that if node sends any data afterwards it will be shown again. Boolean type is_sink information is required to let the WNT backend to perform additional clean ups if needed.
Updates are sent to clients via real time situation connection using node_metadata message.
Table 35: Delete node message
Request | Response |
{ | { |
Set network data
The method can be used to set application configuration data and diagnostics interval [1]. Only a single network's data can be set with the message although networks field is an array.
is_override_on property is used to define will WNT server override the network data if it is changed from outside of WNT.
Updates are sent to clients per sink via real time situation connection using app_config message.
Table 36: Set network data message for the whole network
Example request | Response |
{ | { |
Table 37: Set network data message for the specific sinks
Example request | Response |
{ | { |
Send data message
The method can be used to send arbitrary data message to a node. The message requires that receiving node sink's node id is defined so the message sending does not create unneeded load to the network. Payload is hexadecimal encoded binary data. At the moment it is not possible to get confirmation that node received the message.
For more information about the fields please see DSAP-DATA_TX.request [1].
Table 38:Send data message
Example request | Response |
{ | { |
Get scratchpad status
The method can be used to query scratchpad status from the nodes in the network. Only a single network's data can be get with the message although networks field is an array. The query can be a single shot or continuous. Continuous query sending interval can be defined by setting rerun_interval_s property.
Table 39:Query types
Query | rerun_interval_s | is_close |
Single shot | 0 | false |
Start continuous | Interval | false |
Stop continuous | 0 | true |
Data is sent to clients per node via real time situation connection using scratchpad_status message.
Table 40: Get scratchpad status message
Example request | Response |
{ | { |
Get components information
The method can be used to query backend components' and gateways' information.
Responses are sent to clients via the real time situation connection using backend_component_info and gateway_info messages.
Please note that the backend component information is returned only from the metadata service, and originator_token is not yet returned via the real time situation connection.
Table 41: Get components information message
Example request | Response |
{ | { |
Real time situation service authentication
The service provides all nodes related data and changes to the metadata. Authentication is done in the start by sending the session id received from the authentication service.
Table 42: Authentication
Request | Response |
{ | { |
After a successful authentication the service starts to send Protocol Buffers encoded data and moves into write only mode. First message(s) will contain the node count per real time situation cluster cell. This information can be used to determine how much data needs to be received before the initial data is received. After this only the changed information is sent to client.
Table 43: Node count message
Path | Data |
Message -> rtsituation_metadata | cluster_no |
Note that all received Protocol Buffers messages has message "Message" as a root item (message.proto).
Time series service data
Time series data is provided by direct access to Influx database. The same credentials used to login to authentication service can be used also to access the database.
The "wirepas" database contains several measurements (Influx equivalent of database table).
Table 44: Database measurements
Measurement | Description |
analytics_next_hop | Hop count to sink |
analytics_nodestate | Node online information * |
analytics_packet | High level information about every received packet |
analytics_traveltime_kpi | Processed information about packets' travel times |
endpoint_247 | Node and boot diagnostics (WM FW >= 5.0) [4] ** |
endpoint_251 | Traffic diagnostics (WM FW < 5.0) [3] ** |
endpoint_252 | Neighbor diagnostics (WM FW < 5.0) [3] ** |
endpoint_253 | Node diagnostics (WM FW < 5.0) [3] ** |
endpoint_254 | Boot diagnostics (WM FW < 5.0) [3] ** |
location_measurement | Positioning measurements received from the nodes ** |
location_update | Computed positions for nodes ** |
remote_api_response | Remote API response information ** |
*Online state uses the values defined in OnlineStatus message (internal.proto).
** Column names use numbering from the WNT Protocol Buffers files.
Wirepas Backend-client [5] contains influx_viewer example which can be used to query information from the Influx with the decoded column names.
Example CURL command to query data
curl.exe -G https://someaddresswnt.extwirepas.com:8886/query --data-urlencode
"u=<username>" --data-urlencode "p=<password>" --data-urlencode "pretty=true" --data-
urlencode "db=wirepas" --data-urlencode "q=show measurements"
Example column names decoding
In the example the query used to query data is "q=select * from endpoint_252".
Table 45: Example response
Response from Influx |
{ |
For example to decode column Message_2, open main WNT Protocol Buffers file message.proto and look for message called Message. This message is used as base of all columns starting with Message_ and the number after the underscore is the field number of the corresponding message. In this case Message_2 can be decoded to network_id.
Table 46: Part of message.proto
message.proto |
message Message { |
Decoding Message_51_2 column name can be done the same way except that the number 51 is sub-message rx_time which is instance of RxData message. Following the previous rules the Message_51_2 can be decoded to be source endpoint of a data message packet.
Table 47: Part of message.proto
message.proto |
message Message {
message RxData { |
Basic data flow and real time situation data
Basic data flow to get continuous data
- Generate e.g. UUID (version 4) which is used as originator token for metadata changes.
- Connect to authentication service and send loginmessage.
- Authentication service sends back session id.
- Do not close the connection as the session id will become invalid.
- Query needed information from the metadata service and use the session idfor the authentication.
- If you need this non-node metadata in your application, you need to store the related information as the real time situation connection message's metadata_update_message will only contain the changed information.
- Connect to the real time situation service and authenticate with the session id.
- Real time situation service starts to push the initial real time data.
- Close the authentication service connection.
- Real time situation connection will still continue to work.
- Read the data from the real time situation.
- Get the initial node data
- Sum up the node counts from the real time situation services.
- When the distinct received node count is the same as the sum of the node counts, the initial real time situation is received.
- Sum up the node counts from the real time situation services.
- Get the changed node data
- From now on the real time situation component will only send changed information (aka delta) when compared to the previous node data.
- You need to keep the initial node state and then apply the changed fields incrementally.
- Messages will contain network_id and source_address fields to distinguish between the nodes.
- Any metadata change will be provided via the connection.
- You can use the originator_token to distinct the changes made by you.
- Get the initial node data
- When you wish to stop receiving the real time data please close the real time situation connection.
If you wish to do metadata changes after authentication service connection is closed, you need to connect and login again to the authentication service, and the service will provide a new session id.
Real time situation data
Real time situation component uses Protocol Buffers messages to send the data. All the incoming messages have a message called Message as a root item (please see message.proto).
Table 48: Important message fields
Field name | Description |
network_id | Network id of the node which sent the message. |
source_address | Node id of the node which sent the message. |
gateway_id | Id of the gateway which routed the message. |
tx_time | Time when the packet was generated by the node. |
rx_time | Time when the packet was received by the gateway. |
travel_time_ms | How long it took for gateway to receive the packet (rx_time – tx_time). |
diagnostics * | Diagnostics data that the node has generated. Contains also the node role and mode. |
rx_data * | Data message information (end points, qos etc.). |
app_config * | Application configuration data and diagnostics interval (sent only by the sinks). |
network_channel | Network channel (sent only by the sinks). |
security_enabled | Are cipher and encryption keys set for the network (sent only by the sinks). |
app_config_response * | Response for setting of the app config (sent only by the sinks). |
gateway_info * | Gateway information response data. |
scratchpad_status * | Scratchpad status response data. |
online_status * | Node online status determined by the backend. |
node_metadata * | Node metadata (location, name, description, positioning role etc.) |
rtsituation_metadata * | Information about real time situation manager (node count). |
metadata_update_message * | Non-node related metadata update information. |
* Sub-message
The backend processes all the incoming messages from the nodes every 30 seconds as a batch processing, so the incoming message via the real time situation connection can contain merged information from several messages of a node.
Coordinate conversions
Introduction
When a floor plan is added into WNT it is required to input the latitude/longitude/altitude (WGS84) of four reference points (A, B, C, D) and a scaling value.
The reference points are used to determine the rotation and translation of the floorplan to the corresponding position on the Earth.
Scaling is used to determine the relation between floor plan image pixels and the real world distance.
Starting from WNT version 2.0 the floorplan information retrieved from the WNT backend includes the rotation and translation information required to make the conversion from/to WGS84 coordinate to/from pixels.
The coordinate conversion assumes that the top-left floorplan image corner has the coordinate (0,0) pixels.
Given the floorplan information provided by the WNT API the following matrices/vectors are used:
- Rotation matrix (using rotation_matrix):
- Translation matrix (using offset_local_to_ecef ):
- Scaling:
WGS84 to pixels
To convert a WGS84 coordinate to pixels the following steps are required:
- Convert the WGS84 coordinate to ECEF (see Section “Coordinate conversions” for the conversion method)
- Given E the ECEF coordinate vector compute the pixel coordinates P as:
The matrix operations can be equivalently expressed as:
where:
Pixels to WGS84
To convert a pixel coordinate (px,py) to WGS84 the following steps are required:
- Compute the ECEF coordinate as:
where:
and R' denote the transpose matrix.
- Convert the ECEF coordinate to WGS84 as shown in Section “Coordinate conversions”.
WGS84 to ECEF conversion
Given a WGS84 coordinate as: φ latitude in radians, λ longitude in radians, η altitude in meters the ECEF coordinate E=xyz in meters is computed as:
where:
ECEF to WGS84 conversion
The conversion from ECEF to WGS84 is an iterative process.
Starting from an initial state computed as:
Iterate the following equations until Δφ<10- and Δh< 10-5:
where |∙| denotes the absolute value and e2 is the same as in Section “Coordinate conversions”.
Finally compute longitude as:
Note that the latitude and longitude values are in radians and the altitude in meters.
Example implementation
You can find an example implementation of the calculations in C from Wirepas Backend-APIs project [6].
References
[1] Wirepas Connectivity Dual-MCU API Reference Manual
[2] Wirepas Network Tool - Client User Guide
[3] Wirepas Mesh Diagnostics Reference Manual
[4] Wirepas Mesh Diagnostics v2 Reference Manual
[5] Backend client
Revision History
Date | Version | Notes |
v3.0A | ||
Legal Notice
Use of this document is strictly subject to Wirepas’ Terms of Use and Legal Notice.
Copyright © 2021 Wirepas Oy