This document provides information for third-party developers about a companion application that is provided with the Itron Networked Solutions hardware development kit (HDK). The HDK allows third parties to develop and attach supported sensors to an Itron Networked Solutions mesh network.
The sample Windows CoAP Server application provides the capability for a third party to simulate a sensor device connected to the Milli HDK. Source code for the application is also available for Windows developers.
Itron Networked Solutions' Internet of Things (IoT) networking service that enables cities, utilities, businesses, and citizens to connect a wide range of intelligent devices and sensors to the network. Devices can be used to address requirements in a variety of sectors, including water, energy, food, transportation, and safety.
In a mesh network, sensor devices communicate using the Constrained Application Protocol (CoAP). Communications with the end devices is facilitated through the Gateway CoAP API.
The HDK contains a Milli module that communicates via an Access Point (or Mini AP) and over a WAN backhaul connection to the CoAP Gateway. A CoAP Client (such as the one provided with the HDK) can reach the sensor by sending requests to the Itron Networked Solutions Data Platform and Gateway APIs. The Milli contains a CoAP proxy server that communicates to an attached sensor via a UART interface using CoAP over HDLC. Embedded in the HDLC are CoAP calls that are handled by the sensor attached to the Milli.
The CoAP Server can assume the role of the sensor device by connecting it to the UART on the Milli HDK. The Server receives a CoAP message on the serial interface, prepares a response, and returns it on the same HDLC connection. It achieves this through the use of “plugins”.
The CoAP Server is written in open-source C# .NET, which, in turn, leverages other open source components. Some of the underlying CoAP implementation is taken from CoAPSharp, a C# implementation provided by EXILANT Technologies. Some sample code from the Data Platform API calls the NewtonSoft JSON serializer/deserializer.
The server provides the following primary features:
- Resource simulation
- Native NIC/Milli operations, including firmware image management and NIC/Milli-specific operations
- Diagnostic operations, such as plugin validation and review of recent CoAP requests and responses
- Tools for generating plugin shell code in the correct simulator format, and for extracting the core code for insertion into the final sensor server implementation
The default tab for the server shows all devices and related resources defined. These are not actual resources, but rather a description of the resources as they might appear if they represented actual sensors.
The “Debug Log” button launches the following window, allowing the user to View and Clear the log. The user can also specify the log level and maximum log size.
The plugin verification allows the user to verify a plugin. This is done by interrogating the loaded dll for entry points that the simulator expects to call. To validate a plugin, select the device and resource from the drop-down menus. The plugin associated with this device and resource should be displayed. Click “Diagnose” to check the plugin. The application will check the four parameters shown and mark the checkbox if the validation is successful. If there is an error during any of the checks, a message with information on the failure will be displayed.
The simulator expects plugins to be of a specific format. The tools tab includes a “Create Empty Resource Simulator” button which builds the appropriate resources required to build a plugin. Please see the later section for further details on creating plugins.
Writing a CoAP Simulator (Plugin)
To create a resource simulation, fill in the resource name and select a target location for the generated code. Then click the Create Empty Resource Simulator button. A new Microsoft Visual Studio project will be generated. The correct programming contract for the Simulator to recognize the result will be generated, as well as stubs for the processing of the standard CoAP functions (PUT, GET, etc).
Associating a Simulation With a Resource
In the “Simulator” tab, select the device under which the resource is to be simulated and click “Edit”.
Click “Add Resource”, create a path, browse to the location of the .dll plugin, set the link attributes, and then click OK to close.
Select “Save and Close” to complete the process.
The next time a discovery call is made to the device, the simulator will return this resource as part of the discovery response. If a GET/PUT etc is performed against this resource, the simulator will be called to perform the operation. The simulator will reply with the appropriate CoAP response.
The simulator described in this document has been written in C# and compiled using .NET Framework version 4.5.2 in Microsoft Visual Studio Professional 2015 running on Windows 8.1 Enterprise.
There are no .NET framework dependencies prior to .NET 4.0. However, you might need to use NuGet to obtain a version of System.Net.Http that is compatible with .NET 4.0.
For information about Windows requirements, go to Visual Studio 2015 System Requirements.
System requirements for earlier versions are typically smaller, so this establishes a reasonable minimum set of system requirements.
Server Application and Source Code Installation
The Windows CoAP Server application can be run standalone. To install, download and run the HdkCoAPServerSetup.msi file. You can choose to install the application to any directory on your hard disk or accept the default location. Shortcuts to the folder are added to the desktop and to the program list. Look for “Starfish HDK Server” icon on the desktop and in the program list. The executable in the folder is called HDKLocalCoapServer.exe.
To obtain any of these items, contact your Itron Networked Solutions representative.
Source Code Installation
Download and run the installer HDKServerSourceInstaller.msi file, which you can obtain from your Itron Networked Solutions representative. You can choose to install the source code to any directory on your hard disk or accept the default location (C:\Silver Spring Networks\Starfish HDK Windows Server Source\). The installation file will generate and populate the following subdirectories:
- coapsharp: A directory that includes the CoAP implementation from CoAPSharp, a C# application provided by EXILANT Technologies.
- Documentation: A directory containing this document.
- DotNetHdkServer: The main client application source code directory. The Visual Studio solution DotNetHdkServer.sln is located in this directory.
- SLDPAPI: A directory that includes sample code from Itron Networked Solutions Data Platform API calls and the NewtonSoft JSON serializer/deserializer.
Building the Solution
To build the solution, open the DotNetHdkSimulator.sln file in Visual Studio and perform the following steps.
- Verify that the solution is set to allow NuGet to download missing packages, and automatically check for missing packages during the build in Visual Studio (look in the Tools menu “NuGet Package Manager” options).
- Use the Package Manager Console (see the Visual Studio Tools menu) to restore any missing packages from online package sources.
- Verify that the project “HdkSimulator” is set as the startup project. If it is not, set it as the startup project by right-clicking on the project in the Solution Explorer and selecting Set as Startup Project.
- Rebuild the solution.
The solution can now be run from Visual Studio (just as the application client installed from the client executable installer can).