WSN OpenAPI Specification - TUT · WSN Wireless Sensor Network 7. iPreface This document describes the WSN OpenAPI specification, which defines a unified ser-vice interface for

WSN OpenAPITechnical Specification

Date: 2013-10-14Version: r1.00-2013

1

This specification has been developed 2009-2013 in Tampere University of Technologyin industry related research projects by

Jukka SuhonenOlli KiveläMika VuoriMarkus RenttoTomi JänttiTeemu LaukkarinenIlkka KauttoMarko Hännikäinen

Copyright c© 2011-2013 2

Contents

i Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8ii Document Notations . . . . . . . . . . . . . . . . . . . . . . . . . . . 8iii Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

I Introduction 11

1 Introduction 131.1 The WSN OpenAPI Concept . . . . . . . . . . . . . . . . . . . . . . . 131.2 Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141.3 Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141.4 Network and Data Model . . . . . . . . . . . . . . . . . . . . . . . . . 151.5 Message Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161.6 Transfer protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

1.6.1 HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161.7 Data Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

1.7.1 XML Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 171.7.2 CSV Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

1.8 Service declaration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

II Interface Specifications 19

2 Authentication and Capability Format 212.1 Authentication Support . . . . . . . . . . . . . . . . . . . . . . . . . . 212.2 Authentication List Operation . . . . . . . . . . . . . . . . . . . . . . . 22

2.2.1 AuthenticationListRequest . . . . . . . . . . . . . . . . . . . . 222.2.2 AuthenticationListResponse . . . . . . . . . . . . . . . . . . . 22

2.3 Authentication Operation . . . . . . . . . . . . . . . . . . . . . . . . . 232.3.1 AuthenticationRequest . . . . . . . . . . . . . . . . . . . . . . 232.3.2 AuthenticationResponse . . . . . . . . . . . . . . . . . . . . . 232.3.3 Password authentication . . . . . . . . . . . . . . . . . . . . . 23

2.4 Capability Query Operation . . . . . . . . . . . . . . . . . . . . . . . . 242.4.1 CapabilityRequest . . . . . . . . . . . . . . . . . . . . . . . . . 242.4.2 CapabilityResponse . . . . . . . . . . . . . . . . . . . . . . . . 24

2.5 XML Schemas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242.6 CSV Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262.7 Revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

3

3 Sensor Information Data Format 273.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273.2 Subscribe Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

3.2.1 SubscribeRequest . . . . . . . . . . . . . . . . . . . . . . . . . 273.2.2 SubscribeResponse . . . . . . . . . . . . . . . . . . . . . . . . 29

3.3 Unsubscribe Operation . . . . . . . . . . . . . . . . . . . . . . . . . . 293.3.1 UnsubscribeRequest . . . . . . . . . . . . . . . . . . . . . . . 303.3.2 UnubscribeResponse . . . . . . . . . . . . . . . . . . . . . . . 30

3.4 Data Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303.4.1 Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303.4.2 DataResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

3.5 Optional Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333.5.1 Block data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

3.6 ACF Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343.7 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

3.7.1 XML Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 343.7.2 CSV Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 37


4 Sensor Archive Data Format 454.1 Query Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

4.1.1 Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454.1.2 Processing of results . . . . . . . . . . . . . . . . . . . . . . . 464.1.3 Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

4.2 ACF Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494.2.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

4.3 XML Schemas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504.4 CSV Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534.5 Revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

5 Node Actuator and Sensor Control 555.1 Register Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

5.1.1 RegisterRequest . . . . . . . . . . . . . . . . . . . . . . . . . . 555.1.2 RegisterResponse . . . . . . . . . . . . . . . . . . . . . . . . . 55

5.2 Unregister Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . 565.2.1 UnregisterRequest . . . . . . . . . . . . . . . . . . . . . . . . 565.2.2 UnregisterResponse . . . . . . . . . . . . . . . . . . . . . . . . 56

5.3 Status Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565.3.1 StatusRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . 575.3.2 StatusResponse . . . . . . . . . . . . . . . . . . . . . . . . . . 57

5.4 Command Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . 585.4.1 CommandRequest . . . . . . . . . . . . . . . . . . . . . . . . . 585.4.2 CommandResponse . . . . . . . . . . . . . . . . . . . . . . . . 59

5.5 Relation to SIDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59


r1.00-2013

5.6 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595.6.1 Registering an actuator . . . . . . . . . . . . . . . . . . . . . . 605.6.2 Requesting actuator status . . . . . . . . . . . . . . . . . . . . 615.6.3 Sending an actuator command . . . . . . . . . . . . . . . . . . 61


6 Metadata Format 656.1 Request Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

6.1.1 Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 656.1.2 Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

6.2 Insert Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666.2.1 InsertRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . 666.2.2 InsertResponse . . . . . . . . . . . . . . . . . . . . . . . . . . 66

6.3 Remove Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666.4 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676.5 ACF Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 686.6 XML Schemas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 696.7 CSV Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 716.8 Revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

7 Network Management Format 737.1 GetStructure Operation . . . . . . . . . . . . . . . . . . . . . . . . . . 737.2 GetStructure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 737.3 GetStructureResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . 737.4 GetMeasurements Operation . . . . . . . . . . . . . . . . . . . . . . . 74

7.4.1 GetMeasurementsRequest . . . . . . . . . . . . . . . . . . . . 747.4.2 GetMeasurementsResponse . . . . . . . . . . . . . . . . . . . . 74

7.5 SetMeasurements Operation . . . . . . . . . . . . . . . . . . . . . . . 757.5.1 SetMeasurementsRequest . . . . . . . . . . . . . . . . . . . . . 757.5.2 SetMeasurementsResponse . . . . . . . . . . . . . . . . . . . . 76

7.6 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 767.7 XML Schemas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 777.8 CSV Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797.9 Revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

III Guidelines and Recommendations 81

8 Predefined Measurement Vocabulary 838.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 838.2 Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . 838.3 Measurement and Actuator Quantities . . . . . . . . . . . . . . . . . . 838.4 Measurement Quantities . . . . . . . . . . . . . . . . . . . . . . . . . 84

8.4.1 openapi:acceleration . . . . . . . . . . . . . . . . . . . . . . . 84


8.4.2 openapi:airpressure . . . . . . . . . . . . . . . . . . . . . . . . 848.4.3 openapi:airvelocity . . . . . . . . . . . . . . . . . . . . . . . . 848.4.4 openapi:batteryvoltage . . . . . . . . . . . . . . . . . . . . . . 848.4.5 openapi:carbonmonoxide . . . . . . . . . . . . . . . . . . . . . 848.4.6 openapi:carbondioxide . . . . . . . . . . . . . . . . . . . . . . 848.4.7 openapi:compass . . . . . . . . . . . . . . . . . . . . . . . . . 868.4.8 openapi:current . . . . . . . . . . . . . . . . . . . . . . . . . . 868.4.9 openapi:electricConsumption . . . . . . . . . . . . . . . . . . . 868.4.10 openapi:electricPower . . . . . . . . . . . . . . . . . . . . . . 868.4.11 openapi:geolocation . . . . . . . . . . . . . . . . . . . . . . . . 868.4.12 openapi:hail . . . . . . . . . . . . . . . . . . . . . . . . . . . . 868.4.13 openapi:humidity . . . . . . . . . . . . . . . . . . . . . . . . . 868.4.14 openapi:illuminance . . . . . . . . . . . . . . . . . . . . . . . 878.4.15 openapi:image . . . . . . . . . . . . . . . . . . . . . . . . . . . 878.4.16 openapi:magneticfield . . . . . . . . . . . . . . . . . . . . . . . 878.4.17 openapi:orientation . . . . . . . . . . . . . . . . . . . . . . . . 878.4.18 openapi:pressure . . . . . . . . . . . . . . . . . . . . . . . . . 878.4.19 openapi:rain . . . . . . . . . . . . . . . . . . . . . . . . . . . . 878.4.20 openapi:temperature . . . . . . . . . . . . . . . . . . . . . . . 878.4.21 openapi:voltage . . . . . . . . . . . . . . . . . . . . . . . . . . 878.4.22 openapi:video . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

8.5 Actuator Quantities . . . . . . . . . . . . . . . . . . . . . . . . . . . . 888.5.1 openapi:binarySwitch . . . . . . . . . . . . . . . . . . . . . . . 888.5.2 openapi:lightSwitch . . . . . . . . . . . . . . . . . . . . . . . . 888.5.3 openapi:linearSwitch . . . . . . . . . . . . . . . . . . . . . . . 888.5.4 openapi:powerSwitch . . . . . . . . . . . . . . . . . . . . . . . 88

8.6 Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 888.6.1 Numerical values . . . . . . . . . . . . . . . . . . . . . . . . . 888.6.2 Binary data . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

8.7 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

9 Transducer Datasheet 919.1 Device information . . . . . . . . . . . . . . . . . . . . . . . . . . . . 919.2 Placement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 919.3 Sensors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 929.4 Actuators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 939.5 Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93


List of Abbreviations

ACF Authentication and Capability Format

CSV Comma Separated Value

HTTP Hypertext Transfer Protocol

M2M Machine-to-machine

MEDF Metadata Format

NMF Network Management Format

NASC Node Actuator and Sensor Control

SADF Sensor Archive Data Format

SIDF Sensor Information Data Format

UML Unified Modeling Language

XML eXtensible Markup Language

WSN Wireless Sensor Network

7

i Preface

This document describes the WSN OpenAPI specification, which defines a unified ser-vice interface for utilizing sensor data collected from heterogeneous sensor networks.This document defines service interfaces for accessing, querying, and collecting sensormeasurements, the message formats and encodings needed to carry the sensor data, andrecommended practices to describe the sensor data.

ii Document Notations

WSN OpenAPI messages are described in this document using the following genericsyntax that does not rely on any specific encoding:

Element Required attribute Optional attribute

Child elementcount Decimald Realf Strings

CDATA

Figure 1: Notation of message structure.

An element is a collection of attributes and child elements. The tree structure in thediagram presents the relations between the elements. The count annotation refers to theplurality of child elements. E.g., 0..1 means that the child element is optional and canappear at most once. The annotation 0..∗ means that the number of occurrences is notlimited.

An element may have required and optional attributes. Each required attribute mustappear on a valid WSN OpenAPI message. Optional attributes (emphasized in the mes-sage notation with a dotted outline) may or may not be present in the element. Anattribute is a duplex of name and value. The notation presents the name of the attribute

along with its value type. d denotes a decimal number (e.g., -1 or 10), f denotes a

real (floating point) number (e.g., -4.2, 20.1 or 10), and s is a string value. A stringvalue should be assumed if a type is not defined in the notation. CDATA refers to thevalue of the element, e.g., sensor measurements.

Message exchanges between entities are described with Unified Modeling Language(UML) sequence diagrams:


r1.00-2013

Client Service

Request

Response

Figure 2: Notation of message exchange between entities.

iii Revision History

Date Revision Author Description

2012-10-04 r1.0 js First version of the document.



Part I

Introduction

11

1 Introduction

WSN OpenAPI is set of specifications that define interfaces and data formats for ac-cessing sensors and actuators (jointly referred to as transducers). WSN OpenAPI sup-ports common sensor tasks comprising sensor data collection, actuator control, real-timealerts based on sensor values, and querying measurement and alert history.

The design goal of WSN OpenAPI has been low complexity to allow both fast adop-tion and the use in resource constrained machine-to-machine (M2M) communications,while being expressive enough to cover the requirements and features of the multitudeof sensor network related applications and technologies.

1.1 The WSN OpenAPI Concept

WSN OpenAPI is a common interface between sensors and the services/applications uti-lizing them. That is, the WSN OpenAPI hides technology specific details and provides acommon interface for applications and other services to access the sensor data.

An example of data collection is shown in Fig. 4. A WSN OpenAPI service associatesthe measured raw sensor values with time and quantity and forwards measurements toclients. To complete the understanding about the measurement, a client may requestrelated information from data archives, such as the current sensor location and measure-ment unit and margin of error.

Figure 3: Unified service access with WSN OpenAPI.

13

Figure 4: Composition of measurement related information.

1.2 Terminology

• Actuator is a device that converts its input to a physical action, for example aswitch or a valve.

• Client is a device that accesses a WSN OpenAPI service. A device may both offera WSN OpenAPI service and act as a client to access services located on otherdevices.

• Data archive is a persistent storage for sensor measurements. WSN OpenAPIdoes not mandate the exact implementation of the data archive, it may be e.g.a database or a file.

• Meta data archive is a persistent storage for node and sensor related informationsuch as sensing accuracy, manufacturer, and model.

• Network is a collection of one or more nodes.

• Node is an independent computing and sensing device (e.g. a computer, a sensordevice, a mobile phone, or a satellite) comprising of one or more transducers anda communication interface for interacting with other nodes.

• Sensor measures a physical quantity and converts its observations to a quantifiablevalue.

• Service denotes the capability to provide sensor values, control sensor devices,etc.

• Session denotes the time during which a connection is active between a client anda service.

• Transducer is a common term to refer to both to an actuator and to a sensor.

1.3 Interfaces

The WSN OpenAPI specification consists of several independent service interfaces (Fig. 5).The interfaces defined in WSN OpenAPI comprise:

• Authentication and Capability Format (ACF): defines methods for authenticationto a WSN OpenAPI service, and provides the means to query the list of supportedinterfaces.


r1.00-2013

Figure 5: WSN OpenAPI interfaces.

Figure 6: Network model.

• Meta-Data Format (MEDF): defines an interface for querying node capabilitiesand sensors.

• Network Management Format (NMF): describes methods for querying networkstructure and status and configuring measurement collection.

• Node Actuator and Sensor Control (NASC): presents an interface for sending ac-tuator commands.

• Sensor Archive Data Format (SADF): defines request and response data formatsfor accessing values stored in a WSN data archive.

• Sensor Information Data Format (SIDF): describes methods and data formats forsubscribing and delivering real-time measurement data.

The interfaces are designed to work independently. A WSN OpenAPI implementationmay choose which interfaces to implement.

1.4 Network and Data Model

WSN OpenAPI uses a hierarchical structure to address nodes and transducers (Fig. 6): asensor network comprises nodes, which contain one or more transducers. As a phys-ical sensor may measure several related quantities e.g. temperature and humidity, atransducer is further divided into components. For example, an acceleration transducercomprises components for acceleration on each axis. While the data model is designedto support complex network hierarchies of Wireless Sensor Networks (WSNs), it can beapplied to single devices such as satellites or mobile phones. In those cases, each devicecan be considered to form a virtual network.

The addressing/naming of the network, node, and sensor IDs is application domainspecific. E.g. for mobile phone’s operator name could be used as network id and mobile


Request version messageId ...

Response version responseCode messageId ...

Figure 7: WSN OpenAPI operation comprising request/response messages.

phone’s serial number could be used as node id. For software components acting assensors program name could be used as sensor id on so forth.

1.5 Message Structure

The WSN OpenAPI interfaces define operations that comprise request/response pair ofmessages (Fig. 7). Each message includes a mandatory version attribute that definesthe version of specification that the message in question uses. The purpose of the at-tribute is to provide means for backward compatibility between different versions ofspecifications. A response to a message should be constructed using the same versionof specification.

The order in which requests are replied is not restricted. E.g., a WSN OpenAPI ser-vice may return results to archive queries that are completed first. The replies may bemapped to the corresponding request with message identifiers. To allow matching aresponse to its request, WSN OpenAPI messages contains an optional message identifier(messageId ). A response message shall contain the same message identifier as the cor-responding request message. The message identifier is intended solely for the benefit ofthe client entity making queries, and its uniqueness is not needed nor enforced by theWSN OpenAPI service.

A response contains a responseCode that indicates whether the operation was suc-cessful or a failure. The response codes in WSN OpenAPI is a subset of HTTP errorcodes and are listed in Table 1.1.

1.6 Transfer protocol

WSN OpenAPI does not mandate any specific transfer or communication protocol. Thespecification may be used both with connection-based and connectionless protocols.WSN OpenAPI uses request/response type operations that are suitable for short-livedconnections.

1.6.1 HTTP

In Hypertext Transfer Protocol (HTTP), the approach is to exchange only one pair of re-quest/response messages, making a separate authentication handshake infeasible. ACFauthentication is not used with HTTP. Instead, the recommended practice is to use aseparate authentication mechanism, such as basic authentication. Refer to [FHBH+99]for the specifics of the method.

When using WSN OpenAPI over HTTP, the value of responseCode is also returnedas a HTTP response status. To reduce messaging overhead, response messages that


r1.00-2013

Table 1.1: Response codes.

Code Name Description

200 OK Operation was successful202 Accepted The request was accepted but the operation was not yet

completed204 No Content Operation was successful but did not have any results206 Partial Content Operation was successful but only part of the results

were returned400 Bad request Message was malformed e.g. invalid XML403 Forbidden Client does not have sufficient privileges to complete

the operation422 Unprocessable Entity Request syntax was correct but its semantics was incor-

rect408 Request Timeout Request could not be completed in time422 Unprocessable entity Operation was recognized but did not contain all re-

quired elements or attributes500 Internal server error An unexpected error occurred at the service (typically

indicates an implementation bug)501 Not Implemented Operation or its contents are not supported

have an empty body need not be returned with HTTP and a client should not expectthe reception of these messages. Furthermore, as a HTTP connection involves only oneset of request/response messages, the use of messageId field is unnecessary and thusdiscouraged.

1.7 Data Formats

To ease interoperability e.g., between different machine architectures, WSN OpenAPImessages use textual presentation instead of binary formats. WSN OpenAPI messagesare defined in eXtensible Markup Language (XML) and Comma Separated Value (CSV)formats. XML format is being adopted as a common language between software sys-tems, and benefits from the common availability of parser libraries and language sup-port. CSV is targeted at Machine-to-machine (M2M) communications where the band-width is limited and the use of data compression to reduce message sizes would requiretoo much processing power.

All formats share the same semantics and have similar message structure, allowingan.

1.7.1 XML Format

The messages belonging to different WSN OpenAPI interfaces are distinguished withnamespaces (xmlns attribute). When parsing messages, unknown elements and at-tributes are silently ignored to allow forward compatibility with future versions of thespecification.

XML format is case sensitive.


1.7.2 CSV Format

To ease implementation on resource constrained environments, CSV format supportsonly a subset of XML features. The messages in CSV format are formally specified inABNF notation [CO08]. A message is structured as follows:PREFIX ":" MESSAGE-NAME "," VERSION "," LINES *("," VALUE) LF

A PREFIX denotes the WSN OpenAPI interface that defines the message MESSAGE-NAME. VERSION refers to the version of the WSN OpenAPI specification that describesthe contents and semantics of the message. It is followed by LINES field that describesthe number of following lines that belong to this message. LINES can be an empty stringor zero value to denote that the message comprises only the current line. VERSION fieldshave message specific meaning.

When parsing messages, unknown values that follow the message contents specifiedin this document are silently ignored to allow forward compatibility with the futureversions of the specification. An implementation must not use these values to includecustom data. If there is a need to carry custom data along with the WSN OpenAPI dataconnection, the implementation should define a custom message that follows the abovemessage structure and has an empty prefix.

CSV format is case insensitive.

1.8 Service declaration

To ensure interoperability, the implementation specific details left open by this specifi-cation must be agreed between a WSN OpenAPI service and its clients. As an example,Table 1.2 presents a minimum set of details that implementations should agree upon.One way to achieve this is by an informal service declaration, against which clients maybe implemented. Note that the supported interfaces listed in the table may be alterna-tively defined via ACF capability operation (see Section 2.4).

Table 1.2: WSN OpenAPI service declaration

Parameter Description

Service host DNS name or IP addressService port TCP or UDP portTransfer protocol TCP, UDP, HTTP, ...Data format XML or CSVAuthentication method ACF, HTTP Basic access, ...Supported interfaces ACF, SADF, SIDF, ...


Part II

Interface Specifications

19

2 Authentication and Capability Format

Authentication and Capability Format (ACF) provides the means to authenticate WSNOpenAPI devices and query their capabilities.

Specification version 1.3XML namespace urn:wsn-openapi:acf

2.1 Authentication Support

A WSN OpenAPI service may require that a client authenticates itself before sendingmessages. If the authentication is required, other than AuthenticationListRequest andAuthenticationRequest messages sent by a client will be ignored and replied with re-sponse status 401 (Unauthorized) until an authentication is successfully completed.

A WSN OpenAPI service supports one or more of the following authentication meth-ods:

• none: formal authentication is not required

• password: authenticate via username and password

• challenge: authenticate with challenge-response method.

If a formal authentication is not required (authentication method is none), the ex-change of authentication messages is not required. Otherwise, a client must authenticateitself either with password or challenge methods.

A service may combine different methods for different access rights. For example, aservice may allow open access (no authentication required) for some data, while requir-ing password authentication for configuring the network. Maintaining access controllists is implementation specific and outside the scope of this specification.

An example of message exchange is presented in Fig. 8. The use of Authentication-ListRequest and CapabilityRequest messages is optional and may be skipped if the clientknows for sure what interfaces the WSN OpenAPI service supports. The authenticationto the service is done with the AuthenticationRequest message.

21

Client Service

Request supportedauthentication modes(optional)

Authenticateto service

Get supported WSNOpenAPI features(optional)

AuthenticationListRequest

AuthenticationListResponse

AuthenticationRequest

AuthenticationResponse

CapabilityRequest

CapabilityResponse

Figure 8: ACF

2.2 Authentication List Operation

Authentication list operation returns a list of supported authentication methods and doesnot require the connection to be authenticated.

2.2.1 AuthenticationListRequest

AuthenticationListRequest version messageId

Figure 9: Authentication list request

2.2.2 AuthenticationListResponse

AuthenticationListResponse version responseCode messageId

Method0..* name

Figure 10: Authentication list response


r1.00-2013

2.3 Authentication Operation

A device initiates authentication with an AuthenticationRequest message. The contentsof this message depends on the authentication method. If the service does not requireauthentication, the authentication procedure is optional.

Note that WSN OpenAPI assumes that the transport channel is secured, e.g., withIPsec or Transport Layer Security (TLS). As such, the purpose of the authenticationprocedure is not to secure the channel but ensure the access rights to certain measure-ment data.

2.3.1 AuthenticationRequest

AuthenticationRequest version method messageId

Parameter0..*

name value

Figure 11: Authentication request

2.3.2 AuthenticationResponse

AuthenticationResponse version responseCode method messageId

Parameter0..* name value

Figure 12: Authentication response

2.3.3 Password authentication

Password authentication allows identifying the client to the gateway. AuthenticationRe-quest message comprises username and password fields. The following example showsthe password authentication procedure with WSN OpenAPI /XML.

Listing 2.1: Authentication request<AuthenticationRequest version="1.3" xmlns="urn:wsn-openapi:acf" method="password"><Parameter name="username" value="myname"/><Parameter name="password" value="mypass"/>

</AuthenticationRequest>

A service replies to the authentication request with an AuthenticationResponse mes-sage. The response contains a return code 200 OK denoting that the authorization wassuccessful, or 405 Forbidden if the username or password was invalid.

Listing 2.2: Authentication response<AuthenticationResponse version="1.3" xmlns="urn:wsn-openapi:acf" code="200"/>


2.4 Capability Query Operation

The capability query operation lists the WSN OpenAPI interfaces and features that theservice supports.

2.4.1 CapabilityRequest

CapabilityRequest version messageId

Figure 13: Capability request

2.4.2 CapabilityResponse

CapabilityRequestRequest version responseCode messageId

Interface0..* name

Parameter0..* name value

Figure 14: Capability response

Following presents an example of CapabilityResponse in XML:

Listing 2.3: Example of capability response.<CapabilityResponse xmlns="urn:wsn-openapi:acf" version="1.3" responseCode="200"><Interface name="ACF"/><Interface name="SIDF"><Parameter name="acceptPushData" value="false"/><Parameter name="compositeSupport" value="true"/><Parameter name="extDataSupport" value="false"/>

</Interface></CapabilityRequest>

2.5 XML Schemas

Listing 2.4: XML schema for ACF.<xs:schema xmlns="urn:wsn-openapi:acf" xmlns:xs="http://www.w3.org/2001/XMLSchema"

attributeFormDefault="unqualified" elementFormDefault="qualified" targetNamespace="urn:wsn-openapi:acf">

<xs:complexType name="AuthenticationListRequestType"><xs:attribute name="version" type="xs:double" use="required"/><xs:attribute name="messageId" type="xs:string" use="optional"/>

</xs:complexType>

<xs:complexType name="MethodType"><xs:attribute name="name" type="xs:string"/>

</xs:complexType>

<xs:complexType name="ParameterType">


r1.00-2013

<xs:attribute name="name" type="xs:string"></xs:attribute><xs:attribute name="value" type="xs:string"></xs:attribute>

</xs:complexType>

<xs:complexType name="AuthenticationListType"><xs:sequence>

<xs:element name="Method" type="MethodType" minOccurs="0" maxOccurs="unbounded"/>

</xs:sequence><xs:attribute name="version" type="xs:double" use="required" /><xs:attribute name="responseCode" type="xs:integer" use="required" /><xs:attribute name="messageId" type="xs:string" use="optional" />

</xs:complexType>

<xs:complexType name="AuthenticationRequestType"><xs:sequence>

<xs:element name="Parameter" type="ParameterType" minOccurs="0" maxOccurs="unbounded"/>

</xs:sequence><xs:attribute name="method" type="xs:string"/><xs:attribute name="version" type="xs:double" use="required"/><xs:attribute name="messageId" type="xs:string" use="optional"/>

</xs:complexType>

<xs:complexType name="AuthenticationResponseType"><xs:sequence>

<xs:element name="Parameter" type="ParameterType" minOccurs="0" maxOccurs="unbounded"/>

</xs:sequence><xs:attribute name="responseCode" type="xs:integer" use="required"/><xs:attribute name="version" type="xs:double" use="required"/><xs:attribute name="method" type="xs:string" use="required"/><xs:attribute name="messageId" type="xs:string" use="optional"/>

</xs:complexType>

<xs:complexType name="NetworkType"><xs:attribute name="id" type="xs:string" />

</xs:complexType>

<xs:complexType name="CapabilityRequestType"><xs:sequence>

<xs:element maxOccurs="unbounded" minOccurs="0" name="Network" type="NetworkType"/>

</xs:sequence><xs:attribute name="version" type="xs:double" use="required"/><xs:attribute name="messageId" type="xs:string" use="optional"/>

</xs:complexType>

<xs:complexType name="InterfaceType"><xs:sequence>

<xs:element name="Parameter" type="ParameterType" minOccurs="0" maxOccurs="unbounded" />

</xs:sequence><xs:attribute name="name" type="xs:string" />

</xs:complexType>

<xs:complexType name="CapabilityResponseType"><xs:sequence>

<xs:element name="Interface" type="InterfaceType" minOccurs="0" maxOccurs="unbounded" />

</xs:sequence><xs:attribute name="version" type="xs:double" use="required" /><xs:attribute name="responseCode" type="xs:integer" use="required" /><xs:attribute name="messageId" type="xs:string" use="optional" />

</xs:complexType>

<xs:element name="AuthenticationListResponse" type="AuthenticationListType"/><xs:element name="AuthenticationListRequest" type="AuthenticationListRequestType"/>


<xs:element name="AuthenticationRequest" type="AuthenticationRequestType"/><xs:element name="AuthenticationResponse" type="AuthenticationResponseType"/>

<xs:element name="CapabilityRequest" type="CapabilityRequestType"/><xs:element name="CapabilityResponse" type="CapabilityResponseType" />

</xs:schema>

2.6 CSV Definitions

Listing 2.5: CSV definition for ACF.ACF-MESSAGE = AUTHENTICATION-LIST-REQUEST / AUTHENTICATION-LIST-RESPONSE /

AUTHENTICATION-REQUEST / AUTHENTICATION-RESPONSE / CAPABILITY-LIST-REQUEST /CAPABILITY-LIST-RESPONSE

AUTHENTICATION-LIST-REQUEST = "ACF:AUTH-LIST-REQ" "," VERSION "," LINES "," MESSAGE-IDEND-OF-LINE LF

AUTHENTICATION-LIST-RESPONSE = "ACF:AUTH-LIST-RES" "," VERSION "," LINES "," RESPONSE-CODE "," MESSAGE-ID END-OF-LINE *(LF METHOD-LINE) LF

METHOD-LINE = AUTHENTICATION-METHOD END-OF-LINE

AUTHENTICATION-REQUEST = "ACF:AUTH-REQ" "," VERSION "," LINES "," MESSAGE-ID ","AUTHENTICATION-METHOD END-OF-LINE *(LF PARAMETER-LINE) LF

AUTHENTICATION-RESPONSE = "ACF:AUTH-RES" "," VERSION "," LINES "," MESSAGE-ID ","RESPONSE-CODE "," AUTHENTICATION-METHOD END-OF-LINE *(LF PARAMETER-LINE) LF

PARAMETER-LINE = NAME "," VALUE END-OF-LINE

CAPABILITY-LIST-REQUEST = "ACF:CAPABILITY-REQ" "," VERSION "," LINES "," MESSAGE-ID END-OF-LINE LF

CAPABILITY-LIST-RESPONSE = "ACF:CAPABILITY-RES" "," VERSION "," LINES "," MESSAGE-ID "," RESPONSE-CODE END-OF-LINE *(LF INTERFACE-LINE) LF

INTERFACE-LINE = NAME *("," INTERFACE-PARAMETER)INTERFACE-PARAMETER = NAME "," VALUE

AUTHENTICATION-METHOD = "none" / "password" / "challenge"

END-OF-LINE = *("," String)VERSION = DoubleLINES = "" / IntegerNO-LINES = "" / 0MESSAGE-ID = StringRESPONSE-CODE = IntegerNAME = StringVALUE = String

Double = 1*DIGIT ["." 1*DIGIT]String = DQUOTE *VCHAR DQUOTE

2.7 Revision history

Please note the following changes that may affect the compatibility between differentversions of the specification.

XML namespace

• v1.0 to v1.2: XML namespace is urn:ietf:params:xml:ns:acf

• v1.3: XML namespace is urn:wsn-openapi:acf


3 Sensor Information Data Format

Sensor Information Data Format (SIDF) is intended for streaming real-time data fromdata sources to data consumers (Fig. 15). A data exchange is initiated with a subscribemechanism, where a client (data consumer) specifies the data it is interested in and theWSN OpenAPI service delivers the requested data as it becomes available. A WSN Ope-nAPI service may also support the reception of unsolicited push type of data, meaningthat data sources may send data without explicit subscription handshake.

Specification version 1.7XML namespace urn:wsn-openapi:sidf

3.1 Overview

The message delivered to the data consumer may not be the same as the message gener-ated by the data source. A single SIDF Data message can contain several measurementsand events from different data sources. The data pieces that do not match the subscrip-tion are extracted from the message before delivering it to the data consumer. Also,a WSN OpenAPI service may optimize the communication by combining data that isgenerated by different data sources.

3.2 Subscribe Operation

Subscribe operation activates the reception of real-time data from a WSN OpenAPI ser-vice. The typical message exchange in subscription operation is presented in Fig. 16.

3.2.1 SubscribeRequest

A SubscribeRequest message (Fig. 17) generates a subscription to SIDF data. Datais delivered to the subscriber if it matches any of the defined Measurement or Eventelements, or was generated by the source defined in the Network element. The scopeof Measurement and Event elements can be narrowed to the data sources within thecertain networks, nodes or sensors. An empty SubscribeRequest message subscribes toall measurements. See Section 3.7 for usage examples. The SubscribeRequest messagereplaces existing subscriptions from the client.

An inline attribute controls how the data is delivered to the client. If the attributeis not defined or is set to always, data is fully embedded within the Data message.The value never causes all data values whose size exceed inlineThreshold bytes to bedelivered via an external resource. When the inline is set to allow, inlining happens at

27

Source Service Consumer

Data

Data

SubscribeRequest

SubscribeResponse

Data

Data

Figure 15: Exchange of measurement data.

Client Service

Deliver messagesuntil unsubscribed

SubscribeRequest

SubscribeResponse

SIDF

SIDF

Figure 16: Message exchange in the subscribe operation, followed by the reception of sub-scribed data.


r1.00-2013

the discretion of the WSN OpenAPI service. See Section 3.4.1 for more details on inlinedata. The inline and inlineThreshold attributes are ignored if the WSN OpenAPI servicedoes not support external resource.

A client must have read access to the data for the data to be delivered. If the sub-scription request contains networks, nodes, or sensors to which the client does not havean access, the subscription succeeds but data from those sources is not forwarded tothe client. If client’s access privileges change after the subscription has been made, theservice reacts by starting/stopping forwarding data from affected sources.

SubscribeRequest versionf inlines inlineThresholdd messageIds

Measurement0..* quantitys

Network0..* ids

Node0..*

ids

Sensor0..* ids

Event0..*

ids

Network0..* ids

Node0..* ids

Network0..* ids

Node0..* ids

Sensor0..* ids

Figure 17: Subscribe request.

3.2.2 SubscribeResponse

A SubscribeResponse message (Fig. 18) is generated as a response to SubscribeRequest.The responseCode attribute has a value of 200 on success, otherwise the value is oneof the error codes specified in Table 1.1. Note that the subscribe operation fails onlyon a malformed request. If the request fails, the client should expect that an earliersubscription (if any) will remain effective.

SubscribeResponse versionf responseCodes messageIds

Figure 18: Subscribe response

3.3 Unsubscribe Operation

Unsubscribe operation (Fig. 19) drops all existing subscriptions.


Client Service

UnsubscribeRequest

UnsubscribeResponse

Figure 19: Message exchange in the unsubscribe operation.

3.3.1 UnsubscribeRequest

An UnsubscribeRequest message (Fig. 20) instructs the service to drop all existing sub-scriptions belonging to the sender.

UnsubscribeRequest versionf messageIds

Figure 20: Unsubscribe request.

3.3.2 UnubscribeResponse

An UnubscribeResponse message (Fig. 21) is generated as a response to UnsubscribeRequest.The responseCode attribute has a value of 200 on success, otherwise the value is one ofthe error codes specified in Table 1.1. If the request fails, the client should expect thatan existing subscription (if any) will remain effective.

UnsubscribeRequest versionf responseCoded messageIds

Figure 21: Unsubscribe response.

3.4 Data Operation

SIDF Data operation is used to forward measurement and event data to the target.

3.4.1 Data

A Data message (Fig. 22) is structured hierarchically to one or more Network, Node andSensorelements according to the WSN OpenAPI network model (Section 1.4). Networkand nodes may generate (logical) events, while sensors generate measurements.

For compatibility with the earlier versions of the specification, SIDF should be al-lowed as a synonym for Data.


r1.00-2013

Data versionf messageIds replyb

Network0..*

ids

Node0..*

ids

Sensor0..* ids

Measurement0..* quantitys times units

Component0..* ids units types

DATA

Tolerance0..*

fors types units

Component0..* ids units

DATA

Values0..1 ticks

CSV data

Event0..*

ids times types


DATA

Event0..* ids times types

Component0..*

ids units

DATA

Figure 22: SIDF data.

Timestamp

Both Measurement and Event elements are assigned time that indicates the generationtime of the measurement (or event). A timestamp is defined either with an absoluteISO 8601 [BM04] time format or as a relative time. The relative time feature is targetedat devices that do not have real-time clocks. A relative timestamp denotes the timedifference in seconds to the current time. Typically, it is initialized to zero by the datasource, and updated by decreasing the time elapsed in transferring the message via anetwork. Thus, the relative time should be negative to indicate that the measurementwas performed in the past. When receiving a message with the relative timestamp, thereceiver may keep updating the time stamp or convert it to the absolute time by addingthe current absolute time to it.

SIDF timestamp is defined in ABNF as:DATE-FORMAT = RELATIVE-TIME / ABSOLUTE-TIMERELATIVE-TIME = ("+" / "-") 1*DIGIT ["." 1*DIGIT]


Table 3.1: Specified measurement types.

Type Description

base64 Base64 encoded (binary) valueboolean Value is true or falsedecimal Decimal number (-1, 3)

href Link to an external referencereal Real number (e.g., -1, 3.14)

string String value

ABSOLUTE-TIME = DATE "T" TIME TIME-ZONEDATE = ["-"] 4DIGIT "-" %x30-31 DIGIT "-" %x30-33 DIGITTIME = %x30-32 DIGIT ":" %x30-35 DIGIT ":" %x30-35 DIGIT ["." *DIGIT]TIME-ZONE = ( ("+" / "-") 2DIGIT ":" 2DIGIT ) / "Z"

Measurements

A measurement comprises one or more Component elements that contain the measuredvalues. Each component has an identifier (id ) that must be unique within the measure-ment. The identifier defaults to “value” if not defined. A Tolerance element may beused to describe the accuracy of a measurement. Tolerance and component elementshave one-to-one relationship, bound by component id and the for attribute in the toler-ance. Only one tolerance element per component should be defined but a componentdoes not have to have a defined tolerance.

An optional type attribute may be used to give a hint how the measurement datashould be interpreted. The client may choose to ignore the attribute. The pre-definedreserved types are listed in Table 3.1. The href value indicates that the actual datais stored in an external resource (such as a FTP server). The extDataSupport ACFparameter may be used to check whether the WSN OpenAPI service supports the use ofexternal resources to pass the data. Additionally, the supported schemes are listed withextResourceSchemes.

Events

Events indicate logical events, such as alerts and warnings, related to network and nodeentities. An Event element has id attribute that identifies the meaning of the event. Inaddition, an event may have an optional type attribute intended to describe the categoryof the event, e.g., alert or calendar. If not defined, type defaults to “alert”.

3.4.2 DataResponse

A DataResponse message (Fig. 23) is generated in response to a Data message. ADataResponse is generated only if the Data message had its response attribute set totrue. The responseCode attribute has a value of 200 on success. If the Data messagecontains elements to which the sender does not have access rights, a WSN OpenAPI ser-vice will ignore the message (including the elements that would have sufficient rights)and reply with 403 (Forbidden).


r1.00-2013

Table 3.2: Specified tick field values.

Tick Description

hour Hoursmin Minutessec Secondsmsec Milliseconds

DataResponse versionf responseCodes messageIds

Figure 23: Data response.

3.5 Optional Features

3.5.1 Block data

Block data collects several similarly structured measurements within one Measurementelement. It is targeted at transferring large amounts of simple measurement data. Com-ponents act as prototypes for the block data and should only contain attributes. Themeasurement data is encoded within a Values element as RFC 4180 CSV. Only oneValues element per Measurement is allowed, and all Component elements must pre-cede the Values.

The measurements are listed on separate rows within the block. A row begins witha tick count and is followed by one or more data fields. The number of data fields mustmatch the number of preceding components. The tick count defines a measurement timerelative to the time attribute of the enclosing Measurement element. The length of a tickis defined in tick attribute. The tick attribute is optional and defaults to “sec” denotingone second per tick. The list of supported tick values are listed in Table 3.2.

Listing 3.1: Example of block data.<Measurement quantity="openapi:temperature" unit="C" time="2012-12-24T19:00:00Z"><Component/><Values tick="sec">0,12.259,12.3121,12.2160,12.8</Values>

</Measurement>

The contents of the Values element are formatted with the following rules:

• Comma (,) is used as a separator

• Lines end with either with LF or CRLF

• Rows containing only white space characters are ignored

• Preceding white space characters in the ticks field are ignored

• White spaces in the data fields are a part of value


• Data fields containing commas (,) must be quoted with double quotes (")

• Double quotes are encoded repeating the quote twice

• Data fields may not contain end of line characters

The contents of the Values element described as ABNF:SIDF-DATA = 1*(DATA-LINE / EMPTY-LINE)DATA-LINE = *WSP TICKS 1*COLUMN END-OF-LINEEMPTY-LINE = *WSP END-OF-LINETICKS = 1*DIGITCOLUMN = "," (VALUE / DQUOTE QVALUE DQUOTE)VALUE = %x20-2B / %x2D-7EQVALUE = %x20 / %x21 / %x23-7E / DQUOTE DQUOTEEND-OF-LINE = LF / CRLF

Non-printable characters in values are not supported and must be encoded to thesupported character set. This specification does not mandate any specific encoding, butbase64 encoding is recommended for binary files and HTML encoding ("&#" 1*4DIGIT

";") is recommended for text segments.

3.6 ACF Capabilities

SIDF has the follow ACF capability parameters (see Section 2.4).

Table 3.3: ACF capability parameters.

Parameter Type Description

acceptPushData bool Accept insertion of unsubscribed data (see Sec-tion 3.4.1). Default: false.

blockDataSupport bool Supports the reception of block data (see Sec-tion 3.5.1). Default: false.

extDataSupport bool Support for external resources. Default: false.extResourceSchemes strlist Supported external resource schemas as comma sep-

arated string list (e.g., “ftp,http,https”)

3.7 Examples

3.7.1 XML Examples

Listing 3.2: Simple measurement with one value.<Data version="1.7" xmlns="urn:wsn-openapi:sidf"><Network id="1"><Node id="2"><Sensor id="3" ><Measurement quantity="Temperature" unit="C" time="2009-07-03T11:24:46+00:00" ><Component>23.0</Component>

</Measurement></Sensor>

</Node></Network>

</Data>


r1.00-2013

Listing 3.3: Measurement with several components.<SIDF version="1.3" xmlns="urn:wsn-openapi:sidf"><Network id="1"><Node id="2"><Sensor id="3" >

<Measurement quantity="Acceleration" unit="mg" time="2009-07-25T14:24:46+00:00">

<Component id="x">142.0</Component><Component id="y">46.0</Component><Component id="z">895.0</Component><Component id="roll" unit="degree">8.0</Component><Component id="pitch" unit="degree">2.0</Component><Component id="total">907.36156</Component>


</Node></Network>

</SIDF>

Listing 3.4: Multiple measurements in one message.<Data version="1.7" xmlns="urn:wsn-openapi:sidf"><Network id="my_network"><Node id="mynode"><Sensor id="thermometer"><Measurement quantity="temperature" unit="C" time="2012-12-24T19:00:00Z"><Component>12.2</Component>

</Measurement><Measurement quantity="temperature" unit="C" time="2012-12-24T19:59:00Z"><Component>12.3</Component>




</Node></Network>

</Data>

Listing 3.5: Multiple measurements in one message using block data, equivalent to 3.4.<Data version="1.7" xmlns="urn:wsn-openapi:sidf"><Network id="my_network"><Node id="mynode"><Sensor id="thermometer"><Measurement quantity="temperature" unit="C" time="2012-12-24T19:00:00Z"><Component/><Values tick="sec">0,12.259,12.3121,12.2160,12.8</Values>


</Node></Network>

</Data>

Listing 3.6: Data contents stored in an external resource.<Data version="1.7" xmlns="urn:wsn-openapi:sidf"><Network id="my_network"><Node id="mynode">


<Sensor id="camera"><Measurement quantity="openapi:image" unit="jpeg" time="2012-12-24T19:00:00Z"><Component type="href">http://192.168.0.1:8000/data/9vLwCMLMfH8Je</Component>


</Node></Network>

</Data>

Listing 3.7: Data message with different events and measurements.<Data version="1.7" xmlns="urn:wsn-openapi:sidf"><Network id="example"><Node id="1"><Sensor id="thermometer"><Measurement quantity="temperature" unit="C" time="2012-12-24T19:00:00Z"><Component>12.2</Component>

</Measurement></Sensor><Sensor id="0"><Measurement quantity="humidity" unit="%" time="2012-12-24T19:00:48Z"><Component>68</Component>


</Node><Node id="2"><Sensor id="thermometer"><Measurement quantity="temperature" unit="C" time="2012-12-24T18:59:21Z"><Component>21.4</Component>


</Measurement></Sensor><Event id="batteryLevel" type="warning" time="2012-12-24T19:01:18Z"><Component id="level" unit="%">16</Component>

</Event></Node><Node id="3"><Sensor id="thermometer"><Measurement quantity="temperature" unit="C" time="2012-12-24T19:00:00Z"><Component>12.2</Component>



</Node></Network>

</Data>

Listing 3.8: Subscription to all data.<SubscribeRequest version="1.7" xmlns="urn:wsn-openapi:sidf"/>

Listing 3.9: Subscription to data from a specific node.<SubscribeRequest version="1.7" xmlns="urn:wsn-openapi:sidf"><Network id="default"><Node id="123"/>

</Network></SubscribeRequest>


r1.00-2013

Listing 3.10: Subscription to data from a specific node and to temperature measurements fromany node.<SubscribeRequest version="1.7" xmlns="urn:wsn-openapi:sidf"><Measurement quantity="temperature"/><Network id="default"><Node id="2"/>

</Network></SubscribeRequest>

Listing 3.11: Delivered data when the subscription in 3.10 is applied to data in 3.7.<Data version="1.7" xmlns="urn:wsn-openapi:sidf"><Network id="example"><Node id="1"><Sensor id="thermometer"><Measurement quantity="temperature" unit="C" time="2012-12-24T19:00:00Z"><Component>12.2</Component>


</Node><Node id="2"><Sensor id="thermometer"><Measurement quantity="temperature" unit="C" time="2012-12-24T18:59:21Z"><Component>21.4</Component>


</Measurement></Sensor><Event id="batteryLevel" type="warning" time="2012-12-24T19:01:18Z"><Component id="level" unit="%">16</Component>

</Event></Node><Node id="3"><Sensor id="thermometer"><Measurement quantity="temperature" unit="C" time="2012-12-24T19:00:00Z"><Component>12.2</Component>


</Node></Network>

</Data>

Listing 3.12: Unsubscribing from all measurements.<UnsubscribeRequest version="1.7" xmlns="urn:wsn-openapi:sidf"></UnsubscribeRequest>

3.7.2 CSV Examples

Listing 3.13: Simple measurement with one value.SIDF:DATA,1.7,1,,02009-07-03T11:24:46+00:00,1,2,3,Temperature,23.0C

Listing 3.14: Measurement with several components.SIDF:DATA,1.7,1,,02009-07-25T14:24:46+00:00,1,2,3,Acceleration,x=142.0 mg,y=46.0 mg,z=895.0 mg,roll=8.0,

pitch=2.0,total=907.36156 mg

Listing 3.15: Multiple measurements in one message.SIDF:DATA,1.7,1,,0


2012-12-24T19:00:00Z,my_network,mynode,thermometer,temperature,12.22012-12-24T19:59:00Z,my_network,mynode,thermometer,temperature,12.32012-12-24T21:01:00Z,my_network,mynode,thermometer,temperature,12.22012-12-24T21:40:00Z,my_network,mynode,thermometer,temperature,12.8

Listing 3.16: Data subscription to all measurements.SIDF:SUBSCRIBE-REQ,1.7,0,

Listing 3.17: Subscription to the measurements of a specific node.SIDF:SUBSCRIBE-REQ,1.7,1,,default,123

Listing 3.18: Unsubscribing from all measurements.SIDF:UNSUBSCRIBE-REQ,1.7,0,

3.8 XML Schemas

Listing 3.19: XML Schema for SIDF subscribe operation.<xs:schema xmlns="urn:wsn-openapi:sidf" xmlns:xs="http://www.w3.org/2001/XMLSchema"

attributeFormDefault="unqualified" elementFormDefault="qualified" targetNamespace="urn:wsn-openapi:sidf">

<xs:complexType name="SensorType"><xs:attribute name="id" type="xs:string" use="required" />

</xs:complexType>

<xs:complexType name="NodeType"><xs:sequence><xsd:annotation><xsd:documentation>Nodes inside Events do not contain Sensor elements.</xsd:documentation></xsd:annotation>

<xs:element name="Sensor" type="SensorType" minOccurs="0" maxOccurs="unbounded" />

</xs:sequence><xs:attribute name="id" type="xs:string" use="required" />

</xs:complexType>

<xs:complexType name="NetworkType"><xs:sequence>

<xs:element name="Node" type="NodeType" minOccurs="0" maxOccurs="unbounded"/>


</xs:complexType>

<xs:complexType name="EventType"><xs:sequence>

<xs:element name="Network" type="NetworkType" minOccurs="0" maxOccurs="unbounded" />


</xs:complexType>

<xs:complexType name="MeasurementType"><xs:sequence>


</xs:sequence><xs:attribute name="quantity" type="xs:string" use="required" />

</xs:complexType>


r1.00-2013

<xs:complexType name="SubscribeRequestType"><xs:sequence>

<xs:element name="Measurement" type="MeasurementType" minOccurs="0" maxOccurs="unbounded" />

</xs:sequence><xs:sequence>

<xs:element name="Event" type="EventType" minOccurs="0" maxOccurs="unbounded"/>

</xs:sequence><xs:sequence>


</xs:sequence><xs:attribute name="version" type="xs:double" use="required" /><xs:attribute name="inline" type="xs:string" use="optional" default="always" /><xs:attribute name="inlineThreshold" type="xs:integer" use="optional" default="0"

/><xs:attribute name="messageId" type="xs:string" use="optional" />

</xs:complexType>

<xs:complexType name="SubscribeResponseType"><xs:attribute name="version" type="xs:double" use="required" /><xs:attribute name="responseCode" type="ResponseCodeType" use="required" /><xs:attribute name="messageId" type="xs:string" use="optional" />

</xs:complexType>

<xs:element name="SubscribeRequest" type="SubscribeRequestType" /><xs:element name="SubscribeResponse" type="SubscribeResponseType" />

</xs:schema>

Listing 3.20: XML Schema for SIDF unsubscribe operation.<xs:schema xmlns="urn:wsn-openapi:sidf" xmlns:xs="http://www.w3.org/2001/XMLSchema"


<xs:complexType name="UnsubscribeRequestType"><xs:attribute name="version" type="xs:double" use="required" /><xs:attribute name="messageId" type="xs:string" use="optional" />

</xs:complexType>

<xs:complexType name="UnsubscribeResponseType"><xs:attribute name="version" type="xs:double" use="required" /><xs:attribute name="responseCode" type="ResponseCodeType" use="required" /><xs:attribute name="messageId" type="xs:string" use="optional" />

</xs:complexType>

<xs:element name="UnsubscribeRequest" type="UnsubscribeRequestType" /><xs:element name="UnsubscribeResponse" type="UnsubscribeResponseType" />

</xs:schema>

Listing 3.21: XML Schema for SIDF data.<xs:schema xmlns="urn:wsn-openapi:sidf" xmlns:xs="http://www.w3.org/2001/XMLSchema"


<xs:simpleType name="WSNOpenAPITimeType"><xs:restriction base="xs:string"><xs:pattern value="( ’-’? \d{4}’-’[0-1]\d’-’[0-3][0-9] ’T’ [0-2]\d’:’[0-5]\d

’:’[0-5]\d (’.’ \d{3})? ((’+’|’-’) \d{2} ’:’ \d{2})|’Z’) | ( (’+’|’-’)\d+(’.’ \d+)? )"></xs:pattern>

</xs:restriction></xs:simpleType>

<xs:complexType name="EventComponentType"><xs:simpleContent>

<xs:extension base="xs:string">


<xs:attribute name="id" type="xs:string" use="required" /><xs:attribute name="unit" type="xs:string" use="optional" /></xs:extension>

</xs:simpleContent></xs:complexType>


<xs:element maxOccurs="unbounded" minOccurs="0" name="Component" type="EventComponentType" />

</xs:sequence><xs:attribute name="id" type="xs:string" use="required" /><xs:attribute name="type" type="xs:string" use="optional" default="alert"/><xs:attribute name="time" type="WSNOpenAPITimeType" use="optional" />

</xs:complexType>

<xs:complexType name="ToleranceComponentType"><xs:simpleContent>

<xs:extension base="xs:string"><xs:attribute name="id" type="xs:string" use="required" /><xs:attribute name="unit" type="xs:string" use="optional" />

</xs:extension></xs:simpleContent>

</xs:complexType>

<xs:complexType name="ToleranceType"><xs:sequence>

<xs:element name="Component" type="ToleranceComponentType" minOccurs="0"maxOccurs="unbounded" />

</xs:sequence><xs:attribute name="for" type="xs:string" use="required" /><xs:attribute name="type" type="xs:string" use="required" /><xs:attribute name="unit" type="xs:string" use="optional" />

</xs:complexType>

<xs:complexType name="ComponentType"><xs:simpleContent>

<xs:extension base="xs:string"><xs:attribute name="id" type="xs:string" use="optional" default="value" /><xs:attribute name="unit" type="xs:string" use="optional" />

<xs:attribute name="ref" type="xs:anyURI" use="optional" /></xs:extension>


<xs:complexType name="ValuesType"><xs:simpleContent>

<xs:extension base="xs:string"><xs:attribute name="tick" type="xs:string" use="optional"/>


</xs:complexType>

<xs:complexType name="MeasurementType"><xs:sequence><xs:element name="Component" type="ComponentType" /><xs:element name="Tolerance" type="ToleranceType" minOccurs="0" maxOccurs="

unbounded" /><xs:element name="Values" type="ValuesType" minOccurs="0" maxOccurs="1" /></xs:sequence><xs:attribute name="quantity" type="xs:string" use="required" /><xs:attribute name="time" type="WSNOpenAPITimeType" use="required" /><xs:attribute name="unit" type="xs:string" use="optional" />

</xs:complexType>

<xs:complexType name="SensorType"><xs:element name="Measurement" type="MeasurementType" /><xs:attribute name="id" type="xs:string" use="required" />

</xs:complexType>


r1.00-2013

<xs:complexType name="NodeType"><xs:choice minOccurs="1" maxOccurs="unbounded">

<xs:element name="Sensor" type="SensorType"/><xs:element name="Event" type="EventType"/>

</xs:choice><xs:attribute name="id" type="xs:string" use="required" />

</xs:complexType>

<xs:complexType name="NetworkType"><xs:choice minOccurs="1" maxOccurs="unbounded">

<xs:element name="Node" type="NodeType" /><xs:element name="Event" type="EventType" />


</xs:complexType>

<xs:complexType name="DataType"><xs:sequence>

<xs:element maxOccurs="1" minOccurs="1" name="Network" type="NetworkType" /></xs:sequence><xs:attribute name="version" type="xs:double" use="required" /><xs:attribute name="messageId" type="xs:string" use="optional" /><xs:attribute name="reply" type="xs:boolean" use="optional" default="false" />

</xs:complexType>

<xs:complexType name="DataResponseType"><xs:attribute name="version" type="xs:double" use="required" /><xs:attribute name="responseCode" type="xs:string" /><xs:attribute name="messageId" type="xs:string" use="optional" />

</xs:complexType>

<xs:element name="Data" type="DataType" /><xs:element name="SIDF" type="DataType" /><xs:element name="DataResponse" type="DataResponseType" />

</xs:schema>

3.9 CSV Definitions

SIDF/CSV format is currently focused on exchanging measurements with the aim ofminimized parsing overhead. As such, the current current version of the specificationdoes not support events or non-inline data with the CSV format.

Listing 3.22: CSV definition of SIDF.SIDF-MESSAGE = SUBSCRIBE-REQUEST / SUBSCRIBE-RESPONSE / UNSUBSCRIBE-REQUEST /

UNSUBSCRIBE-RESPONSE / DATA-MESSAGE / DATA-RESPONSE

DATA-MESSAGE = "SIDF:DATA" "," VERSION "," LINES "," MESSAGE-ID "," REPLY END-OF-LINELF MEASUREMENT *[LF MEASUREMENT] LF

DATA-RESPONSE = "SIDF:DATA-RSP" "," VERSION "," LINES "," MESSAGE-ID "," RESPONSE-CODEEND-OF-LINE LF

SUBSCRIBE-REQUEST = "SIDF:SUBSCRIBE-REQ" "," VERSION "," LINES "," MESSAGE-ID END-OF-LINE *(LF REQUEST-LINE) LF

SUBSCRIBE-RESPONSE = "SIDF:SUBSCRIBE-RSP" "," VERSION "," NO-LINES "," MESSAGE-ID ","RESPONSE-CODE END-OF-LINE LF

UNSUBSCRIBE-REQUEST = "SIDF:UNSUBSCRIBE-REQ" "," VERSION "," NO-LINES "," MESSAGE-IDEND-OF-LINE LF

UNSUBSCRIBE-RESPONSE = "SIDF:UNSUBSCRIBE-RSP" "," VERSION "," NO-LINES "," MESSAGE-ID "," RESPONSE-CODE END-OF-LINE LF

;; An empty quantity denotes any measurement from the listed network/node/sensorREQUEST-LINE = QUANTITY [ "," NETWORK-ID [ "," NODE-ID [ "," SENSOR-ID ] ] ]

MEASUREMENT = DATE-FORMAT "," NETWORK-ID "," NODE-ID "," SENSOR-ID "," QUANTITY ","COMPONENTS


COMPONENTS = COMPONENT *["," COMPONENT]COMPONENT = VALUE | KEY-VALUE-PAIRKEY-VALUE-PAIR = NAME "=" VALUE

QUANTITY = StringNETWORK-ID = StringNODE-ID = StringSENSOR-ID = String

DATE-FORMAT = RELATIVE-TIME / ABSOLUTE-TIMERELATIVE-TIME = ("+" / "-") 1*DIGIT ["." 1*DIGIT]ABSOLUTE-TIME = DATE "T" TIME TIME-ZONEDATE = ["-"] 4DIGIT "-" %x30-31 DIGIT "-" %x30-33 DIGITTIME = %x30-32 DIGIT ":" %x30-35 DIGIT ":" %x30-35 DIGIT ["." *DIGIT]TIME-ZONE = ( ("+" / "-") 2DIGIT ":" 2DIGIT ) / "Z"

END-OF-LINE = *("," String)VERSION = DoubleLINES = "" / IntegerNO-LINES = "" / 0MESSAGE-ID = StringRESPONSE-CODE = IntegerNAME = StringVALUE = StringREPLY = Boolean

Double = 1*DIGIT ["." 1*DIGIT]String = DQUOTE *VCHAR DQUOTEInteger = 1*DIGITBoolean = BIT



Subscriptions

v1.0 Subscribe operation comprises SIDFRequest and SIDFResponse messages. Aclient drops the subscription by sending an empty SIDFRequest.

v1.2 Subscribe operation comprises Request and Response messages. These are func-tionally similar to the SIDFRequest and SIDFResponse in the earlier versions.

v1.7 Subscribe operation uses SubscribeRequest, SubscribeResponse. An empty Sub-scribeRequest subscribes all data instead of dropping earlier subscriptions as inthe previous versions. Unsubscribe is now a separate operation comprising Un-subscribeRequest, UnsubscribeResponse messages.

XML namespace

v1.0 XML namespace is urn:ietf:params:xml:ns:sidf

v1.6 XML namespace is urn:wsn-openapi:sidf


r1.00-2013

Features

v1.4 Added Tolerance element

v1.7 Renamed SIDF message to Data

v1.7 Deprecated name attributes from Network and Node elements in Data

v1.7 Added optional feature for block data (Values element).



4 Sensor Archive Data Format

Sensor Archive Data Format (SADF) defines the methods to retrieve measurementsfrom the WSN OpenAPI data archive.

Specification version 1.4XML namespace urn:wsn-openapi:sadf

4.1 Query Operation

The Query operation is used to query measurements from the data archive. The resultsmay be returned as inline within the response message (default) or as a reference toan external resource, e.g., a HTTP link. In the latter case, the client retrieves the dataseparately. The type of resource is identified by the URI schema in the response. Theservice should support at least http: schema but it may also implement other schemas.

Authentication or security mechanisms for the accessing the data from external re-sources are outside the scope of this specification. One method is to return a randomURI resource that cannot be guessed and accessed by unintended parties within a rea-sonable time. The service should keep the resource available until it is read at least once,but the resource may be removed after a sufficient time period. Information about theservice time limits can be made available to the client via ACF capabilities.

4.1.1 Query

A Query message (Fig. 24) requests data from within the timeframe defined by the startand end attributes (start and end times are inclusive). If the specified timeframe points tothe future, the service gathers received data up to the time when the query was received.When not specified, the start time defaults to the beginning of the data archive history,and the end time defaults to the reception time of the query. If the latestOnly attribute isset to true, the query returns at most one result for every (network id, node id, sensorid, measurement quantity), (network id, node id, event id), and (network id, event id)duple. The returned result will have the newest time stamp within the timeframe of thequery.

The recipient will gather the data matching to the request and return them to therequesting client. The results contain data that matches any of the defined Measurementor Event elements or was generated by the source defined in the Network element. Thescope of Measurement and Event can be narrowed to the data sources within the certainnetworks, nodes or sensors. If the query does not contain any Measurement, Event orNetwork elements, all measurements within the timeframe will be returned.

45

An inline attribute controls how the results are delivered to the client. If the attributeis not defined or is set to always, data is fully embedded within the Response message.The value never causes all data values whose size exceed inlineThreshold bytes to bedelivered via an external resource. When the inline is set to allow, inlining happens atthe discretion of the WSN OpenAPI service. See Section 3.4.1 for more details on inlinedata. The inline and inlineThreshold attributes are ignored if the WSN OpenAPI servicedoes not support external resource.

To avoid receiving an excess amount of results, a query may limit the total numberof measurements and events within the response with maxResults attribute. If the resultset would be too large, the response will comprise first maxResult result entries fromquery start time. This way, the client may make another query starting from the lastreceived time instance to receive more unique data.

The client must have read access right to the data that matches the subscription.Specifically, if Query contains data sources (network/node/sensor) to which the clientdoes not have access rights, the elements are silently ignored and data relating to themis not returned.

Query versionf startt endt latestOnlyb inlines inlineThresholdd

maxResultsd messageIds

Measurement0..*

quantitys

Network0..* ids

Node0..* ids

Sensor0..* ids

Process0..1

types timed units aligns

Event0..* ids

Network0..* ids

Node0..*

ids

Network0..* ids

Node0..* ids

Sensor0..* ids

Figure 24: Archive data request.

4.1.2 Processing of results

An optional Process element may be defined to limit the size of returned data set andfilter it to a more suitable format e.g., for a presentation on user interfaces. The process-ing is performed separately for each measurement component. Components that do not


r1.00-2013

contain numeric values are not processed and will not be included in the results. Thesupport for the processing is not required, an implementation may

Processing is applied in periodic time intervals starting from the start time. Theinterval is defined with time and unit attributes, where the time is the length of the stepand unit is its unit. The valid values for the time unit are listed in Table 4.1. A Requestmessage must contain both time and unit attributes or neither of them. If the attributesare not defined, the time step defaults to the query length (end -start). Calendar eventssuch as day light saving or leap days are ignored.

Table 4.1: Time units in query processing.

Unit Description

day Dayshour Hoursmin Minutessec Seconds

The type attribute instructs how the data should be processed. Supported processingtypes are listed in Table 4.2. The optional align attribute defines the location of withinthe time interval that is used for the time stamp in the merged measurement. Valuesstart, middle and end set the timestamp to the start, middle or end of the time in-terval, respectively. Values first, average and last take the first, average, or lasttimestamp among the measurements within the interval, respectively. The processing isillustrated in Fig. 25.

Table 4.2: Query process types.

Type Description

min Minimum value within the time intervalavg Average value within the time intervalmax Maximum value within the time intervalsum Sum of all values within the time intervalcount Number of measurements within the time interval

4.1.3 Response

Response is generated as a response to Query and returns the related data. The re-sponseCode value is 200 (OK) on success, 206 (Partial content) if the number of resultentries exceeded maxResults, and 501 (Not implemented) if the request contained pro-cess instructions that the WSN OpenAPI service does not support.


(a) Source data (b) Unprocessed results

(c) Middle aligned, averaged results (d) Start aligned, maximum results

Figure 25: Example of processing measurement with two components (separated with differentcolors).

Response versionf responseCoded messageIds

Network0..*

ids

Node0..*

ids

Sensor0..* ids

Measurement0..* quantitys timet units

Component0..* ids units types

DATA

Tolerance0..* fors types units


DATA

Values0..1 ticks

CSV data

Event0..* ids time types


DATA

Event0..* ids time types


DATA

Figure 26: Archive data response.


r1.00-2013

The message structure is similar to the SIDF Data specification (see 3.4.1). To re-duce messaging overhead, measurements can optionally be enclosed by a Measurementselement that defines a common quantity and unit for the included measurements.


SADF has the following capability parameters (2.4).



blockDataSupport bool Supports the reception of block data (see Sec-tion 3.5.1). Default: false.

extDataSupport bool Support for external resources. Default: false.extResourceSchemes strlist Supported external resource schemas as comma sep-

arated string list (e.g., “http,https”)extDataRetainTime int Data retain timeout in seconds. Defines the time that

a data guaranteed to be found in an external resourceafter the completion of a query. The timeout 0 de-notes that data is retained indefinitely.

4.2.1 Examples

The following example retrieves temperature measurements from node 3 between givenstart and end times.

Listing 4.1: SADF/XML query request.<Query version="1.4" xmlns="urn:wsn-openapi:sadf" start="2009-07-03T11:24:46+00:00" end

="2009-07-03T11:28:46+00:00" messageId="1" latest="true"><Measurement quantity="Temperature" /><Network id="1" /><Node id="2">

<Sensor id="3"/></Node>

</Network></Query>

Listing 4.2: SADF/XML response to the message in 4.1.<Response version="1.4" responseCode="200" messageId="1" xmlns="urn:wsn-openapi:sadf"><Network id="1"><Node id="2"><Sensor id="1" ><Measurement quantity="Location" unit="WGS84" time="2009-03-03T11:24:46+00:00"><Component id="latitude">52.686</Component><Component id="longitude">2.193</Component><Component id="altitude">100</Component>


</Node><Node id="3"><Sensor id="1" ><Measurement quantity="Location" unit="WGS84" time="2009-03-03T11:24:46+00:00"><Component id="latitude">52.786</Component><Component id="longitude">2.293</Component><Component id="altitude">100</Component>



</Node><Node id="2"><Sensor id="3" ><Measurement quantity="Temperature" unit="C" time="2009-07-03T11:24:46+00:00"><Component id="value">23.0</Component>

</Measurement><Measurement quantity="Temperature" unit="C" time="2009-07-03T11:26:46+00:00"><Component id="value">23.1</Component>

</Measurement><Measurement quantity="Temperature" unit="C" time="2009-07-03T11:28:46+00:00"><Component id="value">23.0</Component>


</Node><Node id="3"><Sensor id="3" ><Measurement time="2009-07-03T11:24:46+00:00"><Component id="value">20.0</Component>

</Measurement><Measurement time="2009-07-03T11:26:46+00:00"><Component id="value">20.1</Component>

</Measurement><Measurement time="2009-07-03T11:28:46+00:00"><Component id="value">20.0</Component>


</Node><Node id="2"><Sensor id="1" ><Measurement quantity="Acceleration" unit="mg" time="2009-07-03T11:24:46+00:00"><Component id="x">245</Component><Component id="y">124</Component><Component id="z">800</Component><Component id="total">846</Component>


</Node></Network>

</Response>

Listing 4.3: SADF/CSV query.SADF:QUERY,1.4,2,,2009-07-25T14:20:00Z,2009-07-25T14:30:00ZM,TemperatureM,IlluminanceN,1

Listing 4.4: SADF/CSV response to the message in 4.3.SADF:RESPONSE,1.4,1,,2002009-07-25T14:24:48+00:00,1,2,3,Temperature,23.0

4.3 XML Schemas

Listing 4.5: XML Schema for SADF Query.<xs:schema xmlns="urn:wsn-openapi:sadf" xmlns:xs="http://www.w3.org/2001/XMLSchema"

attributeFormDefault="unqualified" elementFormDefault="qualified" targetNamespace="urn:wsn-openapi:sadf">

<xs:complexType name="ProcessType"><xs:attribute name="type" type="xs:string" use="required"/><xs:attribute name="time" type="xs:integer" use="optional"/>


r1.00-2013

<xs:attribute name="unit" type="xs:string" use="optional"/></xs:complexType>

<xs:complexType name="RequestMeasurementType"><xs:sequence>

<xs:element name="Process" type="ProcessType" minOccurs="0" maxOccurs="1"/></xs:sequence>

<xs:attribute name="quantity" type="xs:string" use="required"/></xs:complexType>

<xs:complexType name="RequestEventType"><xs:attribute name="id" type="xs:string" use="required"/>

</xs:complexType>

<xs:complexType name="RequestSensorType"><xs:attribute name="id" type="xs:string" use="required"/>

</xs:complexType>

<xs:complexType name="RequestNodeType"><xs:sequence>

<xs:element name="Sensor" type="RequestSensorType" minOccurs="0" maxOccurs="1"/>

</xs:sequence><xs:attribute name="id" type="xs:string" use="required"/>

</xs:complexType>

<xs:complexType name="RequestNetworkType"><xs:sequence>

<xs:element name="Node" type="RequestNodeType" minOccurs="0" maxOccurs="1"/></xs:sequence><xs:attribute name="id" type="xs:string" use="required"></xs:attribute>

</xs:complexType>

<xs:complexType name="QueryRequestType"><xs:sequence>

<xs:element name="Measurement" type="RequestMeasurementType" minOccurs="0"maxOccurs="unbounded"/>

<xs:element name="Event" type="RequestEventType" minOccurs="0" maxOccurs="unbounded"/><xs:element name="Network" type="RequestNetworkType" minOccurs="0" maxOccurs="

unbounded"/></xs:sequence>

<xs:attribute name="version" type="xs:double" use="required"/><xs:attribute name="start" type="xs:dateTime" use="optional"/><xs:attribute name="end" type="xs:dateTime" use="optional"/><xs:attribute name="latestOnly" type="xs:boolean" use="optional" default="false"/><xs:attribute name="inline" type="xs:string" use="optional" default="always"/><xs:attribute name="inlineThreshold" type="xs:integer" use="optional" default="1024"

/><xs:attribute name="maxResults" type="xs:integer" use="optional" default="0"/><xs:attribute name="messageId" type="xs:string" use="optional"/>

</xs:complexType>

<xs:element name="Query" type="QueryRequestType"></xs:element></xs:schema>

Listing 4.6: XML Schema for SADF Response.<xs:schema xmlns="urn:wsn-openapi:sadf" xmlns:xs="http://www.w3.org/2001/XMLSchema"

attributeFormDefault="unqualified" elementFormDefault="qualified" targetNamespace="urn:wsn-openapi:sadf">

<xs:complexType name="EventComponentType"><xs:simpleContent>




</xs:complexType>


<xs:element maxOccurs="unbounded" minOccurs="0" name="Component" type="EventComponentType" />

</xs:sequence><xs:attribute name="id" type="xs:string" use="required" /><xs:attribute name="time" type="xs:dateTime" use="required" /><xs:attribute name="type" type="xs:string" use="optional" default="alert"/>

</xs:complexType>

<xs:complexType name="ToleranceComponentType"><xs:simpleContent>



</xs:complexType>

<xs:complexType name="ToleranceType"><xs:sequence>

<xs:element name="Component" type="ToleranceComponentType" minOccurs="0"maxOccurs="unbounded" />

</xs:sequence><xs:attribute name="for" type="xs:string" use="required" /><xs:attribute name="type" type="xs:string" use="required" /><xs:attribute name="unit" type="xs:string" use="optional" />

</xs:complexType>

<xs:complexType name="ComponentType"><xs:simpleContent>

<xs:extension base="xs:string"><xs:attribute name="id" type="xs:string" use="optional" default="value" /><xs:attribute name="unit" type="xs:string" use="optional" />

<xs:attribute name="ref" type="xs:anyURI" use="optional" /></xs:extension>


<xs:complexType name="ValuesType"><xs:simpleContent>

<xs:extension base="xs:string"><xs:attribute name="tick" type="xs:string" use="optional"/>


</xs:complexType>

<xs:complexType name="MeasurementType"><xs:sequence><xs:element name="Component" type="ComponentType" /><xs:element name="Tolerance" type="ToleranceType" minOccurs="0" maxOccurs="

unbounded" /><xs:element name="Values" type="ValuesType" minOccurs="0" maxOccurs="1" /></xs:sequence><xs:attribute name="quantity" type="xs:string" use="required" /><xs:attribute name="time" type="xs:dateTime" use="required" /><xs:attribute name="unit" type="xs:string" use="optional" />

</xs:complexType>

<xs:complexType name="SensorType"><xs:sequence>

<xs:element name="Measurement" type="MeasurementType" minOccurs="1" maxOccurs="1"/>


</xs:complexType>


r1.00-2013


<xs:element name="Sensor" type="SensorType"/><xs:element name="Event" type="EventType"/>


</xs:complexType>


<xs:element name="Node" type="NodeType" /><xs:element name="Event" type="EventType" />


</xs:complexType>

<xs:complexType name="QueryResponseType"><xs:sequence>

<xs:element maxOccurs="1" minOccurs="1" name="Network" type="NetworkType" /></xs:sequence><xs:attribute name="version" type="xs:double" use="required" />

<xs:attribute name="responseCode" type="xs:string" use="required"/><xs:attribute name="messageId" type="xs:string" use="optional" />

</xs:complexType>

<xs:element name="Response" type="QueryResponseType" />

</xs:schema>

4.4 CSV Definition

SADF/CSV format is currently focused on exchanging measurements with the aim ofminimized parsing overhead. As such, the current current version of the specificationdoes not support events.

Listing 4.7: ABNF Definition of SADF/CSV.SADF-MESSAGE = DATA-REQUEST / DATA-RESPONSE

DATA-REQUEST = "SADF:REQ" "," VERSION "," LINES "," MESSAGE-ID "," STARTTIME ","ENDTIME "," LATEST-ONLY "," MAX-RESULTS END-OF-LINE *(LF REQUEST-LINE) LF

DATA-RESPONSE = "SADF:RSP" "," VERSION "," LINES "," MESSAGE-ID "," RESPONSE-CODE END-OF-LINE *[LF MEASUREMENT] LF

REQUEST-LINE = REQ-MEASUREMENT / REQ-NETWORKREQ-MEASUREMENT = "M," QUANTITY ["," PROCESS-TYPE ["," TIME ["," UNIT ]]]REQ-NETWORK = "N," NETWORK-ID ["," NODE-ID ["," SENSOR-ID]]

MEASUREMENT = DATE-FORMAT "," NETWORK-ID "," NODE-ID "," SENSOR-ID "," QUANTITY ","COMPONENTS

COMPONENTS = COMPONENT *["," COMPONENT]COMPONENT = VALUE | KEY-VALUE-PAIRKEY-VALUE-PAIR = NAME "=" VALUE

STARTTIME = ABSOLUTE-TIMEENDTIME = ABSOLUTE-TIME

QUANTITY = StringNETWORK-ID = StringNODE-ID = StringSENSOR-ID = String


END-OF-LINE = *("," String)


VERSION = DoubleLINES = "" / IntegerMESSAGE-ID = StringRESPONSE-CODE = IntegerLATEST-ONLY = BooleanMAX-RESULTS = IntegerNAME = StringVALUE = String




Data query

v1.0 Date query comprises SADFQuery and SADFResponse messages

v1.3 Data query operation comprises Query and Response messages. Functionally,these are similar to the earlier versions.

v1.4 Data query comprises Query and Response messages. These are not compatiblewith the earlier versions.

XML namespace

v1.0 XML namespace is urn:ietf:params:xml:ns:sidf

v1.3 XML namespace is urn:wsn-openapi:sidf

Features

v1.4 Described ACF capabilities

v1.4 Revised data query operation to better reflect real-world use cases:

v1.4 Added Process element to the query. The reasoning is to reduce network trafficby allowing the WSN OpenAPI service to aggregate data.

v1.4 Changed Response structure to follow more closely SIDF message structure, thishas synergies in parsing/handling between the two interfaces

v1.4 Added optional feature: Values component to the Response to allow more efficientdata transfer with block data

v1.4 Moved query time interval from a separate elements to attributes

v1.4 Deprecated Network and Node name attributes


5 Node Actuator and Sensor Control

Node Actuator and Sensor Control (NASC) is intended for controlling actuator devicessuch as light switches or valves. The interface does not limit the actuator to physicaldevices, the interface may be used to exchange configuration information with devices.

Specification version 1.1XML namespace urn:wsn-openapi:nascDependencies SIDF v1.7

5.1 Register Operation

The register operation indicates to the service that a client has a certain set of actuatorsthat can be controlled. As a result, the service may direct relevant command requests(see Section 5.4) to the client.

5.1.1 RegisterRequest

A RegisterRequest message (Fig. 27) generates a subscription to NASC status mes-sages.

RegisterRequest versionf messageIds

Network0..* ids

Node0..*

ids

Actuator0..* ids quantitys

Figure 27: Register request.

5.1.2 RegisterResponse

An RegisterResponse message (Fig. 28) is generated as a response to RegisterRequest.The responseCode attribute has a value of 200 on success. If the request fails, the clientshould expect that an earlier subscription will remain effective.

55

RegisterResponse versionf responseCodes messageIds

Figure 28: Register response.

5.2 Unregister Operation

Unregister operation drops registrations from the service.

5.2.1 UnregisterRequest

An UnregisterRequest message (Fig. 29) instructs the service to drop all existing regis-trations belonging to the sender.

UnregisterRequest versionf messageIds

Figure 29: Unregister request.

5.2.2 UnregisterResponse

An UnregisterResponse message (Fig. 30) is generated as a response to UnregisterRe-quest. The responseCode attribute has a value of 200 on success. If the request fails,the client should expect that an existing registration will remain effective.

UnregisterRequest versionf responseCoded messageIds

Figure 30: Unregister response.

5.3 Status Operation

Status operation retrieves the current status of an actuator or device configuration.


r1.00-2013

Client Service

when changedindependently

StatusRequest

StatusResponse

StatusIndication

Figure 31: Message exchange in the status operation.

5.3.1 StatusRequest

A StatusRequest message requests the current status of one or more actuator. If a Net-work element is not defined, the request retrieves the status from all actuators in allnetworks. Similarly, if the Node or Actuator elements are not defined, the request at-tempts to retrieve the status from all nodes or actuators within the specified networksor nodes, respectively. The optional id attribute targets the request to a specific actu-ator within a node. If the attribute is not defined, the request will return all matchingactuators.

StatusRequest versionf messageIds

Network0..* ids

Node0..* ids

Actuator0..*

quantitys ids

Figure 32: Status request.

5.3.2 StatusResponse

StatusResponse is generated as a response to StatusRequest.


StatusResponse versionf responseCoded messageIds

Network0..* ids

Node0..* ids

Actuator0..* types times ids

Component0..*

ids units types

Value

Figure 33: Status response.

5.4 Command Operation

Command operation modifies the state of the actuator.

Client Service

actuator orconfigurationcommand

commandinitiated

commandcompleted

CommandRequest

CommandResponse

StatusIndication

Figure 34: Message exchange in the command operation.

5.4.1 CommandRequest

A CommandRequest message defines a new state for the actuator. An Actuator elementcontains the actuator quantity and an optional id element to limit the command to aspecific actuator. If not defined, all actuators of quantity in a given node are targeted.


r1.00-2013

CommandRequest versionf times messageIds timeoutd

Network1 ids

Node1 ids

Actuator1 types ids

Component0..*

ids units types

Value

Figure 35: Command request.

5.4.2 CommandResponse

CommandResponse is generated as a response to a CommandRequest message. Theresponse indicates whether the operation succeeded. The responseCode attribute has avalue of 200 if the command was successful. The response code is 202 (Accepted) ifthe command was received, but the actuator state has not yet been changed. The servicewill respond to the client with a SIDF Data (Section 3.4.1) message that contains thenew state when the actuation has been completed.

CommandResponse versionf responseCoded messageIds

Figure 36: Command response.

5.5 Relation to SIDF

The interface relies on SIDF to send actuator status indications1. Actuator states incommands are mapped to a SIDF measurement as follows:

• NASC Actuator quantity→ SIDF Measurement quantity

• NASC Actuator id→ SIDF Sensor id

5.6 Examples

A complex example of NASC message exchange is presented in Fig. 37. In the example,the WSN OpenAPI service is a broker between a sensor device and a WSN OpenAPI client(e.g., a user interface).

1The goal in using SIDF is to avoid duplicate functionality between interfaces. Also, understandingan actuator state as measurements utilizing SADF to maintain the state history.


Device Service Client

Register device'sactuators

Query currentactuator state

Subscribe tostate changes

Request currentactuator state

Actuator statechanged, e.g., due tophysical interaction

Change actuatorstate

Actuator startingto change itsstate

Actuator statechanged

NASC:RegisterRequest

NASC:RegisterResponse

NASC:StatusRequest

NASC:StatusResponse

SIDF:SubscribeRequest

SIDF:SubscribeResponse

NASC:StatusRequest

NASC:StatusResponse

SIDF:Data

SIDF:Data

NASC:CommandRequest

NASC:CommandRequest

NASC:CommandResponse

NASC:CommandResponse

SIDF:Data

SIDF:Data

Figure 37: Example of message exchange between a sensor device and a client.

5.6.1 Registering an actuator

Listing 5.1: Registering an actuator.<RegisterRequest version="1.1" xmlns="urn:wsn-openapi:nasc"><Network id="default"><Node id="101"><Actuator id="0" quantity="openapi:binarySwitch"/>

</Node></Network>

</CommandRequest>

Listing 5.2: Expected response to Ex. 5.1


r1.00-2013

<RegisterResponse version="1.1" xmlns="urn:wsn-openapi:nasc" responseCode="200" />

5.6.2 Requesting actuator status

Listing 5.3: Requesting actuator status from a node.<StatusRequest version="1.1" xmlns="urn:wsn-openapi:nasc"><Network id="default"><Node id="101" />

</Network></StatusRequest>

Listing 5.4: Status response to the request in 5.3<StatusResponse version="1.1" xmlns="urn:wsn-openapi:nasc" responseCode="200"><Network id="default"><Node id="101"><Actuator quantity="openapi:binarySwitch" id="0">ON</Actuator><Actuator quantity="txPower_mW" id="2">1</Actuator>

</Node></Network>

</StatusResponse>

5.6.3 Sending an actuator command

The following example shows a simple actuator command targeted at the actuator 0in the node 101 within the default network. If the id attribute was not defined, thecommand would have turned on all light switches that are connected to the device.

Listing 5.5: Actuator command for a light switch.<CommandRequest version="1.1" xmlns="urn:wsn-openapi:nasc"><Network id="default"><Node id="101"><Actuator quantity="openapi:lightSwitch" id="0"><Component>ON</Component>

</Actuator></Node>

</Network></CommandRequest>

Listing 5.6: Command response on success.<CommandResponse version="1.1" xmlns="urn:wsn-openapi:nasc" responseCode="200"/>

NASC may be used to control virtual actuators or adjust configuration of a device.The following listing shows an example of a message that adjusts node’s operationalconfiguration.

Listing 5.7: Configuration command.<CommandRequest version="1.1" xmlns="urn:wsn-openapi:nasc"><Network id="default"><Node id="101"><Actuator quantity=":configuration"><Component id="sleepPeriod" unit="sec">0.5</Component><Component id="txPower" unit="mW">0</Component>

</Actuator></Node>

</Network></CommandRequest>


5.7 XML Schemas

Listing 5.8: XML schema for NASC.<xs:schema xmlns="urn:wsn-openapi:nasc" xmlns:xs="http://www.w3.org/2001/XMLSchema"

attributeFormDefault="unqualified" elementFormDefault="qualified" targetNamespace="urn:wsn-openapi:nasc">

<xs:complexType name="ActuatorType"><xs:simpleContent>

<xs:extension base="xs:string"><xs:attribute name="type" type="xs:string" use="required" /><xs:attribute name="id" type="xs:string" use="optional" />


</xs:complexType>

<xs:complexType name="NodeType"><xs:sequence>

<xs:element name="Actuator" type="ActuatorType" minOccurs="1" maxOccurs="1"/></xs:sequence>

<xs:attribute name="id" type="xs:string" use="required" /></xs:complexType>


<xs:element name="Node" type="NodeType" minOccurs="1" maxOccurs="1" /></xs:sequence>

<xs:attribute name="id" type="xs:string" use="required" /></xs:complexType>

<xs:complexType name="StatusRequestType"><xs:sequence>


</xs:sequence><xs:attribute name="version" type="xs:double" use="required" /><xs:attribute name="messageId" type="xs:string" use="optional" />

</xs:complexType>

<xs:complexType name="StatusResponseType"><xs:sequence>


</xs:sequence><xs:attribute name="version" type="xs:double" use="required" /><xs:attribute name="responseCode" type="xs:string" use="required" /><xs:attribute name="messageId" type="xs:string" use="optional" />

</xs:complexType>

<xs:complexType name="CommandRequestType"><xs:sequence>

<xs:element name="Network" type="NetworkType" minOccurs="1" maxOccurs="1" /></xs:sequence><xs:attribute name="version" type="xs:double" use="required" /><xs:attribute name="messageId" type="xs:string" use="optional" /><xs:attribute name="timeout" type="xs:integer" use="optional" />

</xs:complexType>

<xs:complexType name="CommandResponseType"><xs:attribute name="version" type="xs:double" use="required" /><xs:attribute name="responseCode" type="xs:integer" use="required" /><xs:attribute name="messageId" type="xs:string" use="optional" />

</xs:complexType>

<xs:element name="StatusRequest" type="StatusRequestType" /><xs:element name="StatusResponse" type="StatusResponseType" /><xs:element name="StatusIndication" type="StatusResponseType" />


r1.00-2013

<xs:element name="CommandRequest" type="CommandRequestType" /><xs:element name="CommandResponse" type="CommandResponseType" />

</xs:schema>

5.8 CSV Definitions

Listing 5.9: CSV definition for NASC.NASC-MESSAGE = STATUS-REQUEST / STATUS-RESPONSE / STATUS-INDICATION / COMMAND-REQUEST /

COMMAND-RESPONSE

STATUS-REQUEST = "NASC:STATUS-REQ" "," VERSION "," LINES "," MESSAGE-ID END-OF-LINE *[LF REQUEST-LINE] LF

STATUS-RESPONSE = "NASC:STATUS-RSP" "," VERSION "," LINES "," MESSAGE-ID "," RESPONSE-CODE END-OF-LINE *[LF STATUS-LINE] LF

STATUS-INDICATION = "NASC:STATUS-IND" "," VERSION "," LINES "," MESSAGE-ID END-OF-LINE*[LF STATUS-LINE] LF

COMMAND-REQUEST = "NASC:COMMAND-REQ" "," VERSION "," ONE-LINE "," MESSAGE-ID END-OF-LINE LF STATUS-LINE LF

COMMAND-RESPONSE = "NASC:COMMAND-RSP" "," VERSION "," NO-LINES "," MESSAGE-ID ","RESPONSE-CODE END-OF-LINE LF

REQUEST-LINE = NETWORK-ID "," NODE-ID "," ACTUATOR-TYPE "," [ACTUATOR-ID]STATUS-LINE = NETWORK-ID "," NODE-ID "," ACTUATOR-TYPE "," [ACTUATOR-ID] "," VALUE

NETWORK-ID = StringNODE-ID = StringACTUATOR-TYPE = StringACTUATOR-ID = String

END-OF-LINE = *("," String)VERSION = DoubleLINES = "" / IntegerONE-LINE = "1"NO-LINES = "" / 0MESSAGE-ID = StringRESPONSE-CODE = IntegerNAME = StringVALUE = String

Double = 1*DIGIT ["." 1*DIGIT]String = DQUOTE *VCHAR DQUOTE



XML namespace

• v1.0: XML namespace is urn:ietf:params:xml:ns:sidf

• v1.1: XML namespace is urn:wsn-openapi:sidf

Features

• v1.1: Revised the simplistic message format to better meet real-world use cases

• v1.1: Deprecated NASC message

• v1.1: Defined Command, Status, (Un)Subscribe, and (Un)Register operations



6 Metadata Format

Metadata Format (MEDF) specifies the methods for storing and accessing sensor relatedmetadata. For example, this metadata may include generic description of a node orinformation about its hardware, sensors, actuators, manufacturer, serial number, andquantities that the node can measure.

MEDF is designed to carry any textual content as its message payload and does notmandate a specific type of metadata. A suggested structure for the sensor metadata isspecified in Section ??. Another possible alternative for metadata is SensorML [BR07].

Specification version 1.1XML namespace urn:wsn-openapi:sadf

6.1 Request Operation

Request operation queries the meta data of a specified node.

6.1.1 Request

A Request message (Fig. 38) retrieves a datasheet for the specified Node in a givenNetwork 1. If the optional time attribute is defined, the WSN OpenAPI service will returnthe newest datasheet that is earlier or equal to the time. Otherwise, the service willreturn the newest datasheet.

Request versionf messageIds

Network1 ids

Node1

ids times

Figure 38: MEDF request message.

6.1.2 Response

A Response message (Fig. 39) is generated as a response to a Request message. TheresponseCode attribute has a value of 200 on success. If a valid data sheet was notfound, the service responds with 204 (No Content).

1Note that MEDF supports only operation that are targeted at a single node. This is intended to reduceimplementation complexity. Otherwise, e.g., a failure on the insertion or deletion of a datasheet wouldrequire additional signaling on which part of the operation failed.

65

Response versionf responseCoded messageIds

Network0..1 ids

Node1

ids times

Sensor datasheet

Figure 39: MEDF response message.

6.2 Insert Operation

Insert operation adds a new datasheet to the meta data archive.

6.2.1 InsertRequest

A InsertRequest (Fig. 40) contains a datasheet for a node that is to be stored. If theoptional time attribute is not defined, the timestamp will be set to the insertion time.If the time coincides with an existing datasheet for the node in question, the existingdatasheet will be replaced. A WSN OpenAPI implementation is expected to store thedatasheets with at least one second granularity. When the replace attribute is set to true,the request will replace all existing datasheets assigned for the node with the new one.

InsertRequest versionf messageIds replaceb

Network1 ids

Node1 ids times

Sensor datasheet

Figure 40: Insert request.

6.2.2 InsertResponse

A InsertResponse message (Fig. 41) is generated as a response to InsertRequest. If theinsert operation succeeded, the responseCode is set to 200 (OK), otherwise the codeindicates an error.

InsertResponse versionf responseCoded messageIds

Figure 41: Insert response.

6.3 Remove Operation

Remove operation (Fig. 42 and Fig. 43) removes an existing data sheet from the metadata archive. If the time attribute is defined, only the datasheet with the specified times-


r1.00-2013

tamp is removed. If the time is not defined, the operation will remove all datasheetsbelonging to the node in question.

RemoveRequest versionf messageIds

Network1

ids

Node1 ids times

Figure 42: Remove request.

RemoveResponse versionf responseCoded messageIds

Figure 43: Remove response.

6.4 Examples

An example of a XML formatted request for a sensor datasheet from a node 2, belongingto network 1:

Listing 6.1: Example of a meta data request.<Request version="1.1" xmlns="urn:wsn-openapi:medf">

<Network id="1"><Node id="2" />

</Network></Request>

The following example shows an example reply to the request 6.1.

Listing 6.2: Example of a meta data response.<Response version="1.1" xmlns="urn:wsn-openapi:medf" responseCode="200">

<Network id="1"><Node id="2" time="2012-07-03T11:24:46+00:00">

<Datasheet><Device><Name>Pocket device</Name>

</Device><Sensor id="0"><Name>Acceleration</Name><Component id="x" quantity="openapi:acceeleration" unit="mg" type="instant" ><MinValue>-4000</MinValue><MaxValue>4000</MaxValue><Resolution>0.25</Resolution>

</Component><Component id="y" quantity="openapi:acceeleration" unit="mg" type="instant" ><MinValue>-4000</MinValue><MaxValue>4000</MaxValue><Resolution>0.25</Resolution>

</Component><Component id="z" quantity="openapi:acceeleration" unit="mg" type="instant" ><MinValue>-4000</MinValue><MaxValue>4000</MaxValue><Resolution>0.25</Resolution>

</Component></Sensor>


</Datasheet></Node>

</Network></Request>

An example of a CSV formatted request for a sensor datasheet from a node 2, be-longing to network 1:

Listing 6.3: Example of requesting meta data.MEDF:REQ,1.1,1,1,2

An example of a CSV formatted request for a sensor datasheet from a node 2, be-longing to network 1 with a specific time. A datasheet that has time 2012-07-03T11:24:46+00:00or earlier is returned.

Listing 6.4: Example of requesting meta data.MEDF:REQ,1.1,1,2,2012-07-03T11:24:46+00:00

An example reply to the request 6.4:

Listing 6.5: Example of meta data response.MEDF:RSP,1.1,,24,2001,2,2012-07-03T11:24:46+00:00<Datasheet><Device><Name>Pocket device</Name>

</Device><Sensor id="0"><Name>Acceleration</Name><Component id="x" quantity="openapi:acceeleration" unit="mg" type="instant" ><MinValue>-4000</MinValue><MaxValue>4000</MaxValue><Resolution>0.25</Resolution>

</Component><Component id="y" quantity="openapi:acceeleration" unit="mg" type="instant" ><MinValue>-4000</MinValue><MaxValue>4000</MaxValue><Resolution>0.25</Resolution>

</Component><Component id="z" quantity="openapi:acceeleration" unit="mg" type="instant" ><MinValue>-4000</MinValue><MaxValue>4000</MaxValue><Resolution>0.25</Resolution>


</Datasheet>


MEDF has the follow ACF capability parameters (see Section 2.4).



metaDataFormat str Metadata format. Defaults to WSN OpenAPI sensordatasheet if not defined.


r1.00-2013

6.6 XML Schemas

Listing 6.6: XML schema for MEDF request.<xs:schema xmlns="urn:wsn-openapi:medf" xmlns:xs="http://www.w3.org/2001/XMLSchema"

attributeFormDefault="unqualified" elementFormDefault="qualified" targetNamespace="urn:wsn-openapi:medf">

<xs:complexType name="NodeType"><xs:attribute name="id" type="xs:string" use="required"/><xs:attribute name="time" type="xs:dateTime" use="optional"/>

</xs:complexType>


<xs:element name="Node" type="NodeType" minOccurs="1" maxOccurs="1"/></xs:sequence><xs:attribute name="id" type="xs:string" use="required"/>

</xs:complexType>

<xs:complexType name="RequestType"><xs:choice minOccurs="1" maxOccurs="1">

<xs:element name="Network" type="NetworkType"/></xs:choice><xs:attribute name="version" type="xs:double" use="required"/><xs:attribute name="messageId" type="xs:string" use="optional"/>

</xs:complexType>

<xs:element name="Request" type="RequestType"/></xs:schema>

Listing 6.7: XML schema for MEDF response.<xs:schema xmlns="urn:wsn-openapi:medf" xmlns:xs="http://www.w3.org/2001/XMLSchema"

attributeFormDefault="unqualified" elementFormDefault="unqualified"targetNamespace="urn:wsn-openapi:medf">

<xs:complexType name="NodeType"><xs:simpleContent>

<xs:extension base="xs:string"><xs:attribute name="id" type="xs:string" use="required"/><xs:attribute name="time" type="xs:dateTime" use="required"/>


</xs:complexType>



</xs:complexType>

<xs:complexType name="ResponseType"><xs:sequence>

<xs:element name="Network" type="NetworkType" minOccurs="1" maxOccurs="1"/></xs:sequence><xs:attribute name="version" type="xs:double" use="required"/><xs:attribute name="messageId" type="xs:string" use="optional"/><xs:attribute name="responseCode" type="xs:integer" use="required"/>

</xs:complexType>

<xs:element name="Response" type="ResponseType"/>

</xs:schema>

Listing 6.8: XML schema for MEDF insert request.


<xs:schema xmlns="urn:wsn-openapi:medf" xmlns:xs="http://www.w3.org/2001/XMLSchema"attributeFormDefault="unqualified" elementFormDefault="qualified" targetNamespace="urn:wsn-openapi:medf">

<xs:complexType name="NodeType"><xs:simpleContent>

<xs:extension base="xs:string"><xs:attribute name="id" type="xs:string" use="required"/><xs:attribute name="time" type="xs:dateTime" use="optional"/>


</xs:complexType>



</xs:complexType>

<xs:complexType name="InsertRequestType"><xs:sequence>

<xs:element name="Network" type="NetworkType" minOccurs="1" maxOccurs="1"/></xs:sequence><xs:attribute name="version" type="xs:double" use="required"/><xs:attribute name="messageId" type="xs:string" use="optional"/>

</xs:complexType>

<xs:element name="InsertRequest" type="InsertRequestType"/>

</xs:schema>

Listing 6.9: XML schema for MEDF insert response.<xs:schema xmlns="urn:wsn-openapi:medf" xmlns:xs="http://www.w3.org/2001/XMLSchema"


<xs:complexType name="InsertResponseType"><xs:attribute name="version" type="xs:double" use="required"/><xs:attribute name="messageId" type="xs:string" use="optional"/><xs:attribute name="responseCode" type="xs:integer" use="optional"/>

</xs:complexType>

<xs:element name="InsertResponse" type="InsertResponseType" /></xs:schema>

Listing 6.10: XML schema for MEDF remove request.<xs:schema xmlns="urn:wsn-openapi:medf" xmlns:xs="http://www.w3.org/2001/XMLSchema"

attributeFormDefault="unqualified" elementFormDefault="qualified" targetNamespace="urn:wsn-openapi:medf">

<xs:complexType name="NodeType"><xs:attribute name="id" type="xs:string" use="required"/><xs:attribute name="time" type="xs:dateTime" use="optional"/></xs:complexType>



</xs:complexType>

<xs:complexType name="RemoveRequestType"><xs:sequence>

<xs:element name="Network" type="NetworkType" minOccurs="1" maxOccurs="1"/></xs:sequence>


r1.00-2013

<xs:attribute name="version" type="xs:double" use="required"/><xs:attribute name="messageId" type="xs:string" use="optional"/>

</xs:complexType>

<xs:element name="RemoveRequest" type="RemoveRequestType"/>

</xs:schema>

Listing 6.11: XML schema for MEDF remove response.<xs:schema xmlns="urn:wsn-openapi:medf" xmlns:xs="http://www.w3.org/2001/XMLSchema"


<xs:complexType name="RemoveResponseType"><xs:attribute name="version" type="xs:double" use="required"/><xs:attribute name="messageId" type="xs:string" use="optional"/><xs:attribute name="responseCode" type="xs:integer" use="optional"/>

</xs:complexType>

<xs:element name="RemoveResponse" type="RemoveResponseType" /></xs:schema>

6.7 CSV Definitions

Listing 6.12: CSV definition for MEDF.MEDF-MESSAGE = GET-REQUEST / GET-RESPONSE / INSERT-REQUEST / INSERT-RESPONSE / REMOVE-

REQUEST / REMOVE-RESPONSE

GET-REQUEST = "MEDF:REQ" "," VERSION "," ONE-LINE "," MESSAGE-ID END-OF-LINE REQUEST-LINE LF

GET-RESPONSE = "MEDF:RSP" "," VERSION "," LINES "," MESSAGE-ID "," RESPONSE-CODE END-OF-LINE RESPONSE-LINE *(LF CONTENT-LINE) LF

INSERT-REQUEST = "MEDF:INSERT-REQ" "," VERSION "," LINES "," MESSAGE-ID END-OF-LINE LFREQUEST-LINE *(LF CONTENT-LINE) LF

INSERT-RESPONSE = "MEDF:INSERT-RSP" "," VERSION "," NO-LINES "," MESSAGE-ID ","RESPONSE-CODE END-OF-LINE LF

REMOVE-REQUEST = "MEDF:REMOVE-REQ" "," VERSION "," ONE-LINE "," MESSAGE-ID "," END-OF-LINE REQUEST-LINE LF

REMOVE-RESPONSE = "MEDF:REMOVE-RSP" "," VERSION "," NO-LINES "," MESSAGE-ID ","RESPONSE-CODE END-OF-LINE LF

REQUEST-LINE = NETWORK-ID "," NODE-ID ["," ABSOLUTE-TIME] END-OF-LINERESPONSE-LINE = NETWORK-ID "," NODE-ID "," ABSOLUTE-TIME END-OF-LINECONTENT-LINE = *VCHAR

NODE-ID = StringNETWORK-ID = String


END-OF-LINE = *("," String)VERSION = DoubleLINES = "" / IntegerONE-LINE = "1"NO-LINES = "" / "0"MESSAGE-ID = StringRESPONSE-CODE = IntegerLATEST-ONLY = BooleanMAX-RESULTS = IntegerNAME = StringVALUE = String

Double = 1*DIGIT ["." 1*DIGIT]


String = *VCHAR / DQUOTE *VCHAR DQUOTEInteger = 1*DIGIT



Request operation

• v1.0: Request operation comprises MEDFRequest and MEDFResponse messages,status code returned in ReturnCode element with the MEDFResponse message

• v1.1: Request operation comprises Request and Response messages, status codereturned with responseCode attribute of the Response message

Insert operation

• v1.0: Insert operation comprises MEDFInsert message (no response specified)

• v1.1: Insert operation comprises Insert and InsertResponse messages

XML namespace

• v1.0: XML namespace is urn:ietf:params:xml:ns:medf

• v1.1: XML namespace is urn:wsn-openapi:medf

Features

• v1.1: Revised the simplistic message format to better meet real-world use cases

• v1.1: Allow other than SensorML metadata formats (implementation decides)

• v1.1: Defined Remove operation


7 Network Management Format

Network Management Format (NMF) specifies the methods for accessing informationthat is related to network structure and configuring the automated collection of sensordata from the network.

Specification version 1.2XML namespace urn:wsn-openapi:nmf

7.1 GetStructure Operation

Structure operation returns the list of known networks, nodes and their transducers.

7.2 GetStructure

A GetStructureRequest (Fig. 44) initiates network structure query on selected networks.If no Network elements are specified, the request will return the structure in all networksto which the user has access. A WSN OpenAPI service may return a cached networkstructure, maintained e.g., based on received traffic, or it may initiate technology specificnetwork poll upon receiving the request to acquire an up-to-date information of networkstructure.

GetStructureRequest versionf messageIds

Network0..*

ids

Figure 44: Get network structure request.

7.3 GetStructureResponse

GetStructureResponse (Fig. 45) is generated as a response to GetStructure. The re-sponseCode value is 200 (OK) on success or 206 (Partial content) if a timeout occurredbefore the network structure could be fully obtained. In the latter case, the client mayre-request the structure after a while.

Each node in the response is associated with a time attribute that is the latest timeinstance of the communication between the service and the node.

73

GetStructureResponse versionf responseCoded messageIds

Network0..* ids

Node0..*

ids times

Transducer0..* ids quantitys

Figure 45: Get network structure response.

7.4 GetMeasurements Operation

GetMeasurements operation returns measurement collection policy. See Section 7.5 formore details on measurement collection policy.

7.4.1 GetMeasurementsRequest

A GetMeasurementsRequest (Fig. 46) requests measurement configuration from one ormore networks. If the request does not contain any Network elements, the responsereturns configuration from all networks.

GetMeasurementsRequest versionf messageIds

Network1..* ids

Figure 46: Get measurements request.

7.4.2 GetMeasurementsResponse

A GetMeasurementsResponse message (Fig. 47) is generated as a response to GetMea-surements. The responseCode value is 200 (OK) on success.

GetMeasurementsResponse versionf responseCoded messageIds

Network0..* ids

Measurement0..* quantitys intervald units

Node0..* ids

Transducer0..* ids

Figure 47: Get measurements request.


r1.00-2013

7.5 SetMeasurements Operation

A SetMeasurements operation defines the measurement collection policy of a network.The policy describes the measurements that are collected from a sensor network anddefines how often they are collected. The policy can be network wide or directed atspecific nodes and transducers.

If the underlying network technology does not support changing the way the mea-surements are collected, the WSN OpenAPI service may emulate the functionality. If theservice supports emulation, the following behavior is expected. For technologies thatdo not support periodic (push style) measurements, the WSN OpenAPI service emulatesthe functionality by polling data with the requested measurement intervals. When thetechnology supports periodic measurements but the measurement interval is not con-figurable (that is, values are reported with a fixed interval), the WSN OpenAPI serviceeither returns a cached value on configured collection interval or polls for fresh values1.

Note that the measurement collection defined in NMF should not be confused withthe SIDF subscriptions. A SIDF subscription affects only one client session whereasthe NMF measurement configuration is a administrator type configuration that affectsall clients and all sessions. For example, if a client’s SIDF subscription requests tem-perature readings but the temperature collection is not enabled, the readings will not bedelivered to the client.

7.5.1 SetMeasurementsRequest

A SetMeasurementsRequest message (Fig. 48) requests the collection of Measurementsfrom one or more Networks. The quantity attribute describes the type of measurement,while the interval and unit attributes defines how often the measurement is collected.The supported measurement time units are listed in Table 7.1. If not targeted to specificnodes, the measurement collection is applied to all nodes in a network.

The SetMeasurements message replaces any previous measurement instructions fromthe included network. The networks that are not listed in the message are not affected. Ifthe contents of a Network element are empty, the request essentially drops the receptionof push data from the network in question.

SetMeasurementsRequest versionf networkIds messageIds

Network1..* ids

Measurement0..*

quantitys intervald units

Node0..*

ids

Transducer0..* ids

Figure 48: Set measurements request.

1The selection of thresholds when to poll fresh values and when to return cached values is a net-work/technology specific detail and is left to the discretion of the WSN OpenAPI service implementa-tion.


Table 7.1: Measurument time units.

Unit Description

day Dayshour Hoursmin Minutessec Secondsmsec Milliseconds

7.5.2 SetMeasurementsResponse

A SetMeasurementsResponse message (Fig. 49) is generated as a response to SetMea-surements. The responseCode value is 200 (OK) on success or 501 (Not implemented)if fulfilling the request requires emulation but the WSN OpenAPI service does not sup-port it. If the request fails, the client should expect that earlier measurement instructionswill remain effective.

SetMeasurementsResponse versionf responseCoded messageIds

Figure 49: Set measurements response.

7.6 Examples

Listing 7.1: Request structures from all known networks.<GetStructureRequest xmlns="urn:wsn-openapi:nmf" version="1.2" />

Listing 7.2: Request the structure from a specific network.<GetStructureRequest xmlns="urn:wsn-openapi:nmf" version="1.2"><Network id="0"/>

</GetStructureRequest>

Listing 7.3: Reply to example 7.2.<GetStructureResponse xmlns="urn:wsn-openapi:nmf" version="1.2"><Network id="0"><Node id="0" time="2012-11-30T12:02:01Z"><Transducer id="0" quantity="openapi:temperature"/>

</Node><Node id="1" time="2012-11-30T12:06:01Z"><Transducer id="0" quantity="openapi:temperature"/><Transducer id="1" quantity="openapi:humidity"/>

</Node></Network>

</GetStructureResponse>

Listing 7.4: Request the measurement configuration of a network.<GetMeasurementsRequest xmlns="urn:wsn-openapi:nmf" version="1.3"><Network id="0"/>

</GetMeasurementsRequest>


r1.00-2013

Listing 7.5: Measurement configuration response.<GetMeasurementsResponse xmlns="urn:wsn-openapi:nmf" version="1.3" responseCode="200"><Network id="0"><Measurement quantity="openapi:temperature" interval="1" unit="min"/><Measurement quantity="openapi:acceleration" interval="1" unit="min"><Node id="3"/>

</Measurement></Network>

</GetMeasurementsResponse>

Listing 7.6: Request electric measurements once per 5 minutes.<SetMeasurementsRequest xmlns="urn:wsn-openapi:nmf" version="1.3"><Network id="0"><Measurement quantity="openapi:electric" interval="5" unit="min"/>

</Network></SetMeasurementsRequest>

Listing 7.7: Stop all measurements from a network.<SetMeasurementsRequest xmlns="urn:wsn-openapi:nmf" version="1.3"><Network id="0"/>

</SetMeasurementsRequest>

Listing 7.8: Response to a successfull measurement configuration.<SetMeasurementsResponse xmlns="urn:wsn-openapi:nmf" version="1.3" responseCode="200"/>

7.7 XML Schemas

Listing 7.9: XML schema for GetStructure operation.<xs:schema xmlns="urn:wsn-openapi:nmf" xmlns:xs="http://www.w3.org/2001/XMLSchema"

attributeFormDefault="unqualified" elementFormDefault="qualified" targetNamespace="urn:wsn-openapi:nmf">

<xs:complexType name="TransducerType"><xs:attribute name="id" type="xs:string" use="required" /><xs:attribute name="quantity" type="xs:string" use="required" />

</xs:complexType>


<xs:element name="Transducer" type="TransducerType" /></xs:choice><xs:attribute name="id" type="xs:string" use="required" /><xs:attribute name="time" type="xs:dateTime" use="required" />

</xs:complexType>


<xs:element name="Node" type="NodeType" /></xs:choice><xs:attribute name="id" type="xs:string" use="required" />

</xs:complexType>

<xs:complexType name="NetworkIdType"><xs:attribute name="id" type="xs:string" use="required" />

</xs:complexType>

<xs:complexType name="GetStructureRequestType"><xs:sequence>

<xs:element minOccurs="0" maxOccurs="unbounded" name="Network" type="NetworkIdType" />

</xs:sequence><xs:attribute name="version" type="xs:double" use="required" />


<xs:attribute name="messageId" type="xs:string" use="optional" /></xs:complexType>

<xs:complexType name="GetStructureResponseType"><xs:sequence>

<xs:element minOccurs="0" maxOccurs="*" name="Network" type="NetworkType" /></xs:sequence><xs:attribute name="version" type="xs:double" use="required" /><xs:attribute name="responseCode" type="xs:string" /><xs:attribute name="messageId" type="xs:string" use="optional" />

</xs:complexType>

<xs:element name="GetStructureRequest" type="GetStructureRequestType" /><xs:element name="GetStructureResponse" type="GetStructureResponseType" />

</xs:schema>

Listing 7.10: XML schema for GetMeasurements operation.<xs:schema xmlns="urn:wsn-openapi:nmf" xmlns:xs="http://www.w3.org/2001/XMLSchema"


<xs:complexType name="TransducerType"><xs:attribute name="id" type="xs:string" use="required" />

</xs:complexType>


<xs:element name="Transducer" type="TransducerType" /></xs:choice><xs:attribute name="id" type="xs:string" use="required" />

</xs:complexType>

<xs:complexType name="MeasurementType"><xs:choice minOccurs="0" maxOccurs="unbounded">

<xs:element name="Node" type="NodeType" /></xs:choice><xs:attribute name="quantity" type="xs:string" use="required" /><xs:attribute name="interval" type="xs:integer" use="required" /><xs:attribute name="unit" type="xs:string" use="required" />

</xs:complexType>


<xs:element name="Measurement" type="MeasurementType" /></xs:choice><xs:attribute name="id" type="xs:string" use="required" />

</xs:complexType>

<xs:complexType name="NetworkIdType"><xs:attribute name="id" type="xs:string" use="required" />

</xs:complexType>

<xs:complexType name="GetMeasurementsRequestType"><xs:sequence>

<xs:element minOccurs="0" maxOccurs="unbounded" name="Network" type="NetworkIdType" />


</xs:complexType>

<xs:complexType name="GetMeasurementsResponseType"><xs:sequence>

<xs:element minOccurs="0" maxOccurs="unbounded" name="Network" type="NetworkType" />

</xs:sequence><xs:attribute name="version" type="xs:double" use="required" />


r1.00-2013

<xs:attribute name="responseCode" type="xs:string" use="required" /><xs:attribute name="messageId" type="xs:string" use="optional" />

</xs:complexType>

<xs:element name="GetMeasurementsRequest" type="GetMeasurementsRequestType" /><xs:element name="GetMeasurementsResponse" type="GetMeasurementsResponseType" />

</xs:schema>

Listing 7.11: XML schema for SetMeasurements operation.<xs:schema xmlns="urn:wsn-openapi:nmf" xmlns:xs="http://www.w3.org/2001/XMLSchema"


<xs:complexType name="TransducerType"><xs:attribute name="id" type="xs:string" use="required" />

</xs:complexType>


<xs:element name="Transducer" type="TransducerType" /></xs:choice><xs:attribute name="id" type="xs:string" use="required" />

</xs:complexType>

<xs:complexType name="MeasurementType"><xs:choice minOccurs="0" maxOccurs="unbounded">

<xs:element name="Node" type="NodeType" /></xs:choice><xs:attribute name="quantity" type="xs:string" use="required" /><xs:attribute name="interval" type="xs:integer" use="required" /><xs:attribute name="unit" type="xs:string" use="required" />

</xs:complexType>


<xs:element name="Measurement" type="MeasurementType" /></xs:choice><xs:attribute name="id" type="xs:string" use="required" />

</xs:complexType>

<xs:complexType name="SetMeasurementsRequestType"><xs:sequence>

<xs:element minOccurs="1" maxOccurs="unbounded" name="Network" type="NetworkType" />


</xs:complexType>

<xs:complexType name="SetMeasurementsResponseType"><xs:attribute name="version" type="xs:double" use="required" /><xs:attribute name="responseCode" type="xs:string" use="required" /><xs:attribute name="messageId" type="xs:string" use="optional" />

</xs:complexType>

<xs:element name="SetMeasurementsRequest" type="SetMeasurementsRequestType" /><xs:element name="SetMeasurementsResponse" type="SetMeasurementsResponseType" />

</xs:schema>

7.8 CSV Definitions

Listing 7.12: CSV definition for NMF.NMF-MESSAGE = GET-STRUCTURE-REQUEST / GET-STRUCTURE-RESPONSENMF-MESSAGE =/ GET-MEASUREMENTS-REQUEST / GET-MEASUREMENTS-RESPONSE


NMF-MESSAGE =/ SET-MEASUREMENTS-REQUEST / SET-MEASUREMENTS-RESPONSE

GET-STRUCTURE-REQUEST = "NMF:GET-STRUCTURE-REQ" "," VERSION "," LINES "," MESSAGE-IDEND-OF-LINE *[LF NETWORK-ID] LF

GET-STRUCTURE-RESPONSE = "NMF:GET-STRUCTURE-RSP" "," VERSION "," LINES "," MESSAGE-ID "," RESPONSE-CODE END-OF-LINE *[LF STRUCTURE] LF

GET-MEASUREMENTS-REQUEST = "NMF:GET-MEASUREMENTS-REQ" "," VERSION "," LINES "," MESSAGE-ID "," NETWORK-ID END-OF-LINE LF

GET-MEASUREMENTS-RESPONSE = "NMF:GET-MEASUREMENTS-RSP" ," VERSION "," LINES "," MESSAGE-ID "," RESPONSE-CODE *[LF MEASUREMENTS] END-OF-LINE LF

SET-MEASUREMENTS-REQUEST = "NMF:SET-MEASUREMENTS-REQ" "," VERSION "," LINES "," MESSAGE-ID "," NETWORK-ID *[LF MEASUREMENTS] END-OF-LINE LF

SET-MEASUREMENTS-RESPONSE = "NMF:SET-MEASUREMENTS-RSP" ," VERSION "," LINES "," MESSAGE-ID "," RESPONSE-CODE END-OF-LINE LF

STRUCTURE = NETWORK-ID "," LINES *[LF STRU-NODES]STRU-NODES = NODE-ID "," ABSOLUTE-TIME "," LINES *[LF STRU-TRANSDUCER]STRU-TRANSDUCER = TRANSDUCER-ID "," QUANTITY

MEASUREMENTS = QUANTITY "," INTERVAL "," UNIT "," LINES *[LF MEAS-NODE]MEAS-NODE = NODE-ID "," LINES *[LF MEAS-TRANSDUCER]MEAS-TRANSDUCER = TRANSDUCER-ID

QUANTITY = StringNETWORK-ID = StringNODE-ID = StringTRANSDUCER-ID = String


END-OF-LINE = *("," String)VERSION = DoubleLINES = "" / IntegerMESSAGE-ID = StringRESPONSE-CODE = Integer




XML namespace

• v1.0 to v1.1: XML namespace is urn:ietf:params:xml:ns:nmf

• v1.2: XML namespace is urn:wsn-openapi:nmf

Features

v1.2 Extensively revised to be inline with the other WSN OpenAPI specifications. Ver-sion is not compatible with the older revisions.


Part III

Guidelines and Recommendations

81

8 Predefined Measurement Vocabulary

Recommendation version 1.3

8.1 Overview

This chapter describes the recommended practice for naming transducers and their val-ues in WSN OpenAPI . The naming provides a common vocabulary for describing themeaning of data.

As the number of possible sensors is vast, listing all possible physical and logicalsensors in one document is not possible. Instead, this document aims to list many typicaltransducers and provide instructions on how their data is to be interpreted. The namingis not exhaustive and does not exclude other naming schemes.

The support for the measurement and actuator types listed in this recommendation isoptional. Thus, an implementation may choose to support only some of the listed types.

8.2 Naming Conventions

This recommendation defines the naming of attributes values for measurements. Namescomprise a prefix and a basename as defined in the following:

Listing 8.1: Measurement naming.NAME = [ PREFIX ":" ] BASENAMEPREFIX = StringBASENAME = String

The openapi prefix may be used to indicate that the measurement follows theserecommendations. The openapi prefix should not be used for any other purposes thanthose that are described in this recommendation.

Other naming conventions may be used instead or in parallel with the naming de-fined in this document. The schemes are differentiated with prefixes.

The naming is case-insensitive. That is, openapi:magneticfield and Openapi:MagneticFieldhave the same meaning.

8.3 Measurement and Actuator Quantities

Measurement quantities and their associated properties are listed in Table 8.1. Theseproperties refer to the attributes in the Measurement element of SIDF and SADF mes-sages. Actuator quantities and their associated properties are listed in Table 8.2. These

83

properties refer to the attributes in the Measurement element of NASC, SIDF, and SADFmessages. In either case, the range describes the accepted value range for a measure-ment value with the given unit.

A measurement/actuator command should include all the listed components. Othercomponents may be included as long as their names do not conflict with the namesdefined in this recommendation. To prevent such situation, it is recommended that thecustom components have a prefix other than "openapi". An empty prefix is acceptable.

A measurement should be described with one of the defined units. In cases only oneunit is defined, the unit attribute can be omitted from the measurement and the receivershould assume that the unit is the one listed in this specification.

8.4 Measurement Quantities

8.4.1 openapi:acceleration

Measures the acceleration applied to the sensor. All values are in SI units (m/s2). x, y,and z components describe the acceleration in the three orthogonal axis in 3 dimensionalspace, while the total component is the vector sum of the x,y,z acceleration components.

A measurement must include x, y, and z components. The inclusion of total compo-nent is optional.

The acceleration values include the effect of gravitational field at the Earth’s surface.Thus, a sensor at the rest state should have the total component of +9.81m/s2, and asensor at freefall has the total acceleration of 0m/s2.

8.4.2 openapi:airpressure

Atmospheric pressure in hPa (equal to millibar).

8.4.3 openapi:airvelocity

Air velocity in m/s and direction as degrees. A measurement must include airvelocitycomponent. In airdirection, 0 equals North, 90 equals East, 180 equals South, and 270equals West.

8.4.4 openapi:batteryvoltage

The electric voltage of sensor device’s internal power source in volts (V ).Note: use openapi:batteryvoltage to indicate the voltage of sensor device’s internal

energy source, and openapi:voltage to indicate other voltage measurements.

8.4.5 openapi:carbonmonoxide

Carbon monoxide concentration in parts per million (ppm).

8.4.6 openapi:carbondioxide

Carbon dioxide concentration in parts per million (ppm).


r1.00-2013

Table 8.1: Predefined measurement types

Quantity Component Unit Range

acceleration x m/s2 (any)y m/s2 (any)z m/s2 (any)total m/s2 (any)

airpressure value mbar (any)airvelocity velocity m/s (any)

direction deg 0 to 360batteryvoltage value V (any)carbonmonoxide value ppm ≥0carbondioxide value ppm ≥0compass value deg ≥0 to 360current value A (any)electricConsumption value kWh (any)electricPower value W (any)geolocation latitude deg WGS 84 latitude

longitude deg WGS 84 longitudealtitude m (any)

hail intensity hits/cm2/h positivecumulative hits/cm2 (any)

humidity value % 0 to 100humidityAir value % 0 to 100humidityAmbient value % 0 to 100humidityGround value % 0 to 100illuminance value lux ≥0image value jpeg Base64 encoded binary

png Base64 encoded binarymagneticfield x uT (any)

y uT (any)z uT (any)

orientation azimuth deg 0 to 360pitch deg -180 to 180roll deg -90 to 90

pressure value hPa (any)rain intensity mm/cm2/h positive

cumulative mm/cm2 positivetemperature value C (any)temperatureAir value C (any)temperatureAmbient value C (any)temperatureSurface value C (any)temperatureGround value C (any)voltage value V (any)video value avi Base64 encoded binary

mpeg Base64 encoded binary


Table 8.2: Predefined actuator types

Quantity Component Unit Range

binarySwitch value - ON or OFFlightSwitch value - ON or OFFlinearSwitch value % 0 to 100powerSwitch value - ON or OFF

8.4.7 openapi:compass

Sensors direction relative to the magnetic north pole in degrees. 0 equals North, 90equals East, 180 equals South, and 270 equals West.

8.4.8 openapi:current

Electric current in amperes (A).

8.4.9 openapi:electricConsumption

Cumulative electric consumption in kWh. The receiver should assume overflow orvalue reset when a cumulative value that is smaller than the previous received value.

8.4.10 openapi:electricPower

Transient electric power in watts (W ).

8.4.11 openapi:geolocation

Geographic location in WGS 84 coordinates. A measurement must include latitude andlongitude components. Altitude is expressed as meters and is OPTIONAL.

Example: latitude -61.450081266, longitude 23.854321640 denotes a location in theEastern and Northern Hemisphere.

8.4.12 openapi:hail

Hail intensity as hits per square centimeter per hour (hits/cm2/h) and the cumulativevalue as hits/cm2/. Note that this recommendation does not define how the cumulativevalue is cleared. The receiver should assume overflow or value reset when a cumulativevalue that is smaller than the previous received value.

8.4.13 openapi:humidity

Relative air humidity in percents. The humidityAir (outdoor), humidityAmbient (in-doors) and humidityGround (soil) quantities are specified as special cases to give thegeneric idea of the measurement target.


r1.00-2013

8.4.14 openapi:illuminance

Ambient light level in SI lux units.

8.4.15 openapi:image

Base64 encoded bitmap image in png (Portable Network Graphics) [Bou97] or jpegformats. The format is defined in the unit attribute of a measurement.

8.4.16 openapi:magneticfield

Magnetic field in the x, y and z axis. Values are in micro-Tesla (uT ).

8.4.17 openapi:orientation

Sensor’s orientation in degrees.Azimuth component describes the angle between the magnetic north direction and

the y-axis, around the z-axis (0?azimuth<360). 0 equals North, 90 equals East, 180equals South, and 270 equals West. Pitch component describes rotation around x-axis(-180 to 180), with positive values when the z-axis moves toward the y-axis. Roll com-ponent describes the rotation around y-axis (-90 to 90), with positive values when thex-axis moves toward the z-axis.

8.4.18 openapi:pressure

Generic pressure in hPa (equal to millibar).

8.4.19 openapi:rain

Rain intensity as millimeters per square centimeter in an hour (mm/cm2/h) and thecumulative value as mm/cm2/. Note that this recommendation does not define how thecumulative value is cleared. The receiver should assume overflow or value reset when acumulative value that is smaller than the previous received value.

8.4.20 openapi:temperature

Temperature reading in Celsius. The temperatureAir (outdoors), temperatureAmbient(indoors), temperatureGround (soil), and temperatureSurface (specific target) quantitiesare specified as special cases to give the generic idea of the measurement target.

8.4.21 openapi:voltage

Electric voltage in volts (V).Note: use openapi:batteryvoltage to indicate the voltage of sensor device’s internal

energy source, and openapi:voltage to indicate other voltage measurements.


8.4.22 openapi:video

Base64 encoded video clip in avi or mpeg formats. The format is defined in the unitattribute of a measurement.

8.5 Actuator Quantities

8.5.1 openapi:binarySwitch

Generic on/off type switch.

8.5.2 openapi:lightSwitch

On/off type switch that controls lighting.

8.5.3 openapi:linearSwitch

A generic linear switch that may have values between 0 and 100.

8.5.4 openapi:powerSwitch

On/off type switch that switches electric current on/off from the target device.

8.6 Encoding

This section specifies how measurement values are encoded.

8.6.1 Numerical values

All numerical values SHALL be formatted as described in Figure 2. White spaces arenot allowed within the number. Any whitespaces in the beginning or at the end of thestring literal SHALL be ignored.

Numerical values in ABNF [CO08].

Listing 8.2: Numerical values.VALUE = 1*DIGIT ["." 1*DIGIT]

8.6.2 Binary data

Binary data shall be encoded in Base64 format as defined in RFC4648 [Jos06]. Linefeeds must not be added to the base-encoded data. The use of padding ("=") in base-encoded data is optional.

8.7 Examples

Optional components can be omitted from the measurements. Listing 8.3 presents anexample of a temperature measurement whose value is interpreted as 23.1 C.


r1.00-2013

Listing 8.3: Measurement without the optional unit or name attributes.<Measurement quantity="openapi:temperature" time="2011-12-13T01:23:45+00:00">

<Component>23.1</Component></Measurement>

Measurements can include custom components (Listing 8.4). To ensure that theirnames do not collide with the WSN OpenAPI specification, the use of ":" (or any otherthan "openapi:") prefix is recommended. Note that in the example, naming the firstcomponent as "value" is not necessary as that is the attribute’s default value.

Listing 8.4: WSN OpenAPI recommended measurement type with a custom component.<Measurement quantity="openapi:temperature" time="2011-12-13T01:23:45+00:00">

<Component name="value">23.1</Component><Component name=":user-input">Too hot</Component>

</Measurement>

The use of units that differ from the specification necessitate either adding a customcomponent or defining a custom measurement (Listing 8.5).

Listing 8.5: Custom measurement.<Measurement quantity="openapi:temperature" time="2011-12-13T05:43:21+00:00" >

<Component unit="C">-198.15</Component><Component name=":value" unit="K">75</Component>

</Measurement><Measurement quantity="custom:temperature" time="2011-12-13T05:43:21+00:00" >

<Component unit="K">75</Component></Measurement>



9 Transducer Datasheet

A WSN OpenAPI sensor datasheet describes device specific properties, placement of asensor device, and transducers that a device contains. Most of the contents are optionaland additional datasheet entries may be defined. The datasheet is designed to be used inconjunction with MEDF interface.

Recommendation version 1.0

9.1 Device information

Device information describes the generic properties and description of a device, modeland type information, and a mapping from a manufacturer given physical serial numberto a logical device identifier.

Table 9.1: Device information.

Type Description

Name User friendly call nameDescription Device specific detailsDeviceId Unique identifier for the deviceSerial Unique identifier given by the manufacturerManufacturer Manufacturer of the deviceModel Manufacturer’s model for the device

9.2 Placement

The placement section describes the device’s installation location. It may be describedwith a free-form textual description, street address, geographical coordinate, locationwithin a building, or with any combination of these. In addition, the placement infor-mation may contain images, e.g., photos taken from the deployment location.

91

Table 9.2: Placement information.

Type Description

Name User friendly name for the placementDescription More detailed description of the placeImages One or more images from the installation siteLocation Geographical coordinatesBuilding Building name, floor, corridor, room, and shelfAddress Street address, city, state, postal code, and country

9.3 Sensors

The generic sensor information is presented in Table 9.3. A sensor has an identifier(id) that points to the similar id field in the SIDF and SADF messages. Other pieces ofinformation are optional and describe generic sensor details and its manufacturer.

Table 9.3: Sensor information.

Type Description

Id Sensor identifier (required)Name User friendly name for the sensorDescription More detailed description of the sensorManufacturer ManufacturerModel Manufacturer’s model

A sensor contains one or more components, that link to the SIDF/SADF measure-ment components via identifiers. Sensor type defines how the readings should be in-terpreted. Possible values for the type are instant, minimum, maximum, average, andcumulative. Instant means that the sensor returns an absolute value of the sensed phe-nomenon (e.g., Watts), whereas the cumulative type means that the measurement resultsalways increase (e.g., kWh).

Table 9.4: Component information per sensor.

Type Description

Id Component identifier (required)Quantity Measurement quantityUnit Measurement unitType Sensor typeResolution Granularity of measurementsAccuracy Accuracy within the measurement rangeMinValue Minimum of measurement rangeMaxValue Maximum of measurement range


r1.00-2013

9.4 Actuators

The generic actuator information is similar to the sensor information and is presented inTable 9.3. The unique identifier (id) that points to the similar id field in the SIDF andSADF messages. An actuator and a sensor within a node may not share an identifier.

An actuator contains one or more components, that link to the SIDF and SADFmeasurement components and NASC command components via identifiers.

Table 9.5: Component information per actuator.

Type Description

Id Component identifier (required)Quantity Measurement quantityType Actuator type (binary, linear, multilevel)Levels Comma separated list of possible levels (multilevel actuator only)MinValue Minimum of actuation range (linear actuator only)MaxValue Maximum of actuation range (linear actuator only)Step Possible step size, starting from minValue (linear actuator only)

9.5 Specifications

The WSN OpenAPI sensor datasheet is defined in the following examples.

Listing 9.1: XML specification of sensor datasheet<Datasheet><Device><Name>Office_3B101</Name><Description>Office air quality</Description><DeviceId>1011</DeviceId><Manufacturer>Company X</Manufacturer><Model>A123</Model><Serial>152-801-1912A</Serial>

</Device>

<Placement><Description>Installed behind air duct</Description>

<Location><Latitude unit="WGS84">61.44995</Latitude><Longitude unit="WGS84">23.85503</Longitude><Altitude unit="m">250</Altitude>

</Location>

<Building><Name>Main building</Name><Floor>3</Floor><Corridor>B</Corridor><Room>101</Room><Shelf></Shelf>

</Building>

<Address><Street>N/A</Street><City>N/A</City><State>N/A</State><PostalCode>N/A</PostalCode><Country>N/A</Country>


</Address></Placement>

<Sensor id="0"><Name>Thermometer</Name><Description>On-board ambient temperature sensor</Description><Model>X</Model><Component id="value" quantity="openapi:temperature" unit="C" type="instant" ><MinValue>-55</MinValue><MaxValue>125</MaxValue><Accuracy>0.5</Accuracy><Resolution>0.25</Resolution>


<Sensor id="1"><Name>Carbondioxide</Name><Description>External carbon dioxide sensor</Description><Model>Y</Model><Component id="value" quantity="openapi:carbondioxide" unit="ppm" type="instant" ><MinValue>400</MinValue><MaxValue>4000</MaxValue><Accuracy unit="%">20</Accuracy><Resolution>1</Resolution>


<Actuator id="2" quantity="power" type="binary"><Name>Light switch</Name><Component id="value" quantity="binarySwitch" type="binary" />

</Actuator>

<Actuator id="3" quantity="power" type="binary"><Name>Fan speed</Name><Component id="value" quantity="power" type="multilevel"><Level>0</Level><Level>1</Level><Level>2</Level><Level>3</Level>

</Component></Actuator>

</Datasheet>


Bibliography

[BM04] Paul V. Biron and Ashok Malhotra. XML Schema Part 2: Datatypes Sec-ond Edition. W3C, w3c recommendation 28 october 2004 edition, Octo-ber 2004.

[Bou97] T. Boutell. PNG (Portable Network Graphics) Specification Version 1.0.IETF, RFC 2083 edition, March 1997.

[BR07] M. Botts and A. Robin. OpenGIS Sensor Model Language (SensorML)Implementation Specification. Open Geospatial Consortium, Inc., 07-000edition, 2007.

[CO08] D. Crocker and P. Overell. Augmented BNF for Syntax Specifications:ABNF. IETF, STD 68, RFC 5234 edition, January 2008.

[FHBH+99] J. Franks, P. Hallam-Baker, J. Hostetler, S. Lawrence, P. Leach, A. Lu-otonen, and L. Stewart. HTTP Authentication: Basic and Digest AccessAuthentication. IETF, RFC 2617 edition, June 1999.

[Jos06] S. Josefsson. The Base16, Base32, and Base64 Data Encodings. IETF,RFC 4648 edition, October 2006.

95

Documents

WSN OpenAPI Specification - TUT · WSN Wireless Sensor Network 7. iPreface This document describes the WSN OpenAPI specification, which defines a unified ser-vice interface for