ONG tutorial - Cocoon

Transcription

Cocoon® Project
User Guide:
ONG tutorial
Date: 28/11/2011
Revision: ong-tutorial-rev6.docx
Open Source M2M development tools for the ETSI TC M2M architecture
This document contains proprietary material of Actility SA and/or its affiliates and subsidiaries (together: "Actility"). Any
unauthorized reproduction, use, of this material, or any part thereof, is strictly prohibited.
Cocoon® project
Open Source ETSI TC M2M development tools
1
CHANGE HISTORY
Date
Rev
Who
Comment
2011-06-27
1
ML
Initial revision
2011-07-06
2
OH
Review
2011-07-15
3
ML
New ONG browser screen shots
Ref
Schemas review
Feedbacks integration
2011-07-17
4
OH
Review 2
2011-08-04
5
ML
Changed document template and cover page
renamed ZigBee driver parameter restoreHanAtReboot to resetHanAtReboot
Hello-world example rework
2011-11-28
2
6
ML
Updated links to “Cocoon” web site.
ABSTRACT
7
This document aims at introducing Actility Object Network Gateway ( ONG) reference implementation of the ETSI
TC M2M gateway framework, focusing on its purpose, architecture and interfaces. The ONG , a component of the
Actility ThingPark® solution, acts as a gateway between one or more fieldbus or automation networks (such as
Home Area Networks), and an operator hosted M2M infrastructure. The ONG, like the rest of the ThingPark®
solution, is based on ETSI TC M2M reference model and protocols.
8
This document targets two different categories of readers:
3
4
5
6
9

Engineers who want to learn more about the ONG architecture and capabilities
10

Developers who plan to build ETSI M2M Gateway Applications ( GA) running on the ONG, or ETSI M2M
Network Applications (NA) interacting with the ONG via the ETSI M2M core network.
11
12
13
Accordingly, this document is split into two main sections:

The first section describes the ONG functional scope, what parts of the ETSI TC M2M architecture it
implements and how it interacts with its environment.

The second section is a programmer’s guide which describes the ONG APIs and protocols, as well as the
implementation and capabilities of the ONG ETSI M2M Gateway Service Capabilities ( GSC). In this
preview release of the ONG, an ETSI TC M2M driver for ZigBee 1.0 is provided for the Texas Instruments
CC2531 (http://focus.ti.com/docs/toolsw/folders/print/cc2531emk.html), enabling
developers to
implement any GA or NA interacting with ZigBee networks.
14
15
16
17
18
19
20
21
REFERENCE
[M2M-FunctionalArchitecture]
Machine- to- Machine communications (M2M); Functional architecture (release 1)
[ONG-Install]
Actility ONG installer guide
ETSI, TS 102.690 (2011-04) M2M(11)0205r1
Actility, userGuide-ONG-install-rev2
[ZCL-specification]
ZigBee Cluster Library specification
ZigBee Alliance, 075123r02ZB
[HA-specification]
© Actility - ONG tutorial
ZigBee Home Automation Public; Application Profile
2/51
Cocoon® project
ZigBee Alliance, 053520r26
[ONG-Browser]
Actility ONG Browser user guide
Actility, User-Guide-ONG-Browser
[OSGi-compendium]
OSGi Service Platform - Service Compendium
The OSGi Alliance, Release 4, Version 4.2
[SCL-M2M-REST]
Actility SCL M2M REST Interface
Actility, User-Guide-SCL-M2M-REST-API
[ZigBee-M2M-REST]
Actility ZigBee M2M REST Interface
Actility, User-Guide-ZigBee-M2M-REST-API
[SONG-API-Javadoc]
Actility SONG Javadoc
http://cocoon.actility.com/javadocs/song-service-api/1.4.0/index.html
[RSS-API-Javadoc]
Actility Resource Storage System
http://cocoon.actility.com/javadocs/rssApi/1.2.0/index.html
22
3/51
Cocoon® project
23
TABLE OF CONTENTS
24
1.
ABBREVIATIONS .................................................................................................................................5
25
2.
DEFINITIONS AND CONVENTIONS ....................................................................................................6
2.1
2.2
26
27
28
1.
30
31
32
33
2.
35
36
37
38
3.
Functional architecture ································································································ 8
Physical architecture ··································································································· 8
ETSI TC M2M GATEWAY IMPLEMENTATION ······································································ 9
Overview of ZigBee/M2M interworking ············································································ 13
ONG PROGRAMMING GUIDE ........................................................................................................... 17
2.1
2.2
2.3
2.4
2.5
34
39
ETSI M2M ARCHITECTURE SUPPORT .................................................................................................8
1.1
1.2
1.3
1.4
29
Resource modeling ····································································································· 6
Applications·············································································································· 6
ONG Gateway Service Capabilities (GSC) ·········································································· 17
Accessing ONG resources ···························································································· 18
Interworking with ZigBee HANs ····················································································· 24
Implementing your own Gateway Application ThingLet ························································· 34
Accessing the ONG via an ETSI M2M core network ····························································· 50
TABLE OF FIGURES .......................................................................................................................... 51
40
41
4/51
Cocoon® project
42
1. ABBREVIATIONS
43
COV
Change of Value
DA
Device Application (ETSI TC M2M abbreviation)
DSC
Device Service Capability (ETSI TC M2M abbreviation)
GA
Gateway Application (ETSI TC M2M abbreviation)
GIP
Gateway Interworking Proxy (ETSI TC M2M abbreviation)
GSC
Gateway Service Capability (ETSI TC M2M abbreviation)
M2M
Machine to machine communication.
NA
Network Application (ETSI TC M2M abbreviation)
NSC
Network Service Capability (ETSI TC M2M abbreviation)
ONG
Object Network Gateway
xA
Device (DA), Gateway (GA) or Network Application (NA)
xSC
Device (DSC), Gateway (GSC) or Network Service Capability (NSC)
44
45
5/51
Cocoon® project
46
2. DEFINITIONS AND CONVENTIONS
47
2.1 RESOURCE MODELING
Resource
A resource (/r) is a collection of 0…m attributes, o…m operations and 0…p sub-resources.
Attributes are represented "by-value", operations and sub-resources are represented "byreference".
A resource can be created / deleted.
A resource must be addressable (i.e. associated with an URI).
Attribute
An attribute models an information element associated to a resource. An attribute can be
associated to a simple type (e.g. an integer) or can be associated to a complex type (e.g. a
list, a structure).
An attribute is represented "by-value".
An attribute may be addressable, typically to provide a direct access. Even when the
attribute is addressable, the attribute remains a part of the resource, and therefore cannot
be created / deleted.
Operation
An operation models an action that can be performed on a resource. For instance a
resource, modeling a light, could have an operation to toggle the light state (toggle/).
An operation is represented "by-reference".
An operation must be addressable. However the operation remains a part of the resource,
and therefore cannot be created / deleted.
Sub-resource
48
49
50
51
In this preview release, we use OASIS oBix (http://www.oasis-open.org/committees/obix/) syntactic conventions
for the XML representation of resources. The following is an example of a resource representation:
<obj name="resource1" href="/r1/">
<int name="attribute1" value="1" href="attribute1/"/>
<str name="attribute2" value="a string" href="attribute2/"/>
<ref name="resource2" href="r2/ href="resource2/"/>
52
53
54
55
A sub-resource is a "child" resource represented "by-reference".
<op name="operation1" href="operation1/"/>
</obj>
56

/r1 is a resource.
57

/r1/attribute1 and /r1/attribute2 are attributes of /r1.
58

/r1/operation1 is an operation of /r1.
59

/r1/resource2 is a sub-resource of /r1.
60
2.2 APPLICATIONS
M2M application
An application, according to ETSI TC M2M conventions, that runs the service logic and uses
M2M Service Capabilities (DSC, GSC or NSC) accessible via an open interface. Three kinds of
M2M applications are defined: Device application (DA), Gateway application (GA) and
Network application (NA).
ThingLet®
Actility implementation of ETSI TC M2M Applications. “ThingLets” are Java applications
which implement the SONG interface (an open API providing access to the ETSI TC M2M
service capabilities) and are hosted by an ONG (Device or Gateway Applications), or by a
network based Application Server (Network Applications).
Actility uses ETSI M2M DA Thinglets to implement object network protocol drivers (e.g. the
ZigBee driver), GA and NA ThingLets are used by developers to implement multi-agent M2M
applications.
HAN application
Application hosted on a HAN device (e.g. for instance ZigBee application hosted on an end
device).
6/51
Cocoon® project
61
62
Figure 1 summarizes the various types of application implementations and their representation according to ETSI
M2M in the ThingPark® framework.
Native M2M device
(implementation)
Native application
ONG
(implementation)
HAN device
(implementation)
M2M application
(representation)
1
1
HAN application
1
1
n
n
1
AS
(implementation)
DA
(DSC or GSC)
DA
(GSC)
1
HAN driver (GIP)
(M2M application)
Hosted thinglet
(M2M application)
1
1
GA
(GSC)
NA
(Network)
1
1
Centralized thinglet
(M2M application)
Figure 1: M2M applications and their representation
63
7/51
Cocoon® project
64
3. ETSI M2M ARCHITECTURE SUPPORT
65
3.1 FUNCTIONAL ARCHITECTURE
66
67
68
69
ThingPark® supports all types of applications defined by ETSI M2M: Network applications (NA), gateway
application (GA) and device applications (DA). The ONG supports both native M2M devices (a device with a native
ETSI M2M capability) and legacy devices (for instance a ZigBee device, without native ETSI M2M capability), via
interworking profiles.
DA (M2M)
GA
DA (Legacy)
dIa
NA
dIa
GSC
mIa
mId
NSC
GIP
Figure 2: ETSI TC M2M functional architecture
70
ThingPark® handles the following communication interfaces:
71

Communication between DA (M2M) and gateway SCL (GSC) : dIa interface
72

Communication between GSC and network SCL (NSC) : mId interface
73

Communication between GA and GSC : dIa interface
74

Communication between NA and NSC : mIa interface
75
76
77
78
79
80
81
82
83
84
The interface between a legacy (non ETSI M2M) DA and a GSC is performed by a gateway interworking proxy
(GIP), a function of the GSC. Currently, this generic function of the GSC is not specified by ETSI M2M, however the
functionality provided by the standard ETSI GA is sufficient for this purpose, and in this preview version of
ThingPark® the GIP is implemented as a GA with specific semantic conventions.
In the current preview release a GIP has been fully specified and implemented for ZigBee 1. More GIPs will be
introduced later, e.g. a wireless mBUS GIP is planned for Q4 2011.
3.2 PHYSICAL ARCHITECTURE
Legacy DAs are hosted by the legacy devices. A legacy device can host several applications. For instance a ZigBee
device can host several on/off switches, where each on/switch (HA, ZigBee device ID 0x000) is a distinct
application.
86
M2M DAs are typically hosted by devices with a native IP capability (for instance 6LoWPAN devices). A device can
host several M2M DAs.
87
The GA, GSC and GIP functions run on an object network gateway (ONG).
85
88
89
The NA and NSC functions run on an application server (AS). ThingPark® supports both HTTP and SIP application
servers.
8/51
Cocoon® project
Legacy
device
M2M
device
e.g. ZigBee
HTTP AS
SIP AS
CoAP or HTTP
HTTP
SIP
Private
Home area network (HAN)
ONG
Public
access network
Public
infrastructure IP network
Figure 3: ThingPark® physical architecture
90
In this physical architecture:
91

dIa (between M2M DA and GSC) is implemented over CoAP or HTTP (typically over a wireless IP network),
92

dIa (between GA and GSC) is a software interface internal to the ONG,
93

mIa (between NA and NSC) is a software interface internal to the application server.
94

mId (between GSC and NSC) is implemented over HTTP or SIP.
95
96
97
98
99
100
101
102
103
104
The devices and the ONG are typically interconnected by a private home area network (HAN), for instance a
ZigBee 1 network or a 6LoWPAN network.
The interconnection between ONGs and ASs is realized by an infrastructure network hosted by Actility. Multiple
access networks can be used, e.g. DSL, cable, or GPRS access network.
3.3 ETSI TC M2M GATEWAY IMPLEMENTATION
The current implementation of the ONG is aligned with the last draft of ETSI TC M2M functional gateway
architecture described in [M2M-Functional-Architecture]. The SCL core implements the SCL functionality as well as
support for gateway applications (GA). The implementation of each fieldbus/automation technology is specified in
an object network interworking profile (GIP). The transport of ETSI M2M mId messages within specific protocols is
specified in protocol bindings.
9/51
Cocoon® project
ETSI M2M GIP profile
ZigBee
Z-wave
SEP2.0
ONG Core
Binding
Other profile
SIP
HTTP
CoAP
Other
bindling
Figure 4: ONG : object network profiles and protocol bindings
105
106
107
108
3.3.1 SCL FUNCTIONS IMPLEMENTED BY THE ONG CORE
A Service Capability layer (SCL) is a REST resource which is available on the ONG (in this case it is named GSC)
and on the network (NSC). A SCL resource implements the following functions:

109
Registrar: This function handles the registration of M2M entities. These registered resources can be local
resources or remote resources.
Typically for a GSC, a local resource is a DA or a GA and a remote resource is a NSC or a NA. Typically for
a NSC, a local resource is a NA and a remote resource is a GSC.
110
111
112
113

114
115
Router: This function routes SONG requests between M2M entities. A GSC router handles routing between
DA, GA and remote SCL (typically a NSC). A NSC router handles routing between NA and remote SCL
(typically a GSC).
The router works in conjunction with ACL engine (for access right control), group engine (for multicasting)
and mirroring engine (for mirroring).
116
117
118
119

ACL engine: This function manages the permissions to access a resource according to access rights
associated to the resources. This function is not implemented in the current preview release.

Mirroring engine: This function provides a mirroring facility both for local resources and remote
resources. This enables the SCL to answer a request received over dIa or mId without querying the actual
resource, and facilitates interworking with sleeping nodes.
120
121
122
123
124
For instance, using mirrored resources published by a DA at registration stage, the GSC will be able to
process dIa or mId requests targeting the those resources on behalf of the DA.
125
126
127
128

Subscription engine: The function manages the sessions associated to subscriptions. A subscription
session is established by an issuer to receive COVs notifications associated to a resource.

Caching engine: This function is for future study (FFS).
129
130
131
10/51
Cocoon® project
132
133

Group engine: This function is for future study (FFS).

Monitoring engine: This function is for future study (FFS).

Entity management engine: This function is for future study (FFS).
134
135
136
137
138
139
3.3.2 SUPPORTED FEATURES (ONG PREVIEW RELEASE)

ETSI M2M Functions and resources:
140

GA
141

GSC
142

GIP implemented as a GA
As stage 3 ETSI specifications are not yet published and therefore the final syntax choices are not yet
finalized, this preview release uses OASIS oBIX syntax conventions, both for ETSI M2M resources and for
container content. As of June 2011, it seemed that ETSI M2M stage 3 documents will use plain XML XSD
143
144
145
for ETSI M2M resources. The final ThingPark® ONG release will align to the published specification.
Container resource content syntax is out of scope of ETSI, and will be defined for each application or
protocol interworking profile.
146
147
148
149

GSC features
150

Mirroring
151

Retargeting
152

Reporting
153

Logging
154

Subscription
155

ZigBee GIP profile features:
156

Network discovery and mirroring
157

ZDO commands
158

ZCL commands
159

ZCL reporting

Mgmt command
160
161

Bindings :
162

binding interface: HTTP REST
163

long polling connection (bidirectional, NAT traversal)
164
3.3.3 FEATURE ROADMAP FOR ONG V1.0
165

ZigBee security support (HA profile)
166

GSC rights management
167

alarming
168

Wireless mBUS profile
169

Implementation of the ETSI M2M XSD schema as per published ETSI M2M documents
170
171
172
173
174
3.3.4 ONG INTERNAL ARCHITECTURE
The ONG internal architecture outlined in this section presents the interworking modules enabling management of
ZigBee 1 networks by ETSI M2M GAs and NAs. However, this interworking architecture is generic and will be
reused for all other object network protocols: only the semantic conventions used by the GIP differ for each
protocol.
11/51
Cocoon® project
175
176
177
178
The ONG runs an OSGi framework deployed over Java Virtual Machine (JVM). The unit of application management
is called an OSGi bundle. OSGi provides a standardized framework supporting bundle isolation, software
deployment and upgrade (bundles deployment/upgrade), software configuration (bundles configuration) and fault
management.
An OSGi bundle per application
(e.g. ZigBee driver, HTTP binding,
GSC, Lobby...)
M2M application (OSGI bundles)
Includes the ONG servlet
container
SONG service (OSGi bundle)
ONG back-end (OSGi bundle)
OSGi framework (felix)
JVM (phoneMe)
Figure 5: ONG software stack
179
ZigBee interface (over the air)
ThingPark ONG
Includes the ZigBee
Coordinator
TI CC2531
USB
USB driver (CDC)
Serial port (virtual)
ZigBee driver (app)
Lobby service (app)
SONG interface
SONG interface
GSC (app)
Hosted service (app)
SONG interface
SONG interface
SONG servlet container
SONG router
Endpoint interface
ONG back-end
SONG interface
HTTP binding (app)
TCP socket
HTTP interface
SONG interface
SIP binding (app)
TCP and/or UDP socket
SIP interface
12/51
Cocoon® project
Figure 6: ONG internal architecture (ZigBee/ETSI TC M2M interworking)
181
The ONG core is implemented as a JAVA servlet container which exposes an internal communication framework
(ONG back-end). Components deployed on top of the ONG core servlet container are called ThingLets®.
182
Two kinds of ThingLets® exist:
180
183

binding ThingLets ® provide mId and dIa network connectivity over a specific transport protocol (e.g. SIP,
HTTP or CoAP…),

service ThingLets® implement particular service logic. Some service ThingLets® are generic (e.g.
interworking drivers to HAN or fieldbus networks provided by Actility), but developers can host their own
ThingLets® on the ONG as part of their service automation logic.
184
185
186
187
188
189
3.4 OVERVIEW OF ZIGBEE/M2M INTERWORKING
190
3.4.1 RESOURCE MODELING
191
192
Integration in the ETSI M2M architecture
oBIX, a popular XML interface model standardized by OASIS, is used as resource syntax for the ZigBee profile.
The ZigBee GIP is implemented as a ETSI M2M GA with specific syntax conventions.
ZigBee driver
Legacy case 1
d
(out of scope)
D
NA
DA
Case 1
mIa
dIa
mId
SCs
NIP
Legacy case 2
d
G
(out of scope)
mId
GA
D‘
Case 2
M2M Core
Service
Capability
platform
dIa
dIa
GIP
DA
mId
SCs
SCs
ZigBee nodes
D
DA
(out of scope)
Legacy case 3
d
dIa
DIP
SCs
mId
Emulation of DA application for
each ZigBee objects (ZigBee
networks, ZigBee nodes and
ZigBee applications)
Figure 7: ZigBee network interface in ETSI M2M
193
194
The GIP emulates a Device Application (DA):
195
-
196
For each ZigBee network: the ZigBee network DA provides access to ZigBee network attributes, and to the
ZigBee controller functionality if the ETSI M2M gateway acts as a ZigBee controller.
13/51
Cocoon® project
197
-
For each network node: the ZigBee network node DA provides access to ZigBee node specific attributes, and
stores indirections to hosted ZigBee applications (which are represented as separate DAs). The IEEE address
of the node is used to identify the DA.
-
For each ZigBee application: the ZigBee application DA provides access to the application clusters. A dotted
name [ieee address].[application #] is used to identify each application DA.
198
199
200
201
202
203
204
205
The GIP registers each DA in the G-SCL to enable discovery and CRUD operations by any GA or NA. CRUD
operations either apply to mirrored representations, or are retargeted and processed dynamically by the GIP.
“Dynamic” attributes are retargeted to ZigBee object through the GIP (e.g. temperature measurement/ measure
M2M ZigBee modeling
value)
gsc
applications
<zb network1>
link
application:
- A application for the ZigBee network
- A application for each ZigBee node
- A application for each ZigBee app
<zb node1>
link
<zb app1>
<zb app2>
link
containers
<client clusters>
container:
- A container for client clusters
- A container for server clusters
<server clusters>
contentInstances
<cluster1>
<cluster2>
Instance:
- Cluster attributes (mirrored)
- Cluster attributes (retargeted)
- Cluster commands (retargeted)
Figure 8: DAs created by the ZigBee GIP, name conventions and usage of containers
206
207
Figure 9 and Figure 10 present some of the attributes used for a ZigBee on/off light and switch application.
14/51
Cocoon® project
GSC
<sclBase>
IEEE address of the ZigBee network
applications
ieee1
IEEE address of the ZigBee node
ieee2
ZigBee on/off light application (IEEEE
+ endpoint)
Ieee2.1
containers
An on/off light does not have
client cluster
zclients
zservers
On/off cluster ID (client)
contentInstances
0x0006
Content:
- 0x0000 on/off attrib. (retargeting)
- ZCL 0x00 off cmd. (retargeting)
- ZCL 0x01 on cmd. (retargeting)
- ZCL 0x02 toggle cmd. (retargeting)
Ieee3
An on/off switch
Ieee3.1
Figure 9: ZigBee on/off light sample (0x0104 profile)
GSC
<sclBase>
IEEE address of the ZigBee network
applications
ieee1
ieee2
An on/off light
Ieee2.1
Ieee3
IEEE address of the ZigBee node
Ieee3.1
ZigBee on/off switch application
(IEEEE + endpoint)
containers
zclients
On/off cluster ID (server)
contentInstances
0x0006
zservers
Content:
- ZDO bind cmd. (retargeting)
An on/off switch does not have
server cluster
Figure 10: ZigBee on/off switch sample (0x0104 profile)
208
Refer to
[SCL-M2M-REST]
and
[ZigBee-M2M-REST]
for reference.
15/51
Cocoon® project
209
210
211
212
3.4.2 CONFIGURATION
The software configuration of an ONG used for ZigBee interworking includes:

A ZigBee driver : a GIP implemented as a ETSI GA ThingLet®, which exposes the ZigBee network
through standard ETSI TC M2M GA resources.

An oBIX Lobby : a ThingLet® which implements the oBIX lobby (the entry point for oBIX clients). This is
only for compliance to oBIX, and not needed for an ETSI M2M client.

A GSC : a servlet which implements the ETSI M2M gateway service capability layer (GSC).

A HTTP binding and/or a SIP binding module : a ThingLet® which transport mId and dIa messages
over HTTP or SIP.

Zero, one or several hosted services : ThingLets® which implement automation logic executed by the
ONG.
213
214
215
216
217
218
219
220
221
222
223
224
225
226
16/51
Cocoon® project
227
4. ONG PROGRAMMING GUIDE
228
4.1 ONG GATEWAY SERVICE CAPABILITIES (GSC)
229
4.1.1 GSC RESOURCES ORGANIZATION
230
231
ETSI TC M2M defines a hierarchical organization of resources hosted on the xSC. Figure 11 presents an overview of
this hierarchical organization of resources. Actility uses the compact naming conventions defined by ZigBee SE 2.0.
gsc/
acl/
scls/
acl/
Registered remote SCL
<scl>/
subs/
apps/
acl/
Registered application
<app>/
acl/
cnts/
acl/
Registered container
<cnt>/
acl/
For ‘subres’ subscription type
subs/
cis/
acl/
<ci>
subs/
Figure 11: GSC resource hierarchy
232
233
234
235
236
237
238
239
240
241
242
For ‘res’ subscription type
4.1.2 MIRRORING AND RETARGETING
The resources discovered by a GIP (object network protocol driver) on a HAN or fieldbus comprise static attributes
and sub-resources, and dynamic parameters. Static representation data, typically device descriptions, supported
attributes and available operations are mirrored by the GIP in the GSC. The GSC is then responsible for managing
these mirror resources.
Dynamic representation data, such as attributes values are not mirrored by the GSC. The GSC only places a
reference to the dynamic data in the mirror representation, the values are accessed indirectly through the GSC by
using the ETSI TC M2M retargeting mechanism. The retargeting mechanism is also used to execute operations. All
retargeted verbs are executed by the GIP. Refer to section [ZigBee-M2M-REST] for further details on mirroring and
retargeting functionalities supported by the ZigBee GIP.
17/51
Cocoon® project
243
4.1.3 SUBSCRIPTION
248
As we saw in section 4.2.5, any xA should be able to create a subscription to a resource. This may be useful for
creating an end user application (by example such as plotting a graph on temperature measurements on the last x
days). The xSC is then responsible for managing this subscription, and particularly the subscription expiration
timer. This timer warrants that subscription always ends (soft state), and thus to prevent ONG from managing
unnecessary resources.
249
Please refer to
244
245
246
247
250
251
252
253
254
255
256
[SCL-M2M-REST]
for a full description of resources managed on xSC.
4.1.4 LOGGING CONTAINERS
You may also want the GSC to manage a logging container, for instance if you need your application to create a
new sub-resource each time it collects a new measure. The GSC will manage the number of content instances of
the container for you: by defining mxni attribute on container properties, you can define the maximum number of
content instances the container may contain. Once this maximum is reached, the GSC will first delete the older
resource before creating the new one.
4.1.5 GSC PERSISTENT STORAGE
258
GSC persits all of its resources in a local database. This allows the GSC to restore all mirrored representations and
settings at start-up.
259
The local database is also available as a resource to any GA (refer to
257
260
4.2 ACCESSING ONG RESOURCES
261
4.2.1 BROWSING ONG RESOURCES AT START-UP
262
263
264
[RSS-API-Javadoc]).
The ONG installation and initial configuration steps are described in document [ONG-Install]. Once successfully
installed and started, you may access the oBIX Lobby resource using your favorite Web browser at
http://<ong_ip_address>/obix/:
265
<obj href="http://10.10.12.202:8080/obix/" is="obix:Lobby">
266
<ref name="about" href="about/" is="obix:About"/>
<op name="batch" in="obix:BatchIn" out="obix:BatchOut"/>
267
269
<ref name="watchService" is="obix:WatchService"/>
<ref name="gsc" href="/gsc/" is="m2m:Scl"/>
270
</obj>
268
271
272
273
274
275
276
277
278
279
The oBIX lobby is the entry point for all OASIS oBIX compliant applications, but you can ignore this resource if your
application is not an oBIX application. You may access the GSC and list all applications by browsing the
http://<ong_ip_address>/gsc/apps/ resource:
<obj href="http://10.10.12.202:8080/gsc/apps/" is="m2m:Apps">
<ref name="acl" href="/gsc/acrs/e7eedd4324ce8dcb/" is="m2m:Acr"/>
<abstime name="ctm" val="2011-06-27T09:51:08.300+01:00" tz="GMT+01:00"/>
<abstime name="mtm" val="2011-06-27T09:53:59.081+01:00" tz="GMT+01:00"/>
<list name="app" of="obix:ref m2m:App">
<ref href="x00124b000122bb78/"/>
281
</list>
<ref name="subs" href="subs/" is="m2m:Subs"/>
282
</obj>
280
283
284
In the example above, one application, named “x00124b000122bb78”, is registered. This application represents
the ZigBee coordinator device (plugged TI USB dongle with CC2531 SoC) that was registered to the GSC by the
18/51
Cocoon® project
285
286
287
288
ZigBee driver. The name used here is the string representation of the 64-bit IEEE address of the device. Please see
section 3.4.1 for an overview on GSC resources organization.
The Actility ONG Browser (a sample ETSI M2M application provided as open source, see
presents the same information graphically in the Navigation tree view:
[ONG-Browser]
for reference)
Figure 12: ONG Browser, showing a ZigBee coordinator installed on MyGateway
289
290
291
By clicking on device0 (the ZigBee coordinator), the ONG browser application will display the available HAN
parameters and provide access to ZigBee network operations in the “properties” panel.
4.2.2 ADDING NEW DEVICES
295
From this point, you may associate new ZigBee devices to the coordinator network. As an example in this
document, we added a light device and a switch device. Both also implement temperature sensors. But first, you
need to allow HAN joining by targeting the “zmgmt_permitjoin” operation sub-resource of the device application
representing the coordinator. For instance to allow HAN joining for 30 seconds send the following request:
296
>>> REQUEST
292
293
294
297
298
POST http://10.10.12.202:8080/gsc/apps/x00124b000122bb78/zmgmt_permitjoin
X-Acy-Method: Invoke
299
300
<?xml version="1.0" encoding="UTF-8"?>
301
302
<obj name="in">
<int name="permitDuration" val="30"/>
303
</obj>
304
305
306
<<< RESPONSE
200 OK
307
308
309
Additional devices can then join the HAN (usually by pressing the ‘join’ button). The ZigBee driver will automatically
publish additional device applications to the GSC. The updated /gsc/apps/ resource may look like this :
310
311
<ref name="acl" href="/gsc/acrs/e7eedd4324ce8dcb/" is="m2m:Acr"/>
312
313
314
316
<ref href="x00124b000122bb78/"/>
<ref href="x10000050c236654a.3/"/>
317
<ref href="x00124b000117b144/"/>
318
<ref href="x00124b000117b144.2/"/>
<ref href="x00124b000117b144.1/"/>
315
319
320
321
<ref href="x10000050c236654a/"/>
<ref href="x10000050c236654a.1/"/>
19/51
Cocoon® project
323
</list>
324
</obj>
322
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
In this document, one can see the resources associated to each ZigBee device that joined the network:
“x00124b000117b144” (a light), “x10000050c236654a” (a switch). The resource name is the string representation
of the 64-bit IEEE addresses of devices. One can also see the resources associated to the ZigBee applications
within each device: for instance “x10000050c236654a.1” and “x10000050c236654a.3” are the two applications
hosted on the switch. “x10000050c236654a.1” represents the On/Off switch application implemented on end point
‘1’. “x10000050c236654a.3” represents the Temperature measurement application implemented on end point ‘3’.
Resources associated to an application are all stored in ETSI M2M containers: in our example available containers
on end point ‘3’ are listed in /gsc/apps/x10000050c236654a.3/cnts/:
<obj href="http://10.10.12.202:8080/gsc/apps/x10000050c236654a.3/cnts/" is="m2m:Cnts">
<ref name="acl" href="/gsc/acrs/0d84bd57ec4d6849/" is="m2m:Acr"/>
<list name="cnt" of="obix:ref m2m:Cnt">
<ref href="zscs/"/>
<ref href="zccs/"/>
</list>
</obj>
The ZigBee-driver automatically performed a discovery procedure on the device and created two containers:
344

zscs: this container contains all “server” clusters implemented by the endpoint,
345

zccs: this container contains all “client” clusters implemented by the endpoint,
346
347
348
349
350
351
352
353
354
355
356
357
358
Note: if an endpoint does not support any client cluster, the zccs container is not created. The same behavior is
implemented with server clusters and the zscs container.
ETSI M2M content instances are then available in /cis/ sub-folder. In our example, the Basic cluster available in
server clusters is accessible using relative path /gsc/apps/x10000050c236654a.3/cnts/zscs/cis/x0000
<obj href="http://10.10.12.202:8080/gsc/apps/x10000050c236654a.3/cnts/zscs/cis/x0000/" is="zb
:Cluster m2m:Ci">
<str name="zcid" val="x0000"/>
<list name="apath">
<op name="x00" href="x00" in="obix:obj" out="obix:obj"/>
<ref name="x0000" href="x0000"/>
360
361
362
359
363
364
365
366
367
368
369
<ref name="zattrs" href="zattrs"/>
371
</list>
<str name="type" val=""/>
372
<str name="code" val=""/>
370
20/51
Cocoon® project
374
<int name="bsize" val="0"/>
<obj name="ctt"/>
375
</obj>
373
376
You can use the ONG Browser to visualize the same information:
Figure 13: ONG browser, device view
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
4.2.3 RETRIEVING ATTRIBUTE VALUES
Attributes values are stored in the cluster resources (client cluster or server cluster). They can be accessed one by
one (e.g. /gsc/apps/x10000050c236654a.3/cnts/zscs/cis/x0000/x0000), or all at once by referencing the subresource
named
zattrs.
In
our
example
with
the
relative
path
/gsc/apps/x10000050c236654a.3/cnts/zscs/cis/x0000/zattrs we get:
<obj href="http://10.10.12.202:8080/gsc/apps/x10000050c236654a.3/cnts/zscs/cis/x0000/zattrs">
<int name="x0000" val="1"/>
<str name="x0004" val="ACME"/>
<str name="x0005" val="P1"/>
<str name="x0006" val="20100501"/>
<enum name="x0007" val="x03"/>
<str name="x0010" val="Actility office"/>
<enum name="x0011" val="x00"/>
<bool name="x0012" val="true"/>
<str name="x0013" val="x00"/>
</obj>
21/51
Cocoon® project
396
4.2.4 UPDATING ATTRIBUTE VALUES
398
When the HTTP binding is used, an attribute value can be updated by using the PUT method. On the same
example, here is the request/response you may experiment:
399
>>> REQUEST
397
400
PUT http://10.10.12.202:8080/gsc/apps/x10000050c236654a.3/cnts/zscs/cis/x0000/x0010
401
402
403
<str name="x0010" val="Actility office"/>
404
405
406
407
<<< RESPONSE
202 Accepted
Using the ONG browser, one can access ZigBee cluster attributes values and modify them (when allowed by the
cluster), using buttons “Read” and “Write”:
Figure 14: ONG Browser, accessing an attribute
408
4.2.5 SUBSCRIBING TO A RESOURCE
412
You may also want to subscribe to an attribute value, and be notified each time the value changes. The ONG also
supports this feature, however, in the current implementation, the resources which will allow subscription must be
declared by configuration: To do so, edit the m2mResourcesModeling.xml file (Please refer to section 4.3.4 for
further details on this file).
413
Warning: this feature will only be available if your device supports COV reporting.
414
The example below activates subscription to the current temperature measured by one of the ZigBee devices:
415
>>> REQUEST
409
410
411
416
POST http://10.10.12.202:8080/gsc/apps/x00124b000117b144.2/cnts/temperature/cis/current
22/51
Cocoon® project
417
X-Acy-Method: Subscribe
418
419
420
<obj is="m2m:Sub">
422
<abstime name="etm" val="2011-06-27T12:00:00Z">
<reltime name="mint" val="PT1M">
423
<enum name="type" val="asyn">
424
<uri name="poc" val="http://...">
<obj name="filter" is="m2m:Filter">
421
425
426
427
428
429
430
<enum name="scope" val="res"/>
<enum name="report" val="newest"/>
<int name="initnty" val="20"/>
</obj>
</obj>
431
432
<<< RESPONSE
433
201 Created
434
435
436
437
For each active subscription, the ONG will send a POST message (with header “X-Acy-Method” set to “NOTIFY”)
periodically and each time the value changes.
To create subscriptions with ONG browser, you simply have to drag-and-drop the “temperature” container from
navigation treeview to dashboard:
Figure 15: ONG Browser, creating a subscription
23/51
Cocoon® project
438
4.3 INTERWORKING WITH ZIGBEE HANS
439
4.3.1 ETSI M2M GIP REPRESENTATION OF A ZIGBEE NETWORK
442
A ZigBee network is composed of one ZigBee coordinator, one or several ZigBee routers and one or several ZigBee
end devices (routers can also act as end-devices). All ZigBee devices host a ZDO (ZigBee Device Object
implementing generic ZigBee parameters and commands) and host zero or several ZigBee applications.
443
The ZigBee GIP (ZigBee driver) models the ZigBee HAN as a collection of M2M legacy Device Applications (DA):
440
441
444

One ZigBee network DA represents the ZigBee coordinator. This DA enables access to ZigBee network
operations (e.g. register a virtual ZigBee device, list all ZigBee devices in the network) and ZDO operations
(zmgmt_permitjoin)

Zero or multiple ZigBee node DAs enable access to the properties of each ZigBee node, and ZDO
operations implemented by the node (zmgmt_bind, zmgmt_leave).

Zero or multiple ZigBee application DAs enable access to ZigBee clusters (e.g. retrieve a ZigBee attribute
value, invoke a ZigBee command on a cluster), and ZDO operations implemented by the application (zbind
and/or zunbind depending on your zigbeeModeling.xml file, see 4.3.4.2).
445
446
447
448
449
450
451
452
453
454
Figure 16 abstracts this representation.
M2M
representation
ONG
ZigBee
Coordinator
(ZigBee network)
1
1
DA
1
Endpoint/router
(ZigBee node)
DA
ZigBee driver
(SONG application)
App. endpoint
(ZigBee application)
1
1
DA
Figure 16: ZigBee HAN representation on ONG
455
456
457
458
459
460
Note: Refer to
contracts.
[ZigBee-M2M-REST]
for an exhaustive list of all supported ZDO operations and associated implemented
4.3.2 ZIGBEE GIP FUNCTIONS
At start-up, the ZigBee GIP instructs the coordinator (a TI CC2530 based USB dongle in this preview release) to
form a HAN. The GIP then audits new devices that have joined the network and creates M2M resources on GSC to
represent these devices and the applications they host. The ZigBee GIP mainly runs two “tasks”:
24/51
Cocoon® project
461

The “discovery task” which is in charge of auditing new devices and re-auditing regularly known devices in
the HAN, and creates and maintains up-to-date their M2M representation mirrored on the GSC,

The “mirroring task” which is in charge of mirroring device applications on the GSC, and of handling
attribute retargeting and operation retargeting verbs.
462
463
464
465
466
467
4.3.2.1 DISCOVERY TASK
The discovery task periodically audits devices of the ZigBee HAN. Figure 17 outlines the GIP activity during a device
audit:
ONG
Zigbee
node
Coord
(ZNP)
IEEE_addr_req
IEEE_addr_rsp
Node_Desc_req
Node_Desc_rsp
Power_Desc_req
Power_Desc_rsp
Active_EP_req
Active_EP_rsp
Simple_Desc_req
Simple_Desc_rsp
Zigbeedriver
GSC
IEEE_addr_req
IEEE_addr_rsp
Node_Desc_req
Node_Desc_rsp
Power_Desc_req
Power_Desc_rsp
Active_EP_req
Active_EP_rsp
Simple_Desc_req
Simple_Desc_rsp
M2M Update /gsc/apps/…
M2M 200 OK
Figure 17: ZigBee GIP discovery activity flow
468
469
470
471
472
473
The GIP audit leverages the IEEE address tables maintained by the ZigBee coordinator and ZigBee routers on the
HAN. Then, each time a new device joins the network and announces itself, the ZigBee GIP operates a complete
audit of this device.
4.3.2.2 MIRRORING TASK
The ZigBee GIP mirrors ZigBee object representations on the GSC. Figure 18 outlines this process, which takes
place right after each ZigBee device audit:
25/51
Cocoon® project
ONG
Zigbee
node
Coord
(ZNP)
<Discovery requests>
<responses>
ReadAttributes req (ep #1)
ReadAttributes resp
Zigbeedriver
<Discovery requests>
<Responses>
GSC
Generated documents also
describe read attributes
ReadAttributes (ep #1)
ReadAttributes resp
ReadAttributes req (ep #n) ReadAttributes (ep #n)
ReadAttributes resp
On each Simple_Desc_rsp the
discoveryTask notifies the mirroringTask.
Then depending on confMirroringTable
content, additional zigbee request may be
sent
Because mirroring policy is
“reporting” for attributes on end point
#1 zigbee-driver sends a “configure
reporting” to this end point, asking for
notifications
ReadAttributes resp
M2M Update(s)
M2M 202 ACCEPTED
Configure Report (ep #1)
Configure Report resp
Configure report (ep #1)
Attribute values changed
Report Attributes
Report Attributes
M2M Update
M2M 200 OK
Figure 18: ZigBee GIP mirroring activity flow
474
475
And then each time a device notifies an attribute COV, the GIP adapts the notification syntax according to ETSI
M2M interworking conventions and proxies this report to the GSC, as outlined in Figure 19:
26/51
Cocoon® project
ONG
Zigbee
node
Coord
(ZNP)
Configure Report (ep #1)
Zigbeedriver
GSC
Configure report (ep #1)
Attribute values
changed
Report Attributes
Report Attributes
M2M Update
M2M 200 OK
Attribute values
changed
Report Attributes
Report Attributes
M2M Update
M2M 200 OK
Configure report (ep #1,
Configure Report (ep #1,
min/max ReportInterval=0xFFFF)
min/max ReportInterval=0xFFFF)
Configuration has changed and end
point #1 has no mirrorred attributes
anymore in
confMirroringTable
Attribute values
changed
Figure 19: ZigBee GIP COV reporting
476
477
4.3.3 ETSI M2M REQUESTS USED BY THE GIP
SONG request
Use cases
From GIP to GSC
CREATE
After initial discovery of a device and its associated resources
When logging entries
UPDATE
When re-auditing a device and its resources
When updating a reporting entry
From GSC to GIP
RETRIEVE
For attribute retargeting functionality, when accessing attributes values (read
access)
UPDATE
For attribute retargeting functionality, when accessing attributes values (write
access)
INVOKE
For command retargeting functionality, when asking for a ZCL operation
For command retargeting functionality, when asking for a ZDO operation
478
Please refer to
[SCL-M2M-REST], [ZigBee-M2M-REST]
and
[SONG-API-Javadoc]
for a full description of SONG APIs.
27/51
Cocoon® project
479
480
481
482
483
484
485
486
487
488
489
4.3.4 DESCRIPTION FILES
The ZigBee GIP needs configuration files to determine what it cannot discover by its own. These files are located in
$ONG_HOME/resources/conf/ folder of the ONG. In the current release the ZigBee GIP needs two configuration
files:
4.3.4.1 M2MRESOURCESMODELING.XML
This file is required for all GIP implementations and provides some flexibility in the ETSI M2M resource modeling
used to represent native object network devices and applications. In the case of the ZigBee GIP, this configuration
file maps native ZigBee objects to their ETSI M2M resource. The configuration file also enables change of value
(COV) reporting for selected ZigBee objects, and provides COV configuration details. Here is an extract of the ONG
GIP default configuration file:
<resourceModeling>
<application filter="ZigBee:/device/x0302" directive="ZigBee:discover">
<resource path="/cnts/temperature/cis/current">
490
491
<reporting>
<attribute name="measuredValue" link="ZigBee:/server/x0402/attribute/x0000"/>
492
493
494
<attribute name="minMeasuredValue" link="ZigBee:/server/x0402/attribute/x0001"/>
495
<attribute name="maxMeasuredValue" link="ZigBee:/server/x0402/attribute/x0002"/>
<attribute name="tolerance" link="ZigBee:/server/x0402/attribute/x0003"/>
496
</reporting>
</resource>
497
498
499
<resource path="/cnts/temperature-log/">
500
<logging stamping="UID" maxInstances="20">
<attribute name="measuredValue" link="ZigBee:/server/x0402/attribute/x0000"/>
501
502
</logging>
</resource>
503
504
505
<covConfiguration filter="ZigBee:/server/x0402/attribute/x0000">
506
<minInterval>PT5M</minInterval>
<maxInterval>PT1H</maxInterval>
507
508
<minCOV>50</minCOV>
</covConfiguration>
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
</application>
</resourceModeling>
In this extract, the configuration applies to devices that match application device ID 0x0302 (Temperature Sensor),
as specified by an ‘application filter’ using ZigBee specific syntax. The configuration file enables COV reporting on
attributes “measured Value” (0x0000), “minMeasured Value” (0x0001), “maxMeasured Value” (0x0002) and
“tolerance” (0x0003) of server cluster “Temperature Measurement” (0x0402), and instructs the GIP to store the
corresponding records in the GSC in a subresource defined by its path “/cnts/temperature/cis/current” relative to
the DA resource representing the ZigBee application.
The “covConfiguration” block defines minimal and a maximal reporting intervals (defining a maxInterval is
mandatory, otherwise “covConfiguration” block is ignored; defining a minInterval is optional), and a minimal COV
threshold to define reporting trigger (optional). For ZigBee protocol implementation, “covConfiguration” parameters
are directly mapped on “ZCL Configuration Reporting” command fields: “Minimum Reporting Interval Field”,
“Maximum Reporting Interval Field” and “Reportable Change Field” (Refer to [ZCL-specification]).
Note that it is possible that the same attribute will be represented twice in the GSC. In the example above, this is
the case for attribute ‘measuredValue’:
1.
The instantaneous value is represented in application container “temperature” in a resource named
“current”. “current” also provides “MinMeasuredValue”, “MaxMeasuredValue” and “Tolerance” attributes
values which never change. These static values are read and refreshed in memory in ZigBee-driver each
time the device is re-audited.
28/51
Cocoon® project
530
531
532
2.
The value history is logged in application container “temperature-log”. Note that if you also need
“MinMeasuredValue”, “MaxMeasuredValue” and “Tolerance” attributes to be logged, you simply have to add
<attribute> XML tags in the <logging> block.
535
Each time a new value of attribute ‘measuredValue’ is reported to the ZigBee GIP (because the value has changed
or because a period of maxInterval has elapsed) it updates resource /gsc/<app>/cnts/temperature/cis/current and
creates a new entry in /gsc/<app>/cnts/temperature-log/cis/.
536
Refer to http://cocoon.actility.com/technical-doc/users/m2mResourceModelingXsd documentation for the XSD.
533
534
537
4.3.4.2 ZIGBEEMODELING.XML
542
The ZigBee-driver is able to discover ZCL attributes by its own, but ZCL operations cannot be discovered the
same way and are defined by convention in the ZigBee Cluster Library specification (refer to [ZCL-specification]). In
order to provide support for extensibility, the ZCL operations are not hardcoded in the driver, but defined in the
ZigBeeModeling.xml configuration file. Here is an extract of the ONG default ZigBeeModeling.xml configuration
file:
543
<ZigBeeModeling>
538
539
540
541
544
545
<cluster id="/server/x0000">
<command>
<in id="/command/x00"/>
</command>
546
547
548
549
</cluster>
<cluster id="/server/x0003">
<command>
<in id="/command/x00">
550
551
<field name="identifyTime" type="x21"/>
</in>
552
553
</command>
<command>
554
555
<in id="/command/x01" />
<out linkedid="/command/x00">
556
557
<field name="timeout" type="x21"/>
558
</out>
</command>
559
560
561
562
563
564
</cluster>
<cluster id="/client/x0006" zdo="zbind,zunbind"/>
<cluster id="/server/x0006" zdo="zbind,zunbind">
<command>
<in id="/command/x02"/>
</command>
565
566
567
568
569
570
571
</cluster>
<ZigBeeModeling>
This file allows providing ZCL operations description per cluster. In the extract we define the following cluster
commands (in the file order):

“Reset to Factory defaults” command (0x00) for Basic cluster (0x0000) as a server which takes no
argument,

For Identify cluster (0x0003) as a server:
572
573
574
o
“Identify” command (0x00) which takes one argument, here named “identifyTime” of type
16-bit unsigned integer (0x21),
o
“Identify Query” command (0x01) which takes no argument and results in “Identify Query
Response” command in return (0x00) with one argument “timeout”.
575
576
577
578
579
580

“Toggle” command (0x02) for On/Off Cluster (0x0006) as a server which takes no argument.
Also notes that ZDO commands “bind” and “unbind” should be added to client On/Off Cluster and server On/Off
Cluster.
29/51
Cocoon® project
582
Please refer to [ZCL-specification] and [HA-specification] documents for further details on available ZigBee clusters,
attributes, operations and ZigBee defined data type.
583
Also refer to http://cocoon.actility.com/technical-doc/users/zigBeeModelingXsd documentation for the XSD.
581
584
585
586
4.3.4.3 GIP RESOURCES REPRESENTATION FOR ZIGBEE 1
When auditing a device and its applications, the GIP ZigBee-driver creates resources to represent them on GSC
(see 3.4) according to pre-defined oBIX contracts (refer to [ZigBee-M2M-REST]):

The ZigBee coordinator representation implements oBIX contracts “m2m:App” (Application) and
“Zb:Network”,
589

A ZigBee node representation implements oBIX contracts “m2m:App” (Application) and “Zb:Node”,
590

A ZigBee application representation implements oBIX contracts “m2m:App” (Application) and
“Zb:Application”,
592

A Zigbee cluster representation implements oBIX contracts “ m2m:Ci” (Content Instance) and “Zb:Cluster”.
593

Each entry of reporting containers or logging containers implements oBIX contracts “ m2m:Ci” (Content
Instance).
587
588
591
594
595
596
597
Configuration file m2mResourcesModeling.xml instructs the GIP to include additional data points within “m2m:Ci”
resources. The XML type of each data points is selected based on the ZigBee data type of the attribute being
represented, according to the following mapping table (Table 1):
598
ZigBee class/type
XML type
Null
For future study (FFS)
General data
obix:str (hexadecimal encoded)
Logical/Boolean
obix:bool
Bitmap
Unsigned integer
obix:int
Note: A value greater than 2^63-1 is represented
as a negative value.
Signed integer
obix:int
Enumeration
obix:enum (hexadecimal encoded)
Floating point
String
obix:real
Octet string
Character string
obix:str (UTF8-encoding)
Long octet string
Long character string
obix:str (UTF8-encoding)
Ordered sequence
Collection
Time
Time of day
obix:reltime
Date
obix:abstime
UTC Time
obix:abstime
Identifier
Miscellaneous
IEEE address
128-bit security –key
30/51
Cocoon® project
Table 1: ZigBee attribute type to XML type mapping
599
600
601
zigbeeModeling.xml file also defines extra-fields to “m2m:Ci” resources types for operations.
4.3.4.4 ZIGBEE GIP RESOURCES EXAMPLE
608
This example illustrates how the content of resources that are automatically created by the ZigBee GIP-driver is
built according to configuration files m2mResourcesModeling.xml and zigbeeModeling.xml. In our example, we
consider a device that implements a Temperature Sensor application (application device ID 0x0302): this
application exposes the Basic server cluster (0x0000), Identify server cluster (0x0003) and the Temperature
Measurement server cluster (0x0302) (such a device typically also exposes client clusters, but for clarity we do not
consider them here). M2mResourcesModeling.xml and zigbeeModeling.xml configuration files are the one described
in the above sections (4.3.4.1 and 4.3.4.2).
609
When the ZigBee GIP-driver audits this application, it will create the following resources:
602
603
604
605
606
607
i)
One resource that represents the ZigBee end device itself: its short address, its IEEE address, etc., as well
as its M2M properties such as the creation time) and the possible interactions (operations zmgmt_bind and
zmgmt_leave). This resource implements both “Zb:Node” and “m2m:App” (Application) oBIX contracts
ii)
615
One resource that represents the Temperature Sensor application. This resource implements both
“m2m:App” (Application) and One “Zb:Application” oBIX contracts. This resource also contains subresources in the following containers:
616
(1) In the zccs container, the client clusters that are not detailed here (sub-path cnts/zccs/cis/…)
617
(2) In the zscs container, the Basic server cluster (sub-path cnts/zscs/cis/x0000):
610
611
612
613
614
618
619
620
621
622
623
624
<obj href="http://192.168.195.128:8080/gsc/apps/x00124b000117b144.2/cnts/zscs/cis/x0000/" is=
"zb:Cluster m2m:Ci">
<abstime name="ctm" val="2011-07-15T10:39:31.208+02:00" tz="Europe/Paris"/>
<abstime name="mtm" val="2011-07-15T10:39:31.208+02:00" tz="Europe/Paris"/>
<list name="apath">
626
627
628
625
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
</list>
<obj name="ctt"/>
</obj>
In this document one can retrieve all the references to access the re-targetable attributes (e.g.
<ref name="x0000" href="x0000"/> for accessing the “ZCL Version” attribute as defined in [ZCL-specification]).
zattrs targets all attributes at once. One can also retrieve the reference for invoking operation “Reset to Factory
defaults” (x00) as defined in zigbeeModeling.xml file.
31/51
Cocoon® project
648
649
650
651
(3) Also in the zscs container, The Identify server cluster (sub-path cnts/zscs/cis/x0003):
653
654
655
<list name="apath">
652
656
657
658
659
660
661
662
</list>
<obj name="ctt"/>
664
665
</obj>
663
666
667
668
669
670
671
672
673
Here again all the cluster resource lists references that can be used for accessing the attributes, and for invoking
operations “Identify” (x00) and “Identify Query” (x01) as they are described in zigbeeModeling.xml file.
in the zscs container, the Temperature Measurement server cluster
(sub-path
cnts/zscs/cis/x0402) for which our example configuration file does not define any ZCL operation:
(4) Also
675
<list name="apath">
676
677
674
678
679
680
681
682
683
684
685
686
</list>
<obj name="ctt"/>
</obj>
687
688
689
690
691
692
693
694
(5) And finally in temperature-log and temperature containers, respectively all the logging (sub-path
cnts/temperature-log/cis/…) and reporting entries (sub-path cnts/temperature/cis/current). Here is one
example reporting entry:
<obj href="http://192.168.195.128:8080/gsc/apps/x00124b000117b144.2/cnts/temperature/cis/curr
ent/" is="m2m:Ci">
696
<list name="apath"/>
697
<obj name="ctt"/>
698
699
700
<int name="MeasuredValue" href="MeasuredValue" val="1950"/>
695
32/51
Cocoon® project
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
<int name="MinMeasuredValue" href="MinMeasuredValue" val="-1000"/>
<int name="MaxMeasuredValue" href="MaxMeasuredValue" val="3095"/>
<int name="Tolerance" href="Tolerance" val="50"/>
</obj>
This resource only implements “m2m:Ci” contract. But as illustrated it also embeds the additional attributes
“MeasuredValue”, “MinMeasuredValue”, “MaxMeasuredValue” and “Tolerance” that we have declared in the
m2mResourcesModeling.xml configuration file. As mentioned in 4.3.4.3, the ZigBee attributes are mapped to an
XML equivalent in the M2M model according to their data type. In our example “MeasuredValue” (i.e. ZCL attribute
0X0000 of server cluster Temperature Measurement 0x0402) has data type “Signed 16-bit Integer” as defined in
[ZCL-specification], and according to Table 1 the ZigBee GIP-driver uses an “int” oBIX child to represent it.
Notice that the resource was initially created at 2011-07-15T10:39:31.199+02:00. The resource is then periodically
refreshed using COV reporting: in the example it was last modified at 2011-07-15T10:48:57.835+02:00.
4.3.4.5 RESETTING HAN CONFIGURATION AFTER ONG REBOOT
The ZigBee-driver supports two different starting modes:

Stateful restart: the GIP restores the HAN characteristics as they were at the previous run (same channel,
same PAN ID, same extended PAN ID, IEEE address tables, …), and then in a second stage the Discovery
task of the GIP will resynchronize the HAN representations on the GSC (at start-up, the GSC also restores
these resources thanks to its local storage mechanism). As a consequence if a device does not recover at
restart and does not rejoin the HAN, its associated resources will still be present in the GSC. Then it is up
to the GSC and the GIP to protect themselves against these undesired resources (Note: in the current
implementation, this case is not correctly handle by the GIP and the GSC, and the concerned resources
have to be deleted by the user via SONG DELETE requests through REST API).

Stateless restart: The GIP rebuilds a new HAN from scratch. In this case, you need to reset all the devices
so that they can join the new formed HAN.
716
717
718
719
720
721
722
723
724
725
726
727
The desired behavior can be selected by setting the CVM parameter “com.actility.ZigBee.resetHanAtReboot”.
Please refer to [ONG-Install] for further details on how to activate this option. By default the ZigBee-driver assumes
that “com.actility.ZigBee.resetHanAtReboot=false” and attempts to restore the HAN at reboot.
730
If you need to change the “defaultRadioChannel” ZigBee-driver parameter, you’ll need to start with option
“com.actility.ZigBee.resetHanAtReboot=true” (Indeed changing the radio channel necessarily implies to form a
new HAN). This parameter is stored in non-volatile memory of the CC2531 USB dongle.
731
There are a few side effects when changing the default value to “false”:
728
729
732

733
734
Resources restored at start-up by the GSC are desynchronized as they represent devices and applications
as they were in the previous HAN. To resynchronize GSC resources with HAN resources, you can:
o
Either erase the database file but then YOU WILL ALSO LOOSE ALL OTHER RESOURCES
STORED INTO THE GSC!
o
Either reset all devices of your HAN so that they will join the new HAN, and then wait until the
GIP has completed its HAN audit. As the audit runs, the GIP will refresh M2M resources one by
one. But be advice that not-audited-device resources will not be erased. As a consequence,
resources may be still accessible through GSC because restored from database, but not known
by the GIP. The requests on these not-audited-device resources will all fail. It is up to the GSC
and the GIP to protect themselves against these undesired resources (Note: in the current
implementation, this case is not correctly handle by the GIP and the GSC, and the concerned
resources have to be deleted by the user via SONG DELETE requests through REST API).
735
736
737
738
739
740
741
742
743
744
745
746

Re-starting the ZigBee-driver with this option has a direct effect on the TI USB CC2531 dongle. It resets
all non-volatile parameters, including routing tables and IEEE address tables. You have to reset your
devices so that they will initiate a new join procedure to newly formed HAN.
33/51
Cocoon® project
747
748
749
750
Note that when running this option, you will see led #1 (the red one) blinking on ZigBee USB dongle. Otherwise,
only led #2 will light on.
In conclusion be really careful with this option, as it has changes the ZigBee GIP behavior and its interactions with
other ONG services.
751
4.4 IMPLEMENTING YOUR OWN GATEWAY APPLICATION THINGLET
752
4.4.1 JAVA RUNTIME ENVIRONMENT
753
754
755
756
757
758
759
760
761
ONG runs on top of J2ME CDC foundation profile Virtual Machine. Therefore the set of available APIs is limited. So
be sure to configure your IDE for using “OSGi minimum 1.2” environment. Also pay attention that generated bytecode is version 1.4 compliant.
4.4.2 HELLOWORLD APPLICATION
In order to illustrate this section, we will use a simple example called “HelloWorld”. This ThingLet® (ETSI M2M GA)
manages a resource (“HelloWorld”) on the GSC that implements a M2M application. At start-up, the servlet creates
the “HelloWorld” resource in “/gsc/apps/” relative path. This resource exposes an operation name “get” and a
read/write attribute named "config". Invoking the operation returns the current value of “Hello Wolrd” string. The
“config” attribute allow setting the value that is returned by the “get” operation.
763
You may also set “config” value by changing "helloWorldWords" bundle configuration key (by default set to "Hello
World !").
764
The following document represents the supported attribute and operation (so called the contract):
762
765
766
767
768
769
770
771
772
773
774
775
776
777
<?xml version='1.0' encoding='UTF-8'?>
<obj href="/gsc/apps/helloWord/">
<str href="meta/" writable="false" displayName="Meta description" display="Describes
retargeted resources" />
<str href="config/" writable="true" displayName="Configuration" display="Configures the
get() operation" />
<op href="get/" in="obix:null" out="#HelloWorldOut" displayName="HelloWorld" display="Get
the Hello World string">
<obj href="#HelloWorldOut" name="out">
<str name="foo" />
</obj>
</op>
</obj>
778
779
780
781
782
783
784
4.4.3 BUNDLE ACTIVATION THROUGH OSGI SERVICE COMPONENT RUNTIME
Service Component Runtime (SCR) is the actor that manages the components and their life cycle (see
compendium]).
4.4.3.1 SCR BOOTSTRAP FILE
In our sample, we have chosen to use SCR for managing the activation of our bundle on OSGi server. To do so,
you will need to embed in your jar file a XML file that describes SCR entries. Here is this XML file of our example:
785
786
<scr:component name="com.actility.helloworld.SongHelloWorld" modified="modified"
immediate="true" xmlns:scr="http://www.osgi.org/xmlns/scr/v1.1.0">
787
[OSGi-
34/51
Cocoon® project
<implementation class="com.actility.helloworld.SongHelloWorld" />
<reference name="ObixService" interface="com.actility.obix.ObixService" />
788
789
<reference name="SongService" interface="com.actility.servlet.song.service.SongService" />
<property name="helloWorldWords" type="String" value="Hello World !" />
790
791
792
793
794
795
796
797
798
799
800
</scr:component>
This file provides the declaration of the main class of the component (com.actility.helloworld.SongHelloWorld in our
example), local services that will be used by the component (“ObixService” and “SongService”), and configuration
keys definitions (“helloWorldWords”).
4.4.3.2 SCR ENTRY POINTS
SCR also defines entry point methods for managing the OSGi bundle: starting it, stopping it and notifying for new
configuration. These methods have to be implemented in the main class defined for the component
(com.actility.helloworld.SongHelloWorld):

802
803
804

807
808
deactivate: this method is invoked by SCR when bundle stops. It allows un-initializing your application
and freeing the resources it accessed.
805
806
activate: this method is invoked by SCR when bundle starts. SCR then provides a component context
that allows accessing to the bundle context data and local services. It also provides the bundle
configuration parameters (if defined). Thanks to this method you can create your ThingLet® application,
the associated servlet and retrieve handlers for services you will need to access for your application.
801

modified: this method is invoked by SCR when the bundle configuration changed. It provides the new
configuration data.
Here is the com.actility.helloworld.SongHelloWorld implementation for our example:
package com.actility.helloworld;
import java.util.Map;
import javax.servlet.ServletContext;
import javax.servlet.ServletException;
import org.apache.log4j.Logger;
import org.osgi.service.component.ComponentContext;
import
import
import
import
import
com.actility.helloworld.servlet.HelloWorldServlet;
com.actility.obix.ObixService;
com.actility.servlet.NamespaceException;
com.actility.servlet.song.service.SongService;
com.actility.util.log.LogUtil;
/**
* @author mlouiset
*
*/
public class SongHelloWorld {
/**
* for serialization
*/
private static final long serialVersionUID = 8843753674222485021L;
private
private
private
private
private
private
private
static final Logger LOG = Logger.getLogger(SongHelloWorld.class);
ComponentContext componentContext;
SongService songService;
ServletContext applicationContext;
ObixService obixService;
HelloWorldServlet helloWorldServlet;
String helloWorldWords;
/**
* Constructor
35/51
Cocoon® project
*/
public SongHelloWorld() {
}
/**
* Apply the configuration.
*
* @param config
* @return true if application restart is required for the changes to take effects, false
*
otherwise.
*/
private boolean setConfiguration(Map config) {
boolean restartNeeded = false;
// Retrieve the parameter values
Object keyValue = config.get("helloWorldWords");
if (keyValue instanceof String) {
helloWorldWords = ((String) keyValue);
}
if (null != helloWorldServlet) {
helloWorldServlet.setHelloWorldWords(helloWorldWords);
}
return restartNeeded;
}
/**
* Called when the configuration associated to the current bundle is modified.
*
* @param config The new configuration
*/
protected void modified(Map config) {
LOG.info("Configuration has been modified...");
boolean restartNeeded = setConfiguration(config);
// you may need to restart the SONG application in order to take into account
// configuration changes.
if (restartNeeded) {
deactivate();
activate(this.componentContext, config);
}
}
/**
* Called to activate the current bundle.
*
* @param componentContext The component context coming from SCR associated to this
*
bundle
* @param config The initial configuration of the bundle
*/
protected void activate(ComponentContext componentContext, Map config) {
this.componentContext = componentContext;
// Initialize log mechanism
LogUtil.init(SongHelloWorld.class.getClassLoader(),
componentContext.getBundleContext(), false);
LOG.info("Starting SONG HelloWorld application...");
try {
obixService = (ObixService) componentContext.locateService("ObixService");
songService = (SongService) componentContext.locateService("SongService");
// create the servlet
helloWorldServlet = new HelloWorldServlet(obixService);
setConfiguration(config);
// create HelloWorld network controller instance and provide it at new
// created application
applicationContext = songService.createApplication("/HelloWorld", "HelloWorld",
null , null, null);
if (LOG.isDebugEnabled()) {
LOG.debug("Context path: " + applicationContext.getContextPath());
}
36/51
Cocoon® project
// register the servlet
songService.registerServiceServlet(applicationContext, "/",
"helloWorldServlet", helloWorldServlet, null, null);
} catch (ServletException e) {
LOG.error("Can't initialize servlet", e);
} catch (NamespaceException e) {
LOG.error("Problem with the name of the SONG Servlet", e);
} catch (Exception e) {
LOG.error("Problem with the contract registration", e);
e.printStackTrace();
}
}
/**
* Called to deactivate the current bundle.
*/
protected void deactivate() {
LOG.info("Stopping HelloWorld application...");
helloWorldServlet.uninit();
if (songService != null) {
songService.unregisterApplication(applicationContext);
}
// Uninitialize log mechanism
LogUtil.close(SongHelloWorld.class.getClassLoader());
}
}
809
4.4.4 LOGGING SERVICE
812
You can simply manage your logs thanks to LogUtil class. This object is provided by the actility-util package and
provides you with a simple API for log manipulation. You only need to invoke the initialize method at bundle
activation (LogUtil.init). You also have to invoke the uninitialize method at bundle deactivation (LogUtil.close).
813
Then for all the classes that need to generate logs, you only have to retrieve a logger handler:
810
811
814
private static final Logger LOG = Logger.getLogger(MyClass.class);
818
Logs are all generated in the same flow. The log flow can be examined through various access methods (in this
preview release through the telnet console and the file system in $ONG_HOME/knopflerfish/osgi/fwdir/data/1/).
Please refer to [ONG-Install] and http://open.actility.com/projects/ong/wiki/Logs for further details on how to manage
logs.
819
Log entries all have the same format:
815
816
817
820
821
<log-level>
<date>
<bundle id> <log message>
Here is an example of log entries generated with “HelloWorld” ThingLet®:
822
info
20110715 12:59:08 bid#80
- BundleEvent INSTALLED
823
info
20110715 12:59:09 bid#80
- BundleEvent RESOLVED
824
info
20110715 12:59:09 bid#80
com.actility.helloworld.SongHelloWorld
- Enable Immediate component:
info
20110715 12:59:09 bid#80
info
20110715 12:59:09 bid#80
com.actility.helloworld.SongHelloWorld
info
20110715 12:59:09 bid#80
SONG HelloWorld application...
debug
20110715 12:59:09 bid#80
path: /HelloWorld
debug
20110715 12:59:09 bid#80
init
- BundleEvent STARTED
- Satisfied: Immediate component:
825
826
827
828
829
830
831
832
833
834
- com.actility.helloworld.SongHelloWorld: Starting
- com.actility.helloworld.SongHelloWorld: Context
- com.actility.helloworld.servlet.HelloWorldServlet:
37/51
Cocoon® project
835
836
837
838
839
840
debug
20110715 12:59:09 bid#80
com.actility.helloworld.servlet.SongCreateRequestHandler: Send SONG CREATE request
(To:song://localhost:8080/gsc/apps/) (content:
<obj name="HelloWorld" is="m2m:App">
<list name="srch" of="obix:str"/>
841
<abstime name="etm" val="1970-01-01T01:00:00.000+01:00" tz="Europe/Paris"/>
842
<enum name="stat" val="online"/>
<ref name="ncs" is="m2m:Ncs"/>
843
844
845
846
847
848
849
850
851
852
853
854
855
856
<uri name="apoc" val="song://localhost:8080/HelloWorld"/>
<list name="apath">
<ref name="HelloWorld" href="HelloWorld"/>
</list>
</obj>
)
info
20110715 12:59:10 bid#80
com.actility.helloworld.servlet.SongCreateRequestHandler: HelloWorld resource created
successfully
4.4.5 SONG INTERFACE
SONG is the java API implementation of the ONG providing access to ETSI M2M service capabilities. This section
aims at highlighting the different steps required for creating your own ThingLet®. Please refer to ONG java
documentation [SONG-API-Javadoc] for a more detailed explanation on each function.
861
A ThingLet® (aka SONG servlet) is a java-based component that interacts with other M2M entities by initiating
requests and processing response messages through the SONG servlet container. A SONG ThingLet® implements
the SONG servlet interface. SONG ThingLets® are part of M2M applications. A M2M application may be composed
of one or more ThingLet®, hosted by an ONG or a network based AS (ThingPark® is a multi-agent application
framework).
862
All ONG resident ThingLets® related to a given M2M application are usually packaged in an OSGi bundle.
857
858
859
860
863
864
865
4.4.5.1 CREATE YOUR APPLICATION
As seen in section 4.4.3.2 above you have to create your application within the activate method. To do this, you
must use the createApplication method of the SongService:
applicationContext = songService.createApplication("/HelloWorld", "HelloWorld",
null, new HelloWorldTimerListener(), null);
866
867
868
869
870
871
872
873
874
You have to specify the application context path, which will be used as relative path for the corresponding GA GSC
registration (here "/HelloWorld"), the application name "HelloWorld" (which will allow you to identify your
application within the SONG servlet container, e.g. for managing logs) and your listener for timer expiration (which
must implement your own actions to perform on timer expiration event).
4.4.5.2 REGISTER A THINGLET® FOR YOUR APPLICATION
Once the Application has been declared to the GSC, you need to register the associated ThingLet(s):
songService.registerServiceServlet(applicationContext, "/",
"helloWorldServlet", helloWorldServlet, null, null);
875
876
877
878
879
In our example, we only need one ThingLet®. But you may require handling more than a single ThingLet®
depending on the needs of your M2M application.
38/51
Cocoon® project
880
881
882
883
4.4.5.3 RETRIEVE REFERENCE ON LOCAL SCL
Any ThingLet® needs to access the Service Capability Layer (either for reading resources, either for creating some
new resources) that is locally running on the GSC. To do this, the ThingLet® has to register at the Lobby as a
listener for the incoming “m2m:Scl” instance. This is done in init function by invoking:
obixService.registerLobbyEntryListener("m2m:Scl", this);
884
885
886
If the SCL is already known by the Lobby or as soon as the Lobby discovers it, the ThingLet® is notified as it
implements LobbyEntryListener interface:
887
public void lobbyEntryRegistered(Ref ref) {
888
…
889
}
890
891
892
4.4.5.4 THINGLETS®
A ThingLet® is a servlet which must implement the API call back methods for the SONG messages which it needs
to process. These functions are:
893

for the received requests: doCreate, doDelete, doInvoke, doNotify, doRetrieve and doUpdate
894

for the received responses: doErrorResponse, doProvisionalResponse and doSuccessResponse
895
Here is the java class that defines the HelloWorld ThingLet®:
package com.actility.helloworld.servlet;
import java.io.IOException;
import java.io.InputStream;
import java.io.UnsupportedEncodingException;
import java.net.URISyntaxException;
import javax.servlet.ServletException;
import obix.Contract;
import obix.Obj;
import obix.Op;
import obix.Ref;
import obix.Str;
import obix.Uri;
import com.actility.m2m.scl.obix.App;
import com.actility.obix.LobbyEntryListener;
import com.actility.obix.ObixService;
import com.actility.servlet.ApplicationSession;
import com.actility.servlet.TimerService;
import com.actility.servlet.song.SongFactory;
import com.actility.servlet.song.SongServlet;
import com.actility.servlet.song.SongServletRequest;
import com.actility.servlet.song.SongServletResponse;
import com.actility.song.obix.model.RequestCallback;
/**
* HelloWorld application sample.
*
39/51
Cocoon® project
* @author mlouiset
*
*/
public class HelloWorldServlet extends SongServlet implements LobbyEntryListener {
/**
* for serialization, required for TimerListener implementation
*/
private static final long serialVersionUID = 1845993818490508756L;
private static final Logger LOG = Logger.getLogger(HelloWorldServlet.class);
private ObixService obixService;
private SongFactory factory;
private TimerService timerService;
private ApplicationSession appSession;
private String helloWorldWords;
/**
* Attribute names
*/
public static final String REQUEST_CONTEXT = "hello-world-song-request-context";
private static final String HELLO_WORLD_META_NAME = "meta";
private static final String HELLO_WORLD_ATTR_NAME = "config";
private static final String HELLO_WORLD_OP_NAME = "get";
private static final String HELLO_WORLD_META_REF = "meta";
private static final String HELLO_WORLD_ATTR_REF = "config";
private static final String HELLO_WORLD_OP_REF = "get";
/**
* Constructor
*
* @param obixService the oBIX service for resource handling.
*/
public HelloWorldServlet(ObixService obixService) {
this.obixService = obixService;
}
/**
* helloWorldWords setter
*
* @param helloWorldWords the new helloWorldWords to set
*/
public void setHelloWorldWords(String helloWorldWords) {
this.helloWorldWords = helloWorldWords;
}
/**
* Hello world operation
*
* @return
*/
private Obj doHelloWorld() {
Obj res = new Obj("HelloWorldOut");
res.add(new Str("foo", helloWorldWords));
40/51
Cocoon® project
return res;
}
public void lobbyEntryRegistered(Ref ref) {
// create an Hello World application
// Create a local image of the resource to publish
Obj genRsc = obixService.buildObj(new Contract(new String[] { "m2m:App" }));
genRsc.setName("HelloWorld");
App helloWorldDoc = (App) genRsc;
// remove all RO attributes
helloWorldDoc.remove(helloWorldDoc.acl());
helloWorldDoc.remove(helloWorldDoc.ctm());
helloWorldDoc.remove(helloWorldDoc.mtm());
helloWorldDoc.remove(helloWorldDoc.cnts());
helloWorldDoc.remove(helloWorldDoc.grps());
helloWorldDoc.remove(helloWorldDoc.subs());
helloWorldDoc.stat().set("online");
// Add ref for retrieving meta
Ref retargetedMeta = new Ref(HELLO_WORLD_META_NAME);
retargetedMeta.setHref(new Uri(HELLO_WORLD_META_REF));
// Add retargeting path
Ref retargetRef = new Ref(HELLO_WORLD_ATTR_NAME);
retargetRef.setHref(new Uri(HELLO_WORLD_ATTR_REF));
Op retargetOp = new Op(HELLO_WORLD_OP_NAME);
retargetOp.setHref(new Uri(HELLO_WORLD_OP_REF));
// provides apoc and apath for retargeting
try {
helloWorldDoc.apoc().set(factory.createLocalURIFrom(getServletContext().getContextPath()).abs
oluteURI() + "/");
} catch (URISyntaxException e) {
LOG.error("Unable to parse URI for building apoc", e);
} catch (ServletException e) {
LOG.error("Unable to create URI for building apoc", e);
}
helloWorldDoc.apath().add(retargetedMeta);
helloWorldDoc.apath().add(retargetRef);
helloWorldDoc.apath().add(retargetOp);
// update GSC resource anyway
new
SongCreateRequestHandler().sendCreateRequest(obixService,
factory, ref.getHref().get(),
(Obj) helloWorldDoc);
this,
appSession,
}
public void lobbyEntryUnregistered(String href) {
// LOG.info("lobbyEntryUnregistered - " + href + " unregistered from local lobby");
}
/**
* Start the servlet
*/
41/51
Cocoon® project
public void init() throws ServletException {
LOG.debug("init");
timerService = (TimerService) getServletContext().getAttribute(TIMER_SERVICE);
factory = (SongFactory) getServletContext().getAttribute(SONG_FACTORY);
if (null == timerService) {
throw new ServletException("timer service is not available");
}
if (null == factory) {
throw new ServletException("SONG factory is not available");
}
// Create an application session to periodically wake-up and probe the resource
try {
appSession = factory.createApplicationSession();
throw new ServletException("Failed to create Hello World application session");
}
obixService.registerLobbyEntryListener("m2m:Scl", this);
}
/**
* Stop the servlet
*/
public void uninit() {
LOG.debug("uninit");
}
/**
* Send back re-targeted attribute value
*
* @param request the received SONG request.
*/
public void sendHelloWorldWords(SongServletRequest request) throws IOException {
SongServletResponse response = null;
try {
Str helloWorld = new Str(helloWorldWords);
byte[] content = obixService.encode(helloWorld);
response = request.createResponse(SongServletResponse.SC_OK);
response.setContent(content, "text/xml; charset=utf-8");
} catch (UnsupportedEncodingException e) {
// response encoding issue.
LOG.error("doRetrieve - unable to set the response content", e);
response = request.createResponse(SongServletResponse.SC_SERVER_INTERNAL_ERROR);
// oBIX encoding issue
LOG.error("doRetrieve - oBIX encoding issue", e);
}
response.send();
}
42/51
Cocoon® project
/**
* Update re-targeted attribute value
*
* @throws IOException
* @throws Exception
*/
public void updateHelloWorldWords(SongServletRequest request) throws IOException {
// decode content
Obj requestContent = null;
if (0 != request.getContentLength()) {
byte[] rawContent;
try {
rawContent = request.getRawContent();
requestContent = obixService.decode(rawContent, "UTF8", false);
} catch (IOException e) {
LOG.error("updateHelloWorldWords - unable to retrieve request content", e);
LOG.error("updateHelloWorldWords - unable to decode oBIX content", e);
}
}
if ((requestContent != null) && (requestContent.isStr())) {
helloWorldWords = ((Str) (requestContent)).get();
response = request.createResponse(SongServletResponse.SC_ACCEPTED);
} else {
response = request.createResponse(SongServletResponse.SC_BAD_REQUEST);
}
response.send();
}
/**
* Send back meta data that describe the ThingLet contract.
*
*/
public void sendMeta(SongServletRequest request) throws IOException {
try {
StringBuffer readMeta = new StringBuffer();
InputStream
in
this.getClass().getClassLoader().getResourceAsStream("meta/meta.xml");
=
byte[] buf = new byte[1024];
while (true) {
int len = in.read(buf, 0, buf.length);
if (len <= 0) {
break;
}
readMeta.append(new String(buf, 0, len));
}
43/51
Cocoon® project
in.close();
response.setContent(readMeta.toString().getBytes(), "text/xml; charset=utf-8");
}
response.send();
}
/**
* Invoke Hello World method and send back the result.
*
* @throws IOException
*/
public void invokeHelloWorldMethod(SongServletRequest request) throws IOException {
Obj result = doHelloWorld();
try {
byte[] content = obixService.encode(result);
response.setContent(content, "text/xml; charset=utf-8");
// oBIX encoding issue
LOG.error("doRetrieve - oBIX encoding issue", e);
}
response.send();
}
public void doRetrieve(SongServletRequest request) throws ServletException, IOException {
String requestPath = request.getPathInfo();
LOG.debug("doRetrieve (getPathInfo:" + requestPath + ")");
}
if (requestPath.endsWith(HELLO_WORLD_ATTR_REF)) {
sendHelloWorldWords(request);
} else if (requestPath.endsWith(HELLO_WORLD_META_REF)) {
sendMeta(request);
} else if (requestPath.endsWith(HELLO_WORLD_OP_REF)) {
invokeHelloWorldMethod(request);
} else {
44/51
Cocoon® project
request.createResponse(SongServletResponse.SC_NOT_FOUND);
}
}
public void doUpdate(SongServletRequest request) throws ServletException, IOException {
LOG.debug("doUpdate (getPathInfo:" + requestPath + ")");
}
if (requestPath.endsWith(HELLO_WORLD_ATTR_REF)) {
updateHelloWorldWords(request);
} else {
}
}
public void doInvoke(SongServletRequest request) throws ServletException, IOException {
LOG.debug("doInvoke (getPathInfo:" + requestPath + ")");
}
if (requestPath.endsWith(HELLO_WORLD_OP_REF)) {
invokeHelloWorldMethod(request);
} else {
}
}
public void doSuccessResponse(SongServletResponse response) throws IOException {
RequestCallback
callback
response.getRequest().getAttribute(REQUEST_CONTEXT);
callback.success(null);
=
(RequestCallback)
}
public void doErrorResponse(SongServletResponse response) throws IOException {
RequestCallback
callback
response.getRequest().getAttribute(REQUEST_CONTEXT);
callback.error(null);
=
(RequestCallback)
}
}
896
Here in the HelloWorld example, we need to support following incoming SONG requests:

SONG RETRIEVE request (for reading the /gsc/apps/HelloWorld/config re-targeted attribute or
/gsc/apps/HelloWorld/meta re-targeted attribute),
899

SONG UPDATE request (for writing the /gsc/apps/HelloWorld/config re-targeted attribute value),
900

SONG INVOKE request (for invoking the /gsc/apps/HelloWorld/get operation).
897
898
45/51
Cocoon® project
902
As HelloWorld sends SONG requests, we also need to implement treatment for incoming SONG 2XX response
(doSuccessResponse) and SONG 3XX, 4XX and 5XX responses (doErrorResponse).
903
Other methods to implement are init and uninit to manage servlet initialization and un-initialization phases.
901
904
905
906
907
908
4.4.5.5 SONG FACTORY
The SONG factory is the facility offered by the SONG API to simplify the handling of ETSI M2M requests and
responses. Here is an example on how you can use the SONG factory to send a SONG CREATE request, after
HelloWorld start-up and when the timer started in init expires. The request is built and sent in method
sendCreateRequest:
package com.actility.helloworld.servlet;
import java.io.IOException;
import java.net.URISyntaxException;
import obix.Obj;
import com.actility.obix.ObixService;
import com.actility.servlet.ApplicationSession;
import com.actility.servlet.song.SongFactory;
import com.actility.servlet.song.SongServletRequest;
import com.actility.servlet.song.SongURI;
import com.actility.song.obix.model.RequestCallback;
/**
* Handle RETRIEVE response for Example1 application
*
* @author mlouiset
*
*/
public class SongCreateRequestHandler implements RequestCallback {
private static final Logger LOG = Logger.getLogger(SongCreateRequestHandler.class);
/*
* (non-Javadoc)
*
* @see com.actility.song.obix.model.RequestCallback#success(java.lang.Object)
*/
public void success(Object result) {
LOG.info("HelloWorld resource created successfully");
}
/*
* (non-Javadoc)
*
* @see com.actility.song.obix.model.RequestCallback#error(java.lang.Throwable)
*/
public void error(Throwable t) {
LOG.info("error - unable to create resource");
}
46/51
Cocoon® project
/**
* Sends the SONG CREATE request
*
* @param obixService the oBIX service
* @param servlet Example1Servlet instance to notify for the result.
* @param appSession application session associated to the Example1Servlet instance
* @param factory SONG factory
* @param gscUri local URI of the GSC
* @param helloWorldDoc document that exposes the Hello World application
*/
public
void
sendCreateRequest(ObixService
ApplicationSession appSession,
obixService,
HelloWorldServlet
servlet,
SongFactory factory, String gscRef, Obj helloWorldDoc) {
// send a SONG RETRIEVE request to get the targeted resource
try {
SongURI toUri = factory.createURI(gscRef + "/apps/");
SongServletRequest
songRequest
=
factory.createRequest(appSession,
SongServletRequest.MD_CREATE, null, toUri);
byte[] content = obixService.encode(helloWorldDoc);
songRequest.setContent(content, "text/xml; charset=utf-8");
songRequest.setHeader("Expected-ID", helloWorldDoc.getName());
songRequest.setAttribute(HelloWorldServlet.REQUEST_CONTEXT, this);
LOG.debug("Send
SONG
CREATE
request
songRequest.getToURI().absoluteURI() + ") (content:\n"
+ new String(songRequest.getRawContent()) + ")");
(To:"
+
}
songRequest.send();
} catch (URISyntaxException e) {
LOG.error("sendUpdateRequest - fail to create URI", e);
} catch (IOException e) {
LOG.error("sendUpdateRequest - fail to send request", e);
}
}
public void provisional(Object result) {
// TODO Auto-generated method stub
}
}
909
910
911
In case of a success response (public void success(Object result) method) or an error response
(public void error(Throwable t) method), “HelloWorld” generates a log entry.
47/51
Cocoon® project
912
4.4.6 INSTALLING AND RUNNING YOUR BUNDLE
913
4.4.6.1 BUNDLE INSTALLATION
914
915
916
917
918
919
920
To install your bundle, you simply have to copy the jar file into the OSGi deployment folder (i.e. “load” sub-folder
for Knopflerfish server). It should start automatically.
4.4.6.2 AND THEN, WHAT DOES HELLOWORLD?
Then you should check that your application runs as expected. In the GSC applications list, you should see the
HelloWord application resource:
>>> GET /gsc/apps/ HTTP/1.1
Host: 10.10.12.202:8080
922
Content-Length: 0
Accept-Language: en
923
User-Agent: Mozilla/5.0
924
Content-Type: application/xml; charset=UTF-8
Accept: */*
921
925
926
927
<<< 200 OK
928
929
930
931
932
933
934
935
<ref name="acl" href="/gsc/acrs/1b86b74f25b8ec93/" is="m2m:Acr"/>
937
<ref href="HelloWorld/"/>
</list>
938
</obj>
936
939
940
941
942
943
You should then retrieve the HelloWord document resource itself:
>>> GET /gsc/apps/HelloWorld HTTP/1.1
Host: 10.10.12.202:8080
Content-Length: 0
945
Accept-Language: en
946
947
Accept: */*
944
948
949
<<< 200 OK
950
951
952
953
954
955
956
957
958
959
960
<uri name="apoc" href="apoc/" val="song://CYH-00606E33445F:6070/HelloWorld/"/>
<ref name="cnts" href="cnts/" is="m2m:Cnts"/>
<uri name="apoc" val="song://localhost:8080/HelloWorld"/>
<list name="apath" href="apath/">
<ref href="config/"/>
<op href="get/" in="obix:obj" out="obix:obj"/>
<ref href="meta/"/>
</list>
<ref name="grps" href="grps/" is="m2m:Grps"/>
48/51
Cocoon® project
961
962
963
964
<ref name="acl" href="/gsc/acrs/153eb06eab6a76a6/" is="m2m:Acr"/>
<list name="srch" of="obix:str"/>
966
<abstime name="etm" val="1970-01-01T01:00:00.000+01:00" tz="Europe/Paris"/>
<enum name="stat" val="unregistered"/>
967
<ref name="ncs" href="ncs/" is="m2m:Ncs"/>
968
</obj>
965
969
970
971
972
973
974
975
You should access the ThingLet® contract:
>>> GET /gsc/apps/HelloWorld/meta HTTP/1.1
Host: 10.10.12.202:8080
Content-Length: 0
Accept-Language: en
977
978
Accept: */*
976
979
980
<<< 200 OK
981
982
983
984
985
986
987
<obj href="/gsc/apps/helloWord/">
<str href="meta/" val="" display="Describes
description"/>
retargeted
<str href="config/" val="" display="Configures
operation" displayName="Configuration" writable="true"/>
989
<op href="get/" in="obix:null" out="#HelloWorldOut" display="Get
string" displayName="HelloWorld">
990
<obj name="out" href="#HelloWorldOut">
991
<str name="foo" val=""/>
</obj>
988
992
993
994
resources" displayName="Meta
the
get()
the
Hello
World
</op>
</obj>
995
996
997
998
999
1000
You should change the “config” value:
>>> PUT /gsc/apps/HelloWorld/config HTTP/1.1
Host: 10.10.12.202:8080
Content-Length: 0
Accept-Language: en
1002
1003
Accept: */*
1001
1004
1005
1006
<str val="My Hello World !!!" />
1007
1008
<<< 202 ACCEPTED
1009
1010
1011
1012
1013
1014
And finally invoke the HelloWorld operation:
>>> POST /gsc/apps/HelloWorld/HelloWorld HTTP/1.1
Host: 10.10.12.202:8080
Content-Length: 0
Accept-Language: en
49/51
Cocoon® project
1015
1016
1017
1018
X-Acy-Method: Invoke
Accept: */*
1019
1020
<<< 200 OK
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
<obj name="HelloWorldOut">
<str name="foo" val="My Hello World !!!" />
</obj>
4.5 ACCESSING THE ONG VIA AN ETSI M2M CORE NETWORK
In the examples provided so far, ONG resources are managed via direct HTTP requests. In a real deployment ONG
resources would be read by the ETSI M2M network service capability layer (NSC), over a secure connection.
The ONG supports networked operations. For this preview release, Actility provides access to a hosted ETSI M2M
NSC, and provides a toolkit for NA application development (see [SCL-M2M-REST] and [ZigBee-M2M-REST]), as well as a
sample NA, the ONG browser.
Please contact Actility support (http://cocoon.actility.com/) in order to register your ONG box at our NSC, and thus
benefit of ONG browser functionalities.
The ONG browser offers a GUI to browse and interact with the ONG M2M resources, and fully supports the ONG
ZigBee GIP resources. Please refer to [ONG-Browser] document for further details on ONG Browser.
1036
50/51
Cocoon® project
1037
5. TABLE OF FIGURES
1038
1039
Figure 1: M2M applications and their representation .........................................................................................7
1040
Figure 2: ETSI TC M2M functional architecture .................................................................................................8
1041
Figure 3: ThingPark® physical architecture .......................................................................................................9
1042
Figure 4: ONG : object network profiles and protocol bindings ........................................................................10
1043
Figure 5: ONG software stack ..........................................................................................................................12
1044
Figure 6: ONG internal architecture (ZigBee/ETSI TC M2M interworking) ......................................................13
1045
Figure 7: ZigBee network interface in ETSI M2M .............................................................................................13
1046
Figure 8: DAs created by the ZigBee GIP, name conventions and usage of containers .................................14
1047
Figure 9: ZigBee on/off light sample (0x0104 profile) .......................................................................................15
1048
Figure 10: ZigBee on/off switch sample (0x0104 profile) .................................................................................15
1049
Figure 11: GSC resource hierarchy ..................................................................................................................17
1050
Figure 12: ONG Browser, showing a ZigBee coordinator installed on MyGateway .........................................19
1051
Figure 13: ONG browser, device view ..............................................................................................................21
1052
Figure 14: ONG Browser, accessing an attribute .............................................................................................22
1053
Figure 15: ONG Browser, creating a subscription ............................................................................................23
1054
Figure 16: ZigBee HAN representation on ONG ..............................................................................................24
1055
Figure 17: ZigBee GIP discovery activity flow ..................................................................................................25
1056
Figure 18: ZigBee GIP mirroring activity flow ...................................................................................................26
1057
Figure 19: ZigBee GIP COV reporting ..............................................................................................................27
1058
1059
51/51

ONG tutorial - Cocoon

Transcription

Similar documents

x-active Product Flyer en.cdr

opusdei.ca

Lab A3-3 The Åstrand-Rhyming Cycle Ergometer Test for Assessing

M2M Ecosystem Development

Read More - Edric Ong

Specifications are subject to change, please see your MODACOM

about M2M TV

Minutes from the January 13, 2016 Meeting

THE CULTURE OF TEACHING AND LEARNING - apjee