Difference between revisions of "IoTGateway/SDK/WirelessSensorNetworkSDK"
(→Abstract) |
Eric.liang (talk | contribs) (→Sensor Network Manager API Definition) |
||
Line 409: | Line 409: | ||
− | + | '''Example:''' | |
'''Condition''' | '''Condition''' | ||
Line 422: | Line 422: | ||
− | + | "IoTGW": { | |
− | + | "WSN": { | |
− | "IoTGW": { | + | "WSN0": { |
− | + | "Info": { | |
− | "WSN": { | + | "e": [{"n":"SenHubList","sv":"","asm":"r"}, |
− | + | {"n":"Topology","sv":"","asm":"r"}, | |
− | "WSN0": { | + | {"n":"Health","v":100,"asm":"r"}, |
− | + | {"n":"Name","sv":"WSN0","asm":"r"} | |
− | "Info": { | + | ], |
− | + | "bn":"Info" | |
− | "e": [{"n":"SenHubList","sv":"","asm":"r"}, | + | }, |
− | + | "bn":"0000852CF4B7B0E8", | |
− | {"n":"Topology","sv":"","asm":"r"},{"n":"Health","v":100,"asm":"r"}, | + | "ver":1 |
− | + | }, | |
− | {"n":"Name","sv":"WSN0","asm":"r"}], | + | "WSN1": { |
− | + | "Info": { | |
− | + | "e": [{"n":"SenHubList","sv":"","asm":"r"}, | |
− | + | {"n":"Topology","sv":"","asm":"r"}, | |
− | }, | + | {"n":"Health","v":100,"asm":"r"}, |
− | + | {"n":"Name","sv":"WSN1","asm":"r"}], | |
− | + | "bn":"Info" | |
− | + | }, | |
− | + | "bn":"0000852CF4B7B0E7", | |
− | + | "ver":1 | |
− | }, | + | }, |
− | + | "bn":"WSN" | |
− | + | }, | |
− | "WSN1": { | + | "ver": 1 |
− | + | } | |
− | "Info": { | ||
− | |||
− | "e": [{"n":"SenHubList","sv":"","asm":"r"}, | ||
− | |||
− | |||
− | |||
− | {"n":"Name","sv":"WSN1","asm":"r"}], | ||
− | |||
− | "bn":"Info" | ||
− | |||
− | }, | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | }, | ||
− | |||
− | "bn":"WSN" | ||
− | |||
− | }, | ||
− | |||
− | "ver": 1 | ||
− | |||
− | } | ||
− | |||
− | |||
− | |||
'''Syntax''' | '''Syntax''' | ||
Line 503: | Line 475: | ||
<div style="margin-left:1.69cm;margin-right:0cm;">[in] control id. Refer to <span style="background-color:#d8d8d8;">SN_CTL_ID</span></div> | <div style="margin-left:1.69cm;margin-right:0cm;">[in] control id. Refer to <span style="background-color:#d8d8d8;">SN_CTL_ID</span></div> | ||
− | + | pParam1 | |
[in] the point to parameter 1 ( data type depend on SN_CTL_ID) | [in] the point to parameter 1 ( data type depend on SN_CTL_ID) | ||
Line 513: | Line 485: | ||
<nowiki>*pPev1</nowiki> | <nowiki>*pPev1</nowiki> | ||
− | [in] | + | [in] reserved for later use. Must be ?ULL?? |
<div style="margin-left:0cm;margin-right:0cm;"><nowiki>*pPev2</nowiki></div> | <div style="margin-left:0cm;margin-right:0cm;"><nowiki>*pPev2</nowiki></div> | ||
Line 520: | Line 492: | ||
'''Return Values ''' | '''Return Values ''' | ||
− | <div style="margin-left:0cm;margin-right:0cm;">SNM__OK: Successfully | + | <div style="margin-left:0cm;margin-right:0cm;">SNM__OK: Successfully to call this function.</div> |
<div style="margin-left:1.905cm;margin-right:0cm;">>0 : Failed to call this function.</div> | <div style="margin-left:1.905cm;margin-right:0cm;">>0 : Failed to call this function.</div> | ||
Line 533: | Line 505: | ||
<div style="margin-left:0cm;margin-right:0cm;">nCtlId: <span style="background-color:#d8d8d8;">SN_Set_ReportSNManagerDataCbf</span></div> | <div style="margin-left:0cm;margin-right:0cm;">nCtlId: <span style="background-color:#d8d8d8;">SN_Set_ReportSNManagerDataCbf</span></div> | ||
− | <nowiki>*</nowiki>pParam1: | + | <nowiki>*</nowiki>pParam1: <span style="background-color:#d9d9d9;">ReportSNManagerDataCbf</span> |
Line 565: | Line 537: | ||
<div style="margin-left:1.69cm;margin-right:0cm;">[in] event id. Refer to <span style="background-color:#d9d9d9;">SN_EVENT_ID</span></div> | <div style="margin-left:1.69cm;margin-right:0cm;">[in] event id. Refer to <span style="background-color:#d9d9d9;">SN_EVENT_ID</span></div> | ||
− | + | pzDataBuffer | |
[in] the point to data with JSON format | [in] the point to data with JSON format |
Revision as of 03:59, 18 August 2016
Date | Version | Description / Major change |
2015/3/30 | 1.1 | Eric Liang, create draft document |
2015/10/08 | 1.2 | Eric Liang, add Get/Set API |
Contents
Abstract
Overview
Introduction
Terminology
This specification makes use of the following additional terminology:
IoT Gateway (IoTGW): It integrates technologies and protocols for networking, embedded control, enterprise-grade security, and easy manageability on which application-specific software can run. Connectivity up to the WISE Cloud and down to sensors and existing controllers embedded in the system. Pre-process filtering and gathering of selected data for delivery.
Sensor Hub (SenHub): A sensor hub is capable of performing some processing, gathering sensory information and communicating with other connected hubs in the network. A sensor hub should be small in size, consume extremely low energy, operate in high volumetric densities, be autonomous and operate unattended, and be adaptive to the environment. As sensor hubs are typically very small electronic devices, they can only be equipped with a limited power source.
Sensor (Sen): Sensor is hardware device that produce a measurable response to a change in a physical condition like temperature or pressure. Sensor measures physical data of the parameter to be monitored.
Resource Type(rt): Each root resource of a function set is assigned a Resource Type parameter, therefore making it possible to discover it. The Resource Type parameter defines the value that MUST be included in the rt= field of the sensor.
IPSO Application Framework
HTTP, REST, XML, JSON, COAP and other key components of web technology are powerful mechanisms in an Internet of Things application.
Note: The objective of the Alliance is not to define technologies, but to document the use of IP-based technologies defined at the standard organizations such as IETF with focus on support by the Alliance of various use cases.
Function Sets: The framework is organized into groups of resource types called Function Sets. A Function Set has a recommended root path, under which its sub-resources are organized. Each Function Set is assigned a Resource Type parameter, therefore making it possible to discover it.
Function Set | Root Path | Resource Type |
General Purpose IO | /gpio | gpio |
Power | /pwr | pwr |
Load Control | /load | load |
Sensors | /sen | sen |
Light Control | /lt | lt |
Message | /msg | msg |
Location | /loc | loc |
Configuration | /cfg | cfg |
IPSO Smart Object
The object model from OMA LWM2M is reused to define application level IPSO Smart Objects. This enables the OMA Name Authority (OMNA) to be used to register new objects, and enables existing LWM2M compliant device libraries and server software to be used as an infrastructure for IPSO Smart Objects
Media Types for Sensor Markup Language (SENML)
Semantics
SenML | JSON | Type | Description |
Base Name | bn | String | This is a string that is prepended to the names found in the entries |
Base Time | bt | Integer | A base time that is added to the time found in an entry |
Base Units | bu | String | A base unit that is assumed for all entries, unless otherwise indicated |
Version | ver | Number | Version number of media type format |
Measurement or Parameters | e | Array | Array of values for sensor measurements or other generic parameters |
Name | n | String | Name of the sensor or parameter |
Units | u | String | Units for a measurement value |
Value | v | Float | Value of the entry |
String Value | sv | String | |
Boolean Value | bv | Boolean | |
Value Sum | s | Float | Integrated sum of the values over time |
Time | t | Integer | Time when value was recorded |
Update Time | ut | Integer | Update time. A time in seconds that represents the maximum time before this sensor will provide an updated reading for a measurement. |
The Data Type of Sensor Data Type
Data Type (type) | SenML Field |
b (boolean) | bv |
s (string) | s |
e (enum) | e |
i (integer) | v |
d (decimal) | v |
h(hexadecimal) | s |
o(octet-stream) | s |
Advantech Sensor Semantics
SenML | JSON | Type | Description |
Min Range Value | min | Float | The minimum value that can be measured by the sensor |
Max Range Value | max | Float | The maximum value that can be measured by the sensor |
Access Mode | asm | String | The access mode of the resource. Ex: read (r), write (w), read/write (rw) |
Standard Format | st | String | The sensor format is which standard format |
Health Status | Health | Integer | The health status of network or device. Range: -1 ~ 100
Good: > 80, Average: 60 ~ 80, Below Average: 40~60, Bad:0~40, -1: Off line or Fault |
Example
{"n":"Room Temp","u":"Cel","v":0,"min":0,"max":100,"asm":"r","type":"d","rt":"ucum.Cel","st":"ipso","exten":"sid=3303"}
Application Program Interface (API)
Event of Callback
typedef enum { // Interface: 1000 ~ 1999 SN_Inf_UpdateInterface_Data = 1000, // Update Interface data // Sensor Hub: 2000 ~ 2999 SN_SenHub_Register = 2000, // A SenHub connected SN_SenHub_SendInfoSpec = 2001, // Report the resource information of SenHub SN_SenHub_AutoReportData = 2002, // Auto report data value of SenHub SN_SenHub_Disconnect = 2003, // A SenHub disconnected SN_SetResult = 3000, // Return the result of setting value } SN_EVENT_ID;
Command ID
typedef enum { SN_Set_ReportSNManagerDataCbf = 3000, // Set Event Callback function point } SN_CTL_ID;
Return Code Definition
typedef enum { SN_ER_NOT_IMPLEMENT = -13, // Dose Not Support this command (501) SN_ER_TIMEOUT = -12 // Request Timeout (408) SN_ER_SYS_BUSY = -11 // System is busy (503) SN_ER_VALUE_OUT_OF_RANGE = -10 // Value is out of range (416) SN_ER_SYNTAX_ERROR = -9 // Format is correct but syntax error (422) SN_ER_FORMAT_ERROR = -8 // Format error (415) = SN_ER_REQUEST_ERROR = -7 // Request error (400) SN_ER_RESOURCE_LOSE = -6 // Resource is lose (410) SN_ER_RESOURCE_LOCKED = -5, // Resource is in setting (426) SN_ER_NOT_FOUND = -4, // Resource Not Found (404) SN_ER_WRITE_ONLY = -3, // Write Only (405) SN_ER_READ_ONLY = -2, // Read Only (405) SN_ER_FAILED = -1, // Failed (500)</div> SN_OK = 0, // Successfully (200)</div> SN_INITILIZED = 1, // Library had initilized</div> } SN_CODE;
Structure Definition
typedef struct _SenHubInfo { char sMAC[MAX_SN_MAC]; // MAC: remove '-' and ':' char sHostName[MAX_SN_HOSTNAME]; // WISE1020-MAC(4) char sSN[MAX_SN_SNO]; // MAC: remove '-' and ':' char sProduct[MAX_SN_PRODUCT_NAME]; // WISE1020 void *pExtened; // Reserve for extension }SenHubInfo;
Sensor Network Manager API Definition
Syntax
SNMCODE SN_Manager_Initialize( );
Description
This function initializes the Sensor Network Manager API Library. You must call this function before using this module.
Parameters
None
Return Values
SNM__OK: Successfully to initialize the Sensor Network Manager module.
SNM_FAILED: Failed to initialize the Sensor Network Manager module.
Syntax
SNMCODE SN_Manager_Uninitialize();
Description
This function uninitialized the Sensor Network Manager Module. You must call this function before closing this module to release resources.
Parameters
None
Return Values
Syntax
SNMCODE SN_Manager_GetCapability(char ** ppzDataBuffer, int *pnLen );
Description
Parameters
*pnLen
[out] the length of the data in ppzDataBuffer
Return Values
Example:
Condition
"IoTGW": { "WSN": { "WSN0": { "Info": { "e": [{"n":"SenHubList","sv":"","asm":"r"}, {"n":"Topology","sv":"","asm":"r"}, {"n":"Health","v":100,"asm":"r"}, {"n":"Name","sv":"WSN0","asm":"r"} ], "bn":"Info" }, "bn":"0000852CF4B7B0E8", "ver":1 }, "WSN1": { "Info": { "e": [{"n":"SenHubList","sv":"","asm":"r"}, {"n":"Topology","sv":"","asm":"r"}, {"n":"Health","v":100,"asm":"r"}, {"n":"Name","sv":"WSN1","asm":"r"}], "bn":"Info" }, "bn":"0000852CF4B7B0E7", "ver":1 }, "bn":"WSN" }, "ver": 1 }
Syntax
SNMCODE SN_Manager_ActionProc( const int nCtlId,
Description
Parameters
pParam1
[in] the point to parameter 1 ( data type depend on SN_CTL_ID)
*pParam2
[in] the point to parameter 2 ( data type depend on SN_CTL_ID)
*pPev1
[in] reserved for later use. Must be ?ULL??
[in] reserved for later use. Must be ?ULL??
Return Values
Example:
*pParam1: ReportSNManagerDataCbf
the ReportSNManagerDataCbf that specify the callback function to be used to notify event.
Syntax
typedef int (*Template:Anchor Template:Anchor ReportSNManagerDataCbf) ( const int Template:Anchor nEventID,
Description
Parameters
pzDataBuffer
[in] the point to data with JSON format
Template:Anchor Template:Anchor Template:Anchor nDataLen
Template:Anchor Template:Anchor Template:Anchor [in] the length of the data in pzDataBuffer
Template:Anchor Template:Anchor **Template:Anchor Template:Anchor Template:Anchor ppOutParam
[out] Template:Anchor User can Template:Anchor Template:Anchor Template:Anchor specify the address or context value when ?{anchor|OLELINK220}} Template:Anchor Template:Anchor SN_SenHub_Register??event called,
Template:Anchor Template:Anchor *Template:Anchor Template:Anchor Template:Anchor Template:Anchor pParam1
[in] the point of data. The data type depends on ?N Event ID??
*pRev1
[in] reserved for later use.
Template:Anchor Template:Anchor Template:Anchor Return Values
Example of Event Code:
- SN_Inf_UpdateInterface_Data:
"IoTGW": {
"WSN": {
"WSN0"{
"Info": {
"e": [{"n":"SenHubList","sv":"Template:Anchor Template:Anchor Template:Anchor 0000000EC6F0F830 ,0000000EC6F0F831"},
{"n":"Neighbor","sv":"0000000EC6F0F830"},
{"n":"Health","v":60}],
"bn":"Info"
}
"bn":"0000852CF4B7B0E8",
"ver":1
},
"bn":"WSN"
},
"ver": 1
[out] the point that storage the user specify address or context value.
- SN_SenHub_SendInfoSpec:
pzDataBuffer : Send SenHub Information
{
"SenHub":{
"SenData": {
"e": [{"n":" temp1", "u":"Cel","v":0,"min":0,"max":100,"asm":"r","type":"d","rt":"ucum.Cel","st":"ipso","exten":""},
"bn":"SenData"
"Info": {
"e": [ {"n":"Name","sv":"Template:Anchor Template:Anchor Template:Anchor Room","asm":"rw"},
{"n":"sw","sv":"1.0.0.2","asm":"r"},
{"n":"reset","bv":0,"asm":"rw"}],
"bn":"Info"
},
?et??{
"e": [ {"n":"Neighbor","sv":"0000000EC6F0F831","asm":"r"},
{"n":"Health","v":88,"asm":"r"},
{"n":"sw","sv":??.0.0.1??"asm":"r"}],
"bn":"Net"
"ver": 1
}
}
Template:Anchor Template:Anchor ppOutParam:
[in] the point of address or context value that pass by user at SN_SenHub_Register event.
- SN_SenHub_AutoReportData
{
"SenHub":{
"SenData": {
"e": [{"n":"temp1","v":17},
{"n":"co2", "v":1001},
{"n":"digital output", "bv":0}],
"bn":"SenData",
"ver":1
},
"Info": {
"e": [{"n":"Health","v":100,"asm":"r"},
{"n":"Name","sv":"Room","asm":"rw"},
{"n":"IoTGW","sv":"0000852CF4B7B0E8","asm":"r"}],
"bn":"Info"
},
"ver": 1
}
}
ppOutParam:
[in] the point of address or context value that pass by user at SN_SenHub_Register event.
[in] the point of address or context value that pass by user at SN_SenHub_Register event.
Syntax
char* SN_Manager_GetData(const char *pszInURI, const ACTION_MODE mode);
Description
This function is used to get values of resource of sensor network manager
( ex: network interface, sensor hub, or sensor ).
Parameters
Return Values
{?tatusCode??200, ?esult??{JSON Object}}
StatusCode : Please refer [Appendix C] for status code.
Result : Result of getting in JSON format
Example:
Get the SenHub (0000000EC6F0F830)? temp1 value
pzInURI: 0000000EC6F0F830/SenHub/SenData/temp1 mode: cache
Result:
{?tatusCode??200, ?esult?? {"n":"temp1","v":17}}
Syntax
char* SN_Manager_SetData(const char *pszInURI, const char *pszValue );
Description
This function is used to get value of resource of sensor network manager in asynchronous.
( ex: network interface, sensor hub, or sensor ). This function would check the set resource and value is correct and settable. If all parameters are correct and returns accept this request immediately. Then it will set value to resource and return the result in asynchronous.
Parameters
Return Values
{?tatusCode??200, ?esult??{JSON Object}}
StatusCode : Please refer [Appendix C] for status code.
Result : Result of setting in JSON format
2.5 Application Sample Code
Please refer to the distribution package for the sample code.
Appendix
Appendix A:Smart Objects defined by this Technical Guideline
Object | Object ID | Multiple Instances? |
IPSO Digital Input | 3200 | Yes |
IPSO Digital Output | 3201 | Yes |
IPSO Analogue Input | 3202 | Yes |
IPSO Analogue Output | 3203 | Yes |
IPSO Generic Sensor | 3300 | Yes |
IPSO Illuminance Sensor | 3301 | Yes |
IPSO Presence Sensor | 3302 | Yes |
IPSO Temperature Sensor | 3303 | Yes |
IPSO Humidity Sensor | 3304 | Yes |
IPSO Power Measurement | 3305 | Yes |
IPSO Actuation | 3306 | Yes |
IPSO Set Point | 3308 | Yes |
IPSO Load Control | 3310 | Yes |
IPSO Light Control | 3311 | Yes |
IPSO Accelerometer | 3313 | Yes |
IPSO Magnetometer | 3314 | Yes |
IPSO Barometer | 3315 | Yes |
Appendix B: The Unified Code for Units of Measure (UCUM)
Symbol | Description |
m | meter |
kg | kilogram |
s | second |
A | ampere |
K | kelvin |
cd | candela |
mol | mole |
Hz | hertz |
rad | radian |
sr | steradian |
N | newton |
Pa | pascal |
J | joule |
W | watt |
C | coulomb |
V | volt |
F | farad |
Ohm | ohm |
S | siemens |
Wb | weber |
T | tesla |
H | henry |
Cel | degrees Celsius |
lm | lumen |
lx | lux |
Bq | becquerel |
Gy | gray |
Sv | sievert |
kat | katal |
pH | pH acidity |
% | Value of a switch. A value of 0.0 indicates the switch is off while 100.0 indicates on. |
count | counter value |
%RH | Relative Humidity |
m2 | area |
l | volume in liters |
m/s | velocity |
m/s2 | acceleration |
l/s | flow rate in liters per second |
W/m2 | irradiance |
cd/m2 | luminance |
Bspl | bel sound pressure level |
bit/s | bits per second |
lat | degrees latitude. Assumed to be in WGS84 unless another reference frame is known for the sensor. |
lon | degrees longitude. Assumed to be in WGS84 unless another reference frame is known for the sensor. |
%EL | remaining battery energy level in percents |
EL | remaining battery energy level in seconds |
beet/m | Heart rate in beets per minute |
beets | Cumulative number of heart beats |
h | Hour. |
Appendix C: Status Code
Status Code | Description |
200 | OK |
201 | Created |
202 | Accepted |
203 | Non-Authoritative Information |
204 | No Content |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
405 | Method Not Allowed |
406 | Not Acceptable |
408 | Request Timeout |
409 | Conflict |
410 | Resource is Gone |
415 | Unsupported Media Type |
416 | Requested Range Not Satisfiable |
426 | Locked |
500 | Internal Server Error |
501 | Not Implemented |
503 | Service Unavailable |
Reference
[1] IPSO Alliance: http://www.ipso-alliance.org/
[2] IPSO Smart Object: IPSO-Smart-Objects-1.0.pdf
[3] SenML: https://datatracker.ietf.org/doc/draft-jennings-senml/
[4] UCUM: http://unitsofmeasure.org/trac/
[5] JavaScript Object Notation (JSON) http://json.org/