CoAP resources

The RIIM platform includes 3 built-in CoAP resources. In addition, the user can create custom CoAP resources in the ICI application through the CoAP API. CoAP resources are accessed by sending a CoAP message to the URI of the node with the name of the resource at the end, for instance: coap://[ip-addr]/my_resource . The resources support GET, PUT, POST and DELETE. All built-in resources support both CoAP and the DTLS secure version CoAPs. All letters in the resource names are lower case.

Generally, Radiocrafts recommends using CBOR (Concise Binary Object Representation, RFC 7049) encoding for transmission of data to/from CoAP resources, as CBOR provides a compact, consistent, and easy to decode way of representing data. All built-in resources use CBOR.

Resource

Address

OTA Resource

IP-addr/OTA

Node Resource

IP-addr/Node

Network Resource

IP-addr/Network

Clock Resource

IP-addr/Clock

ICI Application Resource

IP-addr/<User Defined>

OTA Resource

The OTA resource is a built-in CoAP resource used for over-the-air download of new images. The overall sequence for transmitting and updating an image is realized with 4 commands:

  • Start new OTA transfer (Command 1)

  • Transfer image (Command 2)

  • Switch image (Command 3)

  • Reset node (Command 4)

All commands use the same CBOR structure, and consists of

  • Command number

  • Address (4 bytes)

  • Additional bytes in the payload

Start new OTA transfer

Before starting a transmission of a new image, the FLASH must be cleared. This command can also be used to reset the sequence completely if something goes wrong. The address-field isn’t used and should be set to zero. No additional bytes are in the command.

Example payload:
0x83 0x01 0x1A 0x00 0x00 0x00 0x00 0x58 0x00

Decoded, this is:
83          # array(3)
02          # unsigned(2) – Command 1 (Start new OTA transfer)
1A 00000000 # unsigned(0) – Ignored address field
58 00       # bytes(0)
            #             - Empty data field
Total: 9 bytes

Transfer image

This command transfers a block of the firmware image. The command number is 2. The address specifies where the in the block to start storing, and every image starts at address zero. The additional bytes are the actual block of data

Example payload:
0x83 0x02 0x1A 0x00 0x00 0x00 0x10 0x58 0x08 0x11 0x22 0x33 0x44 0x55 0x66 0x77 0x88

Decoded, this is:
83                      # array(3)
02                      # unsigned(2)  - Command 2
1A 00000010             # unsigned(16) – 32 bit address (Address is 0x10)
58 08                   # bytes(8)     - Size of data field (8 bytes)
    1122334455667788    #              - Data bytes

Switch image

This command basically arms the update. When entering the bootloader at the start of the execution, the bootloader will look for the presence of a new image. If the image is armed, present and error-free, it will be flashed to the actual program space before execution continues. Address and additional bytes aren’t used in the command. Module must be reset after this command to do the update.

Example payload:
0x83 0x03 0x1A 0x00 0x00 0x00 0x00 0x58 0x00

Decoded, this is:
83          # array(3)
03          # unsigned(3) – Command 3 (Switch image)
1A 00000000 # unsigned(0) – Ignored address field
58 00       # bytes(0)    - No bytes in payload
            #             - Empty data field

Reset

This command resets the module

Example payload:
0x83 0x04 0x1A 0x00 0x00 0x00 0x00 0x58 0x00

Decoded, this is:
83          # array(3)
04          # unsigned(3) – Command 4 (Reset)
1A 00000000 # unsigned(0) – Ignored address field
58 00       # bytes(0)    - No bytes in payload
            #             - Empty data field

CoAP OTA response message

All commands get a response with the address of the receiving node plus a copy of the header. The data bytes aren’t sent in the response. This can be used to verify that a message was indeed received and understood correctly.

OTA Sequence

The following figure shows the whole sequence for a complete OTA

OTA sequence

OTA sequence

Node Resource

The Node resource is a built-in CoAP resource used to retrieve information about the node.

GET

Sending a GET message with no payload returns node setup. This table shows the returned payload:

CBOR type

Description

Array of data items

Number of data items in payload. In this case: 7

Tiny unsigned integer

Node type (Border Router, Mesh Router or Leaf)

16-bit unsigned integer

Platform ID

Byte Array of 3 bytes

Platform version (MMmmPP - Major, Minor, Patch)

16-bit unsigned integer

Hardware ID

16-bit unsigned integer

Hardware Revision

 
Example payload:
0x87 0x01 0x19 0x00 0x11 0x43 0x22 0x33 0x44 0x19 0xAA 0xBB 0x19 0xCC 0xDD

Decoded, this is:
85          # array(7)
01          # unsigned(1)     - Node type
19 0011     # unsigned(17)    – Platform ID
43          # bytes(3)
    223344  # 0x223344        – Platform Version
19 AABB     # unsigned(43707) – Hardware ID
19 CCDD     # unsigned(52445) – Hardware Revision
Total: 15 bytes

Network Resource

The Network resource is a built-in CoAP resource used to retrieve network information. A list of neighbors or the whole network topology can be requested. Not all types of node support all network reporting commands. To request the different reports, the payload of the GET message must contain a command and parameter. These are formatted as CBOR:

CBOR type

Description

Array of data items

Number of data items in payload. In this case: 2

Tiny unsigned integer

Command number

16-bit unsigned integer

Command argument

Command

Command Number

Parameter

Supported by

Get own IP addresses

1

Unused

Border Router, Mesh Router, Leaf

Get neighbour nodes

2

Start index

Border Router, Mesh Router

Get NWS topology

3

Start Index

Border Router

 
Example payload
0x82 0x01 0x19 0x11 0x22

82          # array(2)
01          # unsigned(1)     - Command number
19 1122     # unsigned(4386)  - Command argument
Total: 5 bytes

Get own IP addresses

This command returns the IP address of the node. It returns 4 different addresses:

  • PAN ID

  • The local (fe80::)-address

  • The global IPv6 address

  • The link local address (2 bytes)

  • The IPv4 address

This is sent as payload in CBOR encoding. Example:
0x85 0x19 0x12 0x34 0x50 0xFE 0x80 0x12 0x34 0x56 0x78 0x9A 0xBC 0xDE 0xF0 0x12 0x34 0x56 0x78 0x9A 0xBC 0x50 0x12 0x34 0x56 0x78 0x9A 0xBC 0xDE 0xF0 0x12 0x34 0x56 0x78 0x9A 0xBC 0xDE 0xF0 0x42 0x9A 0xBC 0x44 0x11 0x22 0x33 0x44

85                                      # array(4)
19 1234                                 #               - PAN ID
50                                      # bytes(16)
    FE80123456789ABCDEF0123456789ABC    #               - Local IPv6 Address
50                                      # bytes(16)
    123456789ABCDEF0123456789ABCDEF0    #               - Global IPv6 Address
42                                      # bytes(2)
    9ABC                                #               - Short link local address
44                                      # bytes(4)
    11223344                            #               - IPv4 Address
Total: 46 bytes

Get neighbour nodes

This command returns the Interface Identifier (IID) of all neighbors linked to the node and the RSSI of the link to that neighbor. The IID is the rightmost 64 bits (8 byte) of the IPv6 address. The result is taken from a neighbor table in the node, where each neighbor is assigned an index. Get neighbor nodes returns a maximum of 4 nodes each time due to optimization of packet size inside the RIIM Network. This means that the user may need to send multiple GET messages to retrieve all neighbors

0x83 0xE2 0x6C 0x82 0x48 0x11 0x22 0x33 0x44 0x55 0x66 0x77 0x88 0x42 0xFF 0xAB 0x82 0x48 0x22 0x22 0x33 0x44 0x55 0x66 0x77 0x88 0x42 0xFF 0xAB
83                          # array(3)
42                          # bytes(2)
    E26C                    # "\xE2l"     - Responding node’s short address
82                          # array(2)
    48                      # bytes(8)
        1122334455667788    #             - 1st neighbour address
    42                      # bytes(2)
        FFAB                # "\xFF\xAB"  - 1st neighbour RSSI value (2’s complement)
82
    48                      # bytes(8)
        2222334455667788    #             - 2nd neighbour address
    42                      # bytes(2)
        FFAB                # "\xFF\xAB"  - 2nd neighbour RSSI value (2’s complement)
Total: 49 bytes

Get the RIIM Network Topology

This request returns the RIIM network topology. All nodes in the whole network and their connections are stored in the Border Router and nowhere else, so this is only supported by the Border Router. The external connection can transfer larger payloads without packet fragmentation, and a maximum of 2 links are transferred per packet. The links are represented as CBOR pairs of IIDs.

0x82 0x82 0x48 0x11 0x22 0x33 0x44 0x55 0x66 0x77 0x88 0x48 0x22 0x22 0x33 0x44 0x55 0x66 0x77 0x88 0x82 0x48 0x11 0x22 0x33 0x44 0x55 0x66 0x77 0x88 0x48 0x33 0x22 0x33 0x44 0x55 0x66 0x77 0x88

82                          # array(2)
82                          # array(2)
    48                      # bytes(8)
        1122334455667788    #      - Address 1122334455667788 is connected to...
    48                      # bytes(8)
        2222334455667788    #      - ... 2222334455667788
82                          # array(2)
    48                      # bytes(8)
        1122334455667788    #      - Address 1122334455667788 is ALSO connected to..
    48                      # bytes(8)
        3322334455667788    #         - ... 3322334455667788
Total: 39 bytes.

Clock Resource

The Clock resource is a built-in CoAP resource used to set and retrieve synchronized time information. It contains two values, one Time-of-Day offset, and one Epoch offset. These offsets are with regards to the network absolute time described earlier.

83                          # array(3)
02                          # Type(2) - Offset struct
1B or 3B                    # Positive or Negative integer
        1122334455667788    #      - Time-of-Day offset
1B or 3B                    # Positive or Negative integer
        2222334455667788    #      - Epoch offset

These are formatted as CBOR: