OBIX by Example Version 1.0
Working Draft 02
21 January 2015
Technical Committee:
OASIS Open Building Information Exchange (oBIX) TC
Chair:
Toby Considine ([email protected]), University of North Carolina at
Chapel Hill
Editor:
Ludo Bertsch ([email protected]), CABA
Additional artifacts:
This document is one component of a Work Product that also includes:

Other documents or XML schemas:
TBA
Related work:
This document is related to:

OBIX Version 1.1. Edited by Craig Gemmill. Latest version: TBA
Abstract:
Summary of the purpose of the document
Status:
This Working Draft (WD) has been produced by one or more TC Members;
it has not yet been voted on by the TC or approved as a Committee Note
Draft. The OASIS document Approval Process begins officially with a TC
vote to approve a WD as a Committee Note Draft. A TC may approve a
Working Draft, revise it, and re-approve it any number of times as a
Committee Note Draft.
URI patterns:
Initial publication URI:
http://docs.oasis-open.org/obix/obix-example/v1.0/cnd01/obix-examplev1.0-cnd01.doc.
Permanent “Latest version” URI:
http://docs.oasis-open.org/obix/obix-example/v1.0/obix-examplev1.0.doc.
(Managed by OASIS TC Administration; please don’t modify.)
This is intended as a Non-Standards Track Work Product.
The patent provisions of the OASIS IPR Policy do not apply.
Copyright © OASIS Open 2014. All Rights Reserved.
All capitalized terms in the following text have the meanings assigned to them in the OASIS
Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the
OASIS website.
The limited permissions granted above are perpetual and will not be revoked by OASIS or its
successors or assigns.
This document and the information contained herein is provided on an "AS IS" basis and OASIS
DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY
WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP
RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR
PURPOSE.
obix-example-v1.0-wd02
Non-Standards Track
Working Draft 02
Copyright © OASIS Open 2014. All Rights Reserved.
21 January 2015
Page 2 of 13
[Type the document title]
This document and translations of it may be copied and furnished to others, and derivative
works that comment on or otherwise explain it or assist in its implementation may be prepared,
copied, published, and distributed, in whole or in part, without restriction of any kind, provided
that the above copyright notice and this section are included on all such copies and derivative
works. However, this document itself may not be modified in any way, including by removing
the copyright notice or references to OASIS, except as needed for the purpose of developing any
document or deliverable produced by an OASIS Technical Committee (in which case the rules
applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to
translate it into languages other than English.
This is intended as a Non-Standards Track Work Product.
The patent provisions of the OASIS IPR Policy do not apply.
Table of Contents
1
Introduction ............................................................................................................................. 4
1.1 References (non-normative).................................................................................................. 4
2
Simple Thermostat Example .................................................................................................... 5
2.1 System configuration ............................................................................................................. 5
2.2 Add some OBIX Objects to the Thermostat........................................................................... 6
2.3 My first OBIX exchange.......................................................................................................... 7
2.4 More exchanges .................................................................................................................... 8
2.5 Implement the Lobby object ................................................................................................. 8
2.7 Choose an Encoding Type ...................................................................................................... 9
2.8 Choose a Binding Type........................................................................................................... 9
3
More ...................................................................................................................................... 10
Appendix A.
Acknowledgments ................................................................................................. 11
Appendix B.
Some Appendix ...................................................................................................... 12
Subsidiary Appendix Section ............................................................................................... 12
B.1.1 Sub-subsidiary Appendix Section.................................................................................. 12
Appendix C.
Revision History ..................................................................................................... 13
obix-example-v1.0-wd02
Non-Standards Track
Working Draft 02
Copyright © OASIS Open 2014. All Rights Reserved.
21 January 2015
Page 3 of 13
[Type the document title]
2.6 Implement the About object ................................................................................................. 8
This is intended as a Non-Standards Track Work Product.
The patent provisions of the OASIS IPR Policy do not apply.
1 Introduction
. more . .
1.1 References (non-normative)
[Type the document title]
. more . . .
obix-example-v1.0-wd02
Non-Standards Track
Working Draft 02
Copyright © OASIS Open 2014. All Rights Reserved.
21 January 2015
Page 4 of 13
This is intended as a Non-Standards Track Work Product.
The patent provisions of the OASIS IPR Policy do not apply.
2 Simple Thermostat Example
Let’s start with a simple example of how OBIX could be used for a thermostat.
Assume we are designing a new type of thermostat for a manufacturer (let’s call it “XYZ
company”). The thermostat as usual has a setpoint, which is the desired target temperature
that the heating or cooling system is aiming for. The thermostat also measures the ambient
temperature of the room. However, we want this new thermostat to talk to other
manufacturers’ devices, such as tablets or smart phones. We want to allow a customer to
remain where they are with their tablet or smart phone to change the setpoint of our
thermostat without having to go to the thermostat itself. We also want to allow the customer
to check ambient room temperature through the tablet or smart phone.
Most tablets and smart phones have WiFi capability, and using a web browser app through a
WiFi router can interact with remote websites on the Internet - the tablet or smart phone would
be a “client” and the remote website would be a “server”. Let’s assume our example
thermostat also has WiFi capability and appropriate software to support HTTP web server
capability (it would operate like a remote website). This means the tablet or smart phone
(acting as a client) would have the potential to talk directly to the thermostat, but would not be
able to understand each other without a common language between them. That is where OBIX
fits in - describing a common language so that XYZ Company can design its thermostat so that its
setpoint could be changed by another device from another manufacturer.
Each device would have a unique address (url) on the local network – such as 192.168.1.1 for
the thermostat and 192.168.1.5 for the tablet/smart phone. These addresses allow each device
on the local network to be uniquely identified in the same way www.oasis-open.org identifies
the website of OASIS.
Find below in Figure 1, a diagram showing the devices, functions and flow of information.
obix-example-v1.0-wd02
Non-Standards Track
Working Draft 02
Copyright © OASIS Open 2014. All Rights Reserved.
21 January 2015
Page 5 of 13
[Type the document title]
2.1 System configuration
This is intended as a Non-Standards Track Work Product.
The patent provisions of the OASIS IPR Policy do not apply.
Other Manufacturer
XYZ Company
WiFi Thermostat
(HTTP Server)
192.168.1.1
WiFi Tablet/Smart Phone
(HTTP Client)
192.168.1.5
Change Target
Setpoint Temp
Measured
OBIX
Ambient Temp
Figure 1 – System Configuration
2.2 Add some OBIX Objects to the Thermostat
To represent the thermostat in OBIX, we use “objects” and objects within objects, called “child
objects”. The actual names of the objects are defined by the particular industry involved or the
manufacturer. It is through these agreed-on names that a remote device can understand the
type of products involved. In our example, the overall thermostat object becomes
“thermostat”, the Setpoint temperature becomes “setpoint” and the measured ambient
temperature becomes “ambientTemperature”, see Figure 2 below.
"thermostat"
"setpoint"
"ambientTemperature"
Figure 2 – Thermostat OBIX Objects
obix-example-v1.0-wd02
Non-Standards Track
Working Draft 02
Copyright © OASIS Open 2014. All Rights Reserved.
21 January 2015
Page 6 of 13
[Type the document title]
View Temp
OBIX
This is intended as a Non-Standards Track Work Product.
The patent provisions of the OASIS IPR Policy do not apply.
2.3 My first OBIX exchange
Since our thermostat server might have a number of different functions, let’s put the OBIX
functions within a directory called “myobixdir” (e.g. 192.168.1.1/myobixdir).
For the moment, let’s assume our thermostat has a setpoint (or target) of 73 degrees Fahrenheit
and the ambient room temperature is 68.4 degrees.
Let’s try to read values within the thermostat. If the tablet or smart phone needs the default
information from the thermostat, this can be accomplished by entering into the url address field
of a browser the following: http://192.168.1.1/myobixdir/thermostat
192.168.1.5
(Tablet/Smart Phone)
192.168.1.1
(Thermostat)
/myobixdir
Default
Request
"thermostat"
"setpoint"
Default
Response
"ambientTemperature"
The Response (default) from the Thermostat would be something like:
<obj name="thermostat" href="http://192.168.1.1/myobixdir/thermostat/">
<real name="ambientTemperature" val="68.4" unit="obix:units/fahrenheit"/>
<real name="setpoint" writable="true" val="73" unit="obix:units/fahrenheit"/>
</obj>
The above response uses XML, the most common representation of OBIX data. obj is a defined
OBIX term which indicates overall object definition. <obj starts the definition and </obj> ends
the definition. Other terms, such as real, that do not have other children can end their
definition with /> instead of </real>. For further information on XML, refer to . . . real is a
defined OBIX term to indicate a real number such as 68.4.
obix-example-v1.0-wd02
Non-Standards Track
Working Draft 02
Copyright © OASIS Open 2014. All Rights Reserved.
21 January 2015
Page 7 of 13
[Type the document title]
This is a Request to the thermostat for information. One would get back to the tablet or smart
phone a Response containing default information from the objects and child objects from the
thermostat.
This is intended as a Non-Standards Track Work Product.
The patent provisions of the OASIS IPR Policy do not apply.
name is a defined OBIX term used to uniquely identify objects and children. In this case, it
names “ambientTemperature” which has a value of 68.4 degrees Fahrenheit. val is a defined
OBIX term to indicate value. unit is a defined OBIX term to define the units of measure, which
in this case is Fahrenheit.
One can see that the setpoint of the thermostat has a value of 73 degrees, the target
temperature. Notice that setpoint includes writable=”true”, while ambientTemperature does
not. writable is a defined OBIX term to indicate whether the object under question can be
written to or not. By default, objects cannot be written to (read-only). Since
“ambientTemperature” does not include a writable attribute it is read-only. This makes sense
since it is a measured value at the thermostat and there is no expectation that the tablet would
change its value. On the other hand, the setpoint can be written to and changed by the tablet
or smart phone.
href is a defined OBIX term that indicates the url address of the overall thermostat object.
Find below in Figure 3 a list of the OBIX defined terms used so far.
href
name
Description
url address of object
unique identifier of object
obj
object definition
real
value contains a real number such as 68.4
val
value of object
writable
[Type the document title]
OBIX Defined
Term
indicates whether or not object can be written to
Figure 3
With this Response information the tablet or smart phone could display the present status of
thermostat, including its present setpoint and ambient room temperature.
. more . .
2.4 More exchanges
. more . .
2.5 Implement the Lobby object
. more . .
2.6 Implement the About object
. more . .
obix-example-v1.0-wd02
Non-Standards Track
Working Draft 02
Copyright © OASIS Open 2014. All Rights Reserved.
21 January 2015
Page 8 of 13
This is intended as a Non-Standards Track Work Product.
The patent provisions of the OASIS IPR Policy do not apply.
2.7 Choose an Encoding Type
. more . .
2.8 Choose a Binding Type
[Type the document title]
. more . . .
obix-example-v1.0-wd02
Non-Standards Track
Working Draft 02
Copyright © OASIS Open 2014. All Rights Reserved.
21 January 2015
Page 9 of 13
This is intended as a Non-Standards Track Work Product.
The patent provisions of the OASIS IPR Policy do not apply.
3 More
[Type the document title]
. more . .
obix-example-v1.0-wd02
Non-Standards Track
Working Draft 02
Copyright © OASIS Open 2014. All Rights Reserved.
21 January 2015
Page 10 of 13
This is intended as a Non-Standards Track Work Product.
The patent provisions of the OASIS IPR Policy do not apply.
Appendix A. Acknowledgments
The following individuals have participated in the creation of this specification and are gratefully
acknowledged:
Participants:
[Type the document title]
[Participant Name, Affiliation | Individual Member]
[Participant Name, Affiliation | Individual Member]
obix-example-v1.0-wd02
Non-Standards Track
Working Draft 02
Copyright © OASIS Open 2014. All Rights Reserved.
21 January 2015
Page 11 of 13
This is intended as a Non-Standards Track Work Product.
The patent provisions of the OASIS IPR Policy do not apply.
Appendix B. Some Appendix
. more . .
Subsidiary Appendix Section
. more . .
B.1.1 Sub-subsidiary Appendix Section
[Type the document title]
. more . .
obix-example-v1.0-wd02
Non-Standards Track
Working Draft 02
Copyright © OASIS Open 2014. All Rights Reserved.
21 January 2015
Page 12 of 13
This is intended as a Non-Standards Track Work Product.
The patent provisions of the OASIS IPR Policy do not apply.
Appendix C.
Revision
Revision History
Date
9 Oct, 2014
wd02
21 Jan, 2015
Changes Made
Original
Ludo Bertsch
Start of thermostat example
[Type the document title]
wd01
Editor
obix-example-v1.0-wd02
Non-Standards Track
Working Draft 02
Copyright © OASIS Open 2014. All Rights Reserved.
21 January 2015
Page 13 of 13