User Tools

Site Tools



This document covers the reasoning and a high level design for an Iotivity feature to expose ZigBee devices as Iotivity resources.

This feature is tracked in Jira as IOT-540

Problem Statement

Open Interconnect Consortium (OIC) aspires to create a common communication framework to talk to all of the devices in the Internet of Things (IoT). However, there are many existing devices in this space that are using silo’ed solutions. Although, there are application gateways (hubs devices like Smart Things, Revolv, etc.) that talk to many of the different silos, these solutions are insufficient as they often do not export more complete access to the target. This strategy essentially creates another silo and limits innovation on the client side.

Solution Statement

This design maps ZigBee devices including their profiles and clusters to OIC standard profiles by translating between the two protocols in a way that is transparent to the client/controlling devices. In essence, it aspires to express a ZigBee light, for example, as an OIC light which can be discovered, queried and operated on in the same way that any other OIC standard light.

Scope Statement

The implementation target for this design will initially be focused on addressing schedule and testing constraints. The following requirement constraints limit the scope of the initial deliverable:

  • Linux (developed under Ubuntu)
  • CEL's MeshConnect™ EM357 USB Sticks
  • Only profiles that fit the following criteria are required in the initial implementation:
    • Profiles in the home automation category to support the home gateway reference design. Other categories such as health care, industrial, etc. are not current on the plan or record.
    • Profiles that are defined by the OIC Smart Home Task Group
    • Profiles that are defined by the ZigBee Alliance
    • Profiles which have released ZigBee products available for testing
  • ZigBee 3.0 which is not expected to be adopted until Q4/2015 will not be supported
  • No ZigBee scene support
  • ZigBee client–side support only

Design Guidelines

  • Separate translation from protocol plug-in module. The translation layer should be usable without the PPM in cases where the PPM architecture cannot be supported.
  • Translation layers should depend on the core stack and be compiled separately.
  • Changes to the core stack should be kept to a minimum
  • Minimize exposure (ideally zero) to ZigBee constructs in the expression of resource


ZigBee Device and Server Side Cluster Support

The following tables list all of the ZigBee devices that are defined in the ZigBee Home Automation Public Application Profile. The design expresses ZigBee devices and services at OIC resources. Therefore, only the service side clusters are listed here. In addition, common clusters has been omitted from this table.

Key to the notes column:

Note 1 Since the ZigBee gateway design acts as a ZigBee client, Zigbee devices that do not contain server-side cluster will not be supported.
Note 2 ZigBee devices and cluster that cannot be mapped to a standard OIC profile will not be supported in the first release.
[Profile] Indicates that the ZigBee device and cluster in brackets map to the OIC profile listed in the brackets.
<TBD> Indicates that mapping may be possible but further research is required.

Generic Devices

ZigBee Device ZigBee Clusters Notes
On/Off Switch On/Off Switch Configuration (opt) Note 1
Level Control Switch On/Off Switch Configuration (opt) Note 1
On/Off Output On/Off
Level Control Output On/Off
Level Control
Scene Selector <None> Note 1
Configuration Tool <None> Note 1
Remote Control <None> Note 1
Combined Device <None> Note 1
Range Extender <None> Note 1
Mains Power Outlet On/Off
[Smart Plug]
Door Lock Door Lock
Door Lock Controller <None> Note 1
Simple Sensor Binary Input (Basic) Note 2

Lighting Devices

ZigBee Device ZigBee Clusters Notes
On/Off Light On/Off
Dimmable Light On/Off
Level Control
Color Dimmable Light On/Off
Level Control
Color Control
On/Off Light Switch On/Off Switch Configuration (opt) Note 1
Dimmer Switch On/Off Switch Configuration (opt) Note 1
Color Dimmer Switch On/Off Switch Configuration (opt) Note 1
Light Sensor Illuminance Measurement Note 2
Occupancy Sensor Occupancy sensing Note 2

Closure Devices

ZigBee Device ZigBee Clusters Notes
Shade Shade Configuration
Level Control
Shade Controller <None> Note 1
Window Covering Device Window Covering
Window Covering Controller <None> Note 1

HVAC Devices

ZigBee Device ZigBee Clusters Notes
Heating/Cooling Unit On/Off
Fan Control (opt)
Level Control (opt)
Group (opt)
[Air Conditioner]
Thermostat Thermostat
Scenes (opt)
Groups (opt)
Thermostat User Interface Configuration (opt)
Fan Control (opt)
Temperature Measurement (opt)
Occupancy Sensing (opt)
Relative Humidity Measurement (opt)
Temperature Sensor Temperature Measurement <TBD>
Pump Pump Configuration and Control
Level Control (opt)
Alarms (opt)
Pressure Measurement (opt)
Temperature Measurement (opt)
Flow Measurement (opt)
Note 2
Pump Controller <None> Note 1
Pressure Sensor Pressure Measurement Note 2
Flow Sensor Flow Measurement Note 2

Intruder Alarm System Devices

ZigBee Device ZigBee Clusters Notes
IAS Control and Indicating Equipment (CIE) IAS ACE Note 2
IAS Ancillary Control Equipment (ACE) IAS Zone Note 2
IAS Zone IAS Zone Note 2
IAS Warning Device (WD) IAS WD
IAS Zone
Scenes (opt)
Groups (opt)
Note 2


Three deliverables are anticipated as a result of this design:

  • ZigBee protocol translator library
  • ZigBee protocol plug-in for the Protocol Plug-in Manager based on the translator library (above)
  • Minimum change set to the core stack to enable the translator library. Extensions to the core stack API should be designed to enable other translator libraries like Z-Wave to be bound without interfering with each other.

High Level Design


Basic Operation Statement


The following step are envisions to initialize the ZigBee library

  1. Initialize the core stack as a server
  2. Initialize the ZigBee library including radio setup
  3. Bind the ZigBee library to the core stack
    1. ZigBee library will register a callback for discovery requests
    2. ZigBee library will register a path prefix (like ‘/oic’) for all ZigBee resource operations


  • An API will need to be added to the core framework server API to all the registering of one (or more) callbacks for the ZigBee subsystem
  • An API for a new prefix mapped entity handler type will need to be added for delegating requests to the ZigBee subsystem
  • Ideally, the prefix should not be hardcoded in the ZigBee subsystem. It should passed to the ZigBee subsystem to provide the device developer flexibility in ontology design.
  • An ideal design should allow the ZigBee library to register (and deregister) with the core framework without requiring the core frame to be restarted.

ZigBee Resource Discovery

When the core framework server receives a discovery request from a client, the following steps are expected:

  1. The core framework calls the registered ZigBee discovery callback
  2. The ZigBee subsystem will return a list of ZigBee endpoints discovered and encoded as OIC resources. It may either perform the ZigBee discovery in advance or at the time of the OIC request is received. The latter is preferred to prevent storing state and provide the most current list of devices in the network. However, the former may be required if ZigBee discovery latency is unacceptable high.

ZigBee Resource URI

ZigBee devices that are discovered will be presented as OIC resources with the following pattern:

/<prefix>/<pan id>/<network address>/<end point>/<profile id>/<device id>
Prefix The URI prefix specified when the ZigBee sub-system was registered with the code framework
Pan Id The ZigBee PAN ID (0x0000-0x3FFF) encoded as hex
Network Address The 16-bit ZigBee address (0x0000-0xFFF7) encoded as hex
End Point The 16-bit ZigBee end point (0x01-0xF0) encoded as hex
Profile ID The ZigBee application profile id (0x0000-0xFFFF) encoded as hex
Device ID The ZigBee device id

The following example may describe a dimmable light (0x0100) under the home automation profile (0x0104).



  • The profile id and device id in the URI are used to track the ZigBee application behind the end point. The profile/device id maps to the OIC profile that the resource represents. This may be better represented as query name-value pairs or anchors.
  • To reduce schedule risks, ZigBee discovery timing should be evaluated as a POC early.
  • The discovery callback should be designed to handle a non-piggyback response as ZigBee discovery may take some time.

ZigBee Resource Operation

When the core framework server receives a REST operation from a client against a resource, the following steps are expected:

  1. The core framework matches the URI against the ZigBee subsystem registered prefix. If they match continue.
  2. The ZigBee subsystem decodes the URI to map to the target ZigBee endpoint.
  3. The ZigBee subsystem delegates the representation to a OIC-to-ZigBee profile mapper
  4. The ZigBee subsystem dispatches the command to the device.
  5. The ZigBee subsystem returns results


ZigBee Hardware Abstraction

To be defined.

To Do

  • Add sequence diagrams
  • Provide concrete examples based on light bulb
legacy_zigbee_device_support.txt · Last modified: 2015/05/28 17:07 by Patrick Lankswert