Milli Developer Kit Example Application

Example CoAP Server Sensor Implementation With The Milli Dev Kit

Get the Milli Developer Kit Temperature Sensor Reference Application on GitHub
 
This reference application demonstrates how to implement a sensor connected to a CoAP server using the Milli Developer Kit for Arduino v1.0 Developer Kit attached to an Arduino M0, M0 Pro or Due board. The application is a temperature sensor.

Overview

This temperature sensor reference application demonstrates the implementation of a sensor or end device. The Milli Dev Kit has an Arduino shield (aka Milli Shield) that can be attached on top of most standard Arduino boards. The sensor attaches to a CoAP server on the Arduino processor board attached to the Milli Shield

The Arduino hardware supported for use with the Arduino software that comes with the kit are the Adafruit Metro M0 Express, Arduino M0, or M0 Pro (see reference links to the right). Note that the Arduino M0 and the Arduino M0 Pro are obsolete boards no longer sold by Arduino. The code might work with other Arduino boards based on the Atmel SAMD21 series processors, but may require minor code changes.

From the Developer Portal, you can purchase a Milli Dev Kit with the Adafruit Metro M0 Express (or you may purchase the Adafruit processor separately) using the following links:

 

The sensor measurements are handled by a CoAP server running on the Adafruit Metro M0 Express. Communication between the Arduino board and the shield is done via HDLC over one of the Adafruit boards UART. 

The below drawing shows the communication path from Sensor to Client:

 

 

Hardware Needed

The following is necessary to implement this example reference application:

Either a Milli Dev Kit with an Adafruit board including:

 

OR a Milli Dev Kit with an Arduino board purchased elsewhere:

 

Setup for the hardware is described here.

Additionally, you will need the following (links provided in the list of hardware resources to the right):

 

Note: Itron no longer supports the miniAP and strongly recommends that developers use the IoT Edge Router solution instead. 

 

Application Processor Software Needed

For the Adafruit Metro M0 Express, there are two options to load software onto the application processor:

1) Load a complete, fully built image directly onto the board

2) Manually download the software and board support packages and program the board using the Arduino IDE 

For other Arduino boards, the only option is to use the Arduino IDE to manually program the board for the Milli reference application.  Both options are described below.

Complete Image Installation (Adafruit Metro M0 Express ONLY)

This process works with a UF2 bootloader image.  The UF2 image includes everything needed to support the Adafruit Metro M0 Express board, including the reference application CoAP Server code and all necessary board support packages for this hardware.  The CoAP server includes support for the Milli reference application, which uses a temperature sensor.

The steps to complete this process are as follows:

  1. Download the UF2 file mshield-1.4.1.ino.uf2 from the Itron GitHub repository or the Itron Developer Portal Document Center (under IOT....Firmware and Configuration....Milli....Adafruit Metro M0 Express....Firmware Images).
  2. Double click the reset button on the Adafruit board (NOT the Milli shield reset button!)
  3. The large LED on the Adafruit board will start to fade slowly.This indicates the bootloader is running.
  4. The bootloader will make available to your Windows system a USB drive.You should see a notification on your system indicating that a new disk called METROBOOT is available.
  5. Using Windows Explorer, locate and open the METROBOOT disk.
  6. Copy the mshield-1.4.1.ino.uf2 file to the METROBOOT disk.
  7. The Adafruit bootloader will automatically read this file and commit it to flash, and then automatically reboot once complete.
  8. The METROBOOT disk will automatically close and no longer be available in Windows.

Once the METROBOOT disk disappears, the large LED will no longer be illuminated on the Adafruit board, and the board is now ready to support the Milli reference application!

Manual Board Programming (All Boards)

Download the Arduino source code for the reference application from the Itron GitHub repository. Note that the repository link points to the repository root. Downloading or cloning the git repo includes both the HDK and the SDK applications. After you create a copy locally, the Arduino code can be found in the developer_program-master\HDK\Milli5-Arduino CoAP Server\ directory.

In addition to the source code, obtain the following tools (reference links provided at the right):

Software
Version
Comments
Arduino IDE
1.8.7
Download from Arduino.cc
Board support package for Arduino SAMD based boards
1.6.19+
Install from within the Arduino IDE - "Arduino SAMD Boards"
Board support package for Adafruit SAMD Boards (includes the Metro M0 Express)
1.2.3+
Install from within the Arduino IDE - "Adafruit SAMD Boards
Board support package for Adafruit AVR based boards.
1.4.13+
Install from within the Arduino IDE - "Adafruit AVR Boards"
Arduino RTC Zero Library
1.5.2
Install from within the Arduino IDE
Adafruit Unified Sensor Library
1.0.2
Install from within the Arduino IDE
DHT Sensor Library
1.3.0
Install from within the Arduino IDE
FTDI Driver
Latest
For connecting to diagnostic port of the Milli Dev Kit Arduino shield
 
To add support for the Adafruit board managers add the URL https://adafruit.github.io/arduino-board-index/package_adafruit_index.json to the Arduino IDE from the File->Preferences

 

The following tools can be useful in a Microsoft Windows environment:

Milli Shield Stacked on an Arduino

MILLI TEMPERATURE REF APP NAVIGATION

Mill Dev Kit Example Application OverviewMilli Dev Kit Example App Part 2 - CoAP ClientMilli Dev Kit Example App Part 3 - Plot App

HARDWARE RESOURCES

Milli Dev Kit 1.0 with an Arduino (USA & Australia)Milli Developer Kit v1.0 - Singapore Milli Developer Kit v1.0 for EUAdafruit Metro M0 ExpressArduino M0 ProArduino DueDHT11 Temperature SensorAdafruit BreadboardArduino M0

SOFTWARE RESOURCES

Milli Developer Kit Example Application PART 1 Source Code GitHubMilli Developer Kit Example ApplicationArduino IDE from Arduino.ccArduino IDE from Arduino.orgArduino RTC Zero LibraryAdafruit Unified Sensor LibraryDHT Sensor LibraryFTDI DriverArduino RTC Due LibraryAdafruit Arduino Board Packages

REFERENCE RESOURCES

CoAP Tutorial VideosCoAP Reference

Installation & Setup

Reference the following instructions to successfully set up your Milli devices. 

Temp Sensor Reference Application Setup

For instructions on setting up your Dev Kit, refer to the Milli Developer Kit v1.0 Getting Started Guide.

The folowing image illustrates how your hardware set-up should look on complete installation and setup.

 

 

Install Reference Application & Arduino Libraries

In the instructions below, "Arduino M0" is used as the example hardware stacked to the shield. It is interchangeable with whichever hardware is being used for the same purpose. 

This section describes how to: 

  • Install the application and associated libraries
  • Compile and build the MilliShield Arduino software
  • Upload your Arduino program to an Arduino M0 or M0 Pro board
  • Re-start your program
  • Upload your Arduino program to an Arduino Due

 

To Install the application and associated libraries:

  1. Download the Arduino IDE from arduino.cc
     
  2. Install the Arduino IDE
    • Note: The MilliShield Arduino Reference Software consists of two directories; mshield and ssni_coap_server under \developer_program-master\HDK\Milli5-Arduino CoAP Server.
       
  3. Copy the mshield directory to anywhere on your computer system. Typically, it is located here: C:\Users\<user>\Documents\Arduino (replace <user> with your username).


 

  1. Copy the ssni_coap_server directory to the following location (replace <user> with your username): C:\Users\<user>\Documents\Arduino\libraries.

 

  1. Launch the Arduino IDE (open the mshield.ino located in the mshield directory).​
    • In the IDE, navigate to Sketch/Include Library/Contributed Libraries and select ssni_coap_server.
    • ​​​In the IDE, navigate to Sketch/Include Library/Manage Libraries. The Library Manager window appears. See the following image for reference.  


 

  • Add the RTC library:
    • Click Install
    • In the "Select version" drop-down menu, select v1.5.2
    • Locate the RTCZero library
    • Type RTC in the search bar
  • In the search bar, type "Adafruit Unified Sensor" to search for this library
    • ​In the "Select version" drop-down menu, select v1.0.2
    • Click Install
  • In the search bar, type DHT to search for the DHT Sensor Library
    • ​In the "Select version" drop-down menu, select v1.3.0
    • Click Install

 

  1. In the IDE, go to Tools/Board/Boards Manager. The Boards Manager window appears. See image below. 

 

 

  1. Install the following boards:
  • Arduino SAMD Boards
    • Using the drop-down menu, select board support package 1.6.19+
    • Click Install
  • Adafruit AVR Boards
    • Using the drop-down menu, select board support package 1.4.13+
    • Click Install
  • Adafruit SAMD Boards
    • Using the drop-down menu, select board support package 1.2.3+
    • Click Install

 

  1. In the IDE, go to Tools/Board and select the Adafruit Metro M0 Express board.
     
  2. In the IDE, go to Tools/Port and select Adafruit Metro M0 Express.

 

To compile and build the Millishield Arduino software:

  1. In the IDE, click on the check mark in the upper left corner
    OR press Ctrl-R
     
  2. When the build is complete, the following image displays:
     


 

To upload your Arduino program to an Adafruit Metro M0 Express:

  1. On the Adafruit Metro M0 Express board, double click the reset button. The on-board LED starts a slow fade cycle. This indicates the boot loader is active.
     
  2. In the IDE, click on the right arrow in the upper left corner
    OR press Ctrl-U
     
  3. When the upload is complete, you should see something like the below image.

NOTE: This means that your upload was successful, and your Arduino program has started running.

 

  1. After uploading your program, the setting under Tools/Port might have changed. If that is the case, reselect the current port.
     
  2. In the IDE, click on the magnifying glass in the top right corner to launch the Serial Monitor. See image below for reference. 

 

 

Any data sent to the CoAP server on the Arduino from the Milli shield, or sent from the CoAP server to the Milli shield, will appear in the serial monitor.

Note: Debug logging will appear only when an HDLC transfer occurs.

Note: On reset, the Arduino based reference app will monitor the USB on the native USB port for 15 seconds. If a serial connection is not established within the 15 second window, debug output is disabled and the CoAP server is started.

Note: You can use other terminal communication applications to monitor the CoAP Servers debug output.

To re-start your program:

  1. ​ Press the reset button on the Arduino board next to the Native micro USB connector.

WARNING: This is not the blue reset button of the Milli Shield.

 

Install the 4-Pin DHT11 Sensor

See image below for a visual reference to the 4-pin DHT11 temperature sensor with a 10K Ohm pull-up resistor:

 

To connect the Adafruit DHT11 to your Arduino stack:

  1. Connect the Ground wire to Arduino GND.
     
  2. Connect the VCC wire to Arduino 5V.
     
  3. Connect the Signal wire to Arduino Analog Input A4.
    Note: In the below image, the blue wire is connected to Digital Pin 7 instead of A4|
     
  4. Connect the 10K Ohm pull-up resistor between VCC and Signal

 

Add Your Own Sensor

For more information on adding more sensors to your CoAP server implementation, click here.

 

CoAP Server Configuration

Configuring the CoAP Server

The CoAP Server can be configured by by editing defines in the header file mshield.h located in the folder mshield.

Before building the Reference Application:

  1. Locate the LOG_LEVEL define 
  2. Set it according to the amount of debuginformation that should be sent to the seiral monitor:
    • To mute the trace:
      • Set it to 0
    • To get many trace messages:
      • Set it to LOG_DEBUG

 

Before altering the define UART_TIMEOUT_IN_MS, see the section "MilliMesh Network and Application Layer Time-outs" below.

 

If the board in use is not supported, it may be necessary to change the pointers to UART and/or the Serial Monitor (UART_PTR / SER_MON_PTR).

CoAP Observe Max-Age can be adjusted by changing the define COAP_MSG_MAX_AGE_IN_SECS.

Once a sensor has been added, its URI needs to be added to the file mshield.h located in the folder mshield.  For more information on how to add another sensor, click here.

 

Milli Mesh Network and Application Layer Time-outs

Due to the limited memory bandwidth of miliiNICs as well as the requirement on battery powered devices to conserve energy, the millimesh network has greater latency and lower bandwidth than traditional Itron mesh networks. Therefore, the standard CoAP tiemouts for retries on this network are not appropriate.   

It is a requirement that appropriate application layer timeouts on message responses be used in order to avoid unduly overloading the network. It is also strongly suggested that non-confirmable messages be used where possible.

CoAP Server Resources

Available Resources

The following CoAP resources are made available by the Arduino CoAP server part of the reference application.

Resources are described by the following: 

  • A method 
  • A URI to specify the resource name 
  • A query string

 

The default {prefix} for sensor CoAP server resources depends on the firmware version running on the Mill. The firmware should be loaded per the instructions found at How to Update Firmware Images.

  • For firmware version 1.2.1000 build 112738 and earlier {prefix} should be sensor
  • For firmware version 1.2.1000 build 117958 and later {prefix} should be snsr

 

To set the temperature sensor configuration:

  • PUT /{prefix}/arduino/temp?cfg=C
  • PUT /{prefix}/arduino/temp?cfg=F

 

To get the  temperature sensor configuration:

  • GET /{prefix}/arduino/temp?cfg

 

To read the temperature sensor:

  • GET /{prefix}/arduino/temp?sens

 

To request an observe on the temperature sensor:

  • GET /{prefix}/arduino/temp?sens with the CoAP observe header set

 

Arduino Time

The milli automatically issues a PUT to /sensor/arduino/time based on its current setting. 

To see the current setting:

  1. Issue the following GET: 
    • GET /{prefix}/system/time

 

Dev Kit Diagnostic Port and Terminal Access

The Diagnostic Port can be used to set Developer Kit system variables, to update the Milli NIC firmware, and set other preferences. 

To access the Diagnostic Port: 

  1. Attach a USB Smart Cable TTL-232R from e.g. FTDI to J14 on the Milli Shield. See image below for more detail. 
    • Black (GND) connect to innermost pin
    • Orange to middle pin
    • Yellow to outermost pin

  1. Connect the Smart Cable to the diagnostic port 
  2. Ensure that the Terminal Emultaor (such as a Tera Term) is: 
    1. Configured with a Baud Rate of 115,200
    2. Connected to the COM port associated with the Smart Cable 
  3. Reset the Milli Shield by pressing the blue button. A message in the terminal window will appear. See image below. 

 

 

Milli Developer Kit Firmware Upgrade

Refer to the FAQ for directions on upgrading the Mill Dev Kit firmware and how to configure Mill Dev Kit firmware or set firmware sysvars.

 

 

CoAP Client Options

Windows CoAP Client Application

If you have a Microsoft Windows PC, you can download and install the Windows CoAP Client Application. This tool provides an easy-to-use user interface for communicating with CoAP sensor devices. Follow the instructions to install the client application.

 

Java CoAP Client Application

For a CoAP client that needs to:

  • Run on any platform (Windows, Mac OS, Linux) 
  • Be included as part of a shell script 
  • Have a finer grained control over CoAP requests or
  • Allow for more complex CoAP request patterns
  • load and use the Java CoAP Client Application.

This client is command line based and requires command line cptions or request files that direct the clients actions. The Java CoAP Client makes managing Gateway sessions easier for complex CoAP requests patterns.

 

Other Clients

Almost all CoAP Core implementations include sample CoAP clients. Some work better than others. All have limitations and bugs. One popular client is included with the C++ based libcoap implementation.

 

CoAP Gateway

Integral to the Itron network is a CoAP proxy that provides user authentication. Please refer to the CoAP Gateway API for details on Gateway specific CoAP resources and Gateway session management. For access to a personal HDK, all CoAP requests must use the Gateway. Not direct to device CoAP is supported.