Gateway Management Solution Based on Intel® IoT … · Gateway Management Solution Based on ......

Document Number: 332845-001US

Gateway Management Solution Based on

Intel® IoT Platform

API Reference Manual

August 2015

Gateway Management Solution Based on Intel® IoT Platform

API Reference Manual August 2015

2 Document Number: 332845-001US

You may not use or facilitate the use of this document in connection with any infringement or other legal analysis concerning Intel products

described herein. You agree to grant Intel a non-exclusive, royalty-free license to any patent claim thereafter drafted which includes subject matter

disclosed herein

No license (express or implied, by estoppel or otherwise) to any intellectual property rights is granted by this document.

All information provided here is subject to change without notice. Contact your Intel representative to obtain the latest Intel product specifications

and roadmaps.

The products described may contain design defects or errors known as errata which may cause the product to deviate from published

specifications. Current characterized errata are available on request.

Copies of documents which have an order number and are referenced in this document may be obtained by calling 1-800-548-4725 or by visiting:

http://www.intel.com/design/literature.htm.

Intel technologies’ features and benefits depend on system configuration and may require enabled hardware, software or service activation. Learn

more at http://www.intel.com/ or from the OEM or retailer.

No computer system can be absolutely secure.

Intel and the Intel logo are trademarks of Intel Corporation in the U.S. and/or other countries.

*Other names and brands may be claimed as the property of others.

Copyright © 2015, Intel Corporation. All rights reserved.

http://www.intel.com/design/literature.htm

http://www.intel.com/


August 2015 API Reference Manual

Document Number: 332845-001US 3

Contents

1.0 Introduction ............................................................................................................................................ 5

1.1 Reference Documents ................................................................................................................................ 5

2.0 Definitions and Architecture ......................................................................................................... 6

2.1 Architecture ....................................................................................................................................................... 6

2.2 Communication Encryption ..................................................................................................................... 6

3.0 Device API Definition ........................................................................................................................ 7

4.0 Management API Definition ........................................................................................................ 21

4.1 User Management ....................................................................................................................................... 21

4.2 Project Information API........................................................................................................................... 30

4.3 Device Information API ........................................................................................................................... 37

4.4 Data Management API ............................................................................................................................. 54

4.5 Log Management API ................................................................................................................................ 65

5.0 Error Code Range ............................................................................................................................... 69

Appendix A ................................................................................................................................ API List 70

Tables

Table 1. Reference Documents ................................................................................................................................ 5 Table 2. Control APIs in REST Paths .................................................................................................................... 7 Table 3. Control API Interface Details ................................................................................................................. 8 Table 4. Use Roles ........................................................................................................................................................... 21 Table 5. User Management API in Restful Paths ........................................................................................ 21 Table 6. User Management API Details ............................................................................................................ 22 Table 7. Project Information Management API ........................................................................................... 31 Table 8. Project Information Management API Details ......................................................................... 31 Table 9. Device Information Management API ........................................................................................... 37 Table 10. Device Management API Details ....................................................................................................... 38 Table 11. Data Management API ............................................................................................................................. 54 Table 12. Data Management API Details ............................................................................................................ 55 Table 13. Log Management APIs ............................................................................................................................. 65 Table 14. Log Management API Details .............................................................................................................. 66 Table 15. Error Code Ranges ...................................................................................................................................... 69 Table 16. API List ................................................................................................................................................................ 70




Revision History

Date Revision Description

August 2015 1.0 Initial release.

§

Introduction




1.0 Introduction

This document defines the Application Programming Interface (API) between the cloud

backend and the frontend management interface. In addition to the platform

management portal, the frontend also includes system like data visualization. The

document also defines the communication requirements between backend of the

system and gateway device.

1.1 Reference Documents

Table 1. Reference Documents

Document Document No./Location

The JSON Data Interchange Standard ECMA-404

§

Definitions and Architecture




2.0 Definitions and Architecture

2.1 Architecture

In the system, the API system acts as the backend that exports functions by HTTP POST

invocation. The frontend is a UI module that handles all human interactions.

MQTT Broker is adopted for the communication between the backend system and the

edge gateways. The API calls for the edge gateways are named device APIs. The API

calls for platform and data management are named management APIs. These two

categories of APIs bridge the frontend systems and the backend.

2.2 Communication Encryption

The API includes the authentication for user messages. However, it is required to adopt

the transportation layer encryption for additional security.

The API can be wrapped as a JAVA class interface.

§

Device API Definition




3.0 Device API Definition

The device APIs include two categories of APIs: One is the control API for gateways via

the MQTT broker, and the other is the data APIs for gateway submitting data and other

information. The frontend management portal can call the control APIs to manage

individual gateway device.

The control APIs are applied to the gateway device even though they are proxied by the

MQTT Broker. Such APIs include operations to the gateway configuration, applications,

and base platform. Because control APIs need to be transmitted over the network,

executed by the gateway, and then collected the returned value, there are

uncontrollable latency on the network and variance in gateway execution time. Thus

control APIs are all defined as bi-stage APIs, where the stage-1 API call returns an API

query code and its timeout value if successful accepted. The caller has to call the API

status query API (getAPIStatus as the stage-2 API call) with the query code after the

timeout value to obtain the control API return value. If the API has not finished

execution, a new API query code and timeout value is returned for the next status

query.

The following are the control APIs in REST paths.

Table 2. Control APIs in REST Paths

Index API Method and Path Functionality Priority

A.1 POST dev/ctl/getVer Get gateway version.

A.2 POST dev/ctl/getcfg Get gateway configuration.

A.3 POST dev/ctl/setcfg Set gateway configuration.

A.4 POST dev/ctl/ping Get the gateway online status.

A.5 POST dev/ctl/updatefirmware Update gateway firmware.

A.6 POST dev/ctl/system Execute customized system command

A.7 POST dev/ctl/getapplist Get list of applications on gateway

A.8 POST dev/ctl/startapp Start one application

A.9 POST dev/ctl/stopapp Stop one application

A.10 POST dev/ctl/installapp Install one application

A.11 POST dev/ctl/reboot Restart the gateway

A.12 POST dev/ctl/filec2d Transfer a file from cloud to device

A.13 POST dev/ctl/filed2c Transfer a file from device to cloud

A.14 POST dev/ctl/rpccall Call device RPC

A.15 POST dev/ctl/getapistatus Get API execution status






A.16 POST dev/ctl/listcfg List gateway configuration

A.17 POST dev/ctl/preparelog Gateway put log into a local file

A.18 POST dev/ctl/filestats Return information of local file

The following are the API interface details in JAVA language syntax. Both parameters

and return values are defined as JSON message.

Table 3. Control API Interface Details

Index API Details Note

A.15 String getAPIstatus(String json_str);

Functionality: get API execution result.

Params：JSON data structure

{

“method”:”dev/ctl/getapistatus”,

“api_qid”:”QID”, //ASCII query code from the stage-1 control API

call.

“auth_token”:”xxx” //token to represent the calling user.

}

Return value is also JSON message. If the API completes execution,

{

“retcode”:”0”, //API return code, 0 if successful，

//code >10000 indicates errors

… … // Json structure varies based on API.

}

If the stage-1 control API is still executing,

{

“retcode”:”1”, //API in progress code == 1.

“api_qid”:”QID”, //API query ID (QID),






“time_out”:”100”, //Timeout value in millisecond.

}

A.1 String getVer(String json_str);

Params: JSON string

{

“method”:”dev/ctl/getVer”,

“device”:”id”, //device ID that uniquely identifying the gateway

// in format of “/dev/ctl/[project_id]/[gateway_id]/”

// in which project_id is defined by project API,

// gateway_id is returned by gateway mngt API,

// both are ASCII strings.

“auth_token”:”xxx”

}

Return:

JSON STRING

{

“retcode”: “1”, //Return 1 if successful, otherwise >10000

“api_qid”:”QID”; //ASCII API QID

“timeout”:”1000”; //Timeout value in milliseconds.

}

getAPIStatus returns the following JSON structure:

{

“retcode”:”0”, // 0 if successful, or >10000 in case of errors.

"ver": “1.0”






}

A.2 String getCfg(String json_str);

Params:

{

“method”:”dev/ctl/getcfg”,

“device”:”id”, // For format, refer A.1.

“auth_token”:”xxx”,

“path”:”config_path”, //the path that maps to a module/app.

“name”:”config_name” //the name of the configuration entry.

}

Return: Same as getVer();

getAPIStatus() returns the following JSON structure:

{


“value”:value //the value of the config.(int/string/json)

}

A.3 String setCfg(String json_str);

Params:

{

“method”:”dev/ctl/setcfg”,



“path”:”config_path”, //the path that maps to a module/app.






“name”:”config_name”, //the name of the configuration entry.

“value”:value //the new value of the configuration entry.

}



{

“retcode":”0”, // 0 if successful, or >10000 in case of errors.

}

A.4 String Ping(String json_str);

Params:

{

“method”:”dev/ctl/ping”,



}



{


“data”:”pong”

}

A.5 String updateFirmware(String json_str);

Params:

{






“method”:”dev/ctl/updatefirmware”,



“srcaddr”:”url”, // firmware address, remotely or locally.

“version”:”1.1” // New firmware version.

}



{


“data”:”Execution result”

}

A.6 String system(String json_str);

Params:

{

“method”:”dev/ctl/system”,



“cmd”:”system cmd” //the command to be executed

}



{







“data”:”Execution result” //ASCII string.

}

A.7 String getAppList(String json_str);

Params:

{

“method”:”dev/ctl/getapplist”,



}

Return: Same as getVer().


{


“apps”:{

{ “appname”: “appname”, ”version”:”1.0”, “status”:”running”} ,

{ “appname”: “appname”, ”version”:”1.0”, “status”:”stopped”}

}

}

A.8 String startApp(String json_str);

Params:

{

“method”:”dev/ctl/startapp”,








“name”:”appname”, // APP name with full path

“params”:”parameter list”, // App params encoded in base64

}



{



}

A.9 String stopApp(String json_str);

Params:

{

“method”:”dev/ctl/stopapp”,



“name”:”appname” // Name of the app

}



{



}

A.10 String installApp(String json_str);






Params:

{

“method”:”dev/ctl/installapp”,



“apppath”:”url” // Location of the app.

}



{



}

A.11 String reboot(String json_str);

Params:

{

“method”:”dev/ctl/reboot”,



}



{








}

A.12 String fileC2D(String json_str);

Params:

{

“method”:”dev/ctl/filec2d”,



“src”:”path_name or filecontent” //base64 format, 512KB max.

“dest”:”path_name” // destination in the gateway file system.

}



{



}

A.13 String fileD2C(String json_str);

Params:

{

“method”:”dev/ctl/filed2c”,



“src”:”path_name” // the device file path.






“dest”:”path_name” // cloud URL (currently unused).

}



{

“retcode":”0”,

“data”:”File content” //base64 format

}

A.14 String rpcCall(String json_ptr);

Params:

{

“method”:”dev/ctl/rpccall”,



“cmd”:“string” // the RPC information.

}

The cmd consists of three components, “path”, “method”, and json

code, separated by one “space” character. If the json code has space

characters, they are still treats as part of the json code component.

Example of json code includes (one line is one example):

“abc”

1.234

{“abc”:1}

deviceSame as getVer();








{

“retcode":”0”,


}

A.16 String listCfg(String json_str);

Params:

{

“method”:”dev/ctl/listcfg”,



“path”:”config_path”, //path that maps to a module/app, could be

“*”

}



{


“configs”:[ //the list of the config.

{“path”:path, “name”:name, “data_type”:type, “description”:value}



]

}

A.17 String prepareLog(String json_str);






Params:

{

“method”:”dev/ctl/preparelog”,



“time_from”:”time”, // start time in epoch time (float format)

“time_to”:”time”, // end time in epoch time (float format)

“tag”:value // tag filter, could be “*”

}



{


“name”:”filename”, // the path and name of the file.

“compress”:protocol, //compress method of the file,

// support “bz2”, “gz”, “none”.

“size”:size //file size after compression.

}

A.18 String fileStats(String json_str);

Params:

{

“method”:”dev/ctl/filestats”,








"filename": “filename”,

}



{


“size”:filesize // size of the file.

}

§

Management API Definition




4.0 Management API Definition

For security, all management APIs require user authentication. All access to the cloud

platforms should present an “auth_token”. The system and project administrator obtain

the token with a password, and the API user gets the token via public key based

authentication. The token is used in all API calls to the backend, until it is expired or

removed by the logout API.

Management APIs also use JSON as the format for parameters and return values.

Because management APIs happen between cloud backend and the web front with

limited latency, bi-stage is not used here.

4.1 User Management

The cloud management platform defines a number of use roles.

Table 4. Use Roles

User Type Role Descriptions

System admin Super user, read/write to all data. Key functions are creating projects, adding project admin accounts, and access platform logs.

Project admin The main operator of the project management: maintaining project information and associated metadata; device control; query and export data and events.

API user Limited access right: read the metadata from project; access stats, raw data, and alert/event logs.

User management includes creating and modifying user information, together with user

authentication and session management.

Table 5. User Management API in Restful Paths


1.1 POST admin/user/adduser Add user with certain roles.

1.2 POST

admin/user/updateuser

Modify user information

1.3 POST

admin/user/getusrinfo

Get user information






1.4 POST admin/user/setpass Set user password

1.5a POST

admin/user/userlogin1

The login interface for all users.

1.5b POST

admin/user/userlogin2

User login with password

1.6 POST

admin/user/userlogout

The login interface for all users.

1.7 POST

admin/tokens/listtokens

List all active tokens. 2

1.8 POST

admin/tokens/deltoken

Delete one token 2

1.9 POST admin/user/setapikey Set the public key for API user

1.10 POST admin/user/apilogin2 API user login with keys

The following are the API details in JAVA language syntax.

Table 6. User Management API Details


1.1 String addUser(String json_str);

Params:

Json_str string (auth_token and username are required):

{

“method”:”admin/user/adduser”,

“auth_token”:”token”, //User token obtained via login API.

“username”:”user_name”,

“role”:”project_id,admin”, //or“project_id,api”,

//“system,admin” (require platform privilege)

}






Return:

{

“retcode”:”0” // 0 if successful, or >10000 in case of errors.

}

1.2 String updateUser(String json_str);

Params:

Json_str string (auth_token and username are required):

{

“method”:”admin/user/updateuser”,

“auth_token”:”token”, //User token.


“role”:”system,admin”, // or ”project_id,admin”, “project_id,api”,

// “project_id,ops” (currently unused)

“active”：”true” // whether the user account is activated.

}

Return:

{


}

1.3 String getUserInfo(String json_str);

Params:

{

“method”:”admin/user/getuserinfo”,

“auth_token”:”sid”,







}

Return: no password will be returned.

{


“role”:”system,admin”,

“createtime”:time,

“updatetime”:time, // epoch time, float format.

“active”：”true”

}

1.4 String setPass(String json_str);

Params:

{

“method”:”admin/user/setpass”,

“auth_token”:”sid”, // User token, or token of admins

“algorithm”:”SHA256”, //Currently SHA256, may add other

algorithms later.

“username”:”user_name”，

“passhash”:”user_password” // submit the password, so SSL is

required

// this is for server to check strength.

}

Return:

{







}

1.5a String userLogin1(String json_str);

Params:

{

“method”:”admin/user/userlogin1”,


}

Return:

{

“retcode”:”0”,

“login_id”:”xxx”, // login id representing this login request，

//can contain all login information

//so server can be stateless.

“allowed_ops”:”pass”, //Allowed next step process

//”pass” for password login, use userlogin2

//”key” for key-based login, use apilogin2

“algorithm”:” SHA256”, //Algorithm is SHA256

//or RSA (pub/prv)

“challenge”:”xxx”, //challenge string, only for “key” mode.

"alternatives": [...] // All possible methods.

}

1.5b String userLogin2(String json_str);

Params:

{






“method”:”admin/user/userlogin2”,

“login_id”:”xxx”, // login id generated by the server

“response”:”xxx” //Hash value calculated with user password.

}

Return:

{


“auth_token”:”xxx” // user token to be used in later API calls.

}

1.6 String userLogout(String json_str);

Params:

{

“method”:”admin/user/userlogout”,


}

Return:

{


}

1.7 String listTokens(String json_str);

Params:

{

“method”:”admin/tokens/listtokens”,







}

Return:

{


“sessions”:[

{“auth_token”:”xxx”, “uname”:”name”, “ip”:user_ip, “time”:”lasttime”}



]

}

1.8 String delToken(String json_str);

Params:

{

“method”:”admin/tokens/deltoken”,


“delete_token”:”xxx” //token to be deleted.

}

Return:

{


}

1.9 String setApiKey(String json_str);

Params:

{






“method”:”admin/user/setapikey”,

“auth_token”:”sid”, // User token, or token of admins

“algorithm”:”RSA”, // currently only support RSA.


“userkey”:”public_key” // Public key of the user, prv key is kept by

user

// Prv key should never be transmitted.

}

Return:

{


}

1.10 String apiLogin2(String json_str);

Params:

{

“method”:”admin/user/apilogin2”,

“login_id”:”xxx”, // login id representing this login request

“response”:”xxx” //Signature of the login_id with user prv key.

“crand”: “xxx” // A client generated random string,

// less than 256 char in length.

}

Return:

{


“auth_token”:”xxx” // user token to be used in later API calls.






}

Login process example:

1） When a user inputs username and password on the web page, the web page calls

POST /v1/admin/user/userLogin1 HTTP/1.1

Content-type: text/plain

Host: localhost

{

“username”: “root”,

}

2） Server encodes the information of the Login, such as user_name, ip, and time, into

the login id, and returns it

HTTP/1.1 200 OK


{

“retcode”: 0,

“login_id”: “ajldfjsadgjowierjoiwerowiejrsjlkjlkdjglksdjflsdf”,

“allowed_ops”:”PASS”

“algorithm”:”SHA256”,

}

3） The algorithm can be the following:

SHA256(user_password)

POST /v1/admin/user/userLogin2 HTTP/1.1


Host: localhost





{

“login_id”: “ajldfjsadgjowierjoiwerowiejrsjlkjlkdjglksdjflsdf”,

“response”:”xxx”

}

4） The server uses the information in the login_id to verify the correctness of the

response. If correct, generate an auth_token for the user. The auth_token could

contain user role, time, user IP, or server signature.

HTTP/1.1 200 OK


{

“retcode”: 0,

“auth_token”: “ajl9079wierjoiwerowiejrsjlkjlkdjglksdjflsdf”,

}

For API login, the response is the following:

Sign_SHA256_RSA(privateKey, username+challenge+crand)

For example, if the username is “api0123”, the challenge from server is “abcdef”, the

client randomly generates “9876”, and the response is verified by the following:

String message = “api0123abcdef9876”;

Signature sign = Signature.getInstance("SHA256WithRSA");

sign.initVerify(publicKey);

sign.update(message.getBytes());

sign.verify(response);

4.2 Project Information API

The project information management API manages project information and the status

of gateways in this project.





Table 7. Project Information Management API


2.1 POST admin/project/addproject Create a new project

(platform admin only)

2.2 POST

admin/project/updateproject

Update project information

2.3 POST

admin/project/getprojectinfo

Get project information.

2.4 POST

admin/project/deleteproject

Delete a project (platform

admin only)

2.5 POST admin/project/listprojects List all projects in the

platform

2.6 POST

admin/project/listdevinproject

List matched device in a

project

2.7 POST

admin/project/getprojectstats

Return project stats data. 2

2.8 POST

admin/project/listprojectusers

List all users in a project 2


Table 8. Project Information Management API Details


2.1 String addProject(String json_str);

Params:

Json_str structure:

{

“method”:”admin/project/addproject”,

“auth_token”:”token”, // User token

“name”:”project name”, // Name of the project

“vendor”:”vendor name”, // Vendor name






“info”:”project information”, //Short description of the project

“tag”:”test, energy”, //Project tags.

}

Return:

{


“project_id”:”id” // Project ID assigned by the system

}

2.2 String updateProject(String json_str);

Params:

Json_str structure: (token and project_id are required, the others are

options, and note that “vendor” field cannot be changed)

{

“method”:”admin/project/updateproject”,


“project_id”:”id”, // Project ID assigned by the system


“info”:”project information”, // Short description of the project

“tag”:”test, energy”, //Project tags

}

Return:

{


}

2.3 String getProjectInfo(String json_str);






Params:

Json_str structure:

{

“method”:”admin/project/getprojectinfo”,



}

Return:

Json_str structure:

{


“project_id”:”id”, // ASCII string


“vendor”:”vendor name”,

“info”:”project information”,

“createtime”:”time”, //Project creation time in epoch (float

number)

“updatetime”:”time”, //Project update time in epoch (float

number)

“tag”:”test, energy”

}

2.4 String deleteProject (String json_str);

Params:

Json_str structure:

{






“method”:”admin/project/deleteproject”,



}

Return:

Json_str structure:

{


}

2.5 String listProjects (String json_str);

Params:

Json_str structure:

{

“method”:”admin/project/listprojects”,


}

Return:

Json_str structure:

{


“projects”:[ // Deleted projects are not included.

{“id”:”id1”, “name”:”project1” },

{“id”:”id2”, “name”:”project2” },

{“id”:”id3”, “name”:”project3” }






]

}

2.6 String listDevinProject (String json_str);

Params:

Json_str structure:

{

“method”:”admin/project/listdevinproject”,



“filter”:””, //Device filters, currently is empty to match all.

}

Return:

Json_str structure:

{


“total”:100, // Number of devices matched and returned.

“gateways”: [

{ “gateway_id”:id, “name”:gw_name, “status”:status},


{ “gateway_id”:id, “name”:gw_name, “status”:status}

]

}

2.7 String getProjectStats(String json_str);

Params:

TBD






Json_str structure:

{

“method”:”admin/project/getprojectstats”,



}

Return:

Json_str structure:

{


“activedevcounts”:100, // The number of active devices.

“offlinedevcounts”:100, // the number of offline devices.

“alarmstarttime”: time, // UTC time where alarmcounts start.

“alarmcounts”:[“n1”, “n2”, “n3”, …, “n72”]

//number of alarms in each hour.

// hours are UTC time for 0:00 clock from two

// days ago to 24:00 today.

// For remaining hours today, these numbers

// will be 0.

“stats”:”” //other stats.

}

2.8 String listProjectUsers(String json_str);

Params:

Json_str structure:






{

“method”:”admin/project/listprojectusers”,



}

Return:

Json_str structure:

{


“users”:[

{“username”:name, “role”:”project_id,admin”},

{“username”:name, “role”:”project_id,ops”},

{“username”:name, “role”:”project_id,api”}

]

}

4.3 Device Information API

The device information management API maintains the information (metadata) about

devices, such as device information, the data points in a device, and the groups in the

project.

Table 9. Device Information Management API


3.1 POST admin/dev/adddev Add a new device entry.

3.2 POST admin/dev/updatedev Update device information.






3.3 POST admin/dev/getdevinfo Get device information.

3.4 POST admin/dev/deletedev Delete a device entry.

3.5 POST admin/dev/adddatapoint Add a data point to a device

3.6 POST admin/dev/updatedatapoint Remove data point from

device

3.7 POST admin/dev/deletedatapoint Update data point

information

3.8 POST admin/dev/getdatapointinfo Get data point information

3.9 POST admin/dev/listdatapoints List data point in a project

3.10 POST admin/group/addgroup Add a group in this project.

3.11 POST admin/group/updategroup Update group information

3.12 POST admin/group/getgroupinfo Get group information

3.13 POST admin/group/deletegroup Delete a group. 2

3.14 POST admin/group/listgroups List groups in the project.

3.15 POST

admin/project/listdevbygroup

List devices by group

3.16 POST

admin/dev/listdatapointbygroup

List data point by group

3.17 POST admin/group/listgrouppath List hierarchy path of a

group

3.18 POST admin/dev/getdevkey Get the device key of a

device


Table 10. Device Management API Details


3.1 String addDev(String json_str);






Params:

Json_str structure:

{

“method”:”admin/dev/adddev”,


“project_id”:”id”, // Project ID.

“device_hw_id”:”id”, // Hardware ID of a device, can be its

//serial number or MAC address.

“tag”:”china, rockontrol”, //Device tags

“name”:”device name”, //Name of the device.

“vendor”:”intel”, // Device vendor.

“systeminfo”:”x86, linux”, // Software system information of the

device

“groupids”:[id1, id2], // Group IDs this device is associated with

“location”:”address” // User defined location information

// Recommendations: lng:110.2,lat: 48.1

// or gcj02:xxxx

// or bd09ll:xxxx

// or addrd: 100 Main street, Beijing

}

Return:

{


“gateway_id”:”id”, // the device ID assigned to this device

}






3.2 String updateDev(String json_str);

Params:

Json_str structure: token, project_id, and gateway_id are required.

{

“method”:”admin/dev/updatedev”,


“project_id”:”id”, // Project ID.

“gateway_id”:”id”, // Device ID

“device_hw_id”:”id”, // the following are the same as the ones in

// AddDev API.

“tag”:”china, rockontrol”,

“name”:”device name”,

“vendor”:”intel”,

“systeminfo”:”x86, linux”,

“groupids”:[id1, id2],

“location”:”address”,

}

Return:

{


}

3.3 String getDevInfo(String json_str);

Params:

Json_str structure:






{

“method”:”admin/dev/getdevinfo”,


“project_id”:”id”, // Project ID


}

Return:

Json_str structure:

{




“device_hw_id”:”id”, // the following are the same as the ones in

// AddDev API.

“tag”:”china, rockontrol”,

“name”:”device name”,

“vendor”:”intel”,

“systeminfo”:”x86, linux”,

“groupids”:[id1, id2],

“location”:”address”,

“createtime”:time, // Device creation time from epoch (float)

“updatetime”:”time”, //Device update time from epoch (float)

}

3.4 String deleteDev(String json_str);






Params:

Json_str structure:

{

“method”:”admin/dev/deletedev”,


“project_id”:”id”,

“gateway_id”:”id”,

}

Return:

Json_str structure:

{

“retcode”:”0”

}

3.5 String addDataPoint(String json_str);

Params:

Json_str structure:

{

“method”:”admin/dev/adddatapoint”,




“name”:”datapoint”, // Name of the data point

“datatype”:”float”, // Data type of this data point

“dataunit”:”kw”, // Data unit, could be the following






// Kwh/raw Kilowatt hour

// Va/raw A phase voltage

// Vb/raw B phase voltage

// Vc/raw C phase voltage

// activePower/raw Active power

// Celsius/raw Temperature

// t/raw Ton

// Kpa/raw Pressure

// m3/raw Current

“description”:”default”, // User defined description

“groupid”:[group_id1,…] // Groups the data point is associated with

“tag”:”” // Data point tags

“userdata”:url, // User data, could be URL

}

Return:

Json_str structure:

{


“datapoint_id”:”id” // Platform assigned data point ID.

}

3.6 String updateDataPoint(String json_str);

Params:

Json_str structure: token,project_id,gateway_id, datapoint_id are

required.

{






“method”:”admin/dev/updatedatapoint”,




“datapoint_id”:”id” // Data point ID

“name”:”datapoint”, // The following are the same as the ones

// in AddDataPoint API.

“datatype”:”float”,

“dataunit”:”kw”,

“description”:”default”,

“groupid”:[group_id1, ]

“tag”:””,

“userdata”:url,

}

Return:

Json_str structure:

{


}

3.7 String deleteDataPoint(String json_str);

Params:

Json_str structure:

{

“method”:”admin/dev/deletedatapoint”,









“datapoint_id”:”id”, // Data point ID

}

Return:

Json_str structure:

{


}

3.8 String getDataPointInfo(String json_str);

Params:

Json_str structure: token,project_id,gateway_id, datapoint_id are

required

{

“method”:”admin/dev/getdatapointinfo”,





}

Return:

Json_str structure:

{








“name”:”Temperature 1”, // Name of the data point

“datatype”:”float”, // The following are the same as the ones

// in AddDataPoint API.

“dataunit”:”kw”,

“description”:”default”,

“tag”:””,

“userdata”:url,

“groupid”:[group_id1,]

“createtime”:time, // Data point creation time in epoch (float)

“updatetime”:time, // Data point update time in epoch (float)

“deleted”:false // whether data point has been deleted.

}

3.9 String listDataPoints(String json_str);

Params:

Json_str structure:

{

“method”:”admin/dev/listdatapoints”,



“gateway_id”:”id”, // Device ID, could be * for wild card

}

Return:

Json_str structure: Deleted data points will not be included.






{


“datapoints”: [

{“gateway_id”:gid, “id”: id1, “name”:name1, “userdata”:userdata },


{“gateway_id”:gid, “id”: id3, “name”:name3, “userdata”:userdata }

]

}

3.10 String addGroup(String json_str);

Params:

Json_str structure:

{

“method”:”admin/group/addgroup”,



“name”:”South Bldg 1”, // Group name, can also be “meter 1”

“type”:”zone”, // Group type, only two types “zone”,”meter”.

“parentgroupid”:”groupid”, // Parent group, 0 if empty.

// parent group must share the same type

“descriptions”:”Building”, // Description of the group.

“userdata”:”customized”, // User defined data, such as barcode.

“tags”:”meters, dev” // User defined tags

}

Return:






{


“group_id”:”id” // Platform assigned group ID

}

3.11 String updateGroup(String json_str);

Params:

Json_str structure: token, project_id, gateway_id are required.

{

“method”:”admin/group/updategroup”,



“group_id”:”id”, // Group ID

“name”:”South Bldg 1”, // The following are the same as the ones

// defined in AddGroup API.

“type”:”zone”,

“parentgroupid”:”groupid”,

“descriptions”:”Building”,

“userdata”:”customized”,

“tags”:”meters, dev”

}

Return:

{


}






3.12 String getGroupInfo(String json_str);

Params:

Json_str structure:

{

“method”:”admin/group/getgroupinfo”,




}

Return:

Json_str structure:

{




“name”:”South Bldg 1”, // The following are the same as the ones

// defined in AddGroup API.

“type”:”zone”,

“parentgroupid”:”groupid”,

“descriptions”:”Building”,

“userdata”:”customized”,

“tags”:”meters, dev”

“childrengroupids”:[id1, id2], // Groups belong to this group．

// read-only, updated by the system.






“createtime”:time, // Group creation time in epoch (float)

“updatetime”:”time”, // Group update time in epoch (float)

}

3.13 String deleteGroup(String json_str);

Params:

Json_str structure:

{

“method”:”admin/group/deletegroup”,




}

Return:

Json_str structure:

{


}

3.14 String listGroups(String json_str);

Params:

Json_str structure:

{

“method”:”admin/group/listgroups”,








“group_id”:”id1”, // List all groups related to id1, * for wild card

“type”:”meter”, // Group type, * for wild card

}

Return:

Json_str structure:

{


“groups”:[

{“id”:”id1”, “name”:”name1”, “type”:”zone”, “parentid”:”0”},

{“id”:”id2”, “name”:”name1”, “type”:”zone”, “parentid”:”id1”},

{“id”:”id3”, “name”:”name1”, “type”:”zone”, “parentid”:”id1”}

]

}

3.15 String listDevByGroup(String json_str);

Params:

Json_str structure:

{

“method”:”admin/project/listdevbygroup”,



“group_id”:”id1”, // List device in id1 including child groups.

// only applicable to “zone” groups.

}

Return:






Json_str structure:

{


“gateways”:[



{ “gateway_id”:id, “name”:gw_name, “status”:status}

]

}

3.16 String listDataPointByGroup(String json_str);

Params:

Json_str structure:

{

“method”:”admin/dev/listdatapointbygroup”,



“group_id”:”id1”, // List all the datapoints in group id1.

}

Return:

Json_str structure:

{


“datapoints”: [

{“gateway_id”:gid, “id”: id1, “name”:name1, “userdata”:userdata},







{“gateway_id”:gid, “id”: id3, “name”:name3, “userdata”:userdata }

]

}

3.17 String listGroupPath(String json_str);

Params:

Json_str structure:

{

“method”:”admin/group/listgrouppath”,



“group_id”:”gid1”, // the start group ID

}

Return:

Json_str structure:

{


“path”: [

{“id”: gid1, “name”:name1 },

{“id”: parentid1, “name”:name2 },

{“id”: grandparentid2, “name”:name3 },

{“id”: rootid, “name”:rootname }

]

}






3.18 String getDevKey(String json_str);

Params:

Json_str structure:

{

“method”:”admin/dev/getdevkey”,



“gateway_id”:”dev1”, // Device ID

}

Return:

Json_str structure:

{


“devkey”:”xxx” // Device key, could be 256 AES key.

}

4.4 Data Management API

The data management APIs provide the interface to query and export data. The data

could be raw data collected from sensor, or aggregated statistics data (stats data). Stats

data can be based on data from a number of data points from the same or different

devices. This set of API also includes the management of stats data metadata. Because

the export data calls may take time to complete, they are implemented as bi-stage APIs.

Table 11. Data Management API


4.1 POST data/rawdataquery Query raw data by filters.

4.2 POST data/rawdataexport Export raw data. 2






4.3 POST data/getexportstatus Get the data export status.

4.4 POST data/statsdataquery Query stats data by rules. 2

4.5 POST data/statsdataexport Export stats data. 2

4.6 POST data/alarmdataquery Query alarm data.

4.7 POST data/alarmdataexport Export alarm data. 2

4.8 POST alm/pollalarm Poll alarm. 2


Table 12. Data Management API Details


4.1 String rawDataQuery(String json_str);

Params:

Json_str structure:

{

“method”:”data/rawdataquery”,


“maxdatapoints”:”1000”, // Max number of data point to be

returned,

// 0 means unlimited.



“project_id”:”id1”, // Project filter, based on id.

“gateway_id”: “*”, // Gateway ID filter, * for wild card

“datapoint_id”:”*”, // Datapoint ID filter, * for wild card

“skip”:”100”, // Skip the first N number of record in result






// e.g., skip=100 starts from the 101st record.

“order”:”asc/desc” // Order by time, default ascend order.

}

}

Return:

{


"maxpoints": 100, // The total number of records matched.

// independent of maxdatapoint and skip value

"from": t1,

"to": t2,

"metadata": [

{"datapoint": "path", “name”:”name”, “userdata”:uri, “datatype”:type,

“dataunit”:unit}





],

“dataseries”:[

{"datapoint": "path1", “time”:t1, “value”:189}




]

}






Notes:

There are system reserved data points, prefixed with sys_*. These

data points belong to gateways. The current data points include:

sys_online, sys_c0, sys_c1, …, sys_c9. These data points are reserved

by gateway systems to send system level data to the backend. With

the rawdataquery API, the caller can specify these data points and

retrieve the data. The sys_online records the on/off status of the

gateway, 0 represents offline, 1 represents online. Three will be at

least one datapoint per day at the beginning of the day.

These system level data points cannot be managed by data point

management APIs. They will not appear in the data point list API

either.

4.2 String rawDataExport (String json_str);

Params:

Json_str structure:

{

“method”:”data/rawdataexport”,


“output”:”csv”, // Could be ”csv” or “zipcsv”

“time_from”:”time”, // Start time in epoch (float number)

“time_to”:”time”, // End time in epoch (float number)

“project_id”:”id1”, // Project filter

“gateway_id”: “*”, // Gateway filter, * for wild card

“datapoint_id”:”” // data point filter, * for wild card.

}

Return: (Note that this is a bi-stage API)

JSON STRING

{






“retcode”: “1”, //1 if successful, or >10000 in case of errors.

“api_qid”:”QID”; // API query ID in ASCII format

“timeout”:”1000”; // timeout value for stage-2 call (milliseconds)

}

Notes:

See 4.1.

getExportStatus returns the following JSON structure:

{

“retcode”:”0”, //>10000 in case of errors.

"data": “URL” // URL where the export file can be downloaded.

}

4.3 String getExportStatus(String json_str);

Function: query the status and result of data export call,

similar to getAPIStatus

Params: JSON structure

{

“method”:”data/getexportstatus”,

“api_qid”:”QID”, //API query ID from the stage-1 API call.

“auth_token”:”xxx” // user token

}

Return value is also in JSON format, in case of API finished execution,

{

“retcode”:”0”, //API return code, 0 if successful, >10000 for error

“data”:”url” // URL where exported data can be downloaded






}

If the API call is still in progress, return

{

“retcode”:”1”, // Code 1 for inprocess.

“api_qid”:”QID”, // API query QID

“time_out”:”100”, // Timeout value for next query, in millisecond.

}

4.4 String statsDataQuery(String json_str);

Params:

Json_str structure:

{

“method”:”data/statsdataquery”,



returned,





“stats_id”:”*”, // Stats data ID, * for wild card.




}

Return:






{


"maxpoints": 100,

"from": t1,

"to": t2,

"metadata": [

{"statspath": "path", “name”:”name”, “userdata”:uri, “datatype”:type,


{"statspath ": "path", “name”:”name”, “userdata”:uri, “datatype”:type,


{"statspath ": "path", “name”:”name”, “userdata”:uri, “datatype”:type,


],

“dataseries”:[

{"statspath": "path1", “time”:t1, “value”:189}




]

}

4.5 String statsDataExport (String json_str);

Params:

Json_str structure:

{

“method”:”data/statsdataexport”,







“output”:”csv”, // could be ”csv”, “zipcsv”




“stats_id”:”*” // Stats data ID, * for wild card

}


JSON STRING

{




}


{



}

4.6 String alarmDataQuery(String json_str);

Params:

Json_str structure:






{

“method”:”data/alarmdataquery”,



returned,





“tag”:”*”, // Filter based on alarm tag, * for wild card




}

Return:

{


"maxpoints": 100,

"from": t1,

"to": t2,

“dataseries”:[

{"tag": "tag1", “time”:t1, “value”:msg1, “code”: code, “gateway_id”: id,

“alarm_id”: sequence_number},

{"tag": "tag2", “time”:t2, “value”:msg2, “code”: code, “gateway_id”: id,

“alarm_id”: sequence_number }

]






}

Note: There are specified ranges for the alarm code. Code 25000-

29999 are for gateway alarm, code 35000-39999 for gateway log

code, and code 80000-89999 are free for application to usage.

4.7 String alarmDataExport (String json_str);

Params:

Json_str structure:

{

“method”:”data/alarmdataexport”,






“tag”:”*” // alarm filter, * for wild card.

}


JSON STRING

{




}







{



}

4.8 String pollAlarm (String json_str);

Params:

Json_str structure:

{

“method”:”alm/pollalarm”,


“project_id”:”id” // project ID

“timeout”:”time”, // timeout value in milliseconds.

“last_seq”:”seq” // sequence number from last query, may be ””

}

Return:

JSON STRING if alarm is found.

{

“retcode”: “0”, //0 if successful

“retry”:”timeout”, // retry after specified milliseconds.

“gateway_id”:”gw_id”, // gateway ID of the alarm is from.

“timestamp”:”time”, // epoch time of the alarm generated time

“seq”:”seq number”, // sequence number of this alarm.

“code”:”code”, // alarm code or type of alarm.






“tag”:”tag”, // user defined tag on this alarm.

“message”:”msg” // alarm content.

}

If no alarm is found,

{

“retcode”: “2”, //2 if successful.

“retry”:”timeout”, // retry after specified milliseconds.

}

If error happens,

{

“retcode”:”code”, // >10000 error code.

“reason”:”failed reason”

}

4.5 Log Management API

The log management APIs provide interfaces to query and export system log. This is

only available to platform admins.

Table 13. Log Management APIs


5.1 POST logs/rawlogquery Query log data with filter.

5.2 POST logs/rawlogexport Export raw log data.

5.3 POST logs/getservicestats Obtain running stats of

server.

2






Table 14. Log Management API Details


5.1 String rawLogQuery(String json_str);

Params:

Json_str structure:

{

“method”:”logs/rawlogquery”,



returned,




“log_tag”:”Web”, // Log type filter, * for wild card.




}

Return:

{


"maxpoints": 100,

"from": t1,

"to": t2,

“entries”:[






{"time": t1, “tag”:”Web”, “value”:”user logined.”}



]

}

5.2 String rawLogExport (String json_str);

Params:

Json_str structure:

{

“method”:”logs/rawlogexport”,





“log_tag”:”Web”, // Log type filter, * for wild card.

}


JSON STRING

{




}






API 4.3: getExportStatus returns the following JSON structure:

{



}

5.3 String getServiceStats(String json_str);

Params:

Json_str structure:

{

“method”:”logs/getservicestats”,


}

Return:

{


"uptime": “value”, // system uptime in milliseconds.

"log_written": “value”, // number of log entries since last restart

"failed_login": “value”, // number of login fails since last restart

“gw_cmds”: “value” // number of gateway command since restart.

}

§

Error Code Range




5.0 Error Code Range

The error codes of the system are pre-allocated in the following ranges.

Table 15. Error Code Ranges

Error code Purpose Note

0 Reserved for API call return (successful)

1 Reserved for API call return

10000-18999 Reserved for API system error code

19000-19999 Reserved for API SDK return code

20000-24999 Reserved

25000-29999 Allocated for gateway alarms Usable for integration

30000-34999 Reserved

35000-39999 Gateway log code Usable for integration

80000-89999 Allocated for applications to use Usable for integration

§

API List




Appendix A API List

Table 16. API List

Index API Method and Path Description Group

A.1 POST dev/ctl/getVer Get gateway version. Device

control A.2 POST dev/ctl/getcfg Get gateway configuration.

A.3 POST dev/ctl/setcfg Set gateway configuration.

A.4 POST dev/ctl/ping Get the gateway online status.

A.5 POST dev/ctl/updatefirmware Update gateway firmware.

A.6 POST dev/ctl/system Execute customized system

command.

A.7 POST dev/ctl/getapplist Get list of applications on

gateway.

A.8 POST dev/ctl/startapp Start one application.

A.9 POST dev/ctl/stopapp Stop one application.

A.10 POST dev/ctl/installapp Install one application.

A.11 POST dev/ctl/reboot Restart the gateway.

A.12 POST dev/ctl/filec2d Transfer a file from cloud to

device.

A.13 POST dev/ctl/filed2c Transfer a file from device to

cloud.

A.14 POST dev/ctl/rpccall Call device RPC.

A.15 POST dev/ctl/getapistatus Get API execution status.

A.16 POST dev/ctl/listcfg List gateway configuration.

A.17 POST dev/ctl/preparelog Gateway put log into a local file.

A.18 POST dev/ctl/filestats Return information of local file.

API List




1.1 POST admin/user/adduser Add user with certain roles. User

mngt 1.2 POST admin/user/updateuser Modify user information.

1.3 POST admin/user/getusrinfo Get user information.

1.4 POST admin/user/setpass Set user password.

1.5a POST admin/user/userlogin1 The login interface for all users.

1.5b POST admin/user/userlogin2 User login with password.

1.6 POST admin/user/userlogout The login interface for all users.

1.7 POST admin/tokens/listtokens List all active tokens.

1.8 POST admin/tokens/deltoken Delete one token.

1.9 POST admin/user/setapikey Set the public key for API user.

1.10 POST admin/user/apilogin2 API user login with keys.

2.1 POST admin/project/addproject Create a new project (platform

admin only).

Project

mngt

2.2 POST

admin/project/updateproject

Update project information.

2.3 POST

admin/project/getprojectinfo

Get project information.

2.4 POST

admin/project/deleteproject

Delete a project (platform admin

only).

2.5 POST admin/project/listprojects List all projects in the platform.

2.6 POST

admin/project/listdevinproject

List matched device in a project.

2.7 POST

admin/project/getprojectstats

Return project stats data.

2.8 POST

admin/project/listprojectusers

List all users in a project.

3.1 POST admin/dev/adddev Add a new device entry. Device

mngt 3.2 POST admin/dev/updatedev Update device information.

API List




3.3 POST admin/dev/getdevinfo Get device information.

3.4 POST admin/dev/deletedev Delete a device entry.

3.5 POST admin/dev/adddatapoint Add a data point to a device.

3.6 POST

admin/dev/updatedatapoint

Remove data point from device.

3.7 POST

admin/dev/deletedatapoint

Update data point information.

3.8 POST

admin/dev/getdatapointinfo

Get data point information.

3.9 POST admin/dev/listdatapoints List data point in a project.

3.10 POST admin/group/addgroup Add a group in this project.

3.11 POST admin/group/updategroup Update group information.

3.12 POST admin/group/getgroupinfo Get group information.

3.13 POST admin/group/deletegroup Delete a group.

3.14 POST admin/group/listgroups List groups in the project.

3.15 POST

admin/project/listdevbygroup

List devices by group.

3.16 POST

admin/dev/listdatapointbygroup

List data point by group.

3.17 POST

admin/group/listgrouppath

List hierarchy path of a group.

3.18 POST admin/dev/getdevkey Get the device key of a device.

4.1 POST data/rawdataquery Query raw data by filters. Data

mngt 4.2 POST data/rawdataexport Export raw data.

4.3 POST data/getexportstatus Get the data export status.

4.4 POST data/statsdataquery Query stats data by rules.

4.5 POST data/statsdataexport Export stats data.

4.6 POST data/alarmdataquery Query alarm data.

API List




4.7 POST data/alarmdataexport Export alarm data.

4.8 POST alm/pollalarm Poll alarm.

5.1 POST logs/rawlogquery Query log data with filter. Log

mngt 5.2 POST logs/rawlogexport Export raw log data.

5.3 POST logs/getservicestats Obtain running stats of server.

§

Gateway Management Solution Based on Intel® IoT … · Gateway Management Solution Based on ......

Documents

Transcript of Gateway Management Solution Based on Intel® IoT … · Gateway Management Solution Based on ......