From OpenHome

Revision as of 15:47, 29 February 2012

Introduction

This document is for developers using the OpenHome SDK to integrate a Widget into an OpenHome system. Each Widget must have its own driver to allow it to communicate with the OpenHome Nodes.

To help you write your driver, this document provides high level descriptions of the core responsibilities of a Widget driver and gives a detailed walk-through using example code.

Full versions of each file used in the development of the example driver are available in the Appendix.

Prerequisites

To begin development of your Widget driver you must be in possession of the following items:

• your Widget Service XML that describes the properties on your Widget.

• the OpenHome SDK
• your chosen communication protocol's API

The protocol you choose for your Widgets must be the same protocol used on your choice of Node.

Related Documents

The following related OpenHome documentation may be of interest to you:

• ohWidget Technical Overview
• OpenHome Widget Service XML definition
• OpenHome ohNet Device Stack
• OpenHome Node Architecture

Widget Service XML

Widget Service XML

OpenHome Widget driver writing relies heavily on the use of code generated from a single source — the Widget Service XML.

The service and actions your Widget provides are represented in code in a file called a Provider. The Provider is automatically generated from the Widget Service XML and produces an abstract class for you to inherit when you write your concrete class driver.

To aid in the explanation of how the Provider is created and put to use we will follow the development of a driver for a simple light Widget; taking the defined Widget Service XML and stepping through how it is used to generate the other files. Examples of code are used throughout this document to show you how each one is created and used in an OpenHome system.

It is essential that you start with a well-formed Widget Service XML, conforming to the schema defined in the WidgetService.xsd. The following diagram shows the significance of the Widget Service XML in relation to the generated files you will use when writing your driver:

Figure 1: The OpenHome document hierarchy, highlighting the areas specifically used in driver development

Code sample used in this document

Our examples in this document use a Widget Service XML definition for a light Widget called BasicLight.xml.

We will see how the Provider is generated from this XML and how it is used to aid the driver writing process. The examples also show how your chosen communication protocol should be used in the body of the driver code.

Implementation details of specific protocols you choose to use are beyond the scope of this document. However, the samples used in this document show the use of the SimpleUPnP protocol to aid you in your development process.

The SimpleUPnP protocol was developed as a test protocol during the early stages of the OpenHome project. It is included in the OpenHome SDK and can be used as a public resource.

The use of SimpleUPnP in the example files and the code snippets within the following sections is highlighted by the icon. The lines of code marked by must be changed to code from your chosen communication protocol's library. SimpleUPnP is left in to help you understand how a protocol is used in a working example.

The sample code provided attempts to show best-practice coding standards. There are several sections of code that have a mandatory layout or that call specifically named methods and functions. These areas of the code are highlighted where required.

Where the examples do not explicitly state that the code shown is mandatory, you are free to implement it in a different way according to your own coding style and practices.

Driver responsibilities

Driver responsibilities

An OpenHome Widget driver has several responsibilities which must be met before it can be used on an OpenHome Node.

These responsibilities are listed R1 to R7 and are defined here, explaining what each one must do.

R1 Specifying the type of Widget the driver controls

A driver must know which type of Widget it can communicate with and be able to provide that information to the Discovery Module. A driver will normally communicate with one specific type of Widget and will only ever use one communications protocol.

R2 Reacting to a discovered Widget on the network

A driver must create a new IWidgetRegistryEntry object to represent the Widget and use it to listen to changes in the physical Widget's state.

R3 Setting the initial values for the Widget's properties

A driver must set the Widget object's initial properties.

R4 Publishing discovered Widgets in the Local Widget Registry on the Node

Publishing Widgets advertises their presence on the network. This allows Nodes to access the Widgets and present their services for use. A driver must be able to enable and publish a Widget object.

R5 Reacting to an event reported from the Widget

A driver must update the Node with the state of the Widget's properties when the Widget reports a change.

R6 Reacting to actions sent to the Widget

A driver must update a specified property to a new value when instructed to do so by the Node.

R7 Reacting to a Widget's departure

A driver must properly handle the IWidgetRegistryEntry object when the physical Widget is no longer available.

The sections of example code that follow show you how to write a driver from beginning to end. The accompanying text explaining the example code highlights when a responsibility, or part of a responsibility, has been met.

Driver Architecture

Driver Architecture

Drivers are installed on the Node and used when the Node needs to communicate with the Widget. Drivers use several objects to communicate with Widgets over the Widget's lifetime. Figure 2 shows the objects used by the driver and how the responsibilities listed above relate to each one:

Figure 2: The architecture of a driver, showing the driver's relationship to the objects used to communicate with a Widget. Lines between objects show message flow.

The objects contained in the dotted boundary must appear in the code you write to define your driver. The Driver, Provider and IWidgetRegistryEntry objects are all contained in the same driver file. We begin discussing this on page 12.

The other objects are provided by the OpenHome SDK or as installed components on the Node.

The Discovery Module informs the driver of the presence of an available Widget.

Each Node has a Protocol Module which contains the protocol's API. Widgets can communicate with OpenHome Nodes using any one of the set of communications protocols the Node supports. The driver uses your chosen protocol's Protocol Module to communicate with the Widget.

Both the Protocol Module and the Discovery Module are installed on the Node. When you write your driver you will use your Protocol Module to allow the driver to communicate with the Widget.

IWidgetPublisher, IPublishedWidget and DvDevice are objects provided in the OpenHome API. You can read about them in the APIs.