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 bottom URL 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.
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!
Update: on request, I've added the source code for ORT.