Dog2.3 Domotic OSGi Gateway - PoliTO

Dog2.3

Domotic OSGi Gateway

Architecture Insights and development guidelines

Summary

6/15/2012 Dario Bonino - Dog 2.3 2

Intelligent Domotic Environments

System Architecture

Dog 2.3

Overview

Core

Drivers

Add-ons

Run-time operation

Dog Development Guidelines

General Picture

System Architecture

Intelligent Domotic Environments


System Architecture


D D D D D D D D Domotic devices (switches,

buttons, relays, sensors, meters,

…)

Domotic bus (wired, wireless)

GW Bus-to-IP gateway

Bus-to-serial gateway GW

Ethernet, Wi-Fi, USB

User

Interface

Mobile, Web, Home Display,

Multi Touch, Accessibility,

Natural language, …

Data

analysis

ERP, Web services, Stream

processors, Datawarehouse

Dog

Bundles

Device abstraction, Event

abstraction, State abstraction,

Rules engine, …

User

Interface User

Interface

Smart

Appliance

In Ontology We Trust


Devices and networks exposed by means of a formal,

unique, representation

DogOnt (Ontology)

Applications only see DogOnt-based device descriptions

Functionalities

Notifications

Commands

States

State values

Internal representations and drivers must be ontology-

aware, at different degrees

Dog 2.3

Architecture

High-Level Architecture


OSGi - based

2 main layers

3 main bundle groups

Core

Drivers

Add-ons

Core


DogXMLEndPoint DogRESTEndPoint

DogStateMonitor DogScheduler DogExecutor DogDeviceManager DogNotificationManager

DogLogger DogConfigurator

DogDeviceFactory

DogOntLibrary DogDeviceModel

DogSemanticHouseModel

DogSimpleHouseModel

Dog2Library DogJaxBLibrary DogSemanticLibrary MeasureLibrary org.rxtx

Do

gAuto

Sta

rt

Core





DogDeviceFactory



DogSimpleHouseModel


Do

gAuto

Sta

rt

Dog REST EndPoint


Dog REST EndPoint

Provides REST access to Dog

Based on JSON or XML messages

Under development




DogDeviceFactory



DogSimpleHouseModel


Do

gAuto

Sta

rt

Core





DogDeviceFactory



DogSimpleHouseModel


Do

gAuto

Sta

rt

Dog XML EndPoint


Dog XML EndPoint

Provides XML-RPC access to Dog

Based on XML messages

Two Way Connection

Client to send notifications

Server to listen application requests




DogDeviceFactory



DogSimpleHouseModel


Do

gAuto

Sta

rt

Core





DogDeviceFactory



DogSimpleHouseModel


Do

gAuto

Sta

rt

DogStateMonitor


DogStateMonitor

Keeps a snapshot of the state of all devices

Allows for state change listener registration

Supports state querying

Typically asynchronous

Synchronous through a different interface (API)




DogDeviceFactory



DogSimpleHouseModel


Do

gAuto

Sta

rt

Core





DogDeviceFactory



DogSimpleHouseModel


Do

gAuto

Sta

rt

DogScheduler


DogScheduler

Allows to schedule recurring tasks involving

Command execution (done through the command

handling bundles)

State requests (done by reading the current device

state in dog – not on the network)

Notification…?(for what?)




DogDeviceFactory



DogSimpleHouseModel


Do

gAuto

Sta

rt

Core





DogDeviceFactory



DogSimpleHouseModel


Do

gAuto

Sta

rt

DogExecutor


DogExecutor

Dispatches a command to relative device object

Performs command validation

Supports message priority

No pre-defined priority levels

Higher priority Higher Priority Value in the

corresponding DogMessage




DogDeviceFactory



DogSimpleHouseModel


Do

gAuto

Sta

rt

Core





DogDeviceFactory



DogSimpleHouseModel


Do

gAuto

Sta

rt

DogDeviceManager


DogDeviceManager

Implements the OSGi device manager (device

access specification)

Manages device/driver attachment in Dog

When device/driver are added/modified/removed




DogDeviceFactory



DogSimpleHouseModel


Do

gAuto

Sta

rt

Core





DogDeviceFactory



DogSimpleHouseModel


Do

gAuto

Sta

rt

DogNotificationManager


DogNotificationManager

Implements the Event Admin Service Specification

Version 1.2

It is based on a event publish and subscribe model

Filters inner state change notifications from outer

ones (visible to applications)

Dispatches Notification and State Change

Notifications only




DogDeviceFactory



DogSimpleHouseModel


Do

gAuto

Sta

rt

Core





DogDeviceFactory



DogSimpleHouseModel


Do

gAuto

Sta

rt

DogDeviceFactory


DogDeviceFactory

Creates device istances according to the runtime home

configuration

Either provided by the SimpleHouseModel or by the Semantic

House Model




DogDeviceFactory



DogSimpleHouseModel


Do

gAuto

Sta

rt

Core





DogDeviceFactory



DogSimpleHouseModel


Do

gAuto

Sta

rt

DogOntLibrary


DogOntLibrary

All possible

Devices (interfaces)

Functionalities classes

State classes

State value classes

Programmatically generated from DogOnt




DogDeviceFactory



DogSimpleHouseModel


Do

gAuto

Sta

rt

Core





DogDeviceFactory



DogSimpleHouseModel


Do

gAuto

Sta

rt

DogDeviceModel


DogDeviceModel

All possible

Device implementations




DogDeviceFactory



DogSimpleHouseModel


Do

gAuto

Sta

rt

Core





DogDeviceFactory



DogSimpleHouseModel


Do

gAuto

Sta

rt




Manages the home description in form of DogOnt instances

Supports configuration requests

Supports model merging

Implements classification and basic reasoning

Supports interoperation rules extraction

Potentially provides access to all properties/features defined in DogOnt

Can generate XML home configuration to be used by the SimpleHouseModel




DogDeviceFactory



DogSimpleHouseModel


Do

gAuto

Sta

rt

Core





DogDeviceFactory



DogSimpleHouseModel


Do

gAuto

Sta

rt

DogSimpleHouseModel


DogSimpleHouseModel Manages the home description in XML

Used for Dog instances running on devices with low computational power

No model-merge capabilities

No reasoning support

If a SemanticHouseModel is present, this bundle automatically shuts down




DogDeviceFactory



DogSimpleHouseModel


Do

gAuto

Sta

rt

Core





DogDeviceFactory



DogSimpleHouseModel


Do

gAuto

Sta

rt

DogConfigurator


DogConfigurator

Manages bundle-specific configurations

Property files

XML files

Additional files (ontology, images, etc.)

Provides configurations to all bundles implementing the ManagedService interface




DogDeviceFactory



DogSimpleHouseModel


Do

gAuto

Sta

rt

Core





DogDeviceFactory



DogSimpleHouseModel


Do

gAuto

Sta

rt

DogLogger


DogLogger

Provides logging facilities to all Core bundles

Can log on console or file

Can apply different handlers (file, console) to different

logging levels




DogDeviceFactory



DogSimpleHouseModel


Do

gAuto

Sta

rt

Core





DogDeviceFactory



DogSimpleHouseModel


Do

gAuto

Sta

rt

Dog2Library


Dog2Library

Defines all the Message Types used for inter-bundle

communication

Defines all the bundle service interfaces

Defines core-level notifications (not defined in DogOnt)

Provides utility classes to other bundles




DogDeviceFactory



DogSimpleHouseModel


Do

gAuto

Sta

rt

Core





DogDeviceFactory



DogSimpleHouseModel


Do

gAuto

Sta

rt

DogJaxBLibrary


DogJaxBLibrary

Provides XML serialization / de-serialiazion for

Inner messages

Outer messages

Configurations

Etc.




DogDeviceFactory



DogSimpleHouseModel


Do

gAuto

Sta

rt

Core





DogDeviceFactory



DogSimpleHouseModel


Do

gAuto

Sta

rt

DogSemanticLibrary


DogSemanticLibrary

Encapsulates and makes available all semantics-related

libraries

Jena

Pellet

SPARQL query facilitator




DogDeviceFactory



DogSimpleHouseModel


Do

gAuto

Sta

rt

Core





DogDeviceFactory



DogSimpleHouseModel


Do

gAuto

Sta

rt

MeasureLibrary


MeasureLibrary

Exports the JScience library to all Dog bundles

Will define un-supported JScience unit of measures




DogDeviceFactory



DogSimpleHouseModel


Do

gAuto

Sta

rt

Core





DogDeviceFactory



DogSimpleHouseModel


Do

gAuto

Sta

rt

Org.rxtx


Org.rxtx

Exports the serial port API library (rxtx) to all Dog

bundles

Drivers


Drivers


KNXNetIP

EIBLibIP

OpenWebNet

Modbus

Elite

Echelon

ZWave

Texas

Instruments

Driver structure


Network

Driver

Gateway

Driver

Driver Driver

Device Driver

Network Driver


Gateway

Driver

Driver Driver

Device Driver

Network Driver

Handles network-level communication

Protocol

Connection

Polling (when needed)

Defines the network access APIs for all driver

bundles, for the same technology

Driver structure


Network

Driver

Gateway

Driver

Driver Driver

Device Driver

Gateway driver


Gateway

Driver

Driver Driver

Device Driver

Gateway Driver

Supports multi-gateway operation for a given

network technology

Handles the association between devices and gateways

Permits to install device driver bundles only if the

corresponding network gateway is present (in the

configuration)

Driver structure


Network

Driver

Gateway

Driver

Driver Driver

Device Driver

Device Driver


Gateway

Driver

Driver Driver

Device Driver

Device Driver

Implements the DogOnt device features for a given

class of devices

Translates ontology-defined commands,

functionalities and states into network level

messages

One device driver per each DogOnt device class

Sometimes the same driver can serve multiple device

classes but this should be avoided

Add-ons


Add-on


DogRulesBundle

DogPowerModelBundle

DogPowerBundle

DogRulesBundle


DogPowerModelBundle

DogPowerBundle

DogRulesBundle

Provides a rule-engine runtime for

Defining automation scenarios

Interoperation

Complex device behaviors

Programmable through dedicated DogMessages

XML-based rule definitions

Uses notifications as triggers, states as constraints and commands as rule consequent

Supports time-driven triggers

Add-on


DogRulesBundle

DogPowerModelBundle

DogPowerBundle

Add-on


DogRulesBundle

DogPowerModelBundle

DogPowerBundle

DogPowerModelBundle

Handles the power extension of DogOnt

Plug in the main Semantic House Model

Provides power-specific query functionalities on

the model

Add-on


DogRulesBundle

DogPowerModelBundle

DogPowerBundle

Add-on


DogRulesBundle

DogPowerModelBundle

DogPowerBundle

DogPowerBundle

Exploits the DogPowerModelBundle

Provides power consumption estimation based on

Actual measures

Typical/Nominal values defined in the DogOnt power extension

Disaggregates actual measures when needed

Keeps an updated snapshot of the current home power consumption

Runtime Operation


Start-up


Development

Configured in Eclipse (Helios)

Bundles are automatically started

No pre-defined start-up order

Production

Bundles are started by the DogAutoStart bundle

No pre-defined start-up order for most bundles

If both Semantic and Simple House Model are present, the

Simple House Model is shut down

Start-up order?


No explicit order, except for the DogAutoStart bundle

Each bundle waits for the availability of required services

before registering to the OSGi framework

When off-line and run-time dependencies are satisfied,

bundles register their own services, possibly enabling the

registration of other bundles

Library bundles start without waiting

No dependencies

Start-up example


Bundles are installed

Bundles start their lifecycle and become resolved

Bundles with no dependencies start (active)

All library bundles

The other bundles start as soon as their dependencies are satisfied (service being available)

When an House Model provider (either the Simple or the Semantic House Model) becomes available

The device factory creates all devices defined in the house model

The device manager takes care of device/driver attachment

All devices for which a driver cannot be found become idle

Start-up example


On the driver side

Network drivers start as soon as the DogConfigurator is

started (if they need configuration)

Gateway drivers start when their associated network driver

becomes active (exposing the network service)

Device drivers become active if both the network driver and

the gateway driver for their associated technologies are active

When a device (gateway) driver becomes active

All idle devices are matched against the driver

Matching devices attach the driver and become active

Non-Matching devices remain idle

Device access (OSGi)


DogDeviceManager

DeviceDriver

DogDeviceModel

DogDeviceCategory

Command handling (1)


Application

Dog

Command




DogDeviceFactory



DogSimpleHouseModel


Do

gAuto

Sta

rt

KNX Modbus Echelon OpenWebNet ZWave

Command handling (2)


Command

Network Message

Notification handling (1)


Application

Dog

Notification


DogState

Monitor

Dog

Scheduler

Dog

Executor

DogDevice

Manager

DogNotification

Manager


DogDeviceFactory

DogOnt

Library

DogDevice

Model


DogSimpleHouseModel

Dog2Library DogJaxBLibrary DogSemantic

Library MeasureLibrary org.rxtx

Do

gAuto

Sta

rt

KNX Modbus Echelon OpenWebNet ZWave

Rules

PowerModel

Bundle

PowerBundle

Notification handling


Dog Development Guide

A quick reference to Dog development patterns

The Dog Mantra


3. Configuration first

1. In DogOnt we trust

2. Never stop auto-generation

In DogOnt we trust


Internal representations and drivers must be ontology-aware, at different degrees

Therefore:

All device-related bundles / modules / libraries must be compliant with the DogOnt model

Functionalities

States

Behaviors

Whenever a new device must be represented

First check the corresponding ontology

If missing, amend the ontology (by coordinating your action with the coordinator of the ontology development “group”)

If present, conform to the device model when developing the corresponding driver / module / library

In DogOnt we trust (2)


DogOnt is not only for description!

At runtime it is used for

Answering model queries

Configuration

Interoperation rules

Provide model handling capabilities

Model update

Model merging

Model querying (see above)

Offline it is used for

Describing specific environments (related to runtime)

Ensure DogDevice / DogOnt device coherency

By means of AutoGeneration



Even when we do not use it!

Installations with reduced computational power

Simple Home

XML configuration

Auto-generation from the full ontology instantiation

Using the same process adopted for runtime configuration querying using

the Semantic House Model

I.e., it.polito.elite.domotics.ontologies.dogont.DogOnt2XMLDog



Thing

Building thing

Controllable

Appliances

WhiteGoods

Brown

Goods

HousePlants

Electrical

System

HVAC

System Security

UnControllablle

Semantic

House

Model

Device

Representations

Auto

Generation

Configuration Lamp1

Lamp2

Button1

Controls

Controls

Power

Model

Power

Consumption

Eletric Power

Consumption

Configuration

Applicatio

ns

DogOnt

Instances

Lamp1Pw = 18W

Never Stop Auto-generation (2)


Ensure DogDevice / DogOnt device coherency

Autogenerate all possible components starting from the ontology

Device category

Device model

DogCommands

DogStates

DogStateValues

> 400 Java classes in one time (< 1 min)

Advantages

Only two points of failure

The autogeneration process

The class templates used in the generation process



Advantages

Less burden on writing very similar classes

Less errors as writing device-related classes is error prone

Quick generation time

Robust enough to tackle typical ontology changes

Class creation / modification / deletion

Shortcomings

Needs changes if the ontology structure changes heavily

Relation / Property changes

Especially if existing, core properties are modified

However change effect is confined to the auto-generation process



Available through

Dog Utilities

i.e., it.polito.elite.domotics.ontologies.dogont.DogOnt2Dog.

In conclusion…

Never stop auto-generation,

i.e., auto-generate all the Dog modules that can be written by

only exploiting DogOnt and Code templates

Configuration First


Bundle-specific information

E.g., network addresses, ports, sampling times, configuration

files, etc.

Must be exposed through the DogConfigurator service

i.e., must be accessed through the ManagedService interface

Avoid hard-coding

Never, never, never

Hardcode information in bundle code

Soft-hardcode information in the bundle archive

Avoid using configuration parameters for properties defined in

DogOnt

E.g., gateway IP address, gateway port, etc.

Beware of Dog!


1. Think first!

2. Comment, comment and comment!

3. Check spelling

4. Do not hardcode, use configuration

5. Design & implement for the future

6. Do housekeeping

7. Document your choices

Beware of Dog!


/**

* A class implementing the functionalities of a generic Modbus gateway, as modeled in DogOnt. It offers ways to trace the number of currently managed

* gateways and to access the corresponding slaves and registers, this permits multiple-gateway operation in Dog. Currently no gateway-specific functions

* are available, however in future releases functionalities offered by the real devices will be modeled and implemented here.

*

* @author xxxxxxx

*

*/

public class ModbusGatewayDriver implements Driver, ServiceTrackerCustomizer

{

// The OSGi framework context

protected BundleContext context;

// System logger

LogService logger;

// the log identifier, unique for the class

public static String logId = "[ModbusGatewayDriver]: ";

// a reference to the network driver (currently not used by this driver

// version, in the future it will be used to implement gateway-specific

// functionalities).

private ModbusNetwork network;

// the registration object needed to handle the life span of this bundle in

// the OSGi framework (it is a ServiceRegistration object for use by the

// bundle registering the service to update the service's properties or to

// unregister the service).

private ServiceRegistration regDriver;

// the set of currently connected gateways... indexed by their ids

private Map<String, ModbusGatewayDriverInstance> connectedGateways;

…

Beware of Dog!


public void run()

{

// get the service pid

String serivicePid = (String) serviceRef.getProperty(Constants.SERVICE_PID);

Object managedServiceObj = configurationAdmin.context.getService(serviceRef);

if (managedServiceObj instanceof ManagedService)

{

ManagedService managedService = (ManagedService) managedServiceObj;

if (serivicePid != null && managedService != null)

{

this.configAdminLogger.log(LogService.LOG_INFO,

this.logId + String.format("%s search for configuration", serivicePid));

if (configurationAdmin.configFileList.containsKey(servicePid))

{

Properties propConfig = configurationAdmin.getConfigurationFromPid(servicePid);

try

{

managedService.updated(propConfig);

}

catch (ConfigurationException e)

{

this.configAdminLogger.log(LogService.LOG_ERROR,

this.logId + e);

}

this.configAdminLogger.log(LogService.LOG_WARNING,

this.logId + String.format("%s configuration updated",

serivicePid));

}

}

}

…

Spelling errors! No comments!

Questionable use of logging levels!



1. Check DogOnt

2. Respect OSGi specifications

1. Document yourself

2. Ask more-experienced Dog developers

3. Do not re-invent the wheel

4. If something can be done using an OSGi specification, then

the specification is the only correct choice!

3. Respect the DogArchitecture

1. Do not insert strict bundle dependencies, use services!

2. Do not duplicate functions in Dog

3. Do not mix different architectural levels



4. Develop a self-contained contribution

1. Clearly identify the contribution boundaries

2. Ask the development team for changes/improvements

involving other, possibly shared, Dog bundles

5. Work in team

1. Never commit not-working solutions

1. Unless you are the only one working on it and it

still is a “work-in-progress”

2. The solution does not impact on the other’s work

2. Always do complete commits

1. Check all dependencies, libraries, resources, etc.



5. Work in team

3. Always update before committing

1. To detect possible conflicts and get the latest updates

4. Respect the dead / wrong code policy

1. Remove dead code or not working code

2. Be aware that not working / un-complete components are deleted

after one month of grace time

3. Today we’ll delete the Effect bundles since they are in an Error

State since 3 months and 1e-mail alert!

5. Each bundle should have its own trunk (branches and tags),

on the SVN server



6. Be collaborative

1. Amend wrong / deprecated code in Dog as soon as you find it

2. Ask for opinions on your design choices

3. Express your opinions on future works / versions

7. Develop for the future

1. Sound code

2. Polished code

3. Commented code

4. Document your code using Javadoc

5. Write documentation manuals when Javadoc is not sufficient

8. Think first!

Thanks!


License

This work is licensed under the Creative Commons “Attribution-NonCommercial-ShareAlike Unported (CC BY-NC-SA 3,0)” License.

You are free: to Share - to copy, distribute and transmit the work

to Remix - to adapt the work

Under the following conditions: Attribution - You must attribute the work in the manner specified by the

author or licensor (but not in any way that suggests that they endorse you or your use of the work).

Noncommercial - You may not use this work for commercial purposes.

Share Alike - If you alter, transform, or build upon this work, you may distribute the resulting work only under the same or similar license to this one.

To view a copy of this license, visit http://creativecommons.org/licenses/by-nc-sa/3.0/

6/15/2012 91 Dario Bonino - Dog 2.3

Documents

Dog2.3 Domotic OSGi Gateway - PoliTO