N2G Connected Home Service Delivery Platform Service...
Transcript of 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
NET2GRID SDP API 1.0 - 2 / 47 -
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.
NET2GRID SDP API 1.0 - 3 / 47 -
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:
NET2GRID SDP API 1.0 - 4 / 47 -
○ 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.
NET2GRID SDP API 1.0 - 5 / 47 -
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.
NET2GRID SDP API 1.0 - 6 / 47 -
● 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
NET2GRID SDP API 1.0 - 7 / 47 -
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.
NET2GRID SDP API 1.0 - 8 / 47 -
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/
NET2GRID SDP API 1.0 - 9 / 47 -
We are using postman to test our API’s: https://www.getpostman.com/ Below you will find an example to toggle a plug:
NET2GRID SDP API 1.0 - 10 / 47 -
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/
NET2GRID SDP API 1.0 - 11 / 47 -
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/
NET2GRID SDP API 1.0 - 12 / 47 -
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:
{
NET2GRID SDP API 1.0 - 13 / 47 -
"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"
}
NET2GRID SDP API 1.0 - 14 / 47 -
NET2GRID SDP API 1.0 - 15 / 47 -
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:
● 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.
NET2GRID SDP API 1.0 - 16 / 47 -
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)
object could be returned.
Description
Example Example of JSON output:
NET2GRID SDP API 1.0 - 17 / 47 -
{ "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:
● 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:
[ {
"short_address" : 65420 , "ieee_address" : "9574384527220932992" , "simple_descriptors" : [
{ "application_output_cluster_count" : 1 , "application_device_version" : 0 ,
NET2GRID SDP API 1.0 - 18 / 47 -
"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
NET2GRID SDP API 1.0 - 19 / 47 -
}
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 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.
NET2GRID SDP API 1.0 - 20 / 47 -
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:
● JSON encoded array (one array element for every requested property)
● key = str Property ID
NET2GRID SDP API 1.0 - 21 / 47 -
● 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
Example of JSON output:
{ "HouseholdCollection" : [
{ "object_id" : "121" , "description" : "bert1"
} ],
"EnergyMeterCollection" : [
{ "object_id" : "122" , "description" : null
}, {
"object_id" : "123" , "description" : null
}, {
"object_id" : "124" , "description" : null
}, {
"object_id" : "125" , "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",
NET2GRID SDP API 1.0 - 22 / 47 -
"energymeter/current_summation_delivered",
"energymeter/model_identifier",
"energymeter/metering_device_type",
"household/description"
]
}
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 In the result below, only a electricity meter is connected to the P1 port of the SmartBridge
and no gas meter.
Example
Example of JSON output:
{ "HouseholdCollection" : [
{ "object_id" : "121" , "description" : "bert1"
} ],
"EnergyMeterCollection" : [
{ "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" ,
NET2GRID SDP API 1.0 - 23 / 47 -
"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
NET2GRID SDP API 1.0 - 24 / 47 -
{
"format": "json",
"attributes": [
"object_id",
"node_eui64",
"energymeter/current_summation_delivered",
"energymeter/model_identifier",
"energymeter/metering_device_type",
"energymeter/meter_status",
]
}
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 In the result below, only attributes from the Energy Meter connected to the electricity meter
are requested:
Example
Example of JSON output:
{ "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 >
NET2GRID SDP API 1.0 - 25 / 47 -
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:
● 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 ALl samples are within 3600 seconds, hence one result
Example
Example of JSON output:
[ {
"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",
NET2GRID SDP API 1.0 - 26 / 47 -
"samplerate": 10
}
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 With a 10 sec sample rate, the individual measurements are visible
Example
Example of JSON output:
[
{ "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:09:34+02:00" , "last_timestamp" : "2015‐07‐02T13:09:34+02:00" , "timestamp" : "2015‐07‐02T13:09:28+02:00"
}, {
"avg" : 0 , "min" : 0 , "max" : 0 , "count" : "1" , "first_value" : 0 , "last_value" : 0 , "first_timestamp" : "2015‐07‐02T13:09:41+02:00" , "last_timestamp" : "2015‐07‐02T13:09:41+02:00" , "timestamp" : "2015‐07‐02T13:09:38+02:00"
}, {
"avg" : 0 ,
NET2GRID SDP API 1.0 - 27 / 47 -
"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"
}, {
"avg" : 60 , "min" : 60 , "max" : 60 , "count" : "1" , "first_value" : 60 , "last_value" : 60 , "first_timestamp" : "2015‐07‐02T13:14:01+02:00" , "last_timestamp" : "2015‐07‐02T13:14:01+02:00" , "timestamp" : "2015‐07‐02T13:13:58+02:00"
}, {
"avg" : 120 , "min" : 120 , "max" : 120 , "count" : "1" , "first_value" : 120 , "last_value" : 120 , "first_timestamp" : "2015‐07‐02T13:14:20+02:00" , "last_timestamp" : "2015‐07‐02T13:14:20+02:00" , "timestamp" : "2015‐07‐02T13:14:18+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:
● JSON encoded array (one array element for every requested property)
● key = str Property ID ● value = mixed Property Value
● error = str Error message (Optional)
NET2GRID SDP API 1.0 - 28 / 47 -
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
Example of JSON output:
{ "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
NET2GRID SDP API 1.0 - 29 / 47 -
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
NET2GRID SDP API 1.0 - 30 / 47 -
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
NET2GRID SDP API 1.0 - 31 / 47 -
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.
NET2GRID SDP API 1.0 - 32 / 47 -
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
NET2GRID SDP API 1.0 - 33 / 47 -
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
NET2GRID SDP API 1.0 - 34 / 47 -
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
NET2GRID SDP API 1.0 - 35 / 47 -
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
NET2GRID SDP API 1.0 - 36 / 47 -
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.
NET2GRID SDP API 1.0 - 37 / 47 -
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
NET2GRID SDP API 1.0 - 38 / 47 -
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"
NET2GRID SDP API 1.0 - 39 / 47 -
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.
URL https://< SDP_url >/v1/zgd/9574384526952497154/pjoin?access_token=< token >
Method POST
Parameters {
"dur": 90
}
Returns OK
After the SmartReader has joined the network, a new node list is available via:
URL https://< SDP_url >/v1/zgd/9574384526952497154/nodes?access_token=< token >
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
NET2GRID SDP API 1.0 - 40 / 47 -
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
SmartBridge for 90 seconds to permit nodes to join the network.
URL https://< SDP_url >/v1/zgd/9574384526952497154/pjoin?access_token=< token >
Method POST
Parameters {
"dur": 90
}
Returns OK
URL https://< SDP_url >/v1/zgd/9574384526952497154/nodes?access_token=< token >
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
NET2GRID SDP API 1.0 - 41 / 47 -
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.
URL https://< SDP_url >/v1/zgd/9574384526952497154/pjoin?access_token=< token >
Method POST
Parameters {
"dur": 90
}
Returns OK
URL https://< SDP_url >/v1/zgd/9574384526952497154/nodes?access_token=< token >
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
NET2GRID SDP API 1.0 - 42 / 47 -
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
SmartBridge for 90 seconds to permit nodes to join the network.
URL https://< SDP_url >/v1/zgd/9574384526952497154/pjoin?access_token=< token >
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/current_summation_delivered",
"energymeter/model_identifier",
"energymeter/metering_device_type",
"energymeter/meter_status",
"household/description"
]
}
Returns {
NET2GRID SDP API 1.0 - 43 / 47 -
"HouseholdCollection" : [
{ "object_id" : "218" , "description" : "mpare2"
} ],
"EnergyMeterCollection" : [
{ "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" ,
NET2GRID SDP API 1.0 - 44 / 47 -
"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.
NET2GRID SDP API 1.0 - 45 / 47 -
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.
NET2GRID SDP API 1.0 - 46 / 47 -
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
NET2GRID SDP API 1.0 - 47 / 47 -