Software Integration Design Guide

The integration guide is designed to help you to create firmware that will run on an application processor (also known as Device IC). CoAP is the application layer protocol, and the CoAP PDUs will be transmitted and received by the Milli5 over the RF network. CoAP messages must be encoded using the Concise Binary Object Representation (CBOR). Topics you will find in the integration guide include:

 

  • Milli System Architecture
  • Milli CoAP API and URIs
  • Device IC API and URIs
  • Suggested Observable Resources
  • Observe Behaviour
  • Application Security Configuration
  • CBOR Implementation and Examples

 

Additionally, the Device IC communicates with the Milli5 and beyond via CoAP via high level data link control (HDLC) over UART. This is explained in the Device Data Link Layer Protocol Specification.

 

 

 

 

Download NIC Software Integration Guide                             Download Milli Device Data Link Layer Specification 

 

 

 

Sensor Code Template

Several code templates are provided as reference for you to start from. These are not complete running programs but rather sample code for you to examine to get an understanding of the modules and what they do. You should determine the bare minimum functionality that you need. E.g. the resources you want to expose, logging, URI simplification, removal of unused functions. Take what is needed from the sample code and port it to your microcontroller. These can also be found in Document Center.

The first code set is a sensor definition code set using the classic CoAP Server implementation. This is a template for defining your sensor, URIs, observable resources, and other key sensor configurations.

The second code set is a sensor definition using Itron Sensor API (SAPI).  This provides an easier way to define your sensor with our pre-defined CoAP Server library.  SAPI defines how a sensor is defined, initialized, and registered with the CoAP Server Library.

 

 

 

Download CLASSIC Sensor Code                                                                      Download SAPI SEnsor code

 

 

CoAP Server Code Template

The CoAP server code is a library of code for building your CoAP server implementation.  Itron provides two flavors of CoAP server code; our classic CoAP Server, which is a starting place for developers who want to create their own custom CoAP server implementation and Milli5 module integration.

Itron also provides our Sensor API (SAPI) code, which separates partner sensor integration from an fully functioning CoAP server library which is pre-integrated with Milli5.  For more information on SAPI, see our overview.

 

 

 

Download CoAP Server Code                                                            Download SAPI COAP SERVER LIBRARY

 

 

CBOR Encoding Code Template

This is a simple program that encodes the CBOR header as we’d like it done, and treats the supplied message as a byte stream. The idea is that you use the relevant sample code in your firmware, but substitute the sensor data for the message. If you want to do more sophisticated CBOR, great! We have included our cbor_encode.c and cbor.h files as they are required. For your purposes, they can be simplified to remove unnecessary code.

 

Here is a very basic CBOR sample:

Building the CBOR Sample

cc -o cbor_basic_enc cbor_basic_enc.c cbor_encode.c

 

Running

./cbor_basic_enc -m "Hello world" /tmp/hw_message.cbor

 

To examine the contents of the file:

xxd -p /tmp/hw_message.cbor 

 

which should return: 

a20063636834014b48656c6c6f20776f726c64

 

If desired, paste the hex into the right-hand pane of the cbor.me playground and it will decode:

A2                           # map(2)

   00                        # unsigned(0)

   63                        # text(3)

      636834                 # "ch4"

   01                        # unsigned(1)

   4B                        # bytes(11)

      48656C6C6F20776F726C64 # "Hello world"

and

{0: "ch4", 1: h'48656C6C6F20776F726C64'}

 

 

 

Download CBOR Encoding Code