org.osgi.service.zigbee

Interface ZigBeeEndpoint

public interface ZigBeeEndpoint

This interface represents a ZigBee EndPoint. A ZigBeeEndpoint must be registered as a OSGi service with ZigBeeNode.IEEE_ADDRESS, and ZigBeeEndpoint.ENDPOINT_ID properties.

Field Summary

Fields

Modifier and Type	Field and Description
static String	DEVICE_CATEGORY Constant used by all ZigBee devices indicating the device category.
static String	DEVICE_ID Property containing the application device identifier.
static String	DEVICE_VERSION Property containing the application device version.
static String	ENDPOINT_ID Property containing the EndPoint ID of the device.
static String	HOST_PID Property containing the ZigBeeHost's pid.
static String	INPUT_CLUSTERS Property containing a list of input clusters.
static String	OUTPUT_CLUSTERS Property containing a list of output clusters.
static String	PROFILE_ID Property containing the application profile identifier also contained in the ZigBee Simple Descriptor.
static String	ZIGBEE_EXPORT Property used to mark if a ZigBeeEndPoint service is an exported one or not.

Method Summary

Modifier and Type	Method and Description
Promise<Void>	bind(String servicePid, int clusterId) Adds the following entry in the Binding Table of the device:
Promise<List<String>>	getBoundEndPoints(int clusterId) Returns bound endpoints (identified by their service PIDs) on a specific cluster ID.
ZCLCluster	getClientCluster(int clientClusterId) Returns the client cluster identified by the cluster identifier.
ZCLCluster[]	getClientClusters() Returns an array of client (output) clusters.
short	getId() Returns the identifier of this endpoint, that is the Endpoint ID.
BigInteger	getNodeAddress() Returns the IEEE Address of the node containing this endpoint.
ZCLCluster	getServerCluster(int serverClusterId) Returns the server (input) cluster identified by the given identifier.
ZCLCluster[]	getServerClusters() Returns an array of server (input) clusters.
Promise<ZigBeeSimpleDescriptor>	getSimpleDescriptor() Returns the simple descriptor of this endpoint.
void	notExported(ZigBeeException e) Notifies that the base driver is unable to export this endpoint.
Promise<Void>	unbind(String servicePid, int clusterId) Removes the following entry in the Binding Table of the device if it exists:

Field Detail

ENDPOINT_ID

static final String ENDPOINT_ID

Property containing the EndPoint ID of the device. This property is of type Short and its value must be in the range allowed by the ZigBee specifications for Zigbee endpoints identifiers.

It is mandatory service property for ZigBeeEndpoint services.

See Also:

Constant Field Values

PROFILE_ID

static final String PROFILE_ID

Property containing the application profile identifier also contained in the ZigBee Simple Descriptor. This property is of type Integer.

It is mandatory service property for this service.

See Also:

Constant Field Values

HOST_PID

static final String HOST_PID

Property containing the ZigBeeHost's pid. This property is of type String.

The ZigBee local host identifier is intended to uniquely identify the ZigBee local host, since there could be many hosts on the same platform.

All the endpoints that belong to a specific network MUST specify the value of the associated host pid. It is mandatory for imported endpoints, optional for exported endpoints.

See Also:

Constant Field Values

DEVICE_ID

static final String DEVICE_ID

Property containing the application device identifier. This identifier is also contained in the ZigBee Simple Descriptor. This property is of type Integer.

It is mandatory property for this service.

See Also:

Constant Field Values

DEVICE_VERSION

static final String DEVICE_VERSION

Property containing the application device version. The application device version is also contained in the ZigBee endpoint Simple Descriptor. This property is of type Byte.

It is mandatory property for this service.

See Also:

Constant Field Values

INPUT_CLUSTERS

static final String INPUT_CLUSTERS

Property containing a list of input clusters. This list is contained also in the ZigBee Simple Descriptor returned by the ZigBeeEndpoint service. This property is of type int[].

It is mandatory service property for this service.

See Also:

Constant Field Values

OUTPUT_CLUSTERS

static final String OUTPUT_CLUSTERS

Property containing a list of output clusters. This list is contained also in the ZigBee Simple Descriptor of the ZigBeeEndpoint service. This property is of type int[].

It is a mandatory service property for this service.

See Also:

Constant Field Values

ZIGBEE_EXPORT

static final String ZIGBEE_EXPORT

Property used to mark if a ZigBeeEndPoint service is an exported one or not. Imported endpoints do not have this property set. This service property requires no specific values.

See Also:

Constant Field Values

DEVICE_CATEGORY

static final String DEVICE_CATEGORY

Constant used by all ZigBee devices indicating the device category. It is a mandatory service property for this service.

See Also:

Constant Field Values

Method Detail

getId

short getId()

Returns the identifier of this endpoint, that is the Endpoint ID.

Returns:

the identifier of this endpoint, value ranges from 1 to 240.

getNodeAddress

BigInteger getNodeAddress()

Returns the IEEE Address of the node containing this endpoint.

Returns:

the IEEE Address of the node containing this endpoint.

getSimpleDescriptor

Promise<ZigBeeSimpleDescriptor> getSimpleDescriptor()

Returns the simple descriptor of this endpoint. As described in "Table 2.93 Fields of the Simple_Desc_rsp Command" of the ZigBee specification 1_053474r17ZB_TSC-ZigBee-Specification.pdf, a simple_decr request can have the following status: ZDPException.SUCCESS, ZDPException.INVALID_EP, ZDPException.NOT_ACTIVE, ZDPException.DEVICE_NOT_FOUND, ZDPException.INV_REQUESTTYPE or ZDPException.NO_DESCRIPTOR.

Returns:

A promise representing the completion of this asynchronous call. Promise.getValue() returns the node simple descriptor ZigBeeSimpleDescriptor in case of success and Promise.getFailure() returns the adequate ZDPException otherwise.

getServerClusters

ZCLCluster[] getServerClusters()

Returns an array of server (input) clusters.

Returns:

an array of server (input) clusters, returns an empty array if it does not provide any server cluster.

getServerCluster

ZCLCluster getServerCluster(int serverClusterId)

Returns the server (input) cluster identified by the given identifier.

Parameters:

serverClusterId - The server(input) cluster identifier.

Returns:

the server (input) cluster identified by the given identifier, or null if the given id is not listed in the simple descriptor.

Throws:

IllegalArgumentException - If the passed argument is outside the range [0, 0xffff].

getClientClusters

ZCLCluster[] getClientClusters()

Returns an array of client (output) clusters.

Returns:

an array of client (output) clusters, returns an empty array if does not provides any clients clusters.

getClientCluster

ZCLCluster getClientCluster(int clientClusterId)

Returns the client cluster identified by the cluster identifier.

Parameters:

clientClusterId - The client(output) cluster identifier.

Returns:

the client(output) cluster identified by the cluster identifier, or null if the given id is not listed in the simple descriptor.

Throws:

IllegalArgumentException - If the passed argument is outside the range [0, 0xffff].

bind

Promise<Void> bind(String servicePid,
                   int clusterId)

Adds the following entry in the Binding Table of the device:

this.getNodeAddress(), this.getId(), clusterId, device.getNodeAddress(), device.getId()

As described in "Table 2.7 APSME-BIND.confirm Parameters" of the ZigBee specification 1_053474r17ZB_TSC-ZigBee-Specification.pdf, a binding request can have the following results: APSException.SUCCESS, APSException.ILLEGAL_REQUEST, APSException.TABLE_FULL, APSException.NOT_SUPPORTED.

Parameters:

servicePid - the PID of the endpoint to bind to

clusterId - the cluster identifier to bind to

Returns:

A promise representing the completion of this asynchronous call. Promise.getFailure() returns null if the cluster has been successfully bound. The adequate ZigBeeEndpoint is returned otherwise.

unbind

Promise<Void> unbind(String servicePid,
                     int clusterId)

Removes the following entry in the Binding Table of the device if it exists:

this.getNodeAddress(), this.getId(), clusterId, device.getNodeAddress(), device.getId()

As described in "Table 2.9 APSME-UNBIND.confirm Parameters" of the ZigBee specification 1_053474r17ZB_TSC-ZigBee-Specification.pdf, an unbind request can have the following results: APSException.SUCCESS, APSException.ILLEGAL_REQUEST, APSException.INVALID_BINDING.

Parameters:

servicePid - The pid of the service to unbind.

clusterId - The cluster identifier to unbind.

Returns:

A promise representing the completion of this asynchronous call. Promise.getFailure() returns null if the cluster has been successfully bound. The adequate APSException is returned otherwise.

notExported

void notExported(ZigBeeException e)

Notifies that the base driver is unable to export this endpoint. This method is called by the base driver and used to give details about issues preventing the export of an endpoint.

Parameters:

e - A device ZigBeeException the occurred exception.

getBoundEndPoints

Promise<List<String>> getBoundEndPoints(int clusterId)

Returns bound endpoints (identified by their service PIDs) on a specific cluster ID. It is implemented on the base driver with Mgmt_Bind_req command. It is implemented without a command request in local endpoints.

As described in "Table 2.129 Fields of the Mgmt_Bind_rsp Command" of the ZigBee specification 1_053474r17ZB_TSC-ZigBee-Specification.pdf, a Mgmt_Bind_rsp command can have the following status: APSException.NOT_SUPPORTED or any status code returned from the APSME-GET.confirm primitive (see APSException).

Parameters:

clusterId - the cluster identifier of the targeted bindings.

Returns:

A promise representing the completion of this asynchronous call. Promise.getValue() returns a List of the bound endpoint service PIDs if the command is successful. The response object is null and the adequate APSException is returned by Promise.getFailure() otherwise.