COAP APIs

Working with Constrained Application Protocol

Find Your Solution Today. Create an Account

Working with CoAP allows you to access raw device data streams and develop your own applications and interfaces for working within Itron networks.

Developing with CoAP

The most common use case for developing with CoAP is when you would like to make use of the raw network traffic and device data to develop your own custom applications or integrate directly to devices that communicate on an Itron network..

Gateway Description

CoAP Gateway is a UDP-based Constrained Application Protocol (CoAP) service that provides a session management interface. Gateway also acts as a forward proxy for Read/Write access to devices on the Itron mesh network. Users of this API and documentation are expected to be familiar with CoAP functionality.

We highly recommend that you get familiar with CoAP and Itron's implementation of the protocol by reading the CoAP Overview.

 

Here are links to the primary CoAP specifications. It is a good idea to be familiar with these specifications:

  • RFC 7252 - The Constrained Application Protocol (CoAP)
  • RFC 7641 - Observing Resources in the Constrained Application Protocol (CoAP)

 

The Itron CoAP Gateway functions as a standard CoAP forward proxy and its usage primarily follows the CoAP standard. Therefore, it can be implemented with any CoAP framework that also follows the standard. In fact, the Gateway service is implemented using the nCoAP framework (see sidebar).

 

Note: The Firefox Copper (CU) CoAP add-on is not supported at this time.

Available CoAP API

Any CoAP options specifically supported by the CoAP Gateway will be described in its CoAP standard CoRE resource .well-known/core. For details on the features supported by CoAP Gateway, please visit here. APIs are known by their resource URIs.

Milli CoAP API URIs

The Itron Milli NIC supports the following URIs:

URI
Method
CoAP Content Format
Comments
/
GET
text/plain
Returns the Milli CoAP server/proxy version string
/.well-known/core   
GET
application/link-format
Returns supported URIs to the next level down, including application processor sensor URIs
/sys/stats?pwr
GET
application/octet-stream
milli Power Stats Definitions  Expand source
struct power_stats {
    /* These are currently in units of 125ms (bottom 3 bits are sub-second) */
    uint32_t total_time;
    uint32_t sleep_time;
    uint32_t standby_time;
    uint32_t rfc_time;
    uint32_t sfl_time;
    uint32_t nxp_time;
    uint32_t tx_bytes;
    uint32_t rx_time;
    uint32_t charge_ctr_low;
    uint32_t charge_ctr_pause_max;
    uint32_t bat_voltage; /* micro Volts*/
};
typedef struct {
    coap_sens_tl_t tl;          /* type and length */
    char pad[2];                /* align */
    struct power_stats ps;      /* Power stats, all devs */
} coap_sys_pwr_stats_t;
PUT
None
Clear stats
/sys/cfg?pwr
GET
application/octetstream  
Only supported query is pwr for retrieving and storing power information, described here. Not CBOR encoded.
PUT
/sys/snsr?ev=rbt
PUT
None
This is not intended to be used by CoAP clients, rather the CoAP server running in an application processor attached to a MIlli to notify the milli that is has rebooted. The Milli responds by sending CoAP requests to the app processor to set network time and establish observations.

 

Device IC API

The following CoAP URIs must be supported by the CoAP server running on the application processor. The default value of {prefix} is "snsr" in firmware version 1.2.1000 build 117958 and later (it is "sensor" in firmware version 1.2.1000 build 112738 and earlier). When the Device IC receives the request from the Milli, {prefix} will have been stripped from the Uri-Path options. On highly resource-constrained devices, these URIs can be shortened to reduce memory requirements or increase sensor payload size.

URI
Method
CoAP Content Format
Comments
/{prefix}
GET
text/plain
Returns the application processor CoAP server version string
/{prefix}/.well-known/core
GET
application/link-format
Returns supported URIs to the next level down
/{prefix}/sys/time
GET
4 byte binary
Retrieve system time from the application processor CoAP server, network order time_t.
PUT
application/octet-stream

Set the system time on the application processor CoAP server. Currently supports absolute time setting, not incremental. Not CBOR encoded.

Set the system time on the application processor CoAP server. The Milli uses this URI to set the time on the application processor CoAP server in response to at PUT to /sys/snsr?ev=rbt  (see above), a NIC reboot, and mesh network time updates (sent to the NIC approximately every 12 hours). It currently supports absolute time setting, not incremental. Format: Type-Length-Value

1 byte type: 0
1 byte length: 8
1 byte length: 8
2 bytes pad
4 bytes network order seconds since epoch
4 bytes network order milliseconds since epoch

/{prefix}/sys/reset
PUT
-
Reset the device and reboot the application processor CoAP server
/{prefix}/sys/ntf
PUT
None
This is a recommended URI to allow the Milli to notify the application processor CoAP server of events that may be of interest, such as a low battery alert. The payload is a 4 byte event value in host order.
 
Event
Value
Device entering storage mode
1
Device entering service mode
2
Low battery alert
3
Tamper alert
4

 

Address Resolution

CoAP Gateway is accessible from the internet at a domain name which is referred to throughout this document as “gatewayhost."

CoAP Gateway performs address resolution for a CoAP client. So, in order to access a device on the mesh, you must provide the hostname with which it registers with a Itron network DNS server. This is referred to throughout this documentation as "domain." To access a device on the mesh the name is comprised of the prefix "ssn", the MAC address of the NIC in upper case with no colons, and the domain.

ssn<macid>.<domain>

For instance,

ssn0013000300358F2D.SG.YEL01.SSN.SSNSGS.NET

The applicable values for the Itron Starfish Networks are provided in the following table:

Network
Gatewayhost
Domain
Starfish
api.coap-staging.developer.itron.com
sg.yel01.ssn.ssnsgs.net
Any other
Ask your Itron representative
Ask your Itron representative

 

Ports

A typical CoAP client request will have three ports specified in it (remember that access to the Itron network uses a CoAP proxy). Here we use the Java CoAP Client:

 

java -jar sdkcoapclient-1.4.6.one-jar.jar --method GET –clientPort <client port> --proxyHost gatewayhost --proxyPort <proxy port> --deviceHost domain --devicePort <server port> --devicePath /.well-known/core

An specific example with port numbers might look like the following:

java -jar sdkcoapclient-1.4.6.one-jar.jar --method GET –clientPort 6000 --proxyHost api.coap-staging.developer.ssni.com --proxyPort 5683 --deviceHost SSN001350050047dc98.SG.YEL01.SSN.SSNSGS.NET --devicePort 4849 --devicePath /.well-known/core

 

To break that down:

  • Client Port - the port that the client uses to send/receive CoAP traffic for this command. This is specified using the "--clientPort" option. In this example the client is going to use port 6000 on the local machine to send/receive traffic. As described above it is very important to use client port option consistently when communicating with Gateway as the Gateway associates the client port with the session.
  • Proxy Port - the port that the CoAP proxy (i.e. Gateway) is listening for traffic on. This is specified using the "--proxyPort" option. In this example the client is sending requests through the proxy gatewayhost on port 5683.  In the Itron networks, Gateway listens on port 5683 so this should always be used when using the CoAP API on these networks.
  • Server Port - the port that the CoAP server (running on the Milli device) is listening for traffic on. This is specified using the "--devicePort" option. This port will alwas be 4849.

 

Itron Milli NICs are only enabled to communicate on the secure port 4849 (the default port 5683 is not enabled) so this must always be used when communicating with these devices.

 

It is valid to tell a CoAP client to use a client port of 5683 as long as a CoAP server is not running on the same system and already using that port. However, it can be confusing to differentiate the meaning and destination of commands if client and proxy are all using the same ports.  The examples below will use 6000 as the client port for clarity.

 

Security

CoAP client calls to the Gateway are secured using an authenticated session. Authentication requires use of a JWT token (which can be obtained using the Starfish Data Platform tokens API) to establish a CoAP Gateway session. Details of API authentication can be found in the Security section of the API Overview page.

 

Sessions

Sessions are associated with the client account configured on the CoAP Gateway. The Starfish configuration allows for a maximum of 50 concurrent sessions per account, but each must bind to a unique socket (port) on which to receive its responses. By default, the Gateway is configured to close sessions that have been idle for more than ten hours. Sessions can also be closed explicitly via a DELETE operation on the Gateway "/sessions" API.

 

Establishing a session

CoAP clients must use a JWT token (which can be obtained using the Starfish Data Platform tokens API) to establish a CoAP Gateway session.  Refer to the Security section of the API Overview for security, authentication, and how to obtain a token to call APIs. The session is established by POSTing the token as a plain text UTF-8 payload to the Gateway's /sessions resource.

Here is an example using the the libcoap sample client (note the token is hard coded):

 

  • The "-t 0" specifies the content type of the message as UTF-8.
  • The "-f -" means that the content should be read from STDIN (i.e. the echoed text)

 

As a convienence, the Java CoAP Client obtains a token for you every time you establish a CoAP Gateway session (by using the clientId and clientSecret specified). The session is established by making a POST CoAP request to the Gateway /sessions resource. Here is an example using the Java CoAP Client and a conf file:

java -jar sdkcoapclient-1.4.6.one-jar.jar --conf getsession.json

The contents of the getsession.conf file:

{
  "clientPort": "6000",
  "method" : "POST",
  "clientId": "<your clientId>",
  "clientSecret": "<your clientSecret>",
  "devices": [
    {
      "deviceHost": "api.coap-staging.developer.itron.com",
      "devicePort": "5683",
      "devicePath": "/sessions"
    }
  ]
}

 

The session will be rejected if the user authenticators are invalid.

 

Terminate a session

Once you are finished, you SHOULD delete your session. To close a CoAP Gateway session on port 5683:

java -jar sdkcoapclient-1.4.6.one-jar.jar --conf deletesession.json

The contents of the deletesession.conf file:

{
  "clientPort": "6000",
  "method" : "DELETE",
  "devices": [
    {
      "deviceHost": "api.coap-staging.developer.ssni.com",
      "devicePort": "5683",
      "devicePath": "/sessions"
    }
  ]
}

 

If the session is successfully deleted Gateway will respond with a DELETED_202 (message code 66) message.  If the deletion fails for any reason Gateway will respond with a PRECONDITION_FAILED_412 (message code 140) response.

 

Session timeout

Idle sessions are removed from the Gateway. A session is considered idle if traffic has not been sent or received between q CoAP client and Gateway for more than the configured session idle time (defaults to 10 hours). If a CoAP client wants to ensure that its session remains active it can periodically issue requests to one of the Gateway local CoAP resources such as /.well-known/core, /echo or by issuing a CoAP ping (resource "/") against Gateway to generate traffic without burdening the mesh. Traffic generated by CoAP observations generated by CoAP servers running on the mesh also counts as activity. When a session times out, Gateway will send the client a non-confirmable CoAP response SERVICE_UNAVAILABLE_503 (message code 163) message.

Any further requests made on a closed session will be rejected with a UNAUTHORIZED_401 (message code 129) response, indicating that the client needs to re-authenticate.

 

Testing with libcoap 

To get the CoAP client and server programs in your path for testing purposes, you can install libcoap and test CoAP calls as shown in the examples below. 

 

Examples

Given CoAP Gateway running on gatewayhost (see table above) and a device (aka "server") running on NIC mac address 001350050005E7D6 (SSN001350050005E7D6) at domain (see table above), libcoap can be used to test as in the examples below.

Establish a Connection

To establish a session for UDP traffic on port 12345:

 

Get CoAP Resources 

To get CoAP resources on the device NIC behind the CoAP Gateway proxy:

coap-client -v 10 -m get -p 12345 -P gatewayhost:5683 coap://SSN001350050005E7D6.domain:4849/.well-known/core

Example (note in the example the server port has been left out which will use unsecure port 5683 - this would not work with a Milli NIC which requires 4849):

 

 

Get NIC Time 

To get the time on the device NIC behind the CoAP Gateway proxy for NICS that support it (Milli does not support time):

coap-client -v 10 -m get -p 5683 -P gatewayhost:5683 coap://SSN001350050005E7D6.domain:4849/time

Example (note in the example the server port is the unsecure port 5683 - this would not work with a Milli NIC which requires 4849):

 

 

 

 

 

 

 

 

Get NIC GPIO Pin Description 

Note: the Milli NIC does not currently support any GPIOs. This example is for illustration purposes only.

To get a description of the GPIO pins available on the device NIC behind the CoAP Gateway proxy:

coap-client -v 10 -m get -p 5683 -P gatewayhost:5683 coap:// SSN001350050005E7D6.domain:4849/gpio

Example (note in the example the server port is the unsecure port 5683 - this would not work with a Milli NIC which requires 4849):

 

 

 

 

 

 

 

 

Terminate a session

Once you are finished, you should delete your session. To close a CoAP Gateway proxy session on port 12345:

 

Attempt to Get CoAP Resource Not Implemented 

Attempting to get a CoAP resource that has not been implemented on a device behind CoAP Gateway proxy should result in a “5.01 Not Implemented” error. 

coap-client -v 10 -m get -p 5683 -P gatewayhost:5683 coap:// SSN001350050005E7D6.domain:4849/dummy

Example:

 

 

 

 

 

 

 

Attempt to Get CoAP Resources without a Session or without Permission

Attempting to access a device behind CoAP Gateway proxy without a session should result in a “4.01 unauthorized” internal error. Similarly, attempting to access a device without the appropriate permission should display the “4.01 unauthorized” internal error.

coap-client -v 10 -m get -p 5683 -P gatewayhost:5683 coap://devicehost:4849/.well-known/core

 

 

 

 

 

 

 

 

 

Seeking help from the CoAP Gateway

A client can send a request to coap://gatewayhost/help by issuing the following command: 

coap-client -m get -p 54321 coap://api.coap-test.developer.ssni.com/help

The Gateway responds with
v:1 t:CON c:GET i:40cf {} [ ]

To login, send POST to /sessions

To have your session follow your account across different clients, include the query parameter '&sticky=true'.

To logout, send DELETE to /sessions.

To echo a payload, send POST to /echo.