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.
    Author:
    $Id: c2d43f1e070a2b751a705f878098b526cbe2c9e4 $
    • Field Detail

      • IEEE_ADDRESS

        static final java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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

        java.math.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

        java.lang.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

        java.math.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.
      • getLinksQuality

        Promise<java.util.Map<java.lang.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<java.util.Map<java.lang.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<java.lang.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<java.lang.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,
                                           java.lang.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.
      • setUserDescription

        Promise<java.lang.Void> setUserDescription​(java.lang.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.