org.osgi.service.zigbee

Interface ZigBeeNode

All Known Subinterfaces:

ZigBeeHost

public interface ZigBeeNode

This interface represents a ZigBee node, means a physical device that can communicate using the ZigBee protocol.

Each physical device may contain up 240 logical devices which are represented by the ZigBeeEndpoint class.

Each logical device is identified by an EndPoint address, but shares:

• either the 64-bit 802.15.4 IEEE Address
• or the 16-bit ZigBee Network Address.

"Consumers of this API must not implement this interface"

Field Summary

Fields

Modifier and Type	Field and Description
static short	COORDINATOR Constant value used as logical type value when the ZigBee device is a Coordinator.
static String	EXTENDED_PAN_ID Key of String containing the device node network extended PAN ID.
static String	IEEE_ADDRESS Property key for the mandatory node IEEE Address representing node MAC address.
static String	LOGICAL_TYPE Property name for the device logical type.
static String	MANUFACTURER_CODE Property name for a manufacturer code that is allocated by the ZigBee Alliance, relating the manufacturer to the device.
static String	PAN_ID Property containing the ZigBee network PAN ID.
static String	POWER_SOURCE ZigBee power source, that is, 3rd bit of "MAC Capabilities" in Node Descriptor.
static String	RECEIVER_ON_WHEN_IDLE ZigBee receiver on when idle, that is, 4th bit of "MAC Capabilities" in Node Descriptor.
static short	ROUTER Constant value used as logical type value when the ZigBee device is a Router.
static short	ZED Constant value used as logical type value when the ZigBee device is an End Device.

Method Summary

Modifier and Type	Method and Description
ZCLCommandResponseStream	broadcast(int clusterID, ZCLFrame frame) Broadcasts a given ZCL Frame to cluster clusterID on all the ZigBeeEndpoint that are running on this node (endpoint broadcasting).
ZCLCommandResponseStream	broadcast(int clusterID, ZCLFrame frame, String exportedServicePID) Broadcasts a given ZCL Frame to cluster clusterID on all the ZigBeeEndpoint that are running on this node (endpoint broadcasting).
Promise<ZigBeeComplexDescriptor>	getComplexDescriptor() Retrieves the ZigBee node Complex Descriptor.
ZigBeeEndpoint[]	getEndpoints() Returns the array of the endpoints hosted by this node.
BigInteger	getExtendedPanId() Returns the network Extended PAN identifier (EPID).
String	getHostPid() Returns the OSGi service PID of the ZigBee Host that is on the network of this node.
BigInteger	getIEEEAddress() Returns the ZigBee device node IEEE Address of this node.
Promise<Map<String,ZigBeeLinkQuality>>	getLinksQuality() Retrieves the link quality information to the neighbor nodes.
int	getNetworkAddress() Returns the current network address (alias short-address) of this node.
Promise<ZigBeeNodeDescriptor>	getNodeDescriptor() Retrieves the ZigBee node Node Descriptor.
int	getPanId() Returns the network Personal Area Network identifier (PAN ID).
Promise<ZigBeePowerDescriptor>	getPowerDescriptor() Retrieves the ZigBee node Power Descriptor.
Promise<Map<String,ZigBeeRoute>>	getRoutingTable() Retrieves the routing table information of the node.
Promise<String>	getUserDescription() Returns the user description of this node.
Promise<ZDPFrame>	invoke(int clusterIdReq, int expectedClusterIdRsp, ZDPFrame message) Sends the ZDPFrame to this ZigBeeNode with the specified cluster id.
Promise<ZDPFrame>	invoke(int clusterIdReq, ZDPFrame message) Sends the ZDPFrame to this ZigBeeNode with the specified cluster id.
Promise<Void>	leave() Requests this node to leave the ZigBee network.
Promise<Void>	leave(boolean rejoin, boolean removeChildren) Requests the device to leave the network.
Promise<Void>	setUserDescription(String userDescription) Sets the user description of this node.

Field Detail

IEEE_ADDRESS

static final String IEEE_ADDRESS

Property key for the mandatory node IEEE Address representing node MAC address. MAC Address is a 12-digit(48-bit) or 16-digit(64-bit) hexadecimal numbers.

See Also:

Constant Field Values

LOGICAL_TYPE

static final String LOGICAL_TYPE

Property name for the device logical type. The property value is of type Short.

See Also:

Constant Field Values

MANUFACTURER_CODE

static final String MANUFACTURER_CODE

Property name for a manufacturer code that is allocated by the ZigBee Alliance, relating the manufacturer to the device. The property is of type Integer.

See Also:

Constant Field Values

PAN_ID

static final String PAN_ID

Property containing the ZigBee network PAN ID. The property is of type Integer.

See Also:

Constant Field Values

EXTENDED_PAN_ID

static final String EXTENDED_PAN_ID

Key of String containing the device node network extended PAN ID. If the device type is "Coordinator", the extended pan id may be available only after the network is started. It means that internally the ZigBeeHost interface must update the service properties.

This property is of type BigInteger

See Also:

Constant Field Values

POWER_SOURCE

static final String POWER_SOURCE

ZigBee power source, that is, 3rd bit of "MAC Capabilities" in Node Descriptor. Set to true if the current power source is mains power, set to false, otherwise.

This property is of type Boolean.

See Also:

Constant Field Values

RECEIVER_ON_WHEN_IDLE

static final String RECEIVER_ON_WHEN_IDLE

ZigBee receiver on when idle, that is, 4th bit of "MAC Capabilities" in Node Descriptor. Set to true if the device does not disable its receiver to conserve power during idle periods, set to false otherwise.

This property is of type Boolean.

See Also:

Constant Field Values

ZED

static final short ZED

Constant value used as logical type value when the ZigBee device is an End Device.

See Also:

Constant Field Values

COORDINATOR

static final short COORDINATOR

Constant value used as logical type value when the ZigBee device is a Coordinator.

See Also:

Constant Field Values

ROUTER

static final short ROUTER

Constant value used as logical type value when the ZigBee device is a Router.

See Also:

Constant Field Values

Method Detail

getIEEEAddress

BigInteger getIEEEAddress()

Returns the ZigBee device node IEEE Address of this node.

Returns:

the ZigBee device node IEEE Address of this node.

getNetworkAddress

int getNetworkAddress()

Returns the current network address (alias short-address) of this node.

Returns:

the current network address of this node.

getHostPid

String getHostPid()

Returns the OSGi service PID of the ZigBee Host that is on the network of this node.

Returns:

the OSGi service PID of the ZigBee Host that is on the network of this node.

getPanId

int getPanId()

Returns the network Personal Area Network identifier (PAN ID).

Returns:

the network Personal Area Network identifier (PAN ID).

getExtendedPanId

BigInteger getExtendedPanId()

Returns the network Extended PAN identifier (EPID).

Returns:

the network Extended PAN identifier (EPID).

getEndpoints

ZigBeeEndpoint[] getEndpoints()

Returns the array of the endpoints hosted by this node.

Returns:

the array of the endpoints hosted by this node, returns an empty array if this node does not host any endpoint.

getNodeDescriptor

Promise<ZigBeeNodeDescriptor> getNodeDescriptor()

Retrieves the ZigBee node Node Descriptor. As described in Table 2.91 Fields of the Node_Desc_rsp Command of the ZigBee specification, a Node_Desc_rsp command can return with the following status codes:

• ZDPException.SUCCESS
• ZDPException.DEVICE_NOT_FOUND
• ZDPException.INV_REQUESTTYPE
• ZDPException.NO_DESCRIPTOR

Returns:

A promise representing the completion of this asynchronous call. It will be used in order to return the node descriptor ZigBeeNodeDescriptor. If the ZDP Node_Desc_rsp do not return success, the promise must fail with a ZDPException exception with the correct status code.

getPowerDescriptor

Promise<ZigBeePowerDescriptor> getPowerDescriptor()

Retrieves the ZigBee node Power Descriptor. As described in Table 2.92 Fields of the Power_Desc_rsp Command of the ZigBee specification, a Power_Desc_rsp command can return with the following status codes:

• ZDPException.SUCCESS
• ZDPException.DEVICE_NOT_FOUND
• ZDPException.INV_REQUESTTYPE
• ZDPException.NO_DESCRIPTOR

Returns:

A promise representing the completion of this asynchronous call. It will be used in order to return the node power descriptor ZigBeePowerDescriptor. If the ZDP Power_Desc_rsp do not return success, the promise must fail with a ZDPException exception with the correct status code.

getComplexDescriptor

Promise<ZigBeeComplexDescriptor> getComplexDescriptor()

Retrieves the ZigBee node Complex Descriptor.

As described in Table 2.92 Fields of the Complex_Desc_rsp Command of the ZigBee specification, a Complex_Desc_rsp command can return with the following status codes:

• ZDPException.SUCCESS
• ZDPException.DEVICE_NOT_FOUND
• ZDPException.INV_REQUESTTYPE
• ZDPException.NO_DESCRIPTOR

Returns:

A promise representing the completion of this asynchronous call. It will be used in order to return the complex descriptor ZigBeeComplexDescriptor. If the ZDP Complex_Desc_rsp do not return success, the promise must fail with a ZDPException exception with the correct status code.

getLinksQuality

Promise<Map<String,ZigBeeLinkQuality>> getLinksQuality()

Retrieves the link quality information to the neighbor nodes.

An implementation of this method may use the Mgmt_Lqi_req and Mgmt_Lqi_rsp messages to retrieve the Link Quality table (also known as NeighborTableList in the ZigBee Specification).

The method limit the Link Quality table to the ZigBeeNode service discovered.

In case of failure, the target device may report error code ZDPException.NOT_SUPPORTED.

Returns:

A promise representing the completion of this asynchronous call. It will be resolved with the result of this operation. In case of success the resolved value will be a Map containing the Service.PID as String key of the ZigBeeNode service and the value the ZigBeeLinkQuality for that node. In case of errors the promise must fail with the correct ZDPException.

getRoutingTable

Promise<Map<String,ZigBeeRoute>> getRoutingTable()

Retrieves the routing table information of the node. This routing table is also known as RoutingTableList in the ZigBee Specification.

An implementation of this method may use the Mgmt_Rtg_req ZDP command to retrieve the Routing Table .

The target device may report a status code ZDPException.NOT_SUPPORTED in case of failure.

Returns:

A promise representing the completion of this asynchronous call. In case of success, the resolved value will be a Map containing the Service.PID as String key of the ZigBeeNode service and the value the ZigBeeRoute for that node. In case of failure a ZDPException exception with the correct status code must be used to fail the promise.

leave

Promise<Void> leave()

Requests this node to leave the ZigBee network.

As described in Table 2.131 Fields of the Mgmt_Leave_rsp Command of the ZigBee specification, a Mgmt_Leave_rsp ZDP command may return the following status values:

• ZDPException.SUCCESS
• ZDPException.NOT_SUPPORTED
• ZDPException.NOT_AUTHORIZED
• any status code returned from the NLMELEAVE.confirm primitive

Returns:

A promise representing the completion of this asynchronous call. In case of success, the promise is resolved with a null value, otherwise with the correct ZDPException exception.

leave

Promise<Void> leave(boolean rejoin,
                    boolean removeChildren)

Requests the device to leave the network.

As described in Table 2.131 Fields of the Mgmt_Leave_rsp Command of the ZigBee specification, a Mgmt_Leave_rsp command could return the following status values:

• ZDPException.SUCCESS
• ZDPException.NOT_SUPPORTED
• ZDPException.NOT_AUTHORIZED
• any status code returned from the NLMELEAVE.confirm primitive

Parameters:

rejoin - true if the device being asked to leave from the current parent is requested to rejoin the network. Otherwise, false.

removeChildren - true if the device being asked to leave the network is also being asked to remove its child devices, if any. Otherwise, false.

Returns:

A promise representing the completion of this asynchronous call. In case of success, the ZigBeeNode service must be unregistered, first and then the promise may be resolved with a null value, otherwise with the correct ZDPException exception.

invoke

Promise<ZDPFrame> invoke(int clusterIdReq,
                         int expectedClusterIdRsp,
                         ZDPFrame message)

Sends the ZDPFrame to this ZigBeeNode with the specified cluster id. This method expects a specific cluster in the response to the request.

Parameters:

clusterIdReq - the cluster Id of the ZDPFrame that will be sent to the device.

expectedClusterIdRsp - the expected cluster Id of the response to the ZDPFrame sent.

message - the ZDPFrame containing the message.

Returns:

A promise representing the completion of this asynchronous call. In case of success the promise resolves with the response ZDPFrame.

invoke

Promise<ZDPFrame> invoke(int clusterIdReq,
                         ZDPFrame message)

Sends the ZDPFrame to this ZigBeeNode with the specified cluster id. This method expects a specific cluster in the response to the request. This method considers that the 0x8000 + clusterIdReq is the clusterId expected from messaged received for the message sent by this request.

Parameters:

clusterIdReq - the cluster Id of the ZDPFrame that will be sent to the device.

message - the ZDPFrame containing the message.

Returns:

A promise representing the completion of this asynchronous call. In case of success the promise resolves with the response ZDPFrame.

broadcast

ZCLCommandResponseStream broadcast(int clusterID,
                                   ZCLFrame frame)

Broadcasts a given ZCL Frame to cluster clusterID on all the ZigBeeEndpoint that are running on this node (endpoint broadcasting).

Parameters:

clusterID - the cluster ID the broadcast message is directed.

frame - a ZCL Frame that contains the command that have to be broadcast to the specific cluster of all the endpoints running on the node.

Returns:

a response stream instance that collects and allows a client to be asynchronously notified about the ZCLFrame responses sent back by the ZigBee nodes.

broadcast

ZCLCommandResponseStream broadcast(int clusterID,
                                   ZCLFrame frame,
                                   String exportedServicePID)

Broadcasts a given ZCL Frame to cluster clusterID on all the ZigBeeEndpoint that are running on this node (endpoint broadcasting). The source endpoint of the APS message sent, is set to the endpoint identifier of the exportedServicePID service.

Parameters:

clusterID - the cluster ID the broadcast message is directed.

frame - a ZCL Frame that contains the command that have to be broadcast to the specific cluster of all the endpoints running on the node.

exportedServicePID - the source endpoint of the command request. In targeted situations, the source endpoint is the valid service PID of an exported endpoint.

Returns:

a response stream instance that collects and allows the caller to be asynchronously notified about the ZCLFrame responses sent back by the ZigBee nodes.

getUserDescription

Promise<String> getUserDescription()

Returns the user description of this node. As described in Table 2.97 Fields of the User_Desc_rsp Command of the ZigBee specification, a User_Desc_rsp may return the following status:

• ZDPException.SUCCESS
• ZDPException.NOT_SUPPORTED
• ZDPException.DEVICE_NOT_FOUND
• ZDPException.INV_REQUESTTYPE
• ZDPException.NO_DESCRIPTOR

Returns:

A promise representing the completion of this asynchronous call. It will be used in order to return the node user description (String). In case of errors the promise will fail with a ZDPException exception containing the response status code value.

setUserDescription

Promise<Void> setUserDescription(String userDescription)

Sets the user description of this node. As described in Table 2.137 ZDP Enumerations Description of the ZigBee specification, a Set_User_Desc_rsp request may return the following status:

• ZDPException.SUCCESS
• ZDPException.DEVICE_NOT_FOUND
• ZDPException.INV_REQUESTTYPE
• ZDPException.NO_DESCRIPTOR

Parameters:

userDescription - the user description.

Returns:

A promise representing the completion of this asynchronous call. In case of success the promise returns a null value. In case of errors the promise must fail with a ZDPException exception containing the response status code value.