The CoordinatorConnection Service

The central entry point in the ZigBee system is the com.prosyst.mbs.services.zigbee.CoordinatorConnection service in the Runtime. It represents the API to contact a ZigBee coordinator and make requests in the network through it. The service could be used for node discovery and for sending data to the network by means of requests.

For each ZigBee coordinator attached to the same OSGi-aware device, a separate CoordinatorConnection service is registered upon configuring the communication port for communication with the coordinator. To differentiate between the CoordinatorConnection services, use their registration properties which reflect the content of the configurations which triggered services registration.

Device and Service Discovery

Device discovery implies requests to discover the identity of the other nodes participating in the ZigBee network. Service discovery refers to the process of determining the services offered by the other devices. Services are represented by endpoints.

To start device and service discovery:

1. Get the com.prosyst.mbs.services.zigbee.NodeDiscoveryService from the obtained CoordinatorConnection by invoking the getNodeDiscoveryService method.
2. Call the discoverDevices method.
3. The ZigBee module uses OSGi events for notifications for the discovery process starting, finishing and when new devices are discovered. Each ZigBee device is represented as a ZigBeeDevice instance. To get device properties and to retrieve specific device attributes use its getter methods by sending queries in the network. For example, to acquire information about the endpoints of a device, call the getActiveEndpoints method and then retrieve a target endpoint-specific simple descriptor with the getSimpleDescriptor. As a result a SimpleDescriptor object is returned - wrapping the properties of the descriptor such as: supported profile, input/output clusters, etc.

Transmitting Messages to Devices

For exchanging bidirectional messages with ZigBee devices and receive their response, use the com.prosyst.mbs.services.zigbee.TransmitService. It could be obtained by invoking the getTransmitService method of the coordinator-specific CoordinatorConnection service.

A ZigBeeMessage object represents each request to a target device and response from it. Hence, a request to be sent create such an object and use the proper sendMessagetXxx method of TransmitService.

As ZigBeeMessage is an interface, it could be either implemented manually or an instance of the ready implementation ZigBeeMessageImpl to be created.

Pack real data in Frame objects. ZDOFrames are used when communicating at ZDP profile level (ready implementation com.prosyst.mbs.services.zigbee.zdo.ZDOFrameImpl), or ZCLFrames when the requests/responses follow the ZCL specification (ready implementation com.prosyst.mbs.services.zigbee.zcl.general.ZCLFrameImpl).

ZCL Metadata Service (com.prosyst.mbs.services.zigbee.metadata.provider.ZCLMetadataService) is used to easily generate a ZCL frame if the cluster has registered metadata in the service. Having an endpoint's simple descriptor, the supported profile, clusters and information about a command's payload could be obtained from the relevant cluster's commands description. See "Working with ZCL Metadata" for more details.

The information back can be handled either in synchronous or asynchronous way:

• To execute a synchronous command transmission, use one of the sendRequestBlocking methods of TransmitService.
• To transmit a command in asynchronous way, implement the TransmitCallBack interface and use the sendRequest method of TransmitService. The TransmitCallBack listener will be called when a response arrives.

ZCL Parser is used to parse the ZCL Frame of the received ZigBee response message and get the values of the parameters contained in the payload. To parse the frame the CommandDescription object of the response message needs to be received.

See the Using the ZCL Metadata when Transmitting Commands section in this page for more details.

The CoordinatorInterface

The CoordinatorInterface allows direct operation calls on the coordinator device. It can be accessed from CoordinatorConnection service, among the other coordinator services/interfaces. Possible actions are channel switching or resetting the device.