Developing a new ZigBee Interface Controller (ZIC)

This page tries to explain the steps that are need for adding support for a new ZigBee hardware to the ZB4O, we try to explain this steps by using the XBee dongle as example (which is not supported at the moment).
It is important to notice that thanks to the OSGi Framework and the modular design of ZB4O, creating a new ZIC will not affects any other part of the code and users can add / remove ZIC during the execution time, by installing and starting the bundle that provide the implementation of the ZIC.

Introduction: ZB4O Architecture

ZB4O architecture exploits the OSGi Framework and the concept of OSGi Bundle and OSGi Service in order to achieve a modular design. In particular, ZB4O comprises a multi-layer architecture where an lowest layer (Access Layer) provides an abstract from the ZigBee hardware. As you can see from the figure
ZB4O Access Layer architecture
the ZigBee Base Driver API (zigbee.basedriver.api project on SVN) defines the abstraction for the ZigBee network by providing access to each ZigBee EndPoint as ZigBeeDevice OSGi service, while the ZigBee Base Driver (zigbee.basedriver project on SVN) is the component that implements the ZigBee Base Driver API and it takes care of:
  • dispatching of the message from and to the ZigBee network
  • discover and maintains the device composing the ZigBee network
    ZB4O for enabling a plugable ZIC architecture defined a Simple Driver API (aka ZIC, that you can find on zigbee.dongle.api projec on the trunk) which define an abstraction of the ZigBee hardware

To be continued

Appendix A: ZIC Life Cycle

a) Simple Driver interface. Context of method call:

public void setZigBeeNodeMode(NetworkMode m);                                                 // Driver must be in CLOSED state.
public void setZigBeeNetwork(byte ch, short panId);                                           // Driver must be in CLOSED state.
public void setSerialPort(String serialName, int bitRate);                                    // Driver must be in CLOSED state.
public void open(boolean cleanCache);                                                         // Driver must be in CLOSED state.
public void open();                                                                           // Driver must be in CLOSED state.
public void close();                                                                          // Driver can be in CLOSED, NETWORK_READY, NETWORK_INITIALIZING, HARDWARE_READY or CREATED status.
public ZDO_MGMT_LQI_RSP sendLQIRequest(ZDO_MGMT_LQI_REQ request);                             // If Network is not ready, returns null.
public ZDO_IEEE_ADDR_RSP sendZDOIEEEAddressRequest(ZDO_IEEE_ADDR_REQ request);                // If Network is not ready, returns null.
public ZDO_NODE_DESC_RSP sendZDONodeDescriptionRequest(ZDO_NODE_DESC_REQ request);            // If Network is not ready, returns null.
public ZDO_ACTIVE_EP_RSP sendZDOActiveEndPointRequest(ZDO_ACTIVE_EP_REQ request);             // If Network is not ready, returns null.
public ZDO_SIMPLE_DESC_RSP sendZDOSimpleDescriptionRequest(ZDO_SIMPLE_DESC_REQ request);      // If Network is not ready, returns null.
public boolean addAnnounceListener(AnnounceListner listner);                                  // For a generic driver, any Status is acceptable. (Specific drivers might require other conditions. See DriverCC2530 for an example.)
public boolean removeAnnounceListener(AnnounceListner listner);                               // For a generic driver, any Status is acceptable. (Specific drivers might require other conditions. See DriverCC2530 for an example.)
public AF_REGISTER_SRSP sendAFRegister(AF_REGISTER request);                                  // If Network is not ready, returns null.
public AF_DATA_CONFIRM sendAFDataRequest(AF_DATA_REQUEST request);                            // If Network is not ready, returns null.
public ZDO_BIND_RSP sendZDOBind(ZDO_BIND_REQ request);                                        // If Network is not ready, returns null.
public ZDO_UNBIND_RSP sendZDOUnbind(ZDO_UNBIND_REQ request);                                  // If Network is not ready, returns null.
public boolean removeAFMessageListener(AFMessageListner listner);                             // Returns true if listener was sucessfully removed. For a generic driver, any Status is acceptable.
public boolean addAFMessageListner(AFMessageListner listner);                                 // Returns true if listener was sucessfully added. For a generic driver, any Status is acceptable.
public long getExtendedPanId();                                                               // Returns -1 if Network is not ready or an internal error occours.
public long getIEEEAddress();                                                                 // Returns -1 if Network is not ready or an internal error occours.
public int getCurrentPanId();                                                                 // Returns -1 if Network is not ready or an internal error occours.
public int getCurrentChannel();                                                               // Returns -1 if Network is not ready or an internal error occours.
public int getCurrentState();                                                                 // Returns -1 if Network is not ready or an internal error occours.
public int getZigBeeNodeMode();                                                               // Returns -1 if an internal error occours.
public DriverStatus getDriverStatus();                                                        // Simply returns the DriverStatus.
public void addCustomDevice(String endpointNumber, String profileID,
String deviceID, String version, String inputClusters,
String outputCluster); // Driver can be in any Status.
public void createCustomDevicesOnDongle();                                                    // Driver can be in any Status.
public boolean newDevice(AF_REGISTER request);                                                // Can be called in any Status.

P.S.: If you find any mistakes, or feel the information is not enough or not helpful, please send an e-mail to the mailing-list at

(Work in progress...)

Appendix B: Looking for help?

Please post any question on the mailing-list at

Appendix C: Further reading

zb4o-access-layer.png - ZB4O Access Layer architecture (109.2 kB) Stefano Lenzi, 05/23/2014 02:36 pm