From OpenHome

Revision as of 15:58, 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.

Generating the Provider

Generating the Provider

You must generate your provider before you can begin writing your Widget driver. You use your provider as a guide to implement the functions your Widget needs to set the values of its properties.

The current provider generation process is a manual one involving the use of a text transform tool.

Speak to your OpenHome contact who will help you generate your provider.

Future releases of the OpenHome SDK will include a tool to help you generate the provider.

Prerequisites

You must be in possession of:

• the OpenHome SDK, unpacked on your computer
• your Widget Service XML file

Writing a SimpleUPnP driver

Introduction to the SimpleUPnP protocol

The SimpleUPnP protocol was developed as a test protocol used to control emulated Widgets over a custom UPnP service.

This chapter shows how a driver is written using the SimpleUPnP communications protocol. The aim is to show the code using as generic a protocol as possible so that you can see where your own protocol specific code needs to go.

The use of code specific to the SimpleUPnP implementation is highlighted by the use of the icon. The lines of code are marked by this icon to make it easier for you to see where the protocol-specific code must go and what parts of the code are generic.

Register model

SimpleUPnP is modeled on 8 physical registers available on the Widget. Each register is 32-bits wide. They are indexed from 0 to 7 and the last register (register 7) is reserved for storing the Widget's class.

This detail is used by the Protocol Module on the Node to determine which driver is needed to run the new Widget when it has been discovered.

The remaining 7 registers (registers 0 to 6) are free for Widget engineers to assign to the Widget's functions.

Registers 0, 1, 2 and 3 are available as read/write registers. Registers 4, 5 and 6 are readonly registers.

Only the emulated hardware (running on the Node) can change the values held in registers 4, 5 and 6.

Register use in drivers

In the example that follows we have a Basic Light Widget with a very simple function: it can be turned on and turned off. The on/off value is stored in register 0, with values 0=OFF and 1=ON. Register 0 is a read/write register. This means we can change the value stored there using messages passed to the Widget from the Node, and by reacting to physical interactions at the Widget (such as someone manually switching the light on or off).

The mapping of registers to properties on the Widget is decided by the engineers who manufacture the device. You must be provided with the mapping before you begin developing your driver.

Starting the driver

Figure 3 The driver architecture highlighting the Widget driver and its component parts.

When you