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.
Comments (13)
Dec 12, 2009
Jerome Velociter says:
What would you think about allowing JSON-P (http://en.wikipedia.org/wiki/JSON#JS...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.
Dec 12, 2009
Juha Lindfors says:
If you were planning on submitting a patch, go for it!If you were planning on submitting a patch, go for it!
Dec 14, 2009
Kai Kreuzer says:
Hi Juha, I am looking forward to version 2.0 of the controller . Until then, I ...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:
Cheers,
Kai
Dec 15, 2009
Juha Lindfors says:
How do you map status updates from your connectors (such as KNX) to your compon...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.
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.
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.
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
Dec 15, 2009
Kai Kreuzer says:
Regarding vocabulary, I've settled on "command" being an action we want to execu...Ok, I've got these two, let's also address the other fuzzy things:
A few (new) questions are now left:
Dec 27, 2009
mbieser says:
Evening folks. Sounds like you might want to give some thought to a multi-tiere...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
Dec 27, 2009
Kai Kreuzer says:
Hi Mike, Yes, I would also advocate for a very strict separation of the view la...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.
Dec 27, 2009
mbieser says:
>> Do you consider REST to be the best choice for a backend/controller ser...>> 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
Dec 28, 2009
Kai Kreuzer says:
My doubts about REST were rather about the case (5) from above, the server-push ...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?
Dec 28, 2009
mbieser says:
Sounds like a job for an event subsystem (e.g., JMS)? I could image an architect...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
Dec 28, 2009
Kai Kreuzer says:
Ha, that is exactly the answer I wanted to hear My suggestion was to use the OS...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.
Dec 28, 2009
mbieser says:
I like the idea of using OSGI but I think it's bulitin messaging feature is limi...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
Dec 29, 2009
Kai Kreuzer says:
I like the idea of using OSGI but I think it's bulitin messaging feature is limi...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.