Start building your IoT solution with Itron's SLV Platform Create an Account

 

Sensor API is a platform for quickly building Milli5-based IoT solutions that leverage Itron's network infrastructure.  SAPI includes a complete CoAP Server Library that is pre-integrated with the Milli5 module, as well as a simple API for connecting sensors to a network using Milli.  SAPI takes care of network communications details, so you can focus on your sensor applications!

 

Overview

 

Sensor API (SAPI) provides an easy way to add sensors to any Milli based project using the CoAP Server. SAPI is composed of a set of API calls that have been added to the Itron Reference CoAP Server, SAPI frees the developer from needing to know anything about CoAP as the CoAP Server is embedded within.

Sensor API is made available in the hdkmshield project in the Developer Program GitHub (see the reference link in the sidebar), which provides stand alone code based on CMSIS.

 

SAPI Features

 

Sensor API makes it easy to enable the following features for your sensors:

 Provide a response to a sensor CoAP GET request
 Provide a respsone to a configuration CoAP GET request
 Handle a configuration request PUT request to change a sensor's configuration
 Generate periodic observation notifications to upstream systems
 Generate ad-hoc observation notifications to upstream systems

 

The Sensor URI

Sensor API requires a specific URI and CoAP methods be used in developer client software and infrastructure:

 

SENSOR CoAP URIs
URI Query CoAP Method
snsr/arduino/<device type> sens GET
snsr/arduino/<device type> cfg GET
snsr/arduino/<device type> cfg PUT

 

Note that both the middle "classifier" part of the URI ("arduino" in the above table) and the query parameter names can be changed by the developer to support a custom API experience.

 

Sensor Application Flow

 

Sensor API follows the basic arduino application flow (setup and loop).

 

In Setup:

 Initialize the SAPI framework (and indirectly the CoAP Server)
 Register one (or more) sensor(s)
 Initialize one (or more) sensor(s)

 

In Loop:
 Call the SAPI framework run method
 Handle requests based on interrupt handlers

 

Sensor API Architecture

Sensor API (SAPI) includes two primary components, a CoAP Server framework that interacts with the Milli module and exposes your sensor data as CoAP resources to the network, and an application programming interface (API) that you invoke to register your sensors with SAPI and send data over the network. SAPI abstracts your application and sensor code from the details of the Milli, the CoAP server, and network interaction.  SAPI runs on your application processor, and handles the details of communicating with the Milli module using HDLC over a UART interface.  The diagram below represents the SAPI architecture, and also shows which solution components are provided by Itron SAPI (in yellow), and which are provided by the partner (in blue).

 

 

The code samples below show how SAPI is intialized, sensors are registered, and notifications are sent over the network from sensors.  For more information, see the Adding Sensors with Sensor API page. Additional information is provided in the Sensor API User's Guide.

 

Initialize the SAPI Framework

/**
* @brief SAPI Initialization.
*
* Call this function first in your init initialization code (after the bootstrap  code).
* This function will initialize the underlying CoAP Server, the RTC, the SAPI  framework
* and will send the milli a reboot message.
*
* The classifier is used to identify the first level CoAP request handler. A sensor  URL is composed of
* a {prefix} like "snsr", a {classifier} like "arduino", and a sensor resource like  "temp".
* A typical URL would look like this: /snsr/arduino/temp.
* The {prefix} is stripped off by the Milli CoAP Proxy.
*
* @param url_classifier     URL classifier string. If NULL the default is "arduino".  Max length 16 characters.
*/

void sapi_initialize(char *url_classifier);

 

Register a Sensor

/**
* @brief Register a sensor.
*
* Use this function to register sensor. Usually call this in your initialization code  (after the bootstrap code).
* Your sensor code needs to provide a number of callback functions. A sensor package  can support any number of sensors.
*
* Note: 4 sensors max are supported by default (that is you can make 4 registration  calls).
* Note: At this time the CoAP Server will only support one sensor for observations.
*
* @param sensor_type     Sensor device type. For example "temp". Used in client URI's  and MQTT Topic Names.
* @param sensor_init     Pointer to the sensor initialization callback function.
* @param sensor_read     Pointer to the read sensor callback function.
* @param sensor_readcfg  Pointer to the read configuration callback function. If not  supported set to NULL.
* @param sensor_writecfg Pointer to the write configuration callback function. If not  supported set to NULL.
* @param is_observer     Set to 1 if this sensor is to generate observation  notifications. Set to 0 if not.
* @param frequency       Periodic observation generation frequency (in seconds).
* @return Sensor Id.
*/

uint8_t sapi_register_sensor(char *sensor_type, SensorInitFuncPtr sensor_init,  SensorReadFuncPtr sensor_read, SensorReadCfgFuncPtr sensor_readcfg, SensorWriteCfgFuncPtr  sensor_writecfg, uint8_t is_observer, uint32_t frequency);

Initialize a Sensor

/**
* @brief Initialize a sensor (hardware) and sensor related code.
*
* Use this function to do any initialization your sensor code and sensor hardware  required.
* Note that this function will call the sensor init function provided to the  sapi_register_sensor function.
*
* @param sensor_id Id of the sensor to initialize (returned by sapi_register_sensor).
* @return SAPI Error Code
*/

sapi_error_t sapi_init_sensor(uint8_t sensor_id);

 

SAPI Notification Calls

This function pushes a sensor value update to upstream systems immediately over the network.

/**
* @brief Function used to push a notification.
*
* Use this function when your sensor (and code) determines that a message (aka alert)  needs to be pushed
* up to an "application" for processing.
*
* @param sensor_id Id of the sensor to generate an observation notification for.
* @return SAPI Error Code
*/

sapi_error_t sapi_push_notification(uint8_t sensor_id);

Callback Function - Sensor Initialization Handler

/**
* @brief Typedef sensor initialization function pointer.
*
* Callback by SAPI from sapi_init_sensor. It should contain any code needed to initialize the
* hardware sensor and the related sensor code.
*
* @return SAPI Error Code.
*/

sapi_error_t (*SensorInitFuncPtr)();

 

Callback Function - Sensor Read Handler

/**
* @brief Typedef sensor read callback function pointer.
*
* Callback by SAPI in response to a CoAP GET "sens" request.
*
* @param payload Char pointer to the payload. Copy the sensor payload to be returned.
* @param len     Pointer to the payload length. Set the sensor payload length to be  returned.
* @return SAPI Error Code.
*/

sapi_error_t (*SensorReadFuncPtr)(char *payload, uint8_t *len);

Callback Function - Config Read Handler

/**
* @brief Typedef sensor read configuration callback function pointer.
*
* Callback by SAPI in response to a CoAP GET "cfg" request.
*
* @param payload Char pointer to the payload. Copy the config payload to be returned.
* @param len     Pointer to the payload length. Set the config payload length to be  returned.
* @return SAPI Error Code.
*/

sapi_error_t (*SensorReadCfgFuncPtr)(char *payload, uint8_t *len);

 

Callback Function - Config Write Handler

/**
 * @brief Typedef sensor write configuration callback function pointer.
 *
 * Callback by SAPI in response to a CoAP PUT "cfg" request.
 *
 * @param payload Char pointer to the payload. Process the payload to extract configuration.
 * @param len     Pointer to the payload length. Length of the config payload.
 * @return SAPI Error Code.
 */

sapi_error_t (*SensorWriteCfgFuncPtr)(char *payload, uint8_t *len);

Temp Sensor Main Line Code

Using SAPI, here is the main line code for a reference temperature sensor.  This code is provided in the Sensor API reference solution source code on GitHub.

 

#include <Arduino.h>
#include "sapi.h"
#include "TempSensor.h"

static uint8_t temp_sensor_id;

//
//  Setup function.
//
void setup()
{
    sapi_error_t rcode;

    // Initialize Sensor API
    sapi_initialize(NULL);
    
    // Register temp sensor
    temp_sensor_id = sapi_register_sensor(TEMP_SENSOR_TYPE, temp_init_sensor, temp_read_sensor, temp_read_cfg, temp_write_cfg, 1, 180);
    
    // Initialize temp sensor
    rcode = sapi_init_sensor(temp_sensor_id);
}

//
// Application loop function.
//
void loop()
{
    // Call SAPI run to do the heavy lifting
    sapi_run();
}