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/ =========================== ======================================= 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 .. figure:: ../gfx/ota_sequence.png :align: center :alt: 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 .. _target_Get_the_RIIM_Network_Topology: 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: