REDMOND, December 1, 1999 The Home API Working Group today announced that it has merged its efforts with those of the Universal Plug and Play (UPnP) Forum to ensure a unified specification for development of home control software and products.

Press Release

For more details or About Home API

Introduction

This document describes Home API, a set of software services and programming interfaces that enable applications to discover and control home devices such as televisions, VCRs, cable boxes, security systems, lights and climate control systems. The primary goal of Home API is to simplify and reduce the cost of developing software applications that enhance users' entertainment, security, comfort and convenience through the intelligent use of controllable home devices. Home API interfaces are protocol-independent. Applications using Home API are shielded from differences in the underlying networks and protocols used to communicate with home devices.

Background and Environment
The emergence of digital entertainment devices, such as digital TVs, camcorders and other consumer electronic devices controllable across high-speed A/V networks, as well as "no new wire" home data networks using telephone wires, powerlines and RF technology has the potential to create a revolution in the capabilities of home electronics and appliances. "No new wire" networks will enable multiple home PCs, Internet appliances and other home computing devices to exchange data and share Internet connections. In addition, home appliances such as lighting and security systems, and heating and cooling systems increasingly will be integrated into cooperating systems via other networks. Figure 1 depicts a home network consisting of a variety of different devices, physical networks and protocols.

The deployment of home networks and smart controllable home devices will enable the development of compelling new home applications that move us closer to the vision of the "intelligent home" that enhances consumers' comfort, convenience, peace of mind and entertainment. However, one problem in developing such applications is that there are numerous competing home networking protocols and no standard application programming interfaces (APIs) for accessing home devices.

Because of these development difficulties, the members of the Home API Working Group have joined efforts to define and develop APIs and other software infrastructures to encourage the creation of compelling applications that "discover" and interact with home devices. The final result, the Home API Specification and Software Development Kit (SDK), is targeted at independent software and hardware vendors that develop software or hardware for home PCs and controllable home devices. By enabling applications that connect to home devices, all parties (the PC, home networking and home device industries) can benefit through software sales, new device sales and market segment expansion.

APIs vs. Protocols

To understand the scope of Home API, and to put different home networking initiatives in perspective, it is important to understand the difference between a networking protocol and an application programming interface.

Protocols
For two devices to communicate directly with each other, they must agree on the format of the information and rules describing how information is to be exchanged. In other words, they must speak the same language. A protocol describes a language that devices can use to talk to each other. It describes the bits (messages) actually transmitted over a communication network between two or more devices and how the bits are to be interpreted. Examples of protocols are TCP/IP, CEBus, HAVi protocol and X-10.

APIs
An application programming interface specifies how the services of a software module (library or component) are exposed to application programs running on a single platform. An API is typically defined in terms of function calls and parameters passed to the functions. In addition, an API often defines a programming model that describes the order in which function calls can be made, etc. An API implementation may involve communication with other devices, but this is transparent to the caller.

An important distinction between an API and a protocol is that protocols specify inter-device communication and APIs specify local software services within a single device. For example, it is quite common for two completely different APIs on two machines to allow applications to communicate using a common underlying protocol. There is no need to reconcile differences between APIs on two machines because APIs are not externally visible. However, protocols are externally visible and must be supported by both sides to enable communication.

APIs and protocols are sometimes confused because APIs are often layered on top of protocols (e.g., the kind of API allows applications to communicate using protocols). The association between a protocol and an API layered on top of it is often so strong that the distinction between them becomes blurred. However, it is also possible for a protocol-independent API to be layered on top of one or more underlying protocols. Home API adopts this approach.

Relationship to Other Home Networking Initiatives

One of the most commonly asked questions about Home API is how it relates to other home networking initiatives. Virtually all of the other existing and emerging home networking initiatives (HAVi, Universal Plug and Play, Jini, Echonet, VESA Home Network, CEBus, X-10, LonTalk, Home Plug-and-Play, etc.) are primarily concerned with enabling peer-to-peer device interoperability across home networks. To do this, they specify one or more protocols by which home devices communicate. Unfortunately, the inherent diversity of devices and networking requirements is likely to frustrate efforts to establish a set of common protocols for seamless peer-to-peer interoperability across all home devices. For example, home network bandwidths range from a few bits per second for X-10 to 400 Mbps and higher for IEEE 1394. Simple devices with low bandwidth requirements cannot afford the expense of connecting to a high-speed network such as 1394. Furthermore, many protocols suitable for use on high-speed networks are entirely inappropriate for low-speed networks.

To expose the complete set of underlying device and protocol features to applications, many home networking initiatives also define an API that corresponds closely to their protocols. Since home networks are likely to remain heterogeneous, with multiple incompatible protocols used to discover and control different types of devices, application writers are faced with the prospect of using multiple protocol-specific APIs with no common underlying programming model.

Home API differs from these other initiatives in that it does not define a protocol. Instead, it defines a protocol-neutral API and a common programming model for all home devices. Home API also defines an extensible service provider architecture that enables device and network vendors to make their hardware accessible to Home API applications. Home API does not attempt to solve the problem of peer-to-peer device interoperability. Instead, it simply exposes the functionality of home devices to client applications running on a Home API platform. These applications can use Home API to query and control devices that use incompatible protocols without dealing with any protocol-specific issues.

Since Home API is protocol-neutral, it is largely complementary to and synergistic with other home networking initiatives. The Working Group embraces these other initiatives because they should ultimately increase the number of intelligent and communicating devices accessible to Home API applications. Conversely, Home API can also provide benefits to other home networking initiatives. First, Home API's extensible service provider architecture makes it easy for these other initiatives to expose their services and devices to Home API applications. Second, Home API can provide protocol-specific initiatives with a way to discover and expose devices on other networks that support other protocols. Although enabling this type of protocol bridging is not an explicit goal of Home API, it is a legitimate and plausible use of Home API.

Home API Features and Benefits

Home API supports multiple home networks and is designed to allow application programmers to access home devices in a protocol-independent manner. The advantage to the developer is that the way the application accesses a home device is the same, regardless of the underlying protocol that is used to talk to the device. By shielding applications from the underlying heterogeneity of home networks and providing standard APIs for controlling home devices, Home API will help get applications that use home devices developed quickly and easily.

Home API allows applications to control and query the status of home devices. For example, an application could use Home API to query the current temperature of an outside thermometer or change the channel on a television. Home API does not support data streaming such as sending a video stream from a PC to a digital VCR. Other APIs would be used in conjunction with Home API for that purpose.

Figure 4 illustrates the Home API architecture from a client application's perspective. Although devices in this figure may reside on separate physical home networks, Home API hides this detail and provides clients with a uniform view of all home devices. Applications control home devices by setting or getting properties of objects corresponding to those devices. Applications can also subscribe to property change events to receive notification of device state changes. Service providers for underlying devices and networks translate the high-level operations on Home API object properties into corresponding commands sent to devices across networks.

Key Technical Features of Home API
· Enables applications to enumerate, control and receive state change events from home devices.
· Exposes devices such as protocol-independent OLE Automation objects using "properties" to model device controls.
· Defines standard control properties for common home devices. New device types can be defined and additional properties can be easily added to support custom features and devices.
· Supports a variety of home networks and underlying protocols. New or proprietary protocols can be added easily.
· Includes a run-time component to support intelligent home features.
· Enables applications to discover and incorporate user interface components for home devices.
· Integrates well with popular development tools and is accessible from a variety of programming languages, including C++, Java, Microsoft® Visual Basic®, Visual Basic development system Scripting Edition and Java Script.

Benefits of Home API for Applications Developers
Today developers of a home control applications have to deal with the protocol-specific details of the devices and networks the applications use. Furthermore, when new networks and devices become available, developers have to modify the application or install the appropriate drivers to use the device. There is no standard software infrastructure to shield applications from these low-level details. Home API is intended to change this by providing a set of services that will make it easy to develop applications that discover and control home devices.

The following steps are typically required to find and control a device:
· Check hardware interfaces during installation; install appropriate drivers.
· Query the network to discover a controllable device using network-specific protocols.
· Build a command packet for the device according to the network protocol and the device's command syntax.
· Send the command to the device using a driver- or network-specific API.
· Wait for a reply, if reply packets are part of the protocol.

The following steps are required to find and control a device using Home API:
· Discover Home API objects of the desired type.
· Set OLE Automation properties to control the device.

The following Home API example shows how a single line of Visual Basic code can obtain an object corresponding to a VCR device and start its tape playing.

GetObject("home:Living Room/My VCR").Transport.Mode = "play"

Note that this code has no protocol dependencies in it. The actual VCR device might be controlled via an IR command or via an AV/C or HAVi command. The application is shielded from this underlying complexity.

Benefits of Home API for Service Providers and Hardware Vendors
Vendors of controllable devices and home control networks face a dilemma if they want their devices to be usable with home control applications. They must choose which home control applications vendors they want to work with to ensure that their products will have software support at launch. Given the fragmentation of today's home automation market, with no one vendor having significant market share, a hardware vendor needs to work with multiple software vendors to ensure that there is a "critical mass" of software support for product success. In the best case, this would mean writing drivers for multiple home application programs. But, because many of the home automation programs are monolithic and lack the open interfaces needed to support third-party drivers, hardware vendors must convince the software company that their hardware is worthy of support. They also must face the inevitable delays of waiting for the software vendor to incorporate support.

With Home API, hardware developers merely need to write a single Home API-compliant driver for their device that exposes the device and its controllable attributes through Home API. When the user installs this driver, the device will become controllable. This is a major benefit that will greatly speed the acceptance and sales of new controllable devices and control networks into the home.
Benefits of Home API for Consumers
By their very nature, APIs are transparent to end users. Consumers want the benefits of a technologically advanced home, but they don't care how actual products accomplish this. Although end users may not know how Home API works, it does provide several benefits to the homeowner.

Home API will enable consumers to buy a greater selection of applications at lower prices. As Home API speeds the software development process, it will reduce time to market, making better home control applications available sooner. These applications will expand the comfort, security and entertainment features of users' homes at a price substantially below the custom-installed solutions currently found in "high-end" homes.

For example, Home API makes it easier to create entertainment applications that automatically control all of the devices in a home theater system to simplify its configuration and use. Another example is an application that defines "house modes" that allow users to specify a set of actions to be performed as a result of entering a specific mode. The "asleep" mode might cause the security system to arm, the thermostat to be lowered, a nighttime lighting pattern to be set and an alarm clock to be set according to the occupant's schedule. A smart CallerID screener would also adjust its mode to immediately direct certain calls to an answering machine rather than allowing the phone to disturb the occupants.

Furthermore, Home API will speed the support of new home networks and devices. Homeowners won't have to wait for a new release of an application program when installing new controllable devices or home networks. New home devices and networks will ship drivers compatible with Home API and service providers that will readily install into an existing Home API system.

Home API Architecture

This section provides a more technical discussion of the Home API architecture and features. Figure 5 depicts a slightly more detailed view of the Home API architecture than Figure 4. Container objects, property routes and event subscriptions are described in the sections that follow.

Property-Based OLE Automation Object Model
Home API represents home devices as persistent OLE Automation objects with properties corresponding to device functions and controls. For example, a light is represented as an object with a property named Brightness that is used to control and monitor the state of the light. Because Home API uses OLE Automation, client applications written in a variety of languages (e.g., Visual Basic, C++, Java, JavaScript) can discover and control the light.

More complex devices, such as televisions and VCRs, are modeled as a set of subobject properties, such as Tuner, Audio and Display, corresponding to functional subcomponents of the devices. Each of these subobject properties is an object that is composed of a set of properties. For example, Tuner subobjects have a property called Channel. Given a TV Home API object, a client written in Visual Basic would write the following code to tune to Channel 4:

"tv.Tuner.Channel=4"

In addition to controlling devices via properties, clients can also subscribe callback objects to receive asynchronous notification when properties of Home API objects change. These event subscriptions can also include a filter specification to further constrain the events to be generated. For example, a client can request notification when the light's Brightness value changes.

Service Providers
Home API objects are implemented by Home API service providers. The service providers are responsible for handling protocol-level issues. When a property of a Home API object associated with a home device is modified, the service provider converts the property set operation into one or more commands sent across the home network to the corresponding device. Service providers are also responsible for generating property change events for their objects.

Service providers are also responsible for discovering devices using an underlying network or bus enumeration mechanism and creating corresponding Home API objects for them. Service providers for networks, such as X-10, that have no enumeration capabilities will likely require the user to notify them of the installation of a new device through a user interface. The Home API architecture defers all such implementation issues to service providers.

Extensible Home Device Models
Home API includes definitions of a variety of different home devices such as televisions, VCRs, security systems, lights, thermostats, sensors, etc. The purpose of the initial set of device definitions is to represent very basic, common features of home devices. Devices with additional features would be represented as objects that implement the basic property set plus additional properties that expose the extended capabilities of the devices. Home API is designed to make it easy to add such extensions either as new property sets or as custom programming interfaces associated with the Home API objects.

Home API Run Time Supports Autonomous Operation
In addition to exposing a set of objects corresponding to home devices, Home API also includes a run-time component and a set of software-based objects such as timers and expression evaluators. Software-based objects and objects associated with devices can be connected using a special type of object called a property route to cause the run time to perform home automation tasks. Property routes cause changes in properties to be propagated from one object to another (see Figure 5). The run time enables application clients to configure the Home API system to perform tasks on their behalf and then exit, rather than running constantly as a background task on the computer.

Container Objects
Home API objects can be organized hierarchically using container objects that correspond to locations within a house or to certain Home API client applications. Container objects are roughly analogous to file system directories. Each Home API system has a root object that holds a collection of "children" objects such as Living Room, Den, Kitchen, Applications, etc. Objects corresponding to devices in a given room are typically added by the end user to a container named after that room. The container named Applications holds application-specific containers that, in turn, hold objects created by Home API client applications or service providers. (These application-specific containers are analogous to installation directories for program files.)

Object Discovery
Home API enables applications to obtain references to objects either by enumerating containers or by passing object names to a standard COM name-binding function such as the Visual Basic GetObject function. For example, a reference to a Home API object named TV in a container named Living Room can be obtained with the following Visual Basic code:

Set tv = GetObject("home:Living Room/TV")

Furthermore, clients can enumerate containers to retrieve child objects of a given type. (This is useful when initially discovering what devices are present.) Each Home API object has a unique, persistent ID in addition to a user-readable name, and the ID can be used to obtain the object irrespective of the container it belongs to.
Discovery of Custom, Device-Specific Software Components (e.g., User Interfaces)
Home API includes a standard way for service providers or third parties to advertise the availability of additional components and custom programming interfaces associated with a Home API object. For example, a Home API object corresponding to a television might be associated with an embeddable Microsoft ActiveX® Control that provides a graphical user interface for that television. An ActiveX-based container application needing to display an interface for a television could find the Home API TV object and read its Associations property to search for the appropriate ActiveX Control to use.

#########

Microsoft, Visual Basic and ActiveX are registered trademarks or trademarks of Microsoft Corp. in the United States and/or other countries.
Other product and company names herein may be trademarks of their respective owners.

Visit our Frequently Asked Questions page.

Home | About Home API | FAQs | Companies |  In the News |  Members Only
For More Info | Search | Site Map