Package 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 Details

    • 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:

    • LOGICAL_TYPE

      static final String LOGICAL_TYPE
      Property name for the device logical type. The property value is of type Short.
      See Also:

    • 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:

    • PAN_ID

      static final String PAN_ID
      Property containing the ZigBee network PAN ID. The property is of type Integer.
      See Also:

    • 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:

    • 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:

    • 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:

    • ZED

      static final short ZED
      Constant value used as logical type value when the ZigBee device is an End Device.
      See Also:

    • COORDINATOR

      static final short COORDINATOR
      Constant value used as logical type value when the ZigBee device is a Coordinator.
      See Also:

    • ROUTER

      static final short ROUTER
      Constant value used as logical type value when the ZigBee device is a Router.
      See Also:

  • Method Details

    • 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:
      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:
      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:

      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:

      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:

      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:
      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:
      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.