This page last changed on Dec 02, 2009 by admin.

The first draft of Controller 2.0 REST API (this is the API between panels and other external client software that wants to integrate with OR Boss controller) is online at Controller 2.0 API Documentation

Short summary of the changes:

  • (1) & (2): Multiple panel UI definitions can be returned from the controller. The panels can be configured for a specific panel UI, e.g. "MyIphone", "MomsIphone", "WallPanel", "JaysAndroid". There's a logical identifier that allows each user to have their customized UI definition.
  • (3): more built in command parameters for new UI components such as a slider (has a integer value state), or a switch (ON/OFF), or gestures
  • (4): Request a status update for a specific list of UI component IDs
  • (5): Same as #4 except the controller is handling this as a delayed request (suitable for server push): The request in (5) is not returned until there's an update to component state that the panel client does not already have or the request eventually times out due to no device status updates. Normally in the latter case the panel client recreates the request, therefore giving an impression of status push on a unidirectional HTTP request-response protocol.

The Controller 2.0 API and implementation will not be compatible with Controller 1.0 implementations.

What would you think about allowing JSON-P (http://en.wikipedia.org/wiki/JSON#JSONP) responses for all APIs (including the /controller/ one) ?
This would allow to develop the Web Console without the servlet that proxies AJAX requests (like it is built right now) and by extension make possible to deploy it as just a pure JS/HTML web page - without the need to have a web container on the panel/computer that runs the Web Console.

Posted by jvelociter at Dec 12, 2009 18:07

If you were planning on submitting a patch, go for it!

Posted by juha at Dec 12, 2009 23:01

Hi Juha,

I am looking forward to version 2.0 of the controller . Until then, I still have some questions about it, if you don't mind:

  • How do you map status updates from your connectors (such as KNX) to your components (or shall I say "item" or "device" or "command"? I am not yet clear on the vocabulary you use here...)? My question derives from the fact that in KNX the status is sent on a different group address than the command is sent to the actor; so how are these two (or more) group addresses associated?
  • Another important question about the handling of updates: A smart home should actually not require you sending commands all the time; instead, it should mainly inform you about the current status. So on my UI, I usually have a lot of information displayed, without this being associated to a button/command. Most of this information comes from KNX: room temperatures, brightness, motion detection, cistern level etc. Is there already a concept of how these can be modeled and supported in the UI?
  • Talking about sliders, switches and gestures: Does your component model actually know the notion of data types? E.g. could an item have a boolean datatype and I can decide how this is rendered on the different panels (one time as a checkbox, one time as a button, one time as a text field and another time an toggling icon)?
  • Does the OR Boss follow the MVC pattern? If so, why does the controller care about view-related stuff (panels, UI components etc.) at all?

Cheers,
Kai

Posted by kkreuzer at Dec 14, 2009 20:37

How do you map status updates from your connectors (such as KNX) to your components (or shall I say "item" or "device" or "command"? I am not yet clear on the vocabulary you use here...)? My question derives from the fact that in KNX the status is sent on a different group address than the command is sent to the actor; so how are these two (or more) group addresses associated?

There are two decoupled cycles here:

#1 is the controller<->device loop where the protocol implementation API in 2.0 and forward has a method that needs to be implemented for device status – either a polling command to retrieve the status in case of passive devices, or a listener implementation in case of active state updates pushed by devices.

#2 is the cycle between panel<->controller which returns the state to panels as it exists in the controller at that point in time due to the loop in #1. UI components in the controller exist as an ID integer by which they are associated to commands or status event.

The actual protocol implementations still need to be worked on.

Regarding vocabulary, I've settled on "command" being an action we want to execute on a device, and "event" being something pushed by a device that a controller can listen on.

Another important question about the handling of updates: A smart home should actually not require you sending commands all the time; instead, it should mainly inform you about the current status. So on my UI, I usually have a lot of information displayed, without this being associated to a button/command. Most of this information comes from KNX: room temperatures, brightness, motion detection, cistern level etc. Is there already a concept of how these can be modeled and supported in the UI?

Yes. It should be part of this discussion Re: Changes for the iphone.xml but I haven't yet updated it with component update related details regarding <monitor> (now renamed to <sensor>), <slider>, <image> and <label> components.

It's been on my TODO list for a while so I'll try to get to updating this information.

In short, it goes like this:

Components other than <button> can be linked to state updates either implicitly (<switch> to boolean state, active <slider> to integer state) or explicitly via <sensor> components linked to <label>, <image> and passive <slider>.

Where a <label> or <image> is linked to a sensor, it receives its string label value or image source to render based on the state string returned by the <sensor> as part of the update cycle in loop #2 above, instead of displaying a static image or label.

Talking about sliders, switches and gestures: Does your component model actually know the notion of data types? E.g. could an item have a boolean datatype and I can decide how this is rendered on the different panels (one time as a checkbox, one time as a button, one time as a text field and another time an toggling icon)?

At low level, yes. UI Components are mapped via their UI ID to commands or status events. Therefore a single status can be represented by multiple UI components in panel display.

Switches are boolean types, slider state is an integer value. Labels can display string-based state values and <image> elements can map image sources to a specific state value in a <sensor>.

Sensor elements, like commands, are part of the controller model and are decoupled from the view components. Therefore a single command definition can be mapped to multiple button or gesture elements in the UI for example, or a <sensor> can have multiple UI components bound to it.

Does the OR Boss follow the MVC pattern? If so, why does the controller care about view-related stuff (panels, UI components etc.) at all?

Yes of course. Panels only have the view whereas the controller manages the control (obviously) and the model. Controller maps UI component IDs to actions (device commands or events) that can modify the model data (which is often in the device itself). The panel.xml contains the UI definition and has no bearing on the controller other than

1) the controller serves it to panels on request to render the UI
2) the panel.xml contains a UI component ID which corresponds to an ID mapping to action/event on the controller.xml side

Posted by juha at Dec 15, 2009 16:48

Regarding vocabulary, I've settled on "command" being an action we want to execute on a device, and "event" being something pushed by a device that a controller can listen on.

Ok, I've got these two, let's also address the other fuzzy things:

  • we have a controller.xml as a configuration of the controller
  • we have a panel.xml (previously iphone.xml, is this correct?) for the views (being served by the controller), defining UI components (I'd prefer the terms widget or UI control), i.e. buttons, sliders, labels, etc.
  • the controller.xml does the mapping between view and data - in this case between "UI components" and commands/events.

A few (new) questions are now left:

  1. Wouldn't it make sense to also model the data part? As described above, the controller refers to the data element using commands/events. I see several problems with this:
    • The reference to a data element contains low-level technical information (like KNX group addresses or TCP/IP ports) - this is no good separation of concerns and does not allow the technical configuration to be done independently from the rest.
    • The incoming status update events are nowhere clearly associated to a data element - they are only linked to UI components.
    • The points above lead to a too fine-grained data model (which will be horrible to maintain); there should not be one data element for "turn light on" and another for "turn light off", but IMHO the data model should be on a higher, more logical level. We could have model elements such as "window blinds kitchen" with possible commands "move up", "move down", "step up", "step down", "move to 30%" and listening to incoming events like "blinds are up" or "blinds are at 60%".
    • You do not have an explicit data type for your data elements; their data type is rather inferred from the associated UI component, which is not good as the data model should be view-independent.
    • You need to update the UI composer for every new technical connector (and I'll come up with many more!) - if you had a logical data model with a global set of data types, this would not be necessary at all.
    • You cannot store the state of a data element in the ORB (if you have to do so one day)
    • You will have no chance to introduce a rule engine without a data model, right? And looking at the user forum, I have the impression that a rule engine actually IS an often mentioned requirement.
  2. How do UIs get the initial states? Does the UI have to do a (4) request of status update for all its components? This will be way too slow, if the controller passes this over to the devices themselves - note that on KNX this is an asynchronous request, running at a whopping 9600bps. I am quite certain that the controller will have to cache the states here.
  3. Should the UI poll for updates only on the currently visible screen (that's what I understand from your discussions)? So what happens if the user quickly jumps back and forth between the screens? Will this trigger a complete screen update request everytime? Maybe it would be worth to listen for updates of components on other screens in the background as well? Might of course depend on the frequency of updates and the number of screens, but it could be worth to think about.
Posted by kkreuzer at Dec 15, 2009 23:17

Evening folks.

Sounds like you might want to give some thought to a multi-tiered architecture, one having a separate presentation layer and backend.  This is how many commercial webapps work - the backend has a REST interface to heterogeneous clients, including, but not limited to, an in-process presentation servlet. This way you can support new clients since they all consume the same REST interface. What if I want to add a javascript RIA? No problem, just have it consume JSON directly from the backend server. Syndicate over ATOM? Implement an ATOM View (Spring makes this very easy to do, btw, using the AbstractController and a ViewResolver bean). Are we confounding the notion of MVC with the notion of a separate presentation tier? MVC in this sense separates business objects (the model) from their representation (ATOM/XML/JSON, etc).

As someone experienced with writing enterprise servers using java and spring, and writing open-source automation engines, I'll be following this project with keen interest.

Keep up the good work.

--Mike

Posted by mbieser at Dec 27, 2009 04:09

Hi Mike,

Yes, I would also advocate for a very strict separation of the view layer from the backend as you describe it. I think this would open up OR for many new kinds of (user-)interfaces. As your ATOM example shows, this might make very different approaches possible than with the current panel.xml. Thinking of ATOM, one could even go further and think of IM integration, such as Jabber or Growl. But wait, is this then still a USER interface or rather a new protocol integration...? IMHO, there is no clear separation of these two kinds of interfaces, so could we think of a common specification for both?

Do you consider REST to be the best choice for a backend/controller service? Just wondering as we will have to process many (push) events here, which is not the necessarily optimal for REST.

Posted by kkreuzer at Dec 27, 2009 14:49

>> Do you consider REST to be the best choice for a backend/controller service? Just wondering as we will have to process many (push) events here, which is not the necessarily optimal for REST.

Absolutely. Ideally the interface is kept as "RESTful" as possible. Some take shortcuts here in the case of modify operations, and use URIs like: /device/12345/turn_on .

My personal preference is to stay 100% RESTful by using a uniform resource representation across read AND write ops. For example: PUT /device/12345 with message body: < device state="on"/ > to switch ON a device - Example GET/device/12345 returns: < device id="12345" name="kitchen_lights" state="on" ... />.

This approach requires slightly more parsing on the server side, but there are frameworks that handle this representation-->object mapping (e.g., Spring REST support). GET/PUT/POST/DELETE are really the only commands one needs, and they are the only protocol commands I would expect a client to understand. The application-specific stuff is entirely in the schema (XSD).

Other protocols have no business in the backend server proper. They can be layered on top of the backend, as alternate presentation layers.

--Mike

Posted by mbieser at Dec 27, 2009 21:25

My doubts about REST were rather about the case (5) from above, the server-push status updates, which will result in open HTTP request for data polling. For me, this is just an awkward workaround for an insufficiency that HTTP (and with it REST) has - it is simply not meant to triggered from both sides. What's your view on this?

Posted by kkreuzer at Dec 28, 2009 19:20

Sounds like a job for an event subsystem (e.g., JMS)? I could image an architecture where the client initially synchronizes state with the server, then consumes events to maintain "best effort" consistency with changing system state. Thoughts?

--Mike

Posted by mbieser at Dec 28, 2009 20:31

Ha, that is exactly the answer I wanted to hear
My suggestion was to use the OSGi EventAdmin service as such an event subsystem - see my comment about rule support. If OR would decide to move towards OSGi, this would be directly available (as it is part of the OSGi 4.2 spec) and very easy to use.
One could e.g. use the REST URIs as topic names and use the HTTP body XML as the event payload, so one could stay very close to the REST principles - just allowing either side to send events.

Posted by kkreuzer at Dec 28, 2009 20:58

I like the idea of using OSGI but I think it's bulitin messaging feature is limited to communicating bwtn services in the same osgi container. (plz correct me if wrong here). Besides, I think we would want something more accessible to external clients -there are JMS implementations/bindings that can be consumed by a number of different scripting/programming languages.

Like the idea of maintaining consistency in resource naming and staying RESTful.

--Mike

Posted by mbieser at Dec 28, 2009 21:46

I like the idea of using OSGI but I think it's bulitin messaging feature is limited to communicating bwtn services in the same osgi container.

Yes, but nothing prevents you from opening it up to a cross-container messaging - see the project LightSabre for example, which pushes the EventAdmin to JMS (ok, it's still in an alpha state...). You could also think of Spring remoting JMS to allow JMS communication. As Juha has a strong opinion on keeping a central ORB, I guess the standard setup would anyhow be to have everything running in a single OSGi container - and the EventAdmin would support this in a very lightweight way (no need for a seperate JMS provider like ActiveMQ or others).

If you then want to add special (external) clients that might require JMS or HTTP REST protocols, you can simply add an OSGi bundle to the ORB which offers this service.

Posted by kkreuzer at Dec 29, 2009 09:09
Document generated by Confluence on Jun 05, 2016 09:30