Overview
The Sensor API with temperature sensor reference application demonstrates how a sensor is implemented on an IoT device. The Milli Dev Kit Milli Shield board is compliant with the Arduino electrical and mechanical specifications. It can be attached to any MCU that supports the Arduino standards. Usually, the Milli Shield board is fitted on top of an MCU board. Sensors are wired to the shield connectors as needed.
Currently, the Milli Dev Kit v1.0 ships with an Adafruit Metro M0 Express MCU board. This board is based on the Atmel SAMD21 series MCU. Note that this board is not included in the Singapore Milli Dev Kit. See the reference link to the right for details on the Metro M0 Express board.
The Sensor API reference source can be made to work on other MCU boards 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:
- Milli Dev Kit v1.0 with an Adafruit Metro M0 Express - USA & Australia
- Milli Developer Kit v1.0 - Singapore
- Milli Developer Kit v1.0 for EU
The temperature sensor code is incorporated into the devices Sensor API code, which reads the sensor when requested (or when a CoAP observation is generated). Sensor API has an integral CoAP server which proxies CoAP through the attached Milli Shield. The Milli Shield and the Sensor API code use HDLC as a link protocol over a serial connection.
The below drawing shows the communication path from Sensor to Client:
Hardware Components Needed
The Sensor API reference application requires the following components:
Either a Milli Dev Kit with an Adafruit Metro M0 Express board including:
- Milli Developer Kit v1.0 with Arduino (USA & Australia)
- Milli Developer Kit v1.0 for EU (EU & Middle East)
OR a Milli Dev Kit with an Adafruit Metro M0 Express board purchased elsewhere:
- Milli Developer Kit v1.0 - Singapore (Singapore)
AND - Adafruit Metro M0 Express
Setup for the hardware is described here.
Additionally, you will need the following parts (links provided in the list of hardware resources to the right):
- One of the following devices for backhaul on Itron mesh network. This should be setup and communicating with Itron first.
- IoT Edge Router HW1 - USA, Canada & Jamaica (must be WAN mode capable and purchased after 11/9/2017)
- IoT Edge Router HW2 - Australia & Singapore (must be WAN mode capable and purchased after 11/9/2017)
- IoT Edge Router HW3 - Europe & Middle East
- An Adafruit DHT11 4-pin temperature sensor
- Wires for connecting the sensor to the Milli Dev Kit
- Breadboard for mounting the sensor (if you want to avoid soldering)
Software Components Needed
Once you have the hardware components assembled, you will need to load the Sensor API reference package onto your Adafruit Metro M0 Express board. There are two options to load this software onto the application processor:
Option 1) Load a complete, fully built UF2 (USB Flashing Format) image directly onto the board. Many manufacturers are providing UF2 flashing support and STM are among these.
Option 2) Set up a development environment, get the source code from the GitHub git repo, and build the UF2 file. Then follow option one.
It is recommended to start with, that you use option 1. This allows you to prove that the end-to-end data communication path is working. It is easier to resolve network problems before you add the complexity of a development environment.
For other MCU boards, the only option is to use a development environment and build a version of the Sensor API reference package specific to the target MCU.
Sensor API UF2 Installation (Adafruit Metro M0 Express)
This process works with a UF2 bootloader image. The UF2 image includes everything needed to support the Adafruit Metro M0 Express board, including the Sensor API reference application (with integral CoAP Server) and temperature sensor.
The steps to complete this process are as follows:
- Download the UF2 file mshield-1_4_8.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). Note that a zip file is provided on the Developer Portal Document Center.
- Double click the reset button on the Adafruit board (NOT the Milli shield reset button!)
- The large LED on the Adafruit board will start to fade slowly. This indicates the bootloader is running.
- The bootloader will make available to your Windows system a File Explorer window for the Metro M0 Express USB drive (the METROBOOT disk). You should see a notification on your system indicating that a new disk called METROBOOT is available.
- Using Windows File Explorer, locate and open the METROBOOT disk (if the File Explorer window did not automatically open).
- Copy the mshield-1_4_8.ino.uf2 file to the METROBOOT disk.
- The Adafruit bootloader will automatically read this file and commit it to flash, and then automatically reset once complete.
- 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 Sensor API reference application!
Using a Development Environment (All Boards)
Itron currently recommends the use of the JetBrains CLion IDE for building and modifying the Sensor API reference package. CLion is a flexible IDE that easily supports the GNU set of cross compilers as well as the Segger J-Link debug probes. This IDE allows for straight forward porting of the Sensor API package to different MCU boards.
Detailed instructions on setting up the CLion development environment and building the Sensor API reference package are provided here.
The following CoAP client can be used to communicate with a Milli Dev Kit:
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 AppInstalling the DHT-11 Temperature Sensor
Additinal information on seting up the DHT-11 temperature sensor is provided in this section. 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 of the Milli Developer Kit with the DHT-11 temperature sensor:
Install the 4-Pin DHT11 Sensor Hardware
See image below for a visual reference to the 4-pin DHT-11 temperature sensor with a 10K Ohm pull-up resistor:
To connect the Adafruit DHT11 to your Milli Developer Kit stack:
- Connect the Ground wire to the Milli shield GND.
- Connect the VCC wire to Milli shield 5V.
- Connect the Signal wire to Milli shield Analog Input A4.
Note: In the below image, the blue wire is connected to Digital Pin 7 instead of A4
<<Why?>> - Connect the 10K Ohm pull-up resistor between VCC and Signal
Add Your Own Sensor
For more information on adding more sensors using Sensor API click here.
CoAP Temperature Sensor Resources
Available Resources
The following CoAP resources are made available by Sensor API for the temperature sensor. These resources would be used in conjunction with a CoAP client.
Resources are described by the following:
- A method (GET or PUT)
- A URI to specify the resource name
- A query string
The following CoAP resources are made available by Sensor API for the temperature sensor. These resources would be used in conjunction with a CoAP client.
Resources are described by the following:
- A method (GET or PUT)
- A URI to specify the resource name
- A query
The URI is composed of three parts: /<prefix>/<classifier>/<sensor name> where
- <prefix> is always “snsr”
- <classifier> defaults to “arduino” but can be changed programmatically
- <sensor name> is the name of the sensor, in this case it is “temp”
To set the temperature sensor configuration:
- PUT /snsr/arduino/temp?cfg=C
- PUT /snsr/arduino/temp?cfg=F
To get the temperature sensor configuration:
- GET /snsr/arduino/temp?cfg
To read the temperature sensor:
- GET /snsr/arduino/temp?sens
To request an observe on the temperature sensor:
- GET /snsr/arduino/temp?sens with the CoAP observe option set
Getting Device Time
To get the current network time setting of the device (which is automatically kept by Sensor API) use the following resource:
- GET /snsr/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
- 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
- Connect the Smart Cable to the diagnostic port
- Ensure that the Terminal Emultaor (such as a Tera Term) is:
- Configured with a Baud Rate of 115,200
- Connected to the COM port associated with the Smart Cable
- 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 following pages for directions on upgrading the Mill Dev Kit firmware and how to configure Mill Dev Kit firmware or set firmware sysvars.
CoAP Client Options
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.
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 Milli Developer Kit based sensor devices. Follow the instructions to install the client application.
Other Clients
Almost all CoAP Core implementations include sample CoAP clients. Some work better than others. All have limitations and bugs.
CoAP Gateway
Integral to the Itron network is a CoAP proxy that provides user authentication and security support. Please refer to the CoAP Gateway API for details on Gateway specific CoAP resources and Gateway session management. For access to a Milli Developer Kit HDK, all CoAP requests must proxy through the Gateway. Not direct to device CoAP is supported.