Design and realization of composable web services for home

automation

Elective in Software and ServicesMario Caruso

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

Smart Home [bus]

Devices’ heterogeneity

• Home automation system A + B

Making devices homogeneus

• Devices have to speak the same language.• We must abstract a device from its specific

protocol.• Each device has a software module (proxy)

able to communicate with it:– Send commands– Listen to sensed events

Light actuator(System A)

Light A Proxy

turnOn() turnOff()

Light actuator(System B)

Light B Proxy

A bu

s

B bu

s

Light interface

Protocol A implementation

Ligh

t A

Prox

y Light interface

Protocol B implementation

Ligh

t B

Prox

y

Protocolindependent

Protocoldependent

turnOn() turnOff()

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

Orchestrator

Proxy 1 Proxy 2 Proxy 3 Proxy 4 Proxy 5

Orchestrator

sensoractuator

Proxies simply act as servers

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/

What is DPWS

• DPWS = Devices Profile 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 implementations particularly suited for constrained resource devices.

DPWS Capabilities

• Discover devices and their related services• Send/Receive messages to/from devices• Describe WS (through WSDL etc.)• Subscribe and receive events notifications

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 variable type declaration – The variable instance declaration – The behaviour description

• In particular the developer must implement the transition system that describes both the conversational behaviour and the physical behaviour.

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

Conversational state example

A B

turnOn

turnOffturnOnAssuming that a lamp is modelled by this

transition system:

• If the lamp is in state A• a client can invoke both turnOn

and turnOff operation• But if the lamp is in state B

• a client can only invoke the turn on operation

A working example: DPWSLight

Home automation bus

DPWSLightservice

DPWSClient(e.g. Orchestrator)

The behaviour model

A B

turnOn / ligth:=1

turnOff / light:=0

<?xml version="1.0" encoding="UTF-8"?><service …

<ts>

<state name="B" type="initial-final">

<transition action="turnOn">

<target state="A" />

<postcondition variable="light">

<set-value value="0" /></

postcondition></transition>

</state>

<state name="A" type="initial-final">

<transition action="turnOff">

<target state="B" />

<postcondition variable="light">

<set-value value="0" /></

postcondition></transition>

</state></ts>

</service>

Creating states and variables

• Remember: states and variables can assume only a finite set of values in order to make services’s composition feasible.

• 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

Variables and states declaration

<?xml version="1.0" encoding="UTF-8"?><variable-model

...name="LightLevel">

<value value="0" id="0"/><value value="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>

light-variable.vdd.xmllight_level.vml.xml

<service …<ts>

<state name="B" type="initial-final">

…</state><state name="A" type="initial-

final">…</state>

</ts></service>

light_type.sbl.xml

State Classpackage common;

public class State {public final static String STATE_A = "A";public final static 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(){return state;

}

public void setStateA(){this.state = STATE_A;

}public void setStateB(){

this.state = STATE_B;}

}

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.

Implementing service behaviour

• Each method returns a boolean value according to the sbl specification:– If the current state of the lamp is “B”• If on() method is invoked than we turn on the lamp and

return true• If off() method is invoked than we return false, saying to

our client that is not possible to invoke such action in the current conversational state

A B

turnOn / ligth:=1

turnOff / light:=0

On method/** * Turns on the light */public boolean on(){boolean result = 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;}

LightDevice class

LightDevice

• boolean on()• boolean off()• String getState()• int getVariable()

State

Variable

1..1

1..1

Home automation bus

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.

LightDevice

State

Variable

1..1

1..1

Adding web service capabilities to our lamp

Device Service Operation1..*1..1 1..*1..1

DPWSLight LightService

OnOperation

OffOperation

GetStateOperation

GetValueOperation

GetSarOperation

1..1

1..1

1..1

1..1

1..1

1..1LightDevice

State

Variable

1..1

1..1

1..1

DPWSLight classpublic class DPWSLight extends DefaultDevice implements StateChangedListenerpublic DPWSLight(LightDevice light) {

super();…

this.light = light; service = new LightService();

OnOperation onOp = new OnOperation(light);OffOperation offOp = new OffOperation(light);GetStateOperation getStateOp = new GetStateOperation(light);GetValueOperation getValueOp = new GetValueOperation(light);GetServiceArchiveOperation getSarOp = new GetServiceArchiveOperation();service.addOperation(onOp);service.addOperation(offOp);service.addOperation(getStateOp);service.addOperation(getValueOp);service.addOperation(getSarOp);

… this.addService(service);

OnOperationpublic class OnOperation extends Operation{

private LightDevice light;private static String retvalue = "result";private static String ns = "ns”;

public OnOperation(LightDevice lightdev){super("turnOn",new QName("BasicService", ns));light = lightdev;Element result = new Element(new QName(retvalue, ns), SchemaUtil.getSchemaType(SchemaUtil.TYPE_STRING));this.setOutput(result);

}

@Overridepublic ParameterValue invoke(ParameterValue pv) throws InvocationException {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)

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 variable type declaration (light_level.vml.xml)– The variable instance declaration (light-variable.vdd.xml)– The behaviour description (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)

GetServiceArchieveOperationpublic class GetServiceArchiveOperation extends Operation{

private static String retvalue = "result";private static String ns = "ns" ;

public GetServiceArchiveOperation(){super("getServiceArchive",new QName("BasicService", ns));

ComplexType rqComplex = new ComplexType(new QName("AttachmentType", ns), ComplexType.CONTAINER_SEQUENCE); rqComplex.addElement(new Element(new QName("File", ns),

SchemaUtil.getSchemaType(SchemaUtil.TYPE_BASE64_BINARY))); Element messageOUT = new Element(new QName("AttachmentMsg", ns)); messageOUT.setType(rqComplex);this.setOutput(messageOUT);}

public ParameterValue invoke(ParameterValue pv) throws InvocationException {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.

Client-server interactionClient DPWSLight

“Hello”

GetServiceArchive

Service archive (zip file)

GetState

State = A

turnOff

syntax

syntax +semanthics

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

Asynchronous eventspublic class LightDevice implements BusIndicationListener{…@Override

public void onIndication(BusEventIndication bei) {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();}}}

…private void notifyValue(){Iterator<VariableChangedListener> it = valueListeners.iterator();logger.info("Notifying the change of value to all the listeners");while (it.hasNext()){VariableChangedListener currentListener = it.next();logger.fine("Notifying to listener: " + currentListener.getClass().getName());currentListener.VariableChanged(variable);}}

Asynchronous events

DPWSLight LightService1..1

LightDevice

State

Variable

1..1

1..1

1..1

SimpleValueNotification

DefaultEventSource

Client(subscribed to the event

source)

1..1

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…

DPWS ExplorerDevice Service

PortTypes Operations

Endpoint reference

http://ws4d.e-technik.uni-rostock.de/dpws-explorer/