This week I'm going to try and give a basic overview
of oBIX for people who aren't necessarily
developers. I'm not going to into semantics or
anything remotely in depth so for further
information please read Brian's oBIX specification
document - it really is an excellent guide. The
specification is available from the OASIS website
listed below.
oBIX (Open Building Information
Exchange) Web Services represents an open standard
for third parties to interact with the Niagara AX
framework. Here are some useful URLs to get you
started...
So if you click on the first link, you'll notice
you can navigate your way around a Station and get
back XML documents when clicking on the hyperlinks.
This is because oBIX is based upon the REST standard
for web services. Furthermore, you'll notice each
object in oBIX is an XML document and can be
identified by its own unique URL. Ok, so far so
good?
To replicate the online oBIX server, simply
create a new Station (ensure you have an oBIX
license) and add an ObixNetwork to it. You can now
view the oBIX for the Station by surfing to http://localhost/obix.
Well clicking around the demo Station is as about
as exciting as watching paint dry - so let's go a
bit further. By communicating with an oBiX server
you can...
- Read and write oBIX objects (Points are
bound to be of primary interest to the reader)
- Get back histories (logs)
- Get back alarms
This is were ORT comes in (Obix Request Test).
Please download the Jar file from this article and
place it into your modules directory. This is a
rudimentary Java program that allows users to fire
off HTTP GET, POST and PUT requests to an oBIX
server. Now we need to start ORT by opening a
command prompt (Windows Start -> Niagara -> Your
Niagara Installation -> Console) and entering
nre obixRequestTest:com.tridium.ort.BObixRequestTest.
Now you've got ORT up and running, please ensure you
have an 'admin' user set up with no password.
The good news is that's the difficult part over
and done with. You notice the bottom text field
takes a URL. We can conveniently cut and paste URLs
from our open web browser to make life easier. If
you now hit the 'Send' button, you'll notice the
right hand text editor fills up with the result from
the HTTP GET request. The default response is the
Lobby we got back from when we logged with a web
browser.
Open Workbench, go back to your demo Station and
add a Folder and a NumericWritable to it. Place the
NumericWritable into the middle of your Wiresheet.
Keep the Wiresheet view open because now comes the
fun part!
Go back to ORT and paste in 'http://localhost/obix/config/Folder/NumericWritable'
and hit the 'Send' button. Note how we get back
quite a large XML document that we recognize as a
NumericWritable (see the in1 to in16 Properties).
Note at the bottom of the XML document, we have a
String Property called 'wsAnnotation'. This holds
the position of the component on the Wiresheet. We
are now going to change the position of this
component through oBIX. Because the Property has
'writable=true', we can perform an oBIX Write.
[an error occurred while processing this directive]
To perform the oBIX Write, change the URL to
'http://localhost/obix/config/Folder/NumericWritable/wsAnnotation'
and switch from HTTP GET to PUT via the drop down
list. Now add the following code into the left hand
text editor window <str val="10,10,10" />.
Finally, hit the 'Send' button and watch the
component on your Wiresheet move and resize.
Congratulations, you've just performed an oBIX
Write!
Let's recap on what we've done though. The first
part was navigating our way around the Station via a
Web browser. This was performing an oBIX Read (via
an HTTP GET) to view some oBIX. Next we decided we
wanted to write to a component on the Station. To do
this we needed to know the URL of the component we
were writing to and the figure out the XML for the
argument we were going to perform the HTTP PUT with.
Now let us note one important factor, we just can't
perform an oBIX Write to anything on our Server; the
object has to be marked up with the 'writable=true'
attribute.
So the next question you have will probably be
'That's great but how can I execute an Action on
a Station; like a 'set' Action on a NumericWritable
or perhaps an 'execute' on a Program Object?'.
A good question and one that'll answer in part 2.
By the way, please add any comments to this blog
article if you find it useful!
Came
across this valuable information in the Niagara Blog on how to actually use oBIX!
Good stuff thanks Gareth.
