Design and realization of composable web services for home automation

1. Design and realization of composable web services for home automation Elective in Software and Services Mario Caruso

2. What we are going to see • Brief introduction to home automation systems. • How to make home devices really interoperable • DPWS as a framework for dynamic web services • Implentation of a very simple web service for controlling a lamp • Practical demonstration

3. Smart Home [bus]

4. Devices’ heterogeneity • Home automationsystem A + B

5. Makingdeviceshomogeneus • Deviceshave to speakthe samelanguage. • We must abstract a device from itsspecificprotocol. • Eachdevicehas a software module (proxy) able to communicate with it: • Sendcommands • Listen to sensedevents

6. Protocol independent turnOn() turnOff() turnOn() turnOff() Light A Proxy Light B Proxy Light interface Light interface Light A Proxy Light B Proxy Protocol dependent Protocol A implementation Protocol B implementation A bus B bus Light actuator (System A) Light actuator (System B)

7. SOA • A proxy exposes device’s functionalities as Web Services • Web service pros: • Autonomous • The lifecycle of a proxy is independent from the others • Self-contained functionalities • Interoperable • Abstracts the interface from the implementation (loosely coupled) • Language and platform independent • Remotely invocable • Composable

8. Orchestrator sensor actuator Orchestrator Proxy 2 Proxy 3 Proxy 4 Proxy 1 Proxy 5 Proxies simply act as servers

9. Service implementation • In the next slides we will see how to design and implement services able to control home automation devices. • We will implement services by using the DPWS stack. In particular we will use JMEDS libraries. • http://ws4d.e-technik.uni-rostock.de/jmeds/

10. What is DPWS • DPWS = DevicesProfile for Web Services • a profile is a set of guidelines for how to use Web Services technologies for a given purpose or application. • DPWS is a lightweight subset of WS implementationsparticularly suited for constrained resource devices.

11. DPWS Capabilities • Discoverdevices and theirrelatedservices • Send/Receivemessages to/from devices • Describe WS (through WSDL etc.) • Subscribe and receiveeventsnotifications

12. Rich service description as a contract • When designing/developing a service we start from its rich service description. • The rich service description is composed by three files: • The variabletypedeclaration • The variableinstancedeclaration • The behaviourdescription • In particular the developer must implement the transition system that describes both the conversational behaviour and the physical behaviour.

13. Reminder • How the conversational state differs from the value of a variable? • The conversational state gives an indication about the actions that can be invoked on a service in a specific moment (server-client interaction). • The value of a variable reflects the “physical” state of the device. i.e: the bulb is on or off

14. Conversational state example • Assuming that a lamp is modelled by this transition system: • If the lampis in state A • a client can invoke both turnOn and turnOff operation • But if the lamp is in state B • a client can onlyinvoke the turn on operation turnOn turnOff A B turnOn

15. A working example: DPWSLight DPWSLight service DPWSClient (e.g. Orchestrator) Home automation bus

16. The behaviour model <?xml version="1.0" encoding="UTF-8"?> <service … <ts> <state name="B" type="initial-final"> <transition action="turnOn"> <target state="A" /> <postconditionvariable="light"> <set-valuevalue="0" /> </postcondition> </transition> </state> <state name="A" type="initial-final"> <transition action="turnOff"> <target state="B" /> <postconditionvariable="light"> <set-valuevalue="0" /> </postcondition> </transition> </state> </ts> </service> turnOff / light:=0 A B turnOn / ligth:=1

17. Creating states and variables • Remember: states and variables can assume only a finite set of values in order to makeservices’scompositionfeasible. • By looking at vdd/vml and sbl specifications files we see that allowed states are {A,B} while allowed values for light variable are {0,1}. • Then we create two classes in charge of limiting the possible values: • one to represent the states • and the other to represent the variable

18. Variables and states declaration light_level.vml.xml light-variable.vdd.xml <?xml version="1.0" encoding="UTF-8"?> <variable-model ... name="LightLevel"> <valuevalue="0" id="0"/> <valuevalue="1" id="1"/> </variable-model> <?xml version="1.0" encoding="UTF-8"?> <home name="MyHome" … <variable name="light" type="custom" model="light_level.vml.xml" /> </home> <service … <ts> <state name="B" type="initial-final"> … </state> <state name="A" type="initial-final"> … </state> </ts> </service> light_type.sbl.xml

19. State Class package common; publicclass State { publicfinalstatic String STATE_A = "A"; publicfinalstatic String STATE_B = "B"; private String state; /** * Create a State object and set its value to "off" */ public State(){ this.state = STATE_B; } public String getState(){ returnstate; } publicvoidsetStateA(){ this.state = STATE_A; } publicvoidsetStateB(){ this.state = STATE_B; } }

20. LightDevice class • Then we create a class containing the “business logic” of the lamp. • Such class has: • A state attribute, a light variable (and the related accessor methods) • a method for each action declared (turnOn and turnOff) in the sbl. • Note that this class is the only one aware of the underlying specific home automation protocol. It sends commands to the bus and listens for event coming from the bus.

21. Implementing service behaviour turnOff / light:=0 • Eachmethodreturns a booleanvalueaccording to the sblspecification: • If the current state of the lampis “B” • If on() methodisinvokedthanwe turn on the lamp and returntrue • If off() methodisinvokedthanwereturn false, saying to our client thatisnotpossible to invokesuchaction in the currentconversational state A B turnOn / ligth:=1

22. On method /** * Turns on the light */ publicboolean on(){ booleanresult = false; if (state.getState().equals(State.STATE_B)){ /* * Here the developer inserts protocol dependent instructions * to actuate the light. */ EDSbus.sendBMCOutputControl(deviceNumber, sendingNumber, outputChannel, true); result = true; } return result; }

23. LightDevice class • LightDevice • boolean on() • boolean off() • String getState() • intgetVariable() 1..1 State Variable 1..1 Home automation bus

24. Adding web service capabilities to our lamp • So far we developed a few classes able to communicate with the bus, in particular the LightDevice class. • Now we will make it accessible through web services. 1..1 State LightDevice Variable 1..1

25. Adding web service capabilities to our lamp Device 1..1 1..* Service 1..1 1..* Operation OnOperation 1..1 1..1 State OffOperation LightDevice 1..1 Variable DPWSLight 1..1 LightService 1..1 GetStateOperation 1..1 1..1 GetValueOperation 1..1 1..1 GetSarOperation

26. DPWSLight class publicclassDPWSLightextendsDefaultDeviceimplementsStateChangedListener publicDPWSLight(LightDevice light) { super(); … this.light = light; service = newLightService(); OnOperationonOp = newOnOperation(light); OffOperationoffOp = newOffOperation(light); GetStateOperationgetStateOp = newGetStateOperation(light); GetValueOperationgetValueOp = newGetValueOperation(light); GetServiceArchiveOperationgetSarOp = newGetServiceArchiveOperation(); service.addOperation(onOp); service.addOperation(offOp); service.addOperation(getStateOp); service.addOperation(getValueOp); service.addOperation(getSarOp); … this.addService(service);

27. OnOperation publicclassOnOperationextends Operation{ privateLightDevicelight; privatestatic String retvalue = "result"; privatestatic String ns = "ns”; publicOnOperation(LightDevicelightdev){ super("turnOn",newQName("BasicService", ns)); light = lightdev; Element result = new Element(newQName(retvalue, ns), SchemaUtil.getSchemaType(SchemaUtil.TYPE_STRING)); this.setOutput(result); } @Override publicParameterValue invoke(ParameterValuepv) throwsInvocationException { System.out.println("Light is on!"); boolean ret = light.on(); ParameterValue result = createOutputValue(); if (ret){ ParameterUtil.setString(result, "reply","true"); } else{ ParameterUtil.setString(result, "reply","false"); } return result; } Exactly the name of the action declared in the sbl Call to the on method of LightDevice (protocol-specific)

28. The service archive • Thanks to the WSDL of the service, the client can make syntactically correct invocations of the operations • A client of our lamp service can retrieve its rich description by invoking a specific WS operation: GetServiceArchive. • The latter return a zip file containing • The variabletypedeclaration (light_level.vml.xml) • The variableinstancedeclaration (light-variable.vdd.xml) • The behaviourdescription (light_type.sbl.xml) • At this point the client knows the behaviour of a lamp and can make semantically correct invocations of the operations. • For example it knows that if the service is in conversational state B then it should not invoke the turnOff operation • and if it invokes the turnOn operation the value of the light variable will be 1 (it knows how an operation affects the environment)

29. GetServiceArchieveOperation publicclassGetServiceArchiveOperationextends Operation{ privatestatic String retvalue = "result"; privatestatic String ns = "ns" ; publicGetServiceArchiveOperation(){ super("getServiceArchive",newQName("BasicService", ns)); ComplexTyperqComplex = newComplexType(newQName("AttachmentType", ns), ComplexType.CONTAINER_SEQUENCE); rqComplex.addElement(new Element(newQName("File", ns), SchemaUtil.getSchemaType(SchemaUtil.TYPE_BASE64_BINARY))); Element messageOUT = new Element(newQName("AttachmentMsg", ns)); messageOUT.setType(rqComplex); this.setOutput(messageOUT); } publicParameterValue invoke(ParameterValuepv) throwsInvocationException { System.out.println("Get service archive invoked!!!"); ParameterValue result = createOutputValue(); try { ParameterUtil.setAttachment(result, "File", DPWSFramework.getAttachmentFactory().createFileAttachment("resources/service_archive/BedroomLight.zip", "application/zip")); } catch (IOException e) { System.out.println(e.getMessage()); } return result; } } An Attachment is binary data which is attached to a SOAP message. The attachment isn’t transmitted inline the SOAP part of the message, but appended to the SOAP message by the use of the MIME format.

30. Client-server interaction Client DPWSLight “Hello” syntax GetServiceArchive Service archive (zip file) syntax + semanthics GetState State = A turnOff

31. Asynchronous events • So far we have seen only synchronous operations to retrieve the state/variable of our lamp. • A client can invoke the turnOn operation and, when the operation returns, it can check the conversational state by invoking the GetState operation • What happens if a user in the house presses a wall mounted light switch controlling the lamp? • The service must be aware of the event and change its internal representation of the device

32. Asynchronous events publicclassLightDeviceimplementsBusIndicationListener{ … @Override publicvoidonIndication(BusEventIndicationbei) { logger.info(bei.toString()); if(bei.getValue()==100){ variable.setValueOn(); state.setStateA(); notifyState(); notifyValue(); } else{ if(bei.getValue()==0){ variable.setValueOff(); state.setStateB(); notifyState(); notifyValue(); } } } … privatevoidnotifyValue(){ Iterator<VariableChangedListener> it = valueListeners.iterator(); logger.info("Notifying the change of value to all the listeners"); while (it.hasNext()){ VariableChangedListenercurrentListener = it.next(); logger.fine("Notifying to listener: " + currentListener.getClass().getName()); currentListener.VariableChanged(variable); } }

33. Asynchronous events DefaultEventSource 1..1 State 1..1 LightDevice DPWSLight 1..1 LightService Client (subscribed to the event source) SimpleValueNotification Variable 1..1 1..1

34. Clients • Thanks to DPWS libraries you can develop a custom client able to track the service dynamically, invoke operations and detect events. • But now we will see a generic and universal DPWS client in action…

35. DPWS Explorer Device Service Endpoint reference PortTypes Operations http://ws4d.e-technik.uni-rostock.de/dpws-explorer/