This document provides information for third-party developers about a companion application that is provided with Itron Networked Solutions developer kits. The developer kits enable third parties to develop and attach supported sensors to a Itron Networked Solutions network.
Specifically, this describes a Windows CoAP client user interface provided with the developer kits.The Windows CoAP client provides the ability to communicate via CoAP with a network device. A common use case is to retrieve data from a sensor device connected to a developer kit. This document explains general operation of the client.
By integrating with a developer kit on an Itron Networked Solutions network, sensor devices communicate using the Constrained Application Protocol (CoAP). Communciations with the end devices is facilitated through a CoAP API.
The Milli Dev Kit 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 can reach the sensor by sending requests to the CoAP API. 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 Windows CoAP client communicates with the sensor device via the CoAP Gateway. The Gateway requires that the Dev Kit is registered, and that the NIC/Milli in the kit is able to reach the network. The client calls the Data Platform devices API to obtain a list of devices and their respective resources. CoAP operations such as GET and PUT are sent and their responses are received via the Gateway.
The Windows CoAP Client interface makes use of two APIs:
- Data Platform API: Used to acquire a list of devices registered with Itron Networked Solutions for a specified API key and to ping devices to verify they can be communicated with across the network.
- CoAP API: Used to perform CoAP operations through the Itron Networked Solutions CoAP Gateway and subsequently with the HDK itself.
Upon starting the Client application, a prompt for SFDP API credentials appears. These credentials will be used to acquire a set of resources for each device associated with you. Any devices not plugged in or too far away from an AP will show as unreachable. The client will then issue a Gateway call to display all resources identified with each reachable device.
Reaching Your Devices and Resources via the Gateway
Devices registered to you are provisioned to the Data Platform.
Accessing Registered Devices
Each user is granted credentials consisting of a client ID and a client secret. A list of available devices is retrieved through device API calls. Each API call requires a token. The token is passed as an HTTP request under the Authorization header and is established by first posting the credentials. The POST response includes the token, assuming that you specify the correct credentials. Tokens are typically valid for an hour; after that, a new token must be obtained.
Each call to the Data Platform consists of a GET or a POST operation with the token attached. Therefore, the Data Platform API expects the use of a Uniform Resource Identifier (URI) to specify the kind of request being made.
For purposes of the demonstration client, Itron Networked Solutions wraps all calls necessary to obtain the device list, then pings the devices found to confirm their readiness. The class CoApDeviceFinder is used to fetch the devices. A class called CoApDevices is returned by the LoadNodes method.
Fetching Resources Related to a Device
Resources are fetched on a per-device basis through the CoAP Gateway API. The CoAP Gateway requires a different set of credentials consisting of a username and password. Initially, the credentials are used to establish a socket. This socket is then used for all subsequent communication. The CoAP Gateway performs address resolution for the client and MAC address translation into URIs; these URIs include a request to the CoAP server.
Currently, the string format is SSNmacid.<network URI>; for example, SSN001350050011D7C2.API.COAP-STAGING.DEVELOPER.SSNI.COM:5683/.core/well-known. The client must use a host name that has been registered with the gateway. The Windows CoAP client discovers available CoAP resources for device MAC addresses by performing a GET ./well_known_core operation for each one. The Windows CoAP Client client uses the response to populate CoApResource objects.
The CoAP Gateway supports up to 10 concurrent sessions per user. These sessions are established using the credentials discussed in the previous section, Fetching Resources Related to a Device. Each instance of a PUT, DELETE, or GET operation use a single session (if an open session is available). Each session can take up to four hours to expire, and is associated with a socket (a CoApGatewaySessionManager class was created for this purpose). PUT, DELETE, and GET operations all call this class to acquire open sessions. If no sessions are open, the class uses previously-captured credentials to acquire one.
When the application is ready to close, the Shutdown() method of this class should be called to terminate the currently open session, and to clean up any related socket resources (thus not leaving any orphaned sessions in place). Note that observe functionality is possible due to the fact that the socket connection between the client application and the CoAP server remains the same throughout the entire observation process. Without maintaining the socket connection, the server would not know where to send subsequent responses.
Interacting With Resources
Resources, simulated or real, can support the standard GET/PUT/DELETE CoAP requests and responses. The image below illustrates a GET Request.
The Windows CoAP client 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 SFDP API calls the NewtonSoft JSON serializer/deserializer.
The classes described in this document were 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.
Client Application and Source Code Installation
The Windows test client application can be installed and run standalone.
To install and run a Windows test client standalone, obtain and run the installer HdkClientSetup.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 Client…” icons on the desktop and in the program list. The executable in the folder is called HdkClient.exe.
To obtain any of these items, contact your Itron Networked Solutions representative.
Download and run the installer HDKClientSourceInstaller.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 Client Source\). The installation includes 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.
- DotNetHdkClient: The main client application source code directory. The Visual Studio solution DotNetHdkClient.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 DotNetHdkClient.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 “HdkClient” 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).