Package org.osgi.service.zigbee

Interface ZigBeeHost

All Superinterfaces:
ZigBeeNode
public interface ZigBeeHost extends ZigBeeNode
This interface represents the machine that hosts the code to run a ZigBee device or client. This machine is, for example, the ZigBee chip/dongle that is controlled by the base driver (below/under the OSGi execution environment).

ZigBeeHost is more than a ZigBeeNode.

It must be registered as a OSGi service.

Even if not specified explicitly in the javadoc, any method of this interface must throw an IllegalArgumentException exception if a or one of the passed arguments has a value not admitted by the method.

"Consumers of this API must not implement this interface"

  • Field Details

    • UNLIMITED_BROADCAST_RADIUS

      static final short UNLIMITED_BROADCAST_RADIUS
      Value constant to set an unlimited broadcast radius.
      See Also:

  • Method Details

    • start

      void start() throws Exception
      Starts the host. If the host is a ZigBeeNode.COORDINATOR, then it can be started with or without ZigBeeNode.PAN_ID and ZigBeeNode.EXTENDED_PAN_ID (that is, if no PAN_ID, and Extended PAN_ID are given, then they will be automatically generated and then added to the service properties).

      If the host is a ZigBeeNode.ROUTER, or a ZigBeeNode.ZED, then the host may start without a registered ZigBeeNode.PAN_ID property; the property will be set when the host will find and join a ZigBee network.

      The host status must be persistent, that is, if the host was started, then the host must starts again when the bundle restarts. In addition, the values of channel, pan id, extended pan id, and host PID must remain the same.

      Throws:
      Exception - Any exception related to the communication with the chip.

    • stop

      void stop() throws Exception
      Stops the host.
      Throws:
      Exception - Any exception related to the communication with the chip.

    • isStarted

      boolean isStarted()
      Checks the host's start/stop state.
      Returns:
      true if the host is started.

    • setPanId

      void setPanId(int panId)
      Sets the panId.
      Parameters:
      panId - The network Personal Area Network identifier (PAN ID)
      Throws:
      IllegalArgumentException - if set with a value out of the expected range [0x0000, 0xffff].
      IllegalStateException - If the host is already started.

    • setExtendedPanId

      void setExtendedPanId(BigInteger extendedPanId)
      Sets the extendedPanId.
      Parameters:
      extendedPanId - The network Extended PAN identifier(EPID)
      Throws:
      IllegalStateException - If the host is already started.

    • permitJoin

      void permitJoin(short duration) throws Exception
      Indicates if a ZigBee device can join the network.

      Broadcasts a Mgmt_Permit_req to all routers and the coordinator. If the duration argument is not equal to zero or 0xFF, the argument is a number of seconds and joining is permitted until it counts down to zero, after which time, joining is not permitted. If the duration is set to zero, joining is not permitted. If set to 0xFF, joining is permitted indefinitely or until another Mgmt_Permit_Joining_req is received by the coordinator.

      As described in "Table 2.133 Fields of the Mgmt_Permit_Joining_rsp Command" of the ZigBee specification 1_053474r17ZB_TSC-ZigBee-Specification.pdf, a permitJoin request can have the following status: ZDPException.SUCCESS, ZDPException.INV_REQUESTTYPE, ZDPException.NOT_AUTHORIZED or any status code returned from the NLMEPERMITJOINING.confirm primitive.

      Parameters:
      duration - The time during which associations are permitted.
      Throws:
      Exception - Any exception related to the communication with the chip.

    • setLogicalType

      void setLogicalType(short logicalNodeType) throws Exception
      Sets the host logical node type. ZigBee defines three different types of node: ZigBeeNode.COORDINATOR, ZigBeeNode.ROUTER and ZigBeeNode.ZED.
      Parameters:
      logicalNodeType - The logical node type.
      Throws:
      IllegalStateException - If the host is already started.
      Exception - Any exception related to the communication with the chip.

    • getChannel

      int getChannel() throws Exception
      Returns the current network channel.
      Returns:
      the current network channel.
      Throws:
      Exception - Any exception related to the communication with the chip.

    • updateNetworkChannel

      void updateNetworkChannel(byte channel) throws IOException
      Updates the network channel. 802.15.4 and ZigBee divide the 2.4GHz band into 16 channels, numbered from 11 to 26.

      As described in "Table 2.4.3.3.9 Mgmt_NWK_Update_req" of the ZigBee specification 1_053474r17ZB_TSC-ZigBee-Specification.pdf, this request is sent as broadcast by the network manager with a ScanDuration to be set with the channel parameter.

      Parameters:
      channel - The network channel.
      Throws:
      IllegalStateException - If the host is started, or the host is not a network manager.
      IOException - for serial communication exception.

    • getChannelMask

      int getChannelMask() throws Exception
      Returns the currently configured channel mask.
      Returns:
      the currently configured channel mask.
      Throws:
      Exception - Any exception related to the communication with the chip.

    • setChannelMask

      void setChannelMask(int mask) throws IOException
      Sets a new configured channel mask.

      As described in "Table 2.13 APSME-SET.confirm Parameters" of the ZigBee specification 1_053474r17ZB_TSC-ZigBee-Specification.pdf, a set request can have the following status: APSException.SUCCESS, APSException.INVALID_PARAMETER or APSException.UNSUPPORTED_ATTRIBUTE.

      Parameters:
      mask - A value representing the channel mask.
      Throws:
      IllegalStateException - If the host is already started.
      IOException - for serial communication exception.

    • refreshNetwork

      Promise<Boolean> refreshNetwork() throws Exception
      Forces a new network scan. It checks that the ZigBeeNode services are still representing an available node on the network. It also updates the whole representation of all nodes (endpoints, clusters, descriptors, attributes).
      Returns:
      A promise representing the completion of this asynchronous call. In case of success the promise will resolve with Boolean.TRUE otherwise the promise is failed with an exception.
      Throws:
      Exception - Any exception related to the communication with the chip.

    • getSecurityLevel

      int getSecurityLevel() throws Exception
      Returns the network security level.
      Returns:
      the network security level, that is, 0 if security is disabled, an int code if enabled (see "Table 4.38 Security Levels Available to the NWK, and APS Layers" of the ZigBee specification").
      Throws:
      Exception - Any exception related to the communication with the chip.

    • getPreconfiguredLinkKey

      String getPreconfiguredLinkKey() throws Exception
      Returns the current preconfigured link key.
      Returns:
      the current preconfigured link key.
      Throws:
      Exception - Any exception related to the communication with the chip.

    • createGroupService

      void createGroupService(int groupAddress) throws Exception
      Creates a ZigBeeGroup service that has not yet been discovered by the ZigBee Base Driver or that does not exist on the ZigBee network yet.
      Parameters:
      groupAddress - the address of the group to create.
      Throws:
      Exception - when a ZigBeeGroup service with the same groupAddress already exists.

    • broadcast

      ZCLCommandResponseStream broadcast(int clusterID, ZCLFrame frame)
      Broadcasts a ZCL frame to the cluster ID of all the nodes of the ZigBee network. The setBroadcastRadius(short) method, may be used to limit the broadcast radius used in the subsequent broadcast calls.
      Specified by:
      broadcast in interface ZigBeeNode
      Parameters:
      clusterID - The cluster ID this ZCL frame must be sent to.
      frame - A ZCL Frame.
      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.

    • broadcast

      ZCLCommandResponseStream broadcast(int clusterID, ZCLFrame frame, String exportedServicePID)
      Broadcasts a ZCL frame to the cluster ID of all the nodes of the ZigBee network. The passed exportedServicePID allows to force the source endpoint of the message sent to be the endpoint id of the exported ZigBeeEndPoint service having the specified service.pid property.
      Specified by:
      broadcast in interface ZigBeeNode
      Parameters:
      clusterID - The cluster ID.
      frame - A ZCL Frame.
      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.
      See Also:

    • getBroadcastRadius

      short getBroadcastRadius()
      Returns the current broadcast radius value.
      Returns:
      the current broadcast radius value.

    • setBroadcastRadius

      void setBroadcastRadius(short broadcastRadius)
      Sets the broadcast radius value. By default the ZigBeeHost must use UNLIMITED_BROADCAST_RADIUS as default value for the broadcast.
      Parameters:
      broadcastRadius - - is the number of routers that the messages are allowed to cross. Radius value is in the range from 0 to 0xff.
      Throws:
      IllegalArgumentException - if set with a value out of the expected range.
      IllegalStateException - if set when the ZigBeeHost is "running".

    • setCommunicationTimeout

      void setCommunicationTimeout(long timeout)
      Sets the timeout for the communication sent through this device.
      Parameters:
      timeout - the number of milliseconds before firing a timeout exception.

    • getCommunicationTimeout

      long getCommunicationTimeout()
      Returns the current value set for the communication timeout.
      Returns:
      the current value set for the communication timeout expressed in milliseconds.