IoTGateway/SDK/WirelessSensorNetworkSDK

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

Abstract

This document defines these Advantech Sensor Network Manager APIs and Sensor Data Format for using in Advantech wireless sensor network device.

Overview

Introduction

This document describes how to use the Advantech Sensor Network Manager (Adv SNM) module to get/set IoT sensor network information, data, or status for your sensor device.

The Advantech sensor data format is refer to IPSO Alliance Guide[1]. Use Sensor Markup Language (SENML)[3] defines media types for representing sensor measurements and device parameters in the SenML. Representations are defined in JavaScript Template:Anchor Template:Anchor Template:Anchor Object Notation (JSON)[5].

It includes get IoT gateway interface capability, get/set sensor hub information / sensor data, auto register / deregister sensor network hub, and auto report sensor data.

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

The IPSO Application Framework makes use of IETF standards as building blocks for a simple and efficient RESTful design model for IP smart objects. The framework may be used over either HTTP or CoAP web transfer protocols.

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

IPSO Smart Object[2] Guidelines provide a common design pattern, an object model, that can effectively use the IETF CoAP protocol to provide high level interoperability between Smart Object devices and connected software applications on other devices and services

The common object model is based on the Lightweight M2M (LWM2M 1.0) specification from the Open Mobile Alliance. OMA LWM2M is a device management and service architecture specification based on IETF CoAP, and provides a simple and flexible object template (object model) for constrained device management.

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

This first IPSO Smart Object Guideline describes 18 Smart Object types [Appendix A], including a temperature sensor, a light controller, an accelerometer, a presence sensor, and other common sensor and actuator types representing a variety of use case domains. It is intended as a ?tarter pack??and example of how IPSO Smart Objects can be built to address some application specific use cases

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	String of the entry
Boolean Value	bv	Boolean	Boolean of the entry
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
Message	msg	String	Message for resource
Extension	exten	String	Field for exten

Example

{"n":"Room Temp","u":"Cel","v":0,"min":0,"max":100,"asm":"r","type":"d","rt":"ucum.Cel","st":"ipso","exten":"sid=3303"}

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

Table 1

Appendix B: The Unified Code for Units of Measure (UCUM)

http://unitsofmeasure.org/ucum.html

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.

Table 2

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

Table 3

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/