C. Chauvenet The IPSO Application Framework

IPSO Alliance

Interop Committee

Z. Shelby

Sensinode

C. Chauvenet

Watteco

August 24, 2012

The IPSO Application Framework

draft-ipso-app-framework-04

Abstract

This document defines a RESTful design for use in IP smart object

systems such as Home Automation, Building Automation and other M2M

applications. This design defines sets of REST interfaces that may

be used by a smart object to represent its available resources,

interact with other smart objects and backend services. This

framework is designed to be complementary to existing Web profiles

including SEP2 and oBIX. The document is not and may never be a

standard of any kind. It should be considered only as work in

progress.

Copyright Notice

Copyright (c) 2012 IPSO Alliance and the persons identified as the

document authors. All rights reserved.

[Page 1]

IPSO Draft

The IPSO Application Framework

August 2012

Table of Contents

1.

Overview . . . . . . . . . . .

1.1. Function Sets . . . . . .

1.1.1. Path Template . . . .

1.1.2. Resource Type . . . .

1.1.3. Interface Description

1.1.4. Data Type . . . . . .

1.2. Interaction Model . . . .

1.3. Discovery . . . . . . . .

2. Function Sets . . . . . . . .

2.1. Device . . . . . . . . . .

2.2. General Purpose IO . . . .

2.3. Power . . . . . . . . . .

2.4. Load Control . . . . . . .

2.5. Sensors . . . . . . . . .

2.6. Light Control . . . . . .

2.7. Message . . . . . . . . .

2.8. Location . . . . . . . . .

2.9. Configuration . . . . . .

3. Data Formats . . . . . . . . .

3.1. text/plain . . . . . . . .

3.2. SenML . . . . . . . . . .

4. Examples . . . . . . . . . . .

5. Security Considerations . . .

6. Acknowledgments . . . . . . .

7. Changelog . . . . . . . . . .

8. References . . . . . . . . . .

8.1. Normative References . . .

8.2. Informative References . .

Authors' Addresses . . . . . . . .

[Page 2]

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

3

3

4

4

4

4

4

5

5

5

7

8

9

10

11

11

12

13

14

14

14

15

17

17

17

18

18

18

18

IPSO Draft

1.

The IPSO Application Framework

August 2012

Overview

The IPSO Application Framework makes use of IETF standards as building

blocks for a simple and efficient RESTful design model for IP smart

objects. The framework may be used over either HTTP [RFC2616] or CoAP

[I-D.ietf-core-coap] web transfer protocols. This section describes

the overall design principles of the framework.

HTTP, REST, XML, JSON, COAP and other key components of web

technology are powerful mechanisms in an Internet of Things

application. However, they leave a lot of room for the application

implementers to choose particular ways to represent data and

operations on it.

This document specifies a particular template for using these

mechanisms to represent certain classes of typical Internet of Things

applications. The document is not and may never be a standard of any

kind. It should be considered only as work in progress. The

communication patterns described herein do not represent the only way

to implement applications. Indeed, we expect applications to be

developed with the full richness of the web communications model,

including many standardized application models.

However, we have found these simple patterns helpful in a number of

cases and they may make it easier to develop basic applications

without having to re-create the communications patterns and data

formats every time. The IPSO interoperability committee sees this

document as helpful in testing practical interoperability among a

number of specific devices, for instance.

1.1.

Function Sets

The framework is organized into groups of resource types called

Function Sets. A Function Set has a recommended root path, under

which its sub-resources are organized. Each Function Set is assigned

a Resource Type parameter, therefore making it possible to discover

it. A Function Set SHOULD be located at its recommended root path on

a web server, however it MAY be located under an alternative path if

necessary (for example multi-purpose devices, gateways etc.).

In a Function Set, types of resources are defined. Each type

includes a human readable name, a path template, a Resource Type for

discovery, the Interface Definition and the data type and allowed

values.

[Page 3]

IPSO Draft

1.1.1.

The IPSO Application Framework

August 2012

Path Template

The path template includes a possible index {#} parameter, and

possible fixed path segments. The index {#} allows for multiple

instances of this type of resource, and can be any string. The root

resource of a function set (e.g. for /sen/{#} the root is /sen) may

optionally support the CoRE Batch (core#b) interface definition

[I-D.shelby-core-interfaces]. If supported, this allows a single

request on the parent to manipulate the values of the sub-resources

at once (e.g. a GET on /sen would return a SenML payload with the

values of all the sub-resources of /sen).

1.1.2.

Resource Type

The Resource Type parameter defines the value that MUST be included

in the rt= field of the CoRE Link Format when describing a link to

this resource. This value enables resources to be discovered.

Values in this field are in the form "namespace:type", where

namespace references the specification where the type is defined.

Currently supported namespaces are "ipso." refering to resource types

defined in this specification, and "ucum:" used for generic sensor

units from the Unified Code for Units of Measure (UCUM) specification

[]. It is expected that other namespaces will be

defined in the future.

1.1.3.

Interface Description

The Interface Description parameter defines the REST interface for

that type of resource. This specification makes use of the basic

CoRE resource types defined in [I-D.shelby-core-interfaces]. The

Interface Description MAY be elided from link descriptions of

resource types defined in the framework, but SHOULD be included for

custom extensions to the framework.

1.1.4.

Data Type

The Data Type field defines the type of value (and possible range)

that is returned in response to a GET for that resource or accepted

with a PUT. The actual format of this data is returned in either

text/plain (MUST be supported) or application/senml+json (optional)

formats as defined in Section 3.

1.2.

Interaction Model

This framework is designed for a simple client-server interaction

model on atomic resources, in order to minimize complexity. An IP

smart object runs a simple web server (HTTP or CoAP) and exposes

resources that conform to this framework. Other IP smart objects or

[Page 4]

IPSO Draft

The IPSO Application Framework

August 2012

backend services that want to interact with that IP smart object, act

as a client and make requests to interact with those resources. When

using HTTP, polling is used to request values. When using CoAP both

polling and the use of Observation is supported including the query

string parameters defined in [I-D.shelby-core-interfaces]. The use

of Observation is highly recommended when there is a need for

continuous readings from a resource.

1.3.

Discovery

The resource semantics defined in this framework are compatible with

Web Linking [RFC5988] and the CoRE Link Format

[I-D.ietf-core-link-format]. A device using to this framework SHOULD

make those resources discoverable by providing links to the resources

on the path /.well-known/core as defined in

[I-D.ietf-core-link-format].

In addition, a device using this framework MAY in addition register

its resources to a Resource Directory using the registration

interface provided by a Resource Directory is defined in

[I-D.shelby-core-resource-directory] if such a directory is

available.

2.

Function Sets

+--------------------+-----------+--------------+

| Function Set

| Root Path | Resouce Type |

+--------------------+-----------+--------------+

| Device

| /dev

| ipso.dev

|

| General Purpose IO | /gpio

| ipso.gpio

|

| Power

| /pwr

| ipso.pwr

|

| Load Control

| /load

| ipso.load

|

| Sensors

| /sen

| ipso.sen

|

| Light Control

| /lt

| ipso.lt

|

| Message

| /msg

| ipso.msg

|

| Location

| /loc

| ipso.loc

|

| Configuration

| /cfg

| ipso.cfg

|

+--------------------+-----------+--------------+

2.1.

Device

This function set is used to represent information about the IP smart

object device itself, including but not limited to its manufacturer,

serial number and name. This function set MAY be extended with

custom resource types.

[Page 5]

 ................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download