N2G Connected Home Service Delivery Platform Service...

N2G Connected Home Service Delivery Platform

Service Delivery Platform 2.0

Application Programming Interface

Use Case Document

Version: 1.0 - Bert Lutje Berenbroek

Date: 23-06-2015

REVISION HISTORY

1.0 First release 15 Jun 2015

Table of Contents

Introduction Architecture

Overview Technical Architecture

ZigBee Gateway Device (ZGD) Gateway IP Specification N2G’s SmartBridge

IP Host Application (IPHA) Message Queues

LAN API SDP API

General Security HTTPS Methods

Authentication API: oAuth Admin API: Account WAN API EnergyInsight API

Fetching Objects Fetching list of objects for a specific user

NET2GRID SDP API 1.0 - 1 / 47 -

Fetching list of objects & attributes for a specific user Attributes for one specific Energy Meter Query a property of an Energy Meter object between two timestamps

Refresh Objects Definitions

TABLE 1: SmartBridge Properties Energy Meter Properties TABLE 2: Household properties Meter Status replies Energy Meter Unit of Measures Metering Device Types Possible return values for measurements Attributes used by the Energy Meter object TABLE 3: Specific object commands HTTP Status Codes Result Types and Fields

Use Case Document TC001 ‐ SmartBridge installation & create account TC002 ‐ Connect SmartReader to SmartBridge TC003 ‐ Connect SmartSolar to SmartBridge TC004 ‐ Connect SmartPlug to SmartBridge TC013 ‐ SmartBridge factory new & delete account TC101 ‐ Check meter status


Introduction This document describes the exposed functionality of N2G’s Connected Home Service Delivery Platform (SDP). The SDP offers an online virtualisation of the physical world of devices in the internet of things. The SDP virtualisation allows users and Multi Service Organisations (MSO) to monitor, control and administer their devices. Interactions in the physical world are turned into online events, that can be logged, monitored and acted upon via the online SDP. Alternatively, by sending commands via the SDP, users can control their physical devices. This document serves as a guide to the web service interface of the SDP that allows Multi Service Organisations to define and implement their own end‐user services and front‐end applications. It also serves as a rough requirements document for a client‐side SDK for mobile apps.


Architecture

Overview

Most devices have a limited set of programmable attributes, such as on/off, open/close, start/stop, volume,

temperature, etc. Rather than making these devices smarter, the future of the industry is in connecting these

devices to a local hub, that is making the device controlling functions accessible via apps.

The N2G architecture is based on the concept that the hub, the SmartBridge , is providing the physical service and is kept lean and secure with minimal business logic. In Zigbee terminology, a device like the SmartBridge is called a

Zigbee Gateway Device (ZGD) .

The business logic is in the virtualisation layer in the Cloud, allowing manageability, scalability and flexibility of

services. N2G is combining these functions in the Service Delivery Platform (SDP) .

API’s Apps can access most N2G’s SmartBridge functions locally via WiFi and via the SDP cloud, both via a REST interface.

● LAN API This API allows for monitoring and local access, even when there is no connection to the Internet. The

SmartBridge has a local storage facility to accommodate this. However, normal operation is that the

SmartBridge is connected through the Internet to the SDP cloud, to allow e.g. remote management

outside the home environment, statistics and firmware upgrades.

● Cloud API’s

The Net2Grid SDP has two cloud interfaces:


○ WAN API

All functions that are directly related to ZGD and devices that can be performed without virtualization are in the Access API. This API stays close to particular IoT standards, such as Zigbee and Z‐Wave.

○ SDP API Functions that need virtualization concepts to abstract from the IoT standard and concepts to make tasks and devices easier to understand and visualize, are in the SDP API. The SDP API can have add‐ons and/or SDK’s for even more ease of use for App development

WiFi enabled devices can connect via a proxy to the SDP cloud, without being connected to the SmartBridge. Through the proxy N2G supports an OAuth 2.0 authenticated connection with the WiFi device for control and measurement via the SDP. A good example of such a WiFi device is the Nest thermostat. Parameters like humidity, inside, outside and target temperature are stored with the preferred resolution in the SDP. WiFi devices without an OAuth 2.0 cloud API can still be managed by the ZGD. Through the SDP, there is access to other devices on the LAN via a REST API,, thus allowing App developers access to devices that are on the same LAN as the ZGD. ZigBee

The current implementation of the N2G SDP supports the ZigBee protocol in a dual stack implementation. The ZGD supports the Home Automation 1.2 profile as a coordinator on Network 0 and either Smart Energy 1.x or Light Link 1.x as a Sleepy end device on Network 1. Other protocols like Thread can be supported through a firmware upgrade. The SDP and ZGD architecture however allows for abstraction of other radio’s like Z‐Wave, 915, 868 or 433 by adding additional radio’s either on board or through the USB extension slot of the ZGD..

Technical Architecture NET2GRID has adopted the ZigBee Gateway IP specification for it’s Connected Home Service Delivery Platform

(SDP) . This is an official Zigbee specification of a light‐weight communication protocol that can be used both over TCP and UDP. There is a stream of data from the sensor network gateway to the back‐office to report new sensordata (referred to as Reports ). There is also a stream from the back‐office to the sensor networks, used for actuation and ad‐hoc requests, these are called RPC’s (Remote Procedure Calls) . Reports and RPC’s are placed in the message queues in the back‐office, and these message queues serve as integration points to the rest of the system.


There are three main components of the system. First every sensor network has a Zigbee Gateway Device (ZGD) . On the back‐office there runs an IP Host Application (IPHA) maintaining connections to the ZGD’s and using Message Queues for communication with the rest of the back‐office services.

ZigBee Gateway Device (ZGD) The ZGD acts as intermediary between the back‐office and the sensor nodes and can translate the ZigBee node messages sending them over the internet to the IPHA. The NET2GRID SmartBridge is a separate device that acts as ZGD gateway for the rest of the network, but it is also possible to integrate ZGD functionality in an existing device with internet access for a standalone solution.

Gateway IP Specification The Gateway IP specification is authored by the ZigBee Alliance and defines the protocols for interaction between gateway devices and clients. There is quite an extensive document detailing the specifics, but here is a quick summary. The communication can work over multiple transport modi (UDP, TCP, TCP_SSL), with a configurable security level (encryption and authorization), using different message formats (SOAP, REST, ASN encoded‐bytestream). N2G has opted for a TCP connection that is encrypted by SCoP, with the data encoded as ASN1.0 bytestreams. It is possible to use UDP to decrease the overhead, but this lacks the internal retries of the TCP protocol. These retries then need to be programmed on the NHLE layer. There are three layers of interest:

● Secure Communication Protocol (SCoP)

SCoP is the layer of the protocol that handles security and connection management. This is an abstraction layer above the transport modus, making both TCP and UDP “connection oriented” when using SCoP. In the SCoP Information Base it is possible to supply different security credentials and options for the different connections. It uses keepalives to keep track of the connection’s status.

○ 1 ZigBee Document 075468r35 Network Device Gateway Specification ● Gateway Remote Interface Protocol (GRIP)

GRIP is the layer that receives requests from the layer above it, wraps it with metadata and sends it to the SCoP layer. It couples responses it receives from the SCoP layer to the original requests. GRIP dictates possible data formats for specific requests/calls.


● Next Higher Layer Entity (NHLE)

The layer on top of GRIP contains the functionality and integration with the rest of the system / device / network. It converts the messages from the system to valid GRIP messages, and vice versa.

N2G’s SmartBridge N2G has developed its own hardware version of the ZGD called the SmartBridge. The current production version of the SmartBridge is Rev.10:

● EM3585 ZigBee ARM Cortex‐M3 Main application processor ● W5200 TCP/IP Co‐processor ● Serial Memory EEPROM & Flash ● User interface ‐ 3 color LEDs ● Temperature sensor

With the Rev.10 SmartBridge, N2G has succeeded to develop a ZGD with the following key advantages:

● Low Bill of Material (BoM) ● Tight integration with key peripherals (ZigBee & TCP/IP) ● 433 Tx support ● P1 SmartMeter interface & UART ● High Security (Elliptic Curve Signatures on firmware, CBKE and Link Key support, ASN encrypted SDP

interface, Hard‐wired IP stack) ● Flexible Home Network connectivity options ● Firmware upgradable (OTA) ● Low power consumption (<1W) ● Small form factor

The SmartBridge design is available as a license for OEM customers. Firmware Specification

● Application agnostic ZigBee/IP gateway ● Scalable/secure IP based WAN protocol ● REST based protocol for LAN control ● Dual stack supports simultaneous ZigBee Home Automation & Smart Energy networks ● mDNS/LLMNR for LAN device discovery ● Application intelligence for fully independent (offline) Intruder Alarm System ● Local energy data storage for offline historical meter data

○ Power consumption per minute stored for 1 month ○ Total energy delivered/received per hour stored for 1 year ○ Total energy delivered/received per day stored for 5 years

● Command scheduling ‐ examples: ○ Turn plug off at 11:30pm every weekday ○ Read metering data every 90 seconds

● Security ○ Elliptic Curve Signed firmware ○ ASN1.0 Bytestream encrypted cloud communication ○ Hard wired IP stack ○ Install Code support pre‐commissioned nodes ○ CBKE link key encryption for SEP nodes


IP Host Application (IPHA)

The IPHA is very similar in functionality to the ZGD, but runs on the back office. It maintains connections with all it’s associated ZGD’s. It is designed to be as lightweight, non‐blocking and multi‐threaded. Therefore a single IPHA can handle thousands or more ZGD connections. Basically the IPHA acts as intermediary between the ZGD’s and the messages put on the messages queues. The IPHA is written in Java and uses Akka Futures for its concurrency model, and Netty for the transport layer. This implementation is generic and free of specific domain logic, it’s primary purpose is to act as a proxy between the rest of the services and the sensor network.

Message Queues

The IPHA integrates with the rest of the back office through various message queues. The current message queue broker is RabbitMQ, although the principle stands for most of the message queue variants. There are multiple types of queues

● RPC Queues ● Report Queues ● Connection Event Queue ● Discovery Event Queue

The IPHA listens on the RPC Message Queue for new RPC calls which the IPHA wraps in GRIP/SCoP and then send it to the ZGD over it’s preferred transport mode. It also receives reports from the ZGD, which the IPHA unpacks and places on the report queue. Whenever there are changes in the connection status of a ZGD a message is placed on the Connection Event Queue. Whenever a discovery event occurs, (for instance, a node joins or leaves the sensor network), the message is posted on the discovery event queue. Other services can listen on these queues, or post in an RPC queue.

LAN API

The LAN API is described on the N2G developers page: http://developer.net2grid.com/documentation/api/embedded/ The LAN API is a JSON restful API allowing application developers to manage the ZGD and all nodes on the ZigBee network. There are 5 categories of API calls:

● Zigbee Networking Interface ● Gateway Admin ● Scheduled Functions ● Energy History ● Intruder Alarm System

The swagger API description is hosted on the ZGD allowing developers to test API calls in the swagger user interface via the “Try it out!” button. Within the call, the model schema needs to be selected and the parameters can be filled in the window on the left.


The ZGD is hosting a webpage with limited information and user management. The ZGD is supporting both mDNS

and LLMNR LAN device discovery. THe URL is: http://smartbridge.local/


We are using postman to test our API’s: https://www.getpostman.com/ Below you will find an example to toggle a plug:


SDP API

General

The solution consists of two interfaces. One on the level of user administration, to fetch a list of all the portals a user has access to. The other is on the level of a specific portal and allows the client to request data about associated objects. The structure of the webservice is largely influenced by OData and GData formats. (more ATOM related than the SDP API) The URL for the NET2GRID development SDP is: https://ipha‐web.net2grid.net

Security

Requests are done over Secure HTTP with HTTPS oAuth 2.0 authentication. Applications are required to Authenticate through a CLIENT_ID and CLIENT_SECRET.

HTTPS Methods

The different HTTPS methods that can be used all represent a different type of action. So, the same URL, can mean something else when send using POST as compared to sending it using PUT or DELETE.

GET Fetching an object, list of objects or results

POST Create a new object

PUT Update an existing object

DELETE Delete an existing object

SDP Categories The Service Delivery Platform API is consisting of 4 categories:

● Authentication ● Administration ● ZGD WAN ● Energy Insight

All API’s are described in swagger at the link below:

http://developer.net2grid.com/documentation/api/sdp/


Authentication API: oAuth The oAuth API is described on the N2G developers page:

http://developer.net2grid.com/documentation/api/oauth/

With the account username and password, a oAuth token can be created to be used in both the SDP and WAN API

calls.

In order to use the ADMIN account creation API calls, the oAuth token requires the login credentials of a

management user. The WAN and EI API’s can be used both with a management and a user account. The user

account will only be able to control the gateway and network of the ZGD connected to the user account (WAN) and

the Domain Objects the user has rights to (EI). The management account will have control over all ZGD’s and DO’s

to be used in management and support portals.

Tokens are valid for one hour, if the token is expired, the API will give this error message:

{ "error" : "expired_token" ,

"error_description" : "The access token provided has expired"

}

Admin API: Account The ACCOUNT API is described on the N2G developers page:

http://developer.net2grid.com/documentation/api/adm/


Please find below an example of the “createaccount” API call:

URL https://< SDP_url >/v1/admin/createaccount?access_token=< admin _ token >

Parameters

POST

{ "eui": "84df:0c00:0000:3d48", "shortcode": "jaf", "customer_reference": "", "firstname": "T", "lastname": "Est", "emailaddress": "[email protected]", "telephone": "0612341234", "street": "N2G Drive", "house_no": 7, "house_no_suffix": "", "postalcode": "3700 AA", "city": "Zeist", "country": "Netherlands", "country_code": "", "installation_size": "", "panel_capacity": "", "install_date": "", "inverter_count": 0, "orientation_roof": 0, "inclination_panels": "", "panel_make_model": "", "efficiency_factor": "", "internet_with_meter": true, "installation_company": "", "grid_operator": "", "performance_benchmark": "", "channel": "NET2GRID" }

Returns

On success:

● JSON encoded array (one array element for every requested property)

● key = str Property ID ● value = mixed Property Value

● error = str Error message (Optional)

On error:

● str Returns a string when an error has occurred that was so severe that no (partial)

object could be returned.

Description

Example Example of JSON output:

{


"username" : "test1" ,

"password" : "Vfb9C8xk",

"eui" : "84df:0c00:0000:3d48" ,

"channel" : {

" id ":" 1 ",

" name ":" net2grid "

}

}

Where the username is formed out of the first character of the first name, the full last name and an increasing number in case the username is already used.

In case the token is not generated with a management account, there will be the error message below: {

"error" : "not_authorized" ,

"error_description" : "Not authorized"

}

In case the token does not have the correct format, there will be the error message below: {

"error" : "invalid_token" ,

"error_description" : "The access token provided is invalid"

} In case during the “createaccount” process the ZGD is already in use by another account, there will be the error message below: {

"error" : "zgd_registered" ,

"error_description" : "ZGD is already registered"

}

In case during the “createaccount” process the ZGD has not been connected to the SDP platform before, there will be the error message below: {

"error" : "zgd_offline" ,

"error_description" : "ZGD is offline"

}

In case during the “deleteaccount” process the username is not found, there will be the error message below: {

"error" : "invalid_user" ,

"error_description" : "Invalid username specified"

}


WAN API The WAN API is described on the N2G developers page:

http://developer.net2grid.com/documentation/api/wan/

Please find below an example of the “permit join” API call (POST):

URL https://< SDP_url >/v1/zgd/9574384526952497154/pjoin?access_token=< token >

Parameters

POST

{

"dur": 90

}

Returns

On success:




On error:




Description

Example Example of JSON output: "SUCCESS"

The argument contains the duration in seconds for the ZGD to open it’s network for new nodes. The URL contains the decimal presentation of the ZGD’s EUI64: 9574384526952497154 represents: 84df:0c00:0000:0002 In case the token is not generated by a user with rights to connect to the ZGD referred to in the URL, then the error message below will be displayed: {

"error" : " not_authorized " ,

"error_description" : " Your user is not allowed to access this gateway "

}

In case the message format cannot be parsed by the IPHA: {

"error" : "Received error message from IPHA: GENERAL_ERROR"

}

The example network used here contains of a SmartBridge with EUI 84df:0c00:0000:0002 and a SmartPlug with EUI 84df:0c00:1000:0180. For the application to get the node list, we use the “nodes” API call, this is a GET call to the WAN API:

URL https://< SDP_url >/v1/zgd/9574384526952497154/nodes?access_token=< token >

Parameters GET

Returns

On success: ● JSON encoded array (one array element for every requested property) ● key = str Property ID ● value = mixed Property Value ● error = str Error message (Optional)

On error: ● str Returns a string when an error has occurred that was so severe that no (partial)


Description

Example Example of JSON output:


{ "count" : 1 ,

"list" : [

{ "addr" : {

"eui" : "9574384527220932992" , "nwkAddr" : 65420 }

} ]

}

Where 9574384527220932992 is the decimal representation of: 84df:0c00:1000:0180 and the network address is

being used in the LAN API.

To find out if we can toggle this plug, we need to learn more about the services through the “services” API call:

URL https://< SDP_url >/v1/zgd/9574384526952497154/services?access_token=< token >

Parameters GET

Returns

On success:




On error:



Description

Example

Example of JSON output:

[ {

"short_address" : 65420 , "ieee_address" : "9574384527220932992" , "simple_descriptors" : [

{ "application_output_cluster_count" : 1 , "application_device_version" : 0 ,


"application_output_cluster_list" : [ 25

], "application_input_cluster_count" : 5 , "application_device_identifier" : 9 , "application_input_cluster_list" : [

0 , 3 , 4 , 5 , 6

], "endpoint" : 1 , "application_profile_identifier" : 260

}, {

"application_output_cluster_count" : 0 , "application_device_version" : 0 , "application_output_cluster_list" : [ ], "application_input_cluster_count" : 1 , "application_device_identifier" : 9 , "application_input_cluster_list" : [

1794 ], "endpoint" : 10 , "application_profile_identifier" : 260

} ]

}

]

In this call we learn there is a “ON/OFF” cluster (cluster 6) on EndPoint 1 and a “simple metering” cluster (cluster

1794 = 0x702)

With this information, we can send a message to toggle the plug through the WAN API (POST):

URL https://< SDP_url >/v1/zgd/9574384526952497154/zcl?access_token=< token >

Parameters

POST

{

"addr": {

"eui": "9574384527220932992"

},

"endpoint": 1,

"profile": 260,

"cluster": 6,

"clientCmd": false,

"global": false,

"command": 2


}

Returns

On success:




On error:



Description

Example Example of XML output:

{}

The WAN API gives the developer the ultimate flexibility in controlling the complete ZigBee network in real time

without being on the same LAN network and without the usual LAN networking hassle.

There are a few disadvantages though:

● The developer needs to have basic knowledge of the ZigBee Cluster Library in order to use the WAN API

● The developer only has access to real time data, not to historical data

● The latency of the response is depending on the internet connection of the customer. The upspeed ping

time is relevant here. With a good connection, the WAN API can toggle a plug in less than 500ms vs less

than 200ms on the LAN API. With a poor connection the WAN API can take several seconds.

These disadvantages are taken away by the Energy Insight API we will cover now.


EnergyInsight API

The EI API is described on the N2G developers page:

http://developer.net2grid.com/documentation/api/ei/

Unlike the WAN API, the ZGD EUI64 is not required in the API call, the token authentication process only displays

the Domain Objects with the correct permissions for the user

Fetching Objects

Fetching objects, a single object and results are the only supported methods as for now. They all follow the same

syntax which is defined in the URL.

Functionality URL

Fetching a single object /ObjectName/ObjectID/

Fetching all objects in a household /ObjectName/

Fetching results of an objects' property /ObjectName/ObjectId/query (where the

property is listed in the Parameters)

These URLs will work, and are explained in more detail in later chapters. But, it is possible to alter the default

behaviour by specifying which fields you are interested in and specifying a filter on a list, to avoid receiving all the

elements.

Fields To override the default list of fields that are returned, you can set the fields property in the arguments. This is a

reserved property (see TABLE 1 & 2) and contains a comma separated list.

Fetching list of objects for a specific user

URL https://< SDP_url >/v1/insight?access_token=< token >

Parameters POST

Returns On success:


● key = str Property ID


● value = mixed Property Value ● error = str Error message (Optional)

On error:

● str Returns a string when an error has occurred that was so severe that no (partial) object could be returned.

Description Only the SmartBridge is available in the network, no other nodes are present

Example


{ "HouseholdCollection" : [

{ "object_id" : "121" , "description" : "bert1"

} ],

"EnergyMeterCollection" : [

{ "object_id" : "122" , "description" : null

}, {

"object_id" : "123" , "description" : null

}, {


}, {


} ]

}

Specific Attributes can be requested by adding arguments as in the example below:

Fetching list of objects & attributes for a specific user

URL https://< SDP_url >/v1/insight?access_token=< token >

Parameters

POST

{

"format": "json",

"attributes": [

"object_id",

"energymeter/node_eui64",


"energymeter/current_summation_delivered",

"energymeter/model_identifier",

"energymeter/metering_device_type",

"household/description"

]

}

Returns

On success:




On error:



Description In the result below, only a electricity meter is connected to the P1 port of the SmartBridge

and no gas meter.

Example


{ "HouseholdCollection" : [

{ "object_id" : "121" , "description" : "bert1"

} ],


{ "object_id" : "122" , "node_eui64" : "9574384526952512840" , "current_summation_delivered" : "Error: Can not fetch local result on unsaved Fqaa" , "model_identifier" : "SG33" , "metering_device_type" : "" , "meter_status" : null

}, {

"object_id" : "123" , "node_eui64" : "9574384526952512840" , "current_summation_delivered" : 115000 , "model_identifier" : "SG33" , "metering_device_type" : "0" , "meter_status" : "0"

}, {

"object_id" : "124" , "node_eui64" : "9574384526952512840" , "current_summation_delivered" : "Error: Can not fetch local result on unsaved Fqaa" , "model_identifier" : "SG33" ,


"metering_device_type" : "128" , "meter_status" : "255"

}, {

"object_id" : "125" , "node_eui64" : "9574384526952512840" , "current_summation_delivered" : "Error: Can not fetch local result on unsaved Fqaa" , "model_identifier" : "SG33" , "metering_device_type" : "" , "meter_status" : null

} ]

}

Attributes for one specific Energy Meter

URL https://< SDP_url >/v1/insight/energymeter/123?access_token=< token >

Parameters POST


{

"format": "json",

"attributes": [

"object_id",

"node_eui64",




"energymeter/meter_status",

]

}

Returns

On success:




On error:



Description In the result below, only attributes from the Energy Meter connected to the electricity meter

are requested:

Example


{ "EnergyMeterCollection" : [

{ "object_id" : "123" , "node_eui64" : "9574384526952512840" , "current_summation_delivered" : 115000 , "model_identifier" : "SG33" , "metering_device_type" : "0" , "meter_status" : "0"

} ]

}

Query a property of an Energy Meter object between two timestamps To query a time series, we are using the ISO 8601 time standard:

http://www.iso.org/iso/home/standards/iso8601.html

https://en.wikipedia.org/wiki/ISO_8601

URL https://< SDP_url >/v1/insight/energymeter/123/query?access_token=< token >


Parameters

POST

{

"attribute": "instantaneous_demand_delivered",

"rowcount": 10,

"order_dir": "asc",

"start": "2015‐07‐02T11:00:18+02:00",

"end": "2015‐07‐02T13:40:18+02:00",

"samplerate": 3600

}

Returns

On success:




On error:



Description ALl samples are within 3600 seconds, hence one result

Example


[ {

"avg" : 30 , "min" : 0 , "max" : 120 , "count" : "6" , "first_value" : 0 , "last_value" : 120 , "first_timestamp" : "2015‐07‐02T13:01:58+02:00" , "last_timestamp" : "2015‐07‐02T13:14:20+02:00" , "timestamp" : "2015‐07‐02T13:00:18+02:00"

}

]

URL https://< SDP_url >/v1/insight/energymeter/123/query?access_token= < token >

Parameters

POST

{

"attribute": "instantaneous_demand_delivered",

"rowcount": 10,

"order_dir": "asc",

"start": "2015‐07‐02T11:00:18+02:00",

"end": "2015‐07‐02T13:40:18+02:00",


"samplerate": 10

}

Returns

On success:




On error:



Description With a 10 sec sample rate, the individual measurements are visible

Example


[

{ "avg" : 0 , "min" : 0 , "max" : 0 , "count" : "1" , "first_value" : 0 , "last_value" : 0 , "first_timestamp" : "2015‐07‐02T13:01:58+02:00" , "last_timestamp" : "2015‐07‐02T13:01:58+02:00" , "timestamp" : "2015‐07‐02T13:01:58+02:00"

}, {


}, {


}, {

"avg" : 0 ,


"min" : 0 , "max" : 0 , "count" : "1" , "first_value" : 0 , "last_value" : 0 , "first_timestamp" : "2015‐07‐02T13:13:51+02:00" , "last_timestamp" : "2015‐07‐02T13:13:51+02:00" , "timestamp" : "2015‐07‐02T13:13:48+02:00"

}, {


}, {


} ]

Refresh Objects

Specific Attributes can be requested by adding arguments as in the example below:

Refresh Objects

URL https://< SDP_url >/v1/insight/household/107/refresh?access_token=< token >

Parameters GET

note : the household_ID is part of the URL

Returns

On success:





On error:

● str Returns a string when an error has occurred that was so severe that no (partial) object could be returned.

Description The return value is the total number of available Objects. Only new Objects are generated.

Example


{ "OK" : 3

}

Definitions

TABLE 1: SmartBridge Properties

Property ID Name Type Unit Can be Null

object_id Object ID int ‐ N

description Description string ‐ Y

location_description Location Description string ‐ N

hardware_version PCB hardware revision ZGD int ‐ Y

model_identifier Model ID ZGD based on firmware string ‐ Y

application_version Application version of firmware string ‐ Y

sw_build_id Firmware release ID int ‐ Y

ip_address_v4 IP address SmartBridge int ‐ Y

node_online Node Online bool ‐ N

node_eui64 64‐bit Extended Unique Identifier string ‐ N

shortcode Translates the EUI64 to shortcode string ‐ N

Energy Meter Properties

Property ID Name Type Unit Can be Null

object_id Object ID int ‐ N


description Description string ‐ Y

location_description Location Description string ‐ N

current_summation_delivered Current Summation Delivered int ‐ Y

current_summation_received Current Summation Received int ‐ Y

current_tier1_summation_delivered Current Tier1 Summation Delivered int ‐ Y

current_tier1_summation_received Current Tier1 Summation Received int ‐ Y

current_tier2_summation_delivered Current Tier2 Summation Delivered int ‐ Y

current_tier2_summation_received Current Tier2 Summation Received int ‐ Y

instantaneous_demand_delivered Instantaneous Demand Delivered int ‐ Y

instantaneous_demand_received Instantaneous Demand Received int ‐ Y

node_online Node Online bool ‐ N

meter_status Meter Status string ‐ Y

unit_of_measure Unit Of Measure string ‐ N

multiplier Multiplier int ‐ N

divisor Divisor int ‐ N

metering_device_type Metering Device Type string ‐ N

shortcode Translates the EUI64 to shortcode ‐ ‐

TABLE 2: Household properties

Property ID Name Type Can be Null

housetype Residence type Int Y

familymembers Number of family members Int Y

constructionyear Construction year Int Y

volume Residence volume Int Y

heating Int Y


elec_target Target value for electricity Int Y

gas_target Target value for gas Int Y

water_target Target value for water Int Y

solar_max Maximum capacity for panels Int Y

high_and_low Does meter support high/low tariff bool Y

rate_high High rate Int Y

rate_low Low rate Int Y

rate_gas Gas rate Int Y

rate_water Water rate Int Y

firstname First name string Y

lastname Last name string Y

street Street string Y

house_no House number string Y

house_no_suffix House number suffix string Y

postalcode Postal code string Y

city City string Y

country Country string Y

telephone Telephone string Y

labelpartner_id Label partner Int Y

start_date_bill Start date for bill Int Y

command_schedule Command schedule string Y

subscription_valid_until Subscription valid until Int Y

is_subscription_active Is a valid subscription present bool Y

subscription_trial_used Has trial subscription been used bool Y


Meter Status replies ● checkMeter

○ Set to true when a non fatal problem has been detected on the meter such as a measurement error, memory error, self‐check error

● LowBattery ○ Set to true when the battery needs maintenance

● TamperDetect ○ Set to true if tamper event has been detected

● PowerFailure ○ Set to true during a power outage

● PowerQuality ○ Set to true if a power quality event have been detected such as low voltage, high voltage

● LeakDetect ○ Set to true when a leak have been detected

● ServiceDisconnectOpen ○ Set to true when the service has been disconnected to this premise

Energy Meter Unit of Measures The following is a list of implemented Unit Of Measures for both of the currently implemented Energy Meter objects.

● kW (kilo‐Watts) & kWh (kilo‐WattHours) ● m 3 (Cubic Meter) & m 3 /h (Cubic Meter per Hour) ● ft 3 (Cubic Feet) & ft 3 /h (Cubic Feet per Hour) ● ccf ((100 or Centum) Cubic Feet & ccf/h ((100 or Centum) Cubic Feet per Hour) ● US gl (US Gallons) & US gl/h (US Gallons per Hour) ● IMP gl (Imperial Gallons) & IMP gl/h (Imperial Gallons per Hour) ● BTUs & BTU/h ● Liters & l/h (Liters per Hour) ● kPA (gauge) ● kPA (absolute)

Metering Device Types The following types of meters are implemented in the two Energy Meter objects.

● ElectricMetering ● GasMetering ● WaterMetering ● ThermalMetering (not supported in the API) ● PressureMetering (not supported in the API)

Possible return values for measurements When requesting values using the webservice the response can vary depending on the capabilities of a given object. In this article we'll explain the different possible responses and an explanation of what caused it. Currently a lot of the error messages are still in full‐text string form. In a future release we are planning to give the different error messages a distinguishable error code, to make it easier for a client to determine precisely what is wrong.


Situation A valid measurement

Explanation Nothing went wrong

Example <instantaneous_demand calc_value="0" timestamp="2911550639" unit="W">0</instantaneous_demand>

Situation No measurement available

Explanation Either the source has not yet produced any values or the source has not been coupled to the object for long enough to have a value.

Example <instantaneous_demand error="Could not fetch local result of Fqaa 22294 [000d:6f00:0099:05ff/0x0a/0x0400/0x0000]. (No record found)"></instantaneous_demand>

Situation No source available

Explanation The object is currently not coupled to a source that can provide the requested property. That means the sensor is incapable to measure or the configuration is not yet complete.

Example <instantaneous_demand error="Unable to find source for property 'instantaneous_demand' while fetching it's raw value"></instantaneous_demand>

Attributes used by the Energy Meter object The following set of attributes provides a remote access to the reading of the Electric, Gas, Water metering device. Please note: in the following attributes, the term “delivered” refers to the quantity of Energy, Gas or Water that was delivered to the customer from the utility. Likewise, the term “Received” refers to the quantity of Energy, Gas or Water that was received by the utility from the customer. CurrentSummationDelivered attribute CurrentSummationDelivered represents the most recent summed value of Energy, Gas or Water delivered and consumed in the premise. CurrentSummationDelivered is mandatory and must be provided as part of the minimum data set to be provided by the metering device. CurrentSummationDelivered is updated continuously as new measurements are made. CurrentSummationReceived attribute CurrentSummationReceived represents the most recent summed value of Energy, Gas or Water generated and received from the premise. If optionally provided, CurrentSummationReceived is updated continuously as new measurements are made. CurrentTierNSummationDelivered attributes


Attributes CurrentTier1SummationDelivered through CurrentTier5SummationDelivered represent the most recent

summed value of Energy, Gas, or Water delivered to the premise (eg. delivered to the customer from the utility) at

a specific price tier as defined by a TOU schedule or a real time pricing period. If optionally provided, attributes

CurrentTier1SummationDelivered through CurrentTier5SummationDelivered are updated continously as new

measurements are made.

InstantaneousDemand attribute

InstantaneousDemand represent the current Demand of Energy delivered or received at the premise.

InstantaneousDemandDelivered indicates Demand delivered to the premise and InstantaneousDemandReceived

indicates demand received from the premise. InstantaneousDemand is updated continuously as new

measurements are made. The frequency of updates to this field is specific to the metering device, but should be

within the range of once every second to once every 5 seconds.

Divisor attribute

Divisor provides a value to divide the results of applying the Multiplier attribute against a raw or uncompensated

sensor count of Energy, Gas or Water being measured by the metering device. If present, this attribute must be

applied against all summation, consumption and demand values to derive the delivered and received values

expressed in the unit of measure specified. This attribute must be used in conjunction with the Multiplier attribute.

In the webservice, this value is already applied to any of the aforementioned attributes and should therefore not

be used.

Multiplier attribute

Multiplier provides a value to be multiplied against a raw or uncompensated sensor count of Energy, Gas or Water

being measured by the metering device. If present, this attribute must be applied against all summation,

consumption and demand values to derive the delivered and received values expressed in the unit of measure

specified. This attribute must be used in conjunction with the Divisor attribute. In the webservice, this value is

already applied to any of the aforementioned attributes and should therefore not be used.

UnitOfMeasure attribute

UnitOfMeasure provides a label for the Energy, Gas or Water being measured by the metering device. The unit of

measure apply to all summations, consumptions/profile interval and demand/rate supported by this cluster. Other

measurements such as the power factor are self describing. This attribute is an enumerated field.

TABLE 3: Specific object commands

Command Description Object Type

permit_join Open ZigBee network for specified number of sec. DOSmartBridge POST

switch_plug_on Switch plug on DOOnOff GET

switch_plug_off Switch plug off DOOnOff GET


get_plug_status Show current on/off cluster status DOOnOff GET

set_timer_on Sets a timer to on DOSmartBridge POST 1

set_timer_off Sets a timer to off DOSmartBridge POST 1

set_timer_toggle Toggles a timer DOSmartBridge POST 1

remove_timer Remove a timer DOSmartBridge POST 2

refresh_domain_objects Attempt to find newly connected Domain Objects connected to the SmartBridge

DOHousehold GET

1. Body for POST contains two values: 2. tod – time of day in seconds, UTC 3. index – index of timer (0‐15) 4. Body for POST contains a single value: 5. index – index of timer (0‐15)

HTTP Status Codes

Every request will receive a HTTP reply with a status code. Status codes are based on the outcome of the request. 200 – OK 201 – Created 400 – Malformed request (syntactic error) 401 – Unauthorized (no credentials are sent) 403 – Forbidden (cannot access this object with current credentials) 404 – Not found (object does not exist) 409 – Conflict (e‐tags do not match) 500 – Internal server error (when an internal error occurs)

Result Types and Fields

The query method returns a list of results. Exactly which type of Result it returns, is dependent on the query options and the property you query on. The two Result types that currently occur are:

● Result ● ResultSampled

Note that currently all the properties of the result type are returned. Later on we will most likely cut back on the default list of returned result properties and allow the use of the $field query parameter here too. Result This is returned when no sample rate is used.

Property Description


value The measured value

timestamp_formatted Timestamp formatted in RFC3334

ResultSampled This is an aggregate result type that is used when the query has a sample rate. For the sampled result, a couple of results are taken together and returned as a sample.

Property Description

avg The average value of the results in this sample

min The minimum value of all results in this sample

max The maximum value of all results in this sample

first_value The value of the first result in this sample

last_value The value of the last result in this sample

first_timestamp Unix timestamp in milliseconds of the first result in this sample

last_timestamp Unix timestamp in milliseconds of the last result in this sample

timestamp_formatted Timestamp formatted in RFC3334


Use Case Document The NET2GRID HEMS system (Home Energy Management) has 4 components:

SmartBridge • The SmartBridge is our ZigBee gateway connecting through SEP to the SmartMeter and

through HA to other ZigBee devices:

• https://cdn.net2grid.net/pdf/SB3103_SmartBridge_Product_Specification__latest.pdf

SmartSolar • For customers with solar panels, we can monitor real time the peformance of the

panels:

• https://cdn.net2grid.net/pdf/SS3104_SmartSolar_Product_Specification__latest.pdf

SmartReader • In case there is no ZigBee SEP Smart Meter, we offer a SmartReader with a mix of

wired, optical and clamp interfaces:

• https://cdn.net2grid.net/pdf/SR3107_SmartReader_Product_Specification__latest.pdf

DIN Meter • 32A single phase meter to measure per group:

• https://cdn.net2grid.net/pdf/N2G‐DIN_Power_Meter.pdf

SmartPlug • With the SmartPlug we can measure per appliance and switch the load on/off remotely:

• https://cdn.net2grid.net/pdf/SP3102_SmartPlug_Product_Specification__latest.pdf

All products are represented in the SDP

as a node with a unique EUI64 address

reporting energy data into the SDP and

in case of the SmartPlug, a real time

controllable relays from the SDP.


The SDP API supports the customer journeys described below for all devices. As an example, the use cases are represented in a test case to easily replicate the functionality on a custom SDP:

Use Case Customer journey: Device Installation Test Case

UC01 SmartBridge installation & account creation TC001

UC02 Connect SmartBridge to SmartReader TC002

UC03 Connect SmartBridge to SmartSolar TC003

UC04 Connect SmartBridge to SmartPlug TC004

Customer journey: Device replacement

UC10 Replace SmartBridge TC009

UC13 Replace SmartReader TC010

UC11 Move SmartMeter data collection from SmartBridge to SmartReader TC012

UC12 Used SmartBridge can be added to new account when made factory new TC001

UC13 Toggle SmartPlug TC013

Customer journey: Device removal

UC20 Make SmartBridge factory new and delete account TC020


TC001 - SmartBridge installation & create account

URL https://< SDP_url >/v1/admin/createaccount?access_token=< admin_token >

Method POST

Parameters

{

"eui": "84df:0c00:0000:0002",

"shortcode": "c",

"customer_reference": "",

"firstname": "T",

"lastname": "Est",

"emailaddress": "[email protected]",

"telephone": "0612341234",

"street": "N2G Drive",

"house_no": 7,

"house_no_suffix": "",

"postalcode": "1234 AA",

"city": "Zeist",

"country": "Netherlands",

"country_code": "",

"installation_size": "",

"panel_capacity": "",

"install_date": "",

"inverter_count": 0,

"orientation_roof": 0,

"inclination_panels": "",

"panel_make_model": "",

"efficiency_factor": "",

"internet_with_meter": true,

"installation_company": "",

"grid_operator": "",

"performance_benchmark": "",

"channel": "NET2GRID"

}

Returns

"username": "test5",

"password": "GX4qMyxg",

"eui": "84df:0c00:0000:0002",

"channel": {

"id": "1",

"name": "net2grid"


TC002 - Connect SmartReader to SmartBridge Install the SmartReader according to the hardware installation manual. After installation the SmartReader will blink

white fast, this indicates that it is not connected to a network. The call below will open the network of the

SmartBridge for 90 seconds to permit nodes to join the network.

The decimal representation of the SmartBridge EUI64 (84df:0c00:0000:0002) is 9574384526952497154.


Method POST

Parameters {

"dur": 90

}

Returns OK

After the SmartReader has joined the network, a new node list is available via:


Method GET

Parameters

Returns

{ "count" : 1 ,

"list" : [

{ "addr" : {

"eui" : "9574384526969274682" , "nwkAddr" : 39175

} }

]

}

Where the SmartReader with EUI64 84df:0c00:0100:013a has the decimal value: 9574384526969274682


TC003 - Connect SmartSolar to SmartBridge Install the SmartSolar according to the hardware installation manual. After installation the SmartSolar will blink

white fast, this indicates that it is not connected to a network. The call below will open the network of the



Method POST

Parameters {

"dur": 90

}

Returns OK


Method GET

Parameters

Returns

{ "count" : 2 ,

"list" : [

{ "addr" : {

"eui" : " 9574384526986057902 " , "nwkAddr" : 15320

} }, {

"addr" : { "eui" : "9574384526969274682" , "nwkAddr" : 39175

} }

]

}

Where the SmartSolar with EUI64 84df:0c00:0200:18ae has the decimal value: 9574384526986057902


TC004 - Connect SmartPlug to SmartBridge Install the SmartPlug according to the hardware installation manual. After installation the SmartPlug will blink red,

this indicates that it is not connected to a network. The call below will open the network of the SmartBridge for 90

seconds to permit nodes to join the network.


Method POST

Parameters {

"dur": 90

}

Returns OK


Method GET

Parameters

Returns

{ "count" : 3 ,

"list" : [

{ "addr" : {

"eui" : "9574384527220932992" , "nwkAddr" : 65420

} }, {

"addr" : { "eui" : " 9574384526986057902 " , "nwkAddr" : 15320 }

}, {

"addr" : { "eui" : "9574384526969274682" , "nwkAddr" : 39175

} }

]

}

Where the SmartPlug with EUI64 84df:0c00:1000:0180 has the decimal value: 9574384527220932992


TC010/TC012 - Replace SmartReader & move P1 from SmartBridge to SmartReader Install the second SmartReader according to the hardware installation manual. After installation the SmartReader

will blink white, this indicates that it is not connected to a network. The call below will open the network of the



Method POST

Parameters {

"dur": 90

}

Returns OK

After installation, a Refresh Energy Meters is required to generate the new installed energy meter objects:

URL https://< SDP_url >/v1/insight/household/121/refresh?access_token=< token >

Method GET

Parameters

Returns { "OK" : 3

}

Now we are ready to query relevant attributes:

URL https://<SDP_url>/v1/insight?access_token=<token>

Method POST

Parameters

{

"format": "json",

"attributes": [

"object_id",

"energymeter/node_eui64",




"energymeter/meter_status",

"household/description"

]

}

Returns {


"HouseholdCollection" : [

{ "object_id" : "218" , "description" : "mpare2"

} ],


{ "object_id" : "219" , "node_eui64" : "9574384526952497344" , "current_summation_delivered" : "Error: Can not fetch local result on unsaved Fqaa" , "model_identifier" : "SG35" , "metering_device_type" : "" , "meter_status" : null

}, {

"object_id" : "220" , "node_eui64" : "9574384526952497344" , "current_summation_delivered" : 115000 , "model_identifier" : "SG35" , "metering_device_type" : "0" , "meter_status" : "1"

}, {

"object_id" : "221" , "node_eui64" : "9574384526952497344" , "current_summation_delivered" : "Error: Can not fetch local result on unsaved Fqaa" , "model_identifier" : "SG35" , "metering_device_type" : "128" , "meter_status" : "255"

}, {

"object_id" : "224" , "node_eui64" : "9574384526969279402" , "current_summation_delivered" : "Error: Can not fetch local result on unsaved Fqaa" , "model_identifier" : "SR31" , "metering_device_type" : "" , "meter_status" : null

}, {

"object_id" : "226" , "node_eui64" : "9574384526969280193" , "current_summation_delivered" : "Error: Can not fetch local result on unsaved Fqaa" , "model_identifier" : "SR31" , "metering_device_type" : "0" , "meter_status" : "0"

}, {

"object_id" : "228" , "node_eui64" : "9574384526969280193" ,


"current_summation_delivered" : "Error: Can not fetch local result on unsaved Fqaa" , "model_identifier" : "SR31" , "metering_device_type" : "128" , "meter_status" : 255

}, {

"object_id" : "229" , "node_eui64" : "9574384526969280193" , "current_summation_delivered" : "Error: Can not fetch local result on unsaved Fqaa" , "model_identifier" : "SR31" , "metering_device_type" : "129" , "meter_status" : 255

} ]

}

The Energy Meter list show the 3 SmartBridge Energy Meters (EM219, 220, 221) both the old SmartReader (EM224) and the new SmartReader (EM226, 228, 229).

The metering_device_type indicates that EM226 = Electricity, EM228 = gas and EM229 = water.

The gas and water meters are inactive and EM220 (electricity on SmartBridge) went offline. The only online meter is EM226 because we moved the P1 cable with only a Smart Meter connected from the SmartBridge into the new SmartReader.


TC020 - SmartBridge factory new & delete account

URL https://< SDP_url >/v1/admin/deleteaccount?access_token=< admin_token >

Method POST

Parameters { "username": "test" }

Returns OK

TC101 - Check meter status

URL https://< SDP_url >/v1/insight/energymeter/109?access_token=< token >

Method POST

Parameters

{ "format": "json", "attributes": [ "object_id", "node_eui64", "energymeter/current_summation_delivered", "energymeter/model_identifier", "energymeter/metering_device_type", "energymeter/meter_status", ] }

Returns

{ "EnergyMeterCollection" : [

{ "object_id" : "109" , "node_eui64" : "9574384526952497154" , "current_summation_delivered" : 115000 , "model_identifier" : "SG33" , "metering_device_type" : "0" , "meter_status" : "1"

} ]

}

In this case the SmartMeter is no longer connected to the SmartBridge.


TC013 - Toggle SmartPlug

URL https://< SDP_url >/v1/zgd/9574384526952497154/zcl?access_token=< token >

Method POST

Parameters

{ "addr": { "eui": "9574384527220932992" }, "endpoint": 1, "profile": 260, "cluster": 6, "clientCmd": false, "global": false, "command": 2 }

Returns { }

Where the SmartPlug with EUI64 84df:0c00:1000:0180 has the decimal value: 9574384527220932992


N2G Connected Home Service Delivery Platform Service...

Documents

Transcript of N2G Connected Home Service Delivery Platform Service...