Home › WP-RM-117 – Wirepas Mesh Remote API Reference Manual

WP-RM-117 – Wirepas Mesh Remote API Reference Manual

File info: application/pdf · 24 pages · 495.25KB

Familiarity with document WP-RM-100 – Wirepas Mesh. Dual-MCU API Reference Manual [1] is required to understand the concepts in this document. 2.

Full PDF Document

If the inline viewer fails, it will open the original document in compatibility mode automatically. You can also open the file directly.

Extracted Text

WP-RM-117 � Wirepas Mesh Remote API Reference Manual
Reference Manual
Version: v5.0A Applies to Wirepas Mesh firmware release v5.0 onwards
This document describes the Remote API provided by the Wirepas Mesh stack.
Confidential

WP-RM-117 � Wirepas Mesh Remote API Reference Manual - v5.0A

Table of Contents
1. Introduction........................................................................................................................ 4
2. Operation............................................................................................................................ 4 2.1. Request Packets and Responses ................................................................................ 4 2.2. Packet Structure .......................................................................................................... 4 2.3. Writing MSAP and CSAP Attributes ............................................................................. 5 2.4. Reading MSAP and CSAP Attributes ........................................................................... 6
3. Requests and Responses.................................................................................................. 6 3.1. Ping............................................................................................................................. 7 3.2. Begin ........................................................................................................................... 8 3.3. Begin with Lock ........................................................................................................... 8 3.4. End.............................................................................................................................. 9 3.5. Cancel ......................................................................................................................... 9 3.6. Update....................................................................................................................... 10 3.7. Write MSAP Attribute ................................................................................................. 10 3.8. Read MSAP Attribute................................................................................................. 11 3.9. Write CSAP Attribute ................................................................................................. 11 3.10. Read CSAP Attribute ................................................................................................. 13 3.11. MSAP Scratchpad Status........................................................................................... 13 3.12. MSAP Scratchpad Update ......................................................................................... 16 3.13. MSAP Max Queue Time Write ................................................................................... 17 3.14. MSAP Max Queue Time Read ................................................................................... 17 3.15. MSAP Enable Joining Beacon ................................................................................... 17 3.16. MSAP Disable Joining Beacon................................................................................... 18 3.17. MSAP Joining Beacon Status .................................................................................... 19 3.18. Error: Access Denied ................................................................................................. 19 3.19. Error: Write-only Attribute........................................................................................... 19 3.20. Error: Invalid Broadcast Request................................................................................ 20

� Wirepas Ltd. 2020

www.wirepas.com

Confidential

WP-RM-117 � Wirepas Mesh Remote API Reference Manual - v5.0A
3.21. Error: Invalid Begin .................................................................................................... 20 3.22. Error: No Space for Response ................................................................................... 20 3.23. Error: Invalid Value .................................................................................................... 20 3.24. Error: Invalid Length .................................................................................................. 21 3.25. Error: Unknown Request............................................................................................ 21 4. Example Remote API Request and Response Packets .................................................. 21 5. References ....................................................................................................................... 24

� Wirepas Ltd. 2020

www.wirepas.com

Confidential

WP-RM-117 � Wirepas Mesh Remote API Reference Manual - v5.0A

1. Introduction
Wirepas Mesh stack v3.1 onwards provides a way to configure and reconfigure nodes remotely, over the Wirepas Mesh network. Parameters such as node address, network address and node role can be set or queried. This feature is called the Remote API.
The Remote API refers to node parameters in the same way the Wirepas Mesh Dual-MCU API does. Parameters are called attributes and are separated into MSAP (Management Services) and CSAP (Configuration Services). Familiarity with document WP-RM-100 � Wirepas Mesh Dual-MCU API Reference Manual [1] is required to understand the concepts in this document.

2. Operation
The Wirepas Mesh Remote API requests and responses are sent as regular data packets in the Wirepas Mesh network. One or more requests can be combined into a Remote API request packet.
Using the sink node, a request packet is sent to target nodes and the target nodes then send a response packet back to the sink. Only sinks can send Remote API requests via the dual-MCU API. A single-MCU application must make sure it only sends Remote API requests from a sink node.

2.1. Request Packets and Responses
Requests are sent from a sink to a target node as regular data packets. Multiple nodes can be addressed at the same time by using the broadcast address as the destination (however, see section 3.9 for an exception). The Wirepas Mesh stack uses certain reserved source and destination endpoints for identifying Remote API request packets, see Table 1.

Table 1: Reserved Endpoints for Wirepas Mesh Remote API

Request Packet Response Packet

Source Endpoint 255 (0xFF in hexadecimal) 240 (0xF0 in hexadecimal)

Destination Endpoint 240 (0xF0 in hexadecimal) 255 (0xFF in hexadecimal)

When a node receives a request packet that has the correct source and destination endpoints, it processes the requests in the packet and forms a response packet. The response packet is sent to the AnySink address. Response packets have the same reserved endpoints that the request packets have, except in reverse.
Remote API request packets can be sent with either normal or high priority Quality of Service (QoS) class. The response packet uses the same QoS class as the request packet.

2.2. Packet Structure
Each Remote API request packet may contain one or more requests. The requests use a TypeLength-Value format, outlined in Figure 1.

Octet 0 Type

Octet 1 Length

Octets 2 .. n Value

Figure 1: Structure of a Request

� Wirepas Ltd. 2020

www.wirepas.com

Confidential

WP-RM-117 � Wirepas Mesh Remote API Reference Manual - v5.0A

The Type octet identifies the request. It is followed by a Length octet, which indicates how many octets the value occupies. If the Length is non-zero, a number of Value octets follow. Not all requests have values associated with them. In that case, the Length octet is zero and the complete request is only two octets long, i.e. just the Type and Length octets.
Multiple requests can simply be concatenated together, up to the maximum size of a data packet. The maximum size of a data packet depends on firmware version and enabled features. It can be queried by reading CSAP attribute 5: cMTU. See [1] for details.
When a node processes a request packet, it constructs a response packet containing responses for each processed request in the request packet. Responses use the same TypeLength-Value format as requests.
In case of an error, processing stops at the first invalid request. An error response is added to the response packet and rest of the requests in the request packet are ignored.
The type octet is also used to differentiate a request from a response, see Table 2.

Type (Decimal) 0 .. 123 124 .. 127 128 .. 251 252 .. 255

Table 2: Request and Response Types

Type (Hexadecimal) 0x00 .. 0x7B 0x7C .. 0x7F 0x80 .. 0xFB 0xFC .. 0xFF

Purpose Request Reserved for future use Response Error response

Values may occupy more than one octet. Any such values are stored in little endian order, i.e. the least significant octet first.

2.3. Writing MSAP and CSAP Attributes
An overview of the states of configuring one or more MSAP and CSAP attributes is shown in Figure 2.

Start

No reset required

Cancel request

Waiting for
Begin

Cancel request

Countdown

Update

Countdown elapsed
Update request
(time > 0)

Perform update

Begin request
(when no Feature Lock Key set)
Begin with Key request

Cancel request

request
(time > 0)

Update request
(time == 0)

Reset required

(when Feature Lock Key set)

Write MSAP Attribute request
Write CSAP Attribute request

Writing

End request
Begin request
(when no Feature Lock Key set)

Waiting for
Update

Begin with Key request
(when Feature Lock Key set)

Update request
(time == 0)

Reset node

Figure 2: States of Configuring MSAP and CSAP Attributes

� Wirepas Ltd. 2020

www.wirepas.com

Confidential

WP-RM-117 � Wirepas Mesh Remote API Reference Manual - v5.0A
Requests to write to MSAP and CSAP attributes (sections 3.7 and 3.9) do not modify the values of the attributes directly. Instead, the values are written in a temporary buffer which can then be taken in to use with an Update request (see section 3.6) later. Alternatively, a Cancel request (see section 3.5) can be used to discard any buffered values. An Update request is typically sent afterwards in its own packet. The Update request has a countdown timer, so that the update can be triggered with a delay. This is to make sure that, on large networks, even the most remote nodes will have received the Update request before nodes in between have changed their parameters. Writing attributes happens between Begin and End requests (sections 3.2, 3.3 and 3.4). It is not mandatory to have the Begin and End appear on the same request packet, but it is recommended. Otherwise, packets that appear out-of-order may confuse the Remote API request processing. In order to support keeping features securely locked, the Remote API handles feature lock key access differently than the dual-MCU API. See [1] for description of CSAP attributes cFeatureLockBits and cFeatureLockKey. A separate Begin with Lock request (see section 3.3) allows writing to MSAP and CSAP attributes without having to explicitly unlock the feature lock first. Between the Begin with Lock request and End request, requests to write MSAP and CSAP attributes succeed (provided that the key was correct in the Begin with Lock request), even if feature lock bits would otherwise prevent writing of MSAP or CSAP attributes. Begin with Lock request only affects Remote API. It does not let the Dual-MCU API write attributes (if the feature lock bits and key are set to prevent it), for example. More so than with normal Begin request, it is suggested that the Begin with Lock, Write and End requests are all packed in one request packet, so that the feature lock bits do not remain open across request packets. This prevents any packets without a key from modifying MSAP and CSAP attributes.
2.4. Reading MSAP and CSAP Attributes
Reading MSAP and CSAP attributes can happen at any time. The read requests (sections 3.8 and 3.10) do not have to be between Begin and End requests. This implies, that reading MSAP or CSAP attributes is not possible if the feature lock bits and key have been set to prevent reading those attributes.
3. Requests and Responses
Remote API requests are listed in Table 3 and explained in detail below.

� Wirepas Ltd. 2020

www.wirepas.com

Confidential

WP-RM-117 � Wirepas Mesh Remote API Reference Manual - v5.0A

Request (Hexadecimal) 0x00 0x01 0x02 0x03 0x04 0x05 0x0B 0x0C 0x0D 0x0E 0x19 0x1A 0x4F 0x50 0x61 0x62 0x63

Table 3: Request and Response Types

Response (Hexadecimal) 0x80 0x81 0x82 0x83 0x84 0x85 0x8B 0x8C 0x8D 0x8E 0x99 0x9A 0xCF 0xD0 0xE1 0xE2 0xE3

Description Ping Begin Begin with Lock End Cancel Update Write MSAP Attribute Read MSAP Attribute Write CSAP Attribute Read CSAP Attribute MSAP Scratchpad Status MSAP Scratchpad Update MSAP Max Queue Time Write MSAP Max Queue Time Read MSAP Enable Joining Beacon MSAP Disable Joining Beacon MSAP Joining Beacon Status

In case there is an error carrying out a request, an error response is added to the response packet and no further requests from the request packet are processed.
Error responses are listed in Table 4 and explained in detail below.

Table 4: Error Responses

Response (Hexadecimal) 0xF8 0xF9 0xFA 0xFB 0xFC 0xFD 0xFE 0xFF

Description Access Denied Write-only Attribute Invalid Broadcast Request Invalid Begin No Space for Response Invalid Value Invalid Length Unknown Request

3.1. Ping
The Ping request does nothing, except causes a response to be returned. This can be used to determine if a node is running Wirepas Mesh stack that supports Remote API. Remote API was introduced in firmware version 3.1.
Starting from firmware version 3.4, there can be an optional payload of up to 16 octets, which is returned unmodified in the response. By using a unique identifier as the payload, responses can be matched with requests, e.g. when sending multiple requests in rapid succession. The Ping request can also be used to do simple latency testing, e.g. by placing a timestamp in the payload and comparing it to the time a corresponding Ping response is received.
The Ping request can be issued at any time. Format of the Ping request is shown in Figure 3 and the response in Figure 4.

� Wirepas Ltd. 2020

www.wirepas.com

Confidential

WP-RM-117 � Wirepas Mesh Remote API Reference Manual - v5.0A

Octet 0 Type: 0x00
Octet 0 Type: 0x80

Octet 1 Length

Octets 2 .. 17 Payload
Figure 3: Ping Request

Octet 1 Length

Octets 2 .. 17 Payload
Figure 4: Ping Response

3.2. Begin
Configuring MSAP and CSAP attributes is only possible between a Begin request (or Begin with Lock request, section 3.3) and End request (section 3.4). The Begin request allocates a temporary buffer for storing values, which can then be written using the Write MSAP Attribute (section 3.7) and Write CSAP Attribute (section 3.9) requests.
Format of the Begin request is shown in Figure 5 and the response in Figure 6.

Octet 0

Octet 1

Type: 0x01 Length: 0x00

Figure 5: Begin Request

Octet 0

Octet 1

Type: 0x81 Length: 0x00

Figure 6: Begin Response

Whether to use a Begin or Begin with Lock request depends on the feature lock key. If a key is set, only a Begin with Lock request is accepted. If no key is set, only the Begin request can be used. See the description of CSAP attribute cFeatureLockKey in [1].
If a feature lock key is set, the Begin request is rejected with an Access Denied error response (section 0). If an update countdown is running, the request is rejected with an Invalid Begin error response (section 3.21). If there is not enough memory for a temporary buffer, an Invalid Value error response is returned (section 3.23).
It is possible to issue multiple Begin requests before an End request. Any extraneous requests before the first are simply ignored.

3.3. Begin with Lock
The Begin with Lock request is identical to the Begin request (section 3.2), except that it allows temporarily bypassing the feature lock. If a feature lock key is set, only the Begin with Key request is accepted and the Begin request is not. Likewise, only the Begin request can be used if no feature lock key is set. See the description of CSAP attribute cFeatureLockKey in [1].
Format of the Begin with Key request is shown in Figure 7 and the response in Figure 8.

Octet 0 Type: 0x02

Octet 1 Length: 0x10

Octets 2 .. 17 Feature Lock Key

Figure 7: Begin with Lock Request

� Wirepas Ltd. 2020

www.wirepas.com

Confidential

WP-RM-117 � Wirepas Mesh Remote API Reference Manual - v5.0A

Octet 0

Octet 1

Type: 0x82 Length: 0x00

Figure 8: Begin with Lock Response

The Begin with Key request only affects the Write MSAP Attribute (section 3.7) and Write CSAP Attribute (section 3.9) requests, and only until the next End request (section 3.4). Furthermore, Begin with Lock only affects the Remote API, and does not affect the lock state of Dual-MCU API, for example. For longer-term unlocking of the feature lock, use the Write CSAP Request to set the CSAP attribute cFeatureLockKey to FF FF .. FF (hexadecimal), i.e. all bits set. See section 4 for an example.
If the given key is incorrect, or if no feature lock key is set, the Begin with Key request is rejected with an Access Denied error (section 0). If an update countdown is running, the request is rejected with an Invalid Begin error (section 3.21). If there is not enough memory for a temporary buffer, an Invalid Value error response is returned (section 3.23).
It is possible to issue multiple Begin with Key requests before an End request. Any extraneous requests before the first are simply ignored.

3.4. End
After configuring MSAP or CSAP attributes, and End request must be issued. Format of the End request is shown in Figure 9 and the response in Figure 10.

Octet 0

Octet 1

Type: 0x03 Length: 0x00

Figure 9: End Request

Octet 0

Octet 1

Type: 0x83 Length: 0x00

Figure 10: End Response

If no valid Begin request has been issued, an Invalid Begin error response is returned (section 3.21).
It is possible to issue multiple Begin / End request sets before sending an Update request (section 3.6). This way, configuring of attributes can be distributed across many request packets without having to leave the feature lock temporarily open (see the description of Begin with Lock request, section 3.3).

3.5. Cancel
A Cancel request discards all CSAP and MSAP attribute values stored in a temporary buffer and cancels a running update countdown. Cancel requests can be issued at any time. It never returns an error response.
Format of the Cancel request is shown in Figure 11 and the response in Figure 12.

Octet 0

Octet 1

Type: 0x04 Length: 0x00

Figure 11: Cancel Request

� Wirepas Ltd. 2020

www.wirepas.com

Confidential

WP-RM-117 � Wirepas Mesh Remote API Reference Manual - v5.0A

Octet 0

Octet 1

Type: 0x84 Length: 0x00

Figure 12: Cancel Response

3.6. Update
An Update request starts a countdown, after which the MSAP and CSAP attributes are written from a temporary buffer to the actual attributes. The node is then reset, if any of the written attributes require a reboot. See Table 6 and Table 7 for a list of attributes that require a reboot.
Format of the Update request is shown in Figure 13 and the response in Figure 14.

Octet 0 Type: 0x05

Octet 1 Length

Octet 2 Time LSB

Figure 13: Update Request

Octet 3 Time MSB

Octet 0 Type: 0x85

Octet 1 Length: 0x02

Octet 2 Time LSB

Figure 14: Update Response

Octet 3 Time MSB

The countdown time value range is described in Table 5. A special value of 0 is also accepted. It cancels a running countdown. If the countdown time is omitted completely, the current countdown time is reported, or zero if no countdown is running.
Due to the way nodes scan for neighbors right after reboot, it is better for the nodes not to reboot at the same time. To facilitate that, a random delay between 0 and 20 seconds is added to the countdown value. The resulting countdown value is placed in the response.

Table 5: Countdown Time Values

Minimum Value 10 (10 seconds)

Maximum Value 32767 (9 hours, 6 minutes)

If no Begin and End requests were issued, an Invalid Begin error response is returned (section 3.21). If the countdown time is not valid, an Invalid Value error response is returned (section 3.23). If the feature lock key was changed (e.g. via Dual-MCU API) after the Begin with Lock request (section 3.3) was issued, an Access Denied error response is returned (section 0).

3.7. Write MSAP Attribute
The Write MSAP Attribute request allows configuring MSAP attributes. The supported attributes are listed in Table 6. Currently only one MSAP attribute is supported.
When an Update request (section 3.6) is issued and after the countdown time has elapsed, the node is rebooted if any of the attributes that require a reboot is being configured. The sole supported MSAP attribute does not require a reboot.
The Write MSAP Attribute is allowed only after a Begin (section 3.2) or Begin with Lock request (section 3.3) and before an End request (section 3.4). Format of the Write MSAP Attribute request is shown in Figure 15 and the response in Figure 16.

� Wirepas Ltd. 2020

www.wirepas.com

Confidential

WP-RM-117 � Wirepas Mesh Remote API Reference Manual - v5.0A

Octet 0 Type: 0x0B

Octet 1 Length

Octet 2

Octet 3

Attr ID LSB Attr ID MSB

Figure 15: Write MSAP Attribute Request

Octet 0 Type: 0x8B

Octet 1 Length

Octet 2

Octet 3

Attr ID LSB Attr ID MSB

Figure 16: Write MSAP Attribute Response

Attribute ID 9

Table 6: Supported MSAP Attributes

Attribute Name mAccessCycleRange

Value Length (Octets) 4

Octets 4 .. n Value
Octets 4 .. n Value
Reboot Required? No

If no valid Begin request has been issued, an Invalid Begin error response is returned (section 3.21). If the number of octets in the value is incorrect, an Invalid Length error response is returned (section 3.24). In case of a faulty value, an Invalid Value error response is returned (section 3.23). If the attribute ID is not recognized, an Unknown Request error response is returned (section 3.25).

3.8. Read MSAP Attribute
Reading MSAP attributes is done using the Read MSAP Attribute request. The same attribute is supported as with the Write MSAP Attribute request, listed in Table 6.
The Read MSAP Attribute request can be issued at any time. It does not need to be between Begin and End requests. The value returned is the current value of the attribute. There is no way to read the value in the temporary buffer, which is set using the Write MSAP Attribute request (section 3.7).
Format of the Read MSAP Attribute request is shown in Figure 17 and the response in Figure 18.

Octet 0

Octet 1

Octet 2

Octet 3

Type: 0x0C Length: 0x02 Attr ID LSB Attr ID MSB

Figure 17: Read MSAP Attribute Request

Octet 0 Type: 0x8C

Octet 1 Length

Octet 2

Octet 3

Attr ID LSB Attr ID MSB

Figure 18: Read MSAP Attribute Response

Octets 4 .. n Value

If the attribute ID is not recognized, an Unknown Request error response is returned (section 3.25). If feature lock bits prevent reading MSAP attributes, an Access Denied error response is returned (section 0). If a value is not set for an attribute, an Invalid Value error response is returned (section 3.23).

3.9. Write CSAP Attribute
The Write CSAP Attribute request is used for configuring CSAP attributes. The supported attributes are listed in Table 7.

� Wirepas Ltd. 2020

www.wirepas.com

Confidential

WP-RM-117 � Wirepas Mesh Remote API Reference Manual - v5.0A

When an Update request (section 3.6) is issued and after the countdown time has elapsed, the node is rebooted if any of the attributes that require a reboot is being configured. Configuring most CSAP attributes require a reboot.
The Write CSAP Attribute is allowed only after a Begin (section 3.2) or Begin with Lock request (section 3.3) and before an End request (section 3.4). Format of the Write CSAP Attribute request is shown in Figure 19 and the response in Figure 20.

Octet 0 Type: 0x0D

Octet 1 Length

Octet 2

Octet 3

Attr ID LSB Attr ID MSB

Figure 19: Write CSAP Attribute Request

Octets 4 .. n Value

Octet 0 Type: 0x8D

Octet 1 Length

Octet 2

Octet 3

Attr ID LSB Attr ID MSB

Figure 20: Write CSAP Attribute Response

Octets 4 .. n Value

Attribute ID 1 2 3 4 13 14 20 21 22 23

Table 7: Supported CSAP Attributes

Attribute Name cNodeAddress (see Note 1) cNetworkAddress cNetworkChannel cNodeRole (see Note 2) cCipherKey (see Note 3) cAuthenticationKey (see Note 3) cOfflineScan cChannelAllocMap cFeatureLockBits cFeatureLockKey (see Note 3)

Value Length (Octets) 4 3 1 1 or 2 (see Note 4) 16 16 2 4 4 or 8 (see Note 4) 16

Reboot Required? Yes Yes Yes Yes Yes Yes No Yes No No

Note 1:

To prevent accidental misconfiguration of node addresses, the cNodeAddress attribute can only be set using a unicast request packet. Issuing a Write CSAP Attribute request for cNodeAddress in a broadcast packet will result in an Invalid Broadcast Request error response (section 3.20).

Note 2: To prevent accidental misconfiguration of node role, setting a sink to a headnode or subnode, and vice versa, is not permitted. An Invalid Value error response is returned in such a case (section 3.23).

Note 3:

Responses for valid Write CSAP Attribute requests normally contain both the attribute ID and the new value. However, attributes with keys (cCipherKey, cAuthenticationKey and cFeatureLockKey) only contain the attribute ID in the response. This is to reduce the likelihood of accidentally disclosing the keys.

Note 4:

Starting from firmware version 3.4, the cNodeRole and cFeatureLockBits attributes can have an optional bit mask after the value. Any zero bits in the mask will keep the bits from the original value. Only bits set in the mask will be affected. See section 4 for an example.

� Wirepas Ltd. 2020

www.wirepas.com

Confidential

WP-RM-117 � Wirepas Mesh Remote API Reference Manual - v5.0A

3.10.Read CSAP Attribute
Reading CSAP attributes is done using the Read CSAP Attribute request. Supported attributes are the same as with the Write CSAP Attribute request, listed in Table 7.
The Read CSAP Attribute request can be issued at any time. It does not need to be between Begin and End requests. The value returned is the current value of the attribute. There is no way to read the value in the temporary buffer, which is set using the Write CSAP Attribute request (section 3.9).
Format of the Read CSAP Attribute request is shown in Figure 21 and the response in Figure 22.

Octet 0

Octet 1

Octet 2

Octet 3

Type: 0x0E Length: 0x02 Attr ID LSB Attr ID MSB

Figure 21: Read CSAP Attribute Request

Octet 0 Type: 0x8E

Octet 1 Length

Octet 2

Octet 3

Attr ID LSB Attr ID MSB

Figure 22: Read CSAP Attribute Response

Octets 4 .. n Value

If the attribute ID is not recognized, an Unknown Request error response is returned (section 3.25). If feature lock bits prevent reading CSAP attributes, an Access Denied error response is returned (section 0). If a value is not set for an attribute, an Invalid Value error response is returned (section 3.23).
Reading keys (cCipherKey, cAuthenticationKey and cFeatureLockKey) is not possible. If a key is set, a Write-only Attribute error response is returned. If no key is set, the Invalid Value error response is returned, like for any other CSAP attribute that has no value.

3.11.MSAP Scratchpad Status
As an alternative to the out-of-band MSAP Remote Status and MSAP Remote Update requests (see [1] for details), Remote API supports similar functionality from firmware version 3.4 onwards. The old MSAP Remote Status and MSAP Remote Update requests were removed in firmware version 5.0.
The MSAP Scratchpad Status request can be issued at any time. It does not need to be between Begin and End requests. The response is similar but not identical to the old MSAP Remote Status Indication (see [1] for details). The response has either 24 or 39 octets, depending on whether the firmware supports reporting the application area information. The 39octet response was introduced in firmware version v4.0.
Format of the MSAP Scratchpad Status request is shown in Figure 23 and the response in Figure 24. Fields of the response are explained in Table 8 and
Table 9.

Octet 0

Octet 1

Type: 0x19 Length: 0x00

Figure 23: MSAP Scratchpad Status Request

� Wirepas Ltd. 2020

www.wirepas.com

Confidential

WP-RM-117 � Wirepas Mesh Remote API Reference Manual - v5.0A

Octet 0 Type: 0x99

Octet 1 Length

Octets 2 .. 5 Stored Scratchpad Number of Bytes

Octets 6 .. 7 Stored Scratchpad CRC

Octet 8 St Scr Seq

Octet 9

Octet 10

St Scr Type St Scr Status

Octets 11 .. 14 Processed Scratchpad Number of Bytes

Octets 15 .. 16 Processed Scratchpad CRC

Octet 17 Proc Scr Seq

Octets 18 .. 21 Processed Firmware Area ID

Octet 22

Octet 23

Octet 24

Octet 25

FW Major Ver FW Minor Ver FW Maint Ver FW Devel Ver

Octets 26 .. 29 Application Processed Scratchpad Number of Bytes

Octets 30 .. 31 App Proc Scratchpad CRC

Octet 32 App P Scr Seq

Octets 33 .. 36 Processed Application Area ID

Octet 37

Octet 38

Octet 39

Octet 40

App Major Ver App Minor Ver App Maint Ver App Devel Ver

Figure 24: MSAP Scratchpad Status Response

� Wirepas Ltd. 2020

www.wirepas.com

Confidential

WP-RM-117 � Wirepas Mesh Remote API Reference Manual - v5.0A

Start Octet 0 1 2 6 8
9
10
11 15 17
18 22 23 24 25

Table 8: MSAP Scratchpad Status Response Fields

Value Length (Octets) 1 1 4 2 1
1
1
4 2 1
4 1 1 1 1

Description Response type: 0x99 Length in octets, either 24 (0x18) or 39 (0x27) Length of the scratchpad present in the node, in octets, or 0 if no scratchpad is present in the node CRC of the scratchpad present in the node, or 0 if there is no scratchpad present in the node Sequence number of the scratchpad present in the node, or 0 if there is no scratchpad present in the node Type of the scratchpad present in the node:
� 0 = Blank: No valid scratchpad is present � 1 = Present: A valid scratchpad is present, but
has not been marked to be processed � 2 = Process: A valid scratchpad is present and
has been marked to be processed Status of the scratchpad present in the node:
� 255 = New: Bootloader has not yet processed the scratchpad
� 0 = Success: Bootloader has processed the scratchpad successfully
� 1 .. 254 = Error: Bootloader encountered an error while processing the scratchpad
Status is 0 also if there is no scratchpad present in the node Length, in octets, of the scratchpad that produced the firmware currently running on the node CRC of the scratchpad that produced the firmware currently running on the node Sequence number of the scratchpad that produced the firmware currently running on the node Memory area ID of the file in the scratchpad that produced the firmware currently running on the node. Scratchpads may contain multiple firmware images. This value can be used to determine which one the bootloader picked. Major version number of currently running firmware Major version number of currently running firmware Maintenance version number of currently running firmware Development version number of currently running firmware

� Wirepas Ltd. 2020

www.wirepas.com

Confidential

WP-RM-117 � Wirepas Mesh Remote API Reference Manual - v5.0A

Start Octet 26 30 32
33
37 38 39 40

Table 9: Extended MSAP Scratchpad Status Response Fields

Value Length (Octets) 4 2 1
4
1 1 1 1

Description Length, in octets, of the scratchpad that produced the application currently running on the node CRC of the scratchpad that produced the application currently running on the node Sequence number of the application that produced the firmware currently running on the node Memory area ID of the file in the scratchpad that produced the application currently running on the node. Scratchpads may contain multiple application images. This value can be used to determine which one the bootloader picked. Major version number of currently running application Major version number of currently running application Maintenance version number of currently running application Development version number of currently running application

This request does not return error responses, except when there is no space for the fairly large response, in which case a No Space for Response error response is returned (section 3.22).

3.12.MSAP Scratchpad Update
The MSAP Scratchpad Update request marks the scratchpad for processing by the bootloader. After an Update request (section 3.6) is issued and when the countdown reaches zero, the scratchpad is marked for processing and the node is rebooted. This causes the bootloader to go through the scratchpad contents and update any matching stack firmware and application in the node.
The MSAP Scratchpad Update request is allowed only after a Begin (section 3.2) or Begin with Lock request (section 3.3) and before an End request (section 3.4). Format of the MSAP Scratchpad Update request is shown in Figure 25 and the response in Figure 26.

Octet 0

Octet 1

Octet 2

Type: 0x1A Length: 0x01 Scr Sequence

Figure 25: MSAP Scratchpad Update Request

Octet 0

Octet 1

Octet 2

Type: 0x9A Length: 0x01 Scr Sequence

Figure 26: MSAP Scratchpad Update Response

The sole parameter is the scratchpad sequence number. If the stored scratchpad has a different sequence number, or if there is no stored scratchpad, an Invalid Value error response is returned (section 3.23). If no valid Begin request has been issued, an Invalid Begin error response is returned (section 3.21).

� Wirepas Ltd. 2020

www.wirepas.com

Confidential

WP-RM-117 � Wirepas Mesh Remote API Reference Manual - v5.0A

3.13.MSAP Max Queue Time Write
The MSAP Max Queue Time Write request is used to change the current value for how long a message is hold in the node's queue before it is discarded. Queuing time can be changed to normal and high priority messages separately.
Select queuing time carefully, too low a value may cause messages to be discarded unnecessarily and too high a value will result in filling up the message queues. For consistent performance it is recommended to use the same queuing times for the whole network.
Minimum queuing time shall be bigger than access cycle interval in TDMA networks. It is recommended to use multiples of access cycle interval (+ extra) to give time for message repetitions, higher priority messages taking over the access slot etc. Access cycle is not limiting the minimum value in CSMA-CA networks.
Precision of the time when message is discarded depends on the checking interval of message's age. Interval is 1s in CSMA-CA and 15s for energy saving reasons in TDMA networks i.e. precision is 1s or 15s depending on used channel access method.

Octet 0 Type: 0x4F

Octet 1 Length: 0x03

Octet 2 Priority

Octet 3 Time LSB

Figure 27: MSAP Max Queue Time Write Request

Octet 4 Time MSB

Octet 0 Type: 0xCF

Octet 1 Length: 0x03

Octet 2 Priority

Octet 3 Time LSB

Octet 4 Time MSB

Figure 28: MSAP Max Queue Time Write Response

3.14.MSAP Max Queue Time Read
The MSAP Max Queue Time Read request is used to read the current value of how long a message is hold in the node's queue before it is discarded. Queuing time for normal and high priority messages have their own values.

Octet 0

Octet 1

Type: 0x50 Length: 0x01

Octet 2 Priority

Figure 29: MSAP Max Queue Read Request

Octet 0 Type: 0xD0

Octet 1 Length: 0x03

Octet 2 Priority

Octet 3 Time LSB

Figure 30: MSAP MAX Queue Read Response

Octet 4 Time MSB

3.15.MSAP Enable Joining Beacon
The MSAP Enable Joining Beacon request is used to configure and enable periodic transmission of joining beacons. Joining beacons are part of a feature called Open Joining, which was introduced in Wirepas Mesh firmware version 5.0. See [2] for details.
The MSAP Enable Joining Beacon request can be issued at any time. It does not need to be between Begin and End requests. Format of the MSAP Enable Joining Beacon request is shown in Figure 31 and the response in Figure 32. Fields of the request are explained in Table 10.

� Wirepas Ltd. 2020

www.wirepas.com

Confidential

WP-RM-117 � Wirepas Mesh Remote API Reference Manual - v5.0A

Octet 0 Type: 0x61

Octet 1 Length

Octets 2 .. 5 Beacon Interval in �s, LSB First

Octets 6 .. 9 Radio Address, LSB First
Octets 12 .. 15 Joining Type, LSB First

Octet 10 Channel

Octet 11 Power

Octets 16 .. n Payload

Figure 31: MSAP Enable Joining Beacon Request

Octet 0 Type: 0xE1

Octet 1 Length

Octets 2 .. 5 Beacon Interval in �s, LSB First

Octets 6 .. 9 Radio Address, LSB First

Octet 10 Channel

Octet 11 Power

Octets 12 .. 15 Joining Type, LSB First

Octets 16 .. n Payload

Figure 32: MSAP Enable Joining Beacon Response

Start Octet 0 1 2 6 10 11
12 8

Table 10: MSAP Enable Joining Beacon Request and Response Fields

Value Length (Octets) 1 1 4 4 1 1
4 0 to 64

Description Type, request: 0x61, response: 0xE1 Length in octets, 14 (0x0E) to 78 (0x4E) Beacon interval in microseconds Radio address (network address) to use for sending joining beacons Channel to use for sending joining beacons Power in dBm to use for sending joining beacons, a signed 8-bit value Joining type, a 32-bit value that identifies the supported joining protocol Optional payload

3.16.MSAP Disable Joining Beacon
The MSAP Disable Joining Beacon request stops the transmission of periodic joining beacons that were enabled with MSAP Enable Joining Beacon request, above. The request takes no parameters. Format of the MSAP Disable Joining Beacon request is shown in Figure 33 and the response in Figure 34.

Octet 0

Octet 1

Type: 0x62 Length: 0x00

Figure 33: MSAP Disable Joining Beacon Request

Octet 0

Octet 1

Type: 0xE2 Length: 0x00

Figure 34: MSAP Disable Joining Beacon Response

� Wirepas Ltd. 2020

www.wirepas.com

Confidential

WP-RM-117 � Wirepas Mesh Remote API Reference Manual - v5.0A

3.17.MSAP Joining Beacon Status
Querying the status of the joining beacon transmissions is done using the MSAP Joining Beacon Status request. The request takes no parameters. A single status octet is returned in the response: 1 if joining beacon transmissions is enabled, 0 if not.
Format of the MSAP Joining Beacon Status request is shown in Figure 35 and the response in Figure 36.

Octet 0

Octet 1

Type: 0x63 Length: 0x00

Figure 35: MSAP Joining Beacon Status Request

Octet 0

Octet 1

Type: 0xE3 Length: 0x01

Octet 2 Status

Figure 36: MSAP Joining Beacon Status Response

3.18.Error: Access Denied
Access Denied error response is returned in the following situations:
� For Read MSAP Attribute request, if feature lock bits prevent reading MSAP attributes � For Read CSAP Attribute request, if feature lock bits prevent reading CSAP attributes � For Begin request, if a feature lock key is set � For Begin with Lock request, if a feature lock key is not set, or the key given is incorrect � For Update request, if the feature lock key has changed after the last Begin with Lock
request (e.g. via the Dual-MCU API) � For MSAP Joining Beacon requests (Enable, Disable, Status), if the Remote API control
of the joining beacons is disabled by the application
See [1] for description of CSAP attributes cFeatureLockBits and cFeatureLockKey.
Format of the Access Denied error response is shown in Figure 37. It contains the request type that failed and optionally the ID of the attribute that could not be accessed.

Octet 0 Type: 0xF8

Octet 1 Length

Octet 2 Request

Octet 3 Attr ID LSB

Figure 37: Access Denied Response

Octet 4 Attr ID MSB

3.19.Error: Write-only Attribute
Write-only Attribute error response is returned if a key attribute (cCipherKey, cAuthenticationKey and cFeatureLockKey) is read with the Read CSAP Attribute request (section 3.10), and the key is set. If the key is not set, an Invalid Value error response is returned instead (section 3.23).
Format of the Write-only Attribute error response is shown in Figure 38. It contains the request type that failed (i.e. Read CSAP Attribute, section 3.10) and the ID of the key attribute that could not be read.

Octet 0 Type: 0xF9

Octet 1

Octet 2

Octet 3

Length: 0x03 Request: 0x0E Attr ID LSB

Figure 38: Write-only Attribute Response

Octet 4 Attr ID MSB

� Wirepas Ltd. 2020

www.wirepas.com

Confidential

WP-RM-117 � Wirepas Mesh Remote API Reference Manual - v5.0A

3.20.Error: Invalid Broadcast Request
Setting node address is not possible using a broadcast request packet. An Invalid Broadcast Request error response is returned if a Write CSAP Attribute request with cNodeAddress attribute ID is issued in a broadcast request packet.
Format of the Invalid Broadcast Request error response is shown in Figure 39. It contains the request type that failed (i.e. Write CSAP Attribute, section 3.9) and the ID of the key attribute that could not be written (i.e. 1, cNodeAddress).

Octet 0 Type: 0xFA

Octet 1

Octet 2

Octet 3

Length: 0x03 Request: 0x0D Attr ID LSB

Figure 39: Invalid Broadcast Request Response

Octet 4 Attr ID MSB

3.21.Error: Invalid Begin
Invalid Begin error response is returned in the following situations:
� For Begin or Begin with Lock request, if an update countdown is running � For Write MSAP Attribute or Write CSAP Attribute if no Begin request has been issued � For End request, if no Begin or Begin with Lock request has been issued � For Update request, if no Begin and End requests have been issued
Format of the Invalid Begin error response is shown in Figure 40. It contains the request type that failed and optionally the ID of the attribute that could not be written.

Octet 0 Type: 0xFB

Octet 1 Length

Octet 2 Request

Octet 3 Attr ID LSB

Figure 40: Invalid Begin Response

Octet 4 Attr ID MSB

3.22.Error: No Space for Response
Responses to requests in one request packet are always sent in a single response packet. If there is not enough space for a response in the response packet, the request is not processed and the No Space for Response error response is returned instead. No requests after the failing request are processed. If there are less than five octets of space left in the response packet, the No Space for Response error response is omitted.
Format of the No Space for Response error response is shown in Figure 40. It contains the request type that failed and optionally the ID of the attribute that could not be read or written.

Octet 0 Type: 0xFC

Octet 1 Length

Octet 2 Request

Octet 3 Attr ID LSB

Figure 41: No Space for Response, Response

Octet 4 Attr ID MSB

3.23.Error: Invalid Value
An Invalid Value error response is returned in the following situations:
� For Begin or Begin with Lock request, if memory for a temporary buffer could not be allocated
� For Update request, if the countdown time value is invalid

� Wirepas Ltd. 2020

www.wirepas.com

Confidential

WP-RM-117 � Wirepas Mesh Remote API Reference Manual - v5.0A

� For Write MSAP Attribute or Write CSAP Attribute, if the attribute value is invalid � For Read MSAP Attribute or Read CSAP Attribute, if the attribute value is not set � For MSAP Max Queue Time Read, if priority is invalid � For MSAP Max Queue Time Write, if priority or time is invalid � For MSAP Scratchpad Update, if the sequence is incorrect, or there is no scratchpad
stored � For MSAP Enable Joining Beacon, if any of the parameters are incorrect
Format of the Invalid Value error response is shown in Figure 42. It contains the request type and optionally the ID of the attribute in the failed request.

Octet 0 Type: 0xFD

Octet 1 Length

Octet 2 Request

Octet 3 Attr ID LSB

Figure 42: Invalid Value Response

Octet 4 Attr ID MSB

3.24.Error: Invalid Length
If a request has wrong number of octets, an Invalid Length error response is returned. Reasons for the error are:
� The request packet is shorter than what the Length field of the request would indicate. � The Length field is incorrect for a request. � Attribute value is of the wrong length.
Format of the Invalid Length error response is shown in Figure 43. It contains the request type and for attribute write and read requests, the attribute ID.

Octet 0 Type: 0xFE

Octet 1 Length

Octet 2 Request

Octet 3 Attr ID LSB

Figure 43: Invalid Length Response

Octet 4 Attr ID MSB

3.25.Error: Unknown Request
Any request that is not recognized will result in an Unknown Request response. Attribute reading and writing with an unrecognized attribute ID will also cause the Unknown Request response to be returned.
Format of the Unknown Request error response is shown in Figure 44. It contains the request type that could not be recognized, or a request type and the ID of the attribute that could not be recognized.

Octet 0 Type: 0xFF

Octet 1 Length

Octet 2 Request

Octet 3 Attr ID LSB

Figure 44: Unknown Request Response

Octet 4 Attr ID MSB

4. Example Remote API Request and Response Packets
The example below configures a node with the following settings: � Node address: 0x123456 � Network address: 0xABCDEF

� Wirepas Ltd. 2020

www.wirepas.com

Confidential

WP-RM-117 � Wirepas Mesh Remote API Reference Manual - v5.0A

� Network channel: 10 � Node role: low-latency headnode with automatic role selection (0x92) � Encryption key: 10 20 30 40 50 60 70 80 90 A0 B0 C0 D0 E0 F0 00 � Authentication key: 00 F0 E0 D0 C0 B0 A0 90 80 70 60 50 40 30 20 10 � Feature lock bits: prevent reading and writing MSAP and CSAP attributes, prevent
factory reset (0xFFFFEC3F) � Feature lock key: FF EE DD CC BB AA 99 88 77 66 55 44 33 22 11 00
A complete request packet, 99 octets, is as follows (octets shown in hexadecimal):
04 00 01 00 0D 06 01 00 56 34 12 00 0D 05 02 00 EF CD AB 0D 03 03 00 0A 0D 03 04 00 92 0D 12 0D 00 10 20 30 40 50 60 70 80 90 A0 B0 C0 D0 E0 F0 00 0D 12 0E 00 00 F0 E0 D0 C0 B0 A0 90 80 70 60 50 40 30 20 10 0D 06 16 00 3F EC FF FF 0D 12 17 00 FF EE DD CC BB AA 99 88 77 66 55 44 33 22 11 00 03 00
The request packet is deconstructed and explained in Table 11.

Octets (Hexadecimal) 04 00 01 00 0D 06 01 00 56 34 12 00 0D 05 02 00 EF CD AB 0D 03 03 00 0A 0D 03 04 00 92 0D 12 0D 00 10 20 30 40 50 60 70 80 90 A0 B0 C0 D0 E0 F0 00 0D 12 0E 00 00 F0 E0 D0 C0 B0 A0 90 80 70 60 50 40 30 20 10 0D 06 16 00 3F EC FF FF 0D 12 17 00 FF EE DD CC BB AA 99 88 77 66 55 44 33 22 11 00 03 00

Table 11: A Request Packet Description Issue a Cancel request, to put Remote API in a known state. Issue a Begin request. Write 0x123456 to CSAP attribute cNodeAddress Write 0xABCDEF to CSAP attribute cNetworkAddress Write 0x0A to CSAP attribute cNetworkChannel Write 0x92 to CSAP attribute cNodeRole
Write a key to CSAP attribute cCipherKey
Write a key to CSAP attribute cAuthenticationKey
Write lock bits to CSAP attribute cFeatureLockBits
Write a key to CSAP Attribute cFeatureLockKey
Issue an End request.

If everything goes well, the node will respond with 51 octets (shown here in hexadecimal):
84 00 81 00 8D 06 01 00 56 34 12 00 8D 05 02 00 EF CD AB 8D 03 03 00 0A 8D 03 04 00 92 8D 02 0D 00 8D 02 0E 00 8D 06 16 00 3F EC FF FF 8D 02 17 00 03 00
The response packet is deconstructed and explained in Table 12.

� Wirepas Ltd. 2020

www.wirepas.com

Confidential

WP-RM-117 � Wirepas Mesh Remote API Reference Manual - v5.0A

Octets (Hexadecimal) 84 00 81 00 8D 06 01 00 56 34 12 00 8D 05 02 00 EF CD AB 8D 03 03 00 0A 8D 03 04 00 92 8D 02 0D 00
8D 02 0E 00
8D 06 16 00 3F EC FF FF 8D 02 17 00
03 00

Table 12: A Response Packet
Description A Cancel response A Begin response A response for writing CSAP attribute cNodeAddress A response for writing CSAP attribute cNetworkAddress A response for writing CSAP attribute cNetworkChannel A response for writing CSAP attribute cNodeRole A response for writing CSAP attribute cCipherKey, key not repeated in response A response for writing CSAP attribute cAuthenticationKey, key not repeated in response A response for writing CSAP attribute cFeatureLockBits A response for writing CSAP Attribute cFeatureLockKey, key not repeated in response An End response

In order to take the settings into use, an Update request needs to be sent. An Update request with a countdown time of 180 seconds is as follows (octets shown in hexadecimal):
05 02 B4 00
The node will respond with an Update response:
85 02 C5 00
Note, that the response contains a countdown value that is up to 20 seconds greater than the value in the request. See section 3.6 for an explanation of why this happens.
After about three minutes, the node will reboot and have the settings taken into use. Since the feature lock key is set, any further configuration needs to use the Begin with Lock request with the correct key.
Sometimes it is desirable to clear the feature lock key. This can be done with the following request packet (octets shown in hexadecimal):
04 00 02 10 FF EE DD CC BB AA 99 88 77 66 55 44 33 22 11 00 0D 12 17 00 FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF 03 00 05 02 0A 00
A deconstruction of the request packet is shown in Table 13.

Octets (Hexadecimal) 04 00 02 10 FF EE DD CC BB AA 99 88 77 66 55 44 33 22 11 00 0D 12 17 00 FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF 03 00 05 02 0A 00

Table 13: Another Request Packet Description Issue a Cancel request, to put Remote API in a known state.
Issue a Begin with Lock request with the correct key.
Write a blank key to CSAP Attribute cFeatureLockKey.
Issue an End request. Issue an Update request with the smallest possible countdown value of 10 seconds.

The node will respond (octets shown in hexadecimal): 84 00 82 00 8D 02 17 00 83 00 85 02 1F 00

� Wirepas Ltd. 2020

www.wirepas.com

Confidential

WP-RM-117 � Wirepas Mesh Remote API Reference Manual - v5.0A

A deconstruction of the response packet is shown in Table 14.

Octets (Hexadecimal) 84 00 82 00 8D 02 17 00
83 00 85 02 1F 00

Table 14: Another Response Packet
Description A Cancel response A Begin with Lock response A response for writing CSAP Attribute cFeatureLockKey, key not repeated in response An End response An Update response, with actual countdown value returned

After the update countdown has elapsed, the node will set a blank key to cFeatureLockKey CSAP attribute, disabling the feature lock. Since cFeatureLockKey attribute does not require a reboot, the node continues operating normally after the update.
Attributes that contain bits that control the node operation, namely cNodeRole and cFeatureLockBits can be adjusted without affecting all bits at the same time. An optional bit mask was introduced in firmware v3.4.0 for these two attributes.
The following request sets the low-latency bit (bit 7) without affecting the other bits (e.g. autorole and subnode or headnode selection) in the node role. It then clears the OTAP Disable bit (bit 31) in the cFeatureLockBits attribute. The Begin and End requests have been omitted for brevity.
0D 04 04 00 80 80 0D 0A 16 00 00 00 00 00 80 00 00 00
A deconstruction of the request packet is shown in Table 15.

Table 15: Writing Individual Bits of cNodeRole and CFeatureLockBits

Octets (Hexadecimal) 0D 04 04 00 80 80 0D 0A 16 00 00 00 00 00 80 00 00 00

Description Set bit 7 in CSAP attribute cNodeRole
Clear bit 31 in CSAP attribute cFeatureLockBits

Responses to these requests do not have the bit mask, only the resulting value, i.e. original bits where a bit in the mask was cleared and new bits where the mask had a bit set.

5. References

[1]

WP-RM-100 � Wirepas Mesh Dual-MCU API Reference Manual

[2]

WP-AN-324 � Open Joining and Online Provisioning

� Wirepas Ltd. 2020

www.wirepas.com

Confidential