XBeeNetwork (XBee Java Library)

java.lang.Object
- com.digi.xbee.api.XBeeNetwork

Direct Known Subclasses:

DigiMeshNetwork, DigiPointNetwork, Raw802Network, ZigBeeNetwork
```
public class XBeeNetwork
extends Object
```
This class represents an XBee Network.
The network allows the discovery of remote devices in the same network as the local one and stores them.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addDiscoveryListener(IDiscoveryListener listener)` Adds the given discovery listener to the list of listeners to be notified when the discovery process is running.
`RemoteXBeeDevice`	`addRemoteDevice(RemoteXBeeDevice remoteDevice)` Adds the given remote device to the network.
`List<RemoteXBeeDevice>`	`addRemoteDevices(List<RemoteXBeeDevice> list)` Adds the given list of remote devices to the network.
`void`	`clearDeviceList()` Removes all the devices from this network.
`RemoteXBeeDevice`	`discoverDevice(String id)` Discovers and reports the first remote XBee device that matches the supplied identifier.
`List<RemoteXBeeDevice>`	`discoverDevices(List<String> ids)` Discovers and reports all remote XBee devices that match the supplied identifiers.
`RemoteXBeeDevice`	`getDevice(String id)` Returns the first remote device that matches the supplied identifier.
`RemoteXBeeDevice`	`getDevice(XBee16BitAddress address)` Returns the remote device already contained in the network whose 16-bit address matches the given one.
`RemoteXBeeDevice`	`getDevice(XBee64BitAddress address)` Returns the remote device already contained in the network whose 64-bit address matches the given one.
`List<RemoteXBeeDevice>`	`getDevices()` Returns all remote devices already contained in the network.
`List<RemoteXBeeDevice>`	`getDevices(String id)` Returns all remote devices that match the supplied identifier.
`int`	`getNumberOfDevices()` Returns the number of devices already discovered in this network.
`boolean`	`isDiscoveryRunning()` Retrieves whether the discovery process is running or not.
`void`	`removeDiscoveryListener(IDiscoveryListener listener)` Removes the given discovery listener from the list of discovery listeners.
`void`	`removeRemoteDevice(RemoteXBeeDevice remoteDevice)` Removes the given remote XBee device from the network.
`void`	`setDiscoveryOptions(Set<DiscoveryOptions> options)` Configures the discovery options (`NO` parameter) with the given value.
`void`	`setDiscoveryTimeout(long timeout)` Configures the discovery timeout (`NT` parameter) with the given value.
`void`	`startDiscoveryProcess()` Starts the discovery process with the configured timeout and options.
`void`	`stopDiscoveryProcess()` Stops the discovery process if it is running.
`String`	`toString()`

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Method Detail
  - addDiscoveryListener
```
public void addDiscoveryListener(IDiscoveryListener listener)
```
    Adds the given discovery listener to the list of listeners to be notified when the discovery process is running.
    If the listener has already been included, this method does nothing.
    
    Parameters:
    
    listener - Listener to be notified when the discovery process is running.
    
    Throws:
    
    NullPointerException - if listener == null.
    
    See Also:
    
    IDiscoveryListener, removeDiscoveryListener(IDiscoveryListener)
  - addRemoteDevice
```
public RemoteXBeeDevice addRemoteDevice(RemoteXBeeDevice remoteDevice)
```
    Adds the given remote device to the network.
    Notice that this operation does not join the remote XBee device to the network; it just tells the network that it contains that device. However, the device has only been added to the device list, and may not be physically in the same network.
    
    The way of adding a device to the network is based on the 64-bit address. If it is not configured:
    - For 802.15.4 and ZigBee devices, it will use the 16-bit address.
    - For the rest will return false as the result of the addition.
    Parameters:
    
    remoteDevice - The remote device to be added to the network.
    
    Returns:
    
    The remote XBee Device instance in the network, null if the device could not be successfully added.
    
    Throws:
    
    NullPointerException - if RemoteDevice == null.
    
    See Also:
    
    addRemoteDevices(List), removeRemoteDevice(RemoteXBeeDevice), RemoteXBeeDevice
  - addRemoteDevices
```
public List<RemoteXBeeDevice> addRemoteDevices(List<RemoteXBeeDevice> list)
```
    Adds the given list of remote devices to the network.
    Notice that this operation does not join the remote XBee devices to the network; it just tells the network that it contains those devices. However, the devices have only been added to the device list, and may not be physically in the same network.
    
    The way of adding a device to the network is based on the 64-bit address. If it is not configured:
    - For 802.15.4 and ZigBee devices, the 16-bit address will be used instead.
    - For the rest will return false as the result of the addition.
    Parameters:
    
    list - The list of remote devices to be added to the network.
    
    Returns:
    
    A list with the successfully added devices to the network.
    
    Throws:
    
    NullPointerException - if list == null.
    
    See Also:
    
    addRemoteDevice(RemoteXBeeDevice), RemoteXBeeDevice
  - clearDeviceList
```
public void clearDeviceList()
```
    Removes all the devices from this network.
    The network will be empty after this call returns.
    
    Notice that this does not imply removing the XBee devices from the actual XBee network; it just tells the object that the list should be empty now. Next time a discovery is performed, the list could be filled with the remote XBee devices found.
    
    See Also:
    
    removeRemoteDevice(RemoteXBeeDevice)
  - discoverDevice
```
public RemoteXBeeDevice discoverDevice(String id)
                                throws XBeeException
```
    Discovers and reports the first remote XBee device that matches the supplied identifier.
    This method blocks until the device is discovered or the configured timeout expires. To configure the discovery timeout, use the method setDiscoveryTimeout(long).
    
    To configure the discovery options, use the setDiscoveryOptions(Set) method.
    
    Parameters:
    
    id - The identifier of the device to be discovered.
    
    Returns:
    
    The discovered remote XBee device with the given identifier, null if the timeout expires and the device was not found.
    
    Throws:
    
    IllegalArgumentException - if id.length() == 0.
    
    InterfaceNotOpenException - if the device is not open.
    
    NullPointerException - if id == null.
    
    XBeeException - if there is an error discovering the device.
    
    See Also:
    
    discoverDevices(List), getDevice(String), RemoteXBeeDevice
  - discoverDevices
```
public List<RemoteXBeeDevice> discoverDevices(List<String> ids)
                                       throws XBeeException
```
    Discovers and reports all remote XBee devices that match the supplied identifiers.
    This method blocks until the configured timeout expires. To configure the discovery timeout, use the method setDiscoveryTimeout(long).
    
    To configure the discovery options, use the setDiscoveryOptions(Set) method.
    
    Parameters:
    
    ids - List which contains the identifiers of the devices to be discovered.
    
    Returns:
    
    A list of the discovered remote XBee devices with the given identifiers.
    
    Throws:
    
    IllegalArgumentException - if ids.size() == 0.
    
    InterfaceNotOpenException - if the device is not open.
    
    NullPointerException - if ids == null.
    
    XBeeException - if there is an error discovering the devices.
    
    See Also:
    
    discoverDevice(String), RemoteXBeeDevice
  - getDevice
```
public RemoteXBeeDevice getDevice(String id)
```
    Returns the first remote device that matches the supplied identifier.
    Note that this method does not perform a discovery, only returns the device that has been previously discovered.
    
    Parameters:
    
    id - The identifier of the device to be retrieved.
    
    Returns:
    
    The remote XBee device contained in the network with the given identifier, null if the network does not contain any device with that Node ID.
    
    Throws:
    
    IllegalArgumentException - if id.length() == 0.
    
    NullPointerException - if id == null.
    
    See Also:
    
    discoverDevice(String), getDevices(String), RemoteXBeeDevice
  - getDevice
```
public RemoteXBeeDevice getDevice(XBee16BitAddress address)
                           throws OperationNotSupportedException
```
    Returns the remote device already contained in the network whose 16-bit address matches the given one.
    Note that this method does not perform a discovery, only returns the device that has been previously discovered.
    
    Parameters:
    
    address - The 16-bit address of the device to be retrieved.
    
    Returns:
    
    The remote device in the network or null if it is not found.
    
    Throws:
    
    IllegalArgumentException - if address.equals(XBee16BitAddress.UNKNOWN_ADDRESS).
    
    NullPointerException - if address == null.
    
    OperationNotSupportedException - if the protocol of the local XBee device is DigiMesh or Point-to-Multipoint.
  - getDevice
```
public RemoteXBeeDevice getDevice(XBee64BitAddress address)
```
    Returns the remote device already contained in the network whose 64-bit address matches the given one.
    Note that this method does not perform a discovery, only returns the device that has been previously discovered.
    
    Parameters:
    
    address - The 64-bit address of the device to be retrieved.
    
    Returns:
    
    The remote device in the network or null if it is not found.
    
    Throws:
    
    IllegalArgumentException - if address.equals(XBee64BitAddress.UNKNOWN_ADDRESS).
    
    NullPointerException - if address == null.
  - getDevices
```
public List<RemoteXBeeDevice> getDevices()
```
    Returns all remote devices already contained in the network.
    Note that this method does not perform a discovery, only returns the devices that have been previously discovered.
    
    Returns:
    
    A list with all XBee devices in the network.
    
    See Also:
    
    getDevices(String), RemoteXBeeDevice
  - getDevices
```
public List<RemoteXBeeDevice> getDevices(String id)
```
    Returns all remote devices that match the supplied identifier.
    Note that this method does not perform a discovery, only returns the devices that have been previously discovered.
    
    Parameters:
    
    id - The identifier of the devices to be retrieved.
    
    Returns:
    
    A list of the remote XBee devices contained in the network with the given identifier.
    
    Throws:
    
    IllegalArgumentException - if id.length() == 0.
    
    NullPointerException - if id == null.
    
    See Also:
    
    getDevice(String), RemoteXBeeDevice
  - getNumberOfDevices
```
public int getNumberOfDevices()
```
    Returns the number of devices already discovered in this network.
    
    Returns:
    
    The number of devices already discovered in this network.
  - isDiscoveryRunning
```
public boolean isDiscoveryRunning()
```
    Retrieves whether the discovery process is running or not.
    
    Returns:
    
    true if the discovery process is running, false otherwise.
    
    See Also:
    
    startDiscoveryProcess(), stopDiscoveryProcess()
  - removeDiscoveryListener
```
public void removeDiscoveryListener(IDiscoveryListener listener)
```
    Removes the given discovery listener from the list of discovery listeners.
    If the listener is not included in the list, this method does nothing.
    
    Parameters:
    
    listener - Discovery listener to remove.
    
    Throws:
    
    NullPointerException - if listener == null.
    
    See Also:
    
    IDiscoveryListener, addDiscoveryListener(IDiscoveryListener)
  - removeRemoteDevice
```
public void removeRemoteDevice(RemoteXBeeDevice remoteDevice)
```
    Removes the given remote XBee device from the network.
    Notice that this operation does not remove the remote XBee device from the actual XBee network; it just tells the network object that it will no longer contain that device. However, next time a discovery is performed, it could be added again automatically.
    
    This method will check for a device that matches the 64-bit address of the provided one, if found, that device will be removed from the corresponding list. In case the 64-bit address is not defined, it will use the 16-bit address for DigiMesh and ZigBee devices.
    
    Parameters:
    
    remoteDevice - The remote device to be removed from the network.
    
    Throws:
    
    NullPointerException - if RemoteDevice == null.
    
    See Also:
    
    addRemoteDevice(RemoteXBeeDevice), clearDeviceList(), RemoteXBeeDevice
  - setDiscoveryOptions
```
public void setDiscoveryOptions(Set<DiscoveryOptions> options)
                         throws TimeoutException,
                                XBeeException
```
    Configures the discovery options (NO parameter) with the given value.
    
    Parameters:
    
    options - New discovery options.
    
    Throws:
    
    TimeoutException - if there is a timeout setting the discovery options.
    
    XBeeException - if there is any other XBee related exception.
    
    See Also:
    
    setDiscoveryTimeout(long), DiscoveryOptions
  - setDiscoveryTimeout
```
public void setDiscoveryTimeout(long timeout)
                         throws TimeoutException,
                                XBeeException
```
    Configures the discovery timeout (NT parameter) with the given value.
    Note that in some protocols, the discovery process may take longer than the value set in this method due to the network propagation time.
    
    Parameters:
    
    timeout - New discovery timeout in milliseconds.
    
    Throws:
    
    TimeoutException - if there is a timeout setting the discovery timeout.
    
    XBeeException - if there is any other XBee related exception.
    
    See Also:
    
    setDiscoveryOptions(Set)
  - startDiscoveryProcess
```
public void startDiscoveryProcess()
```
    Starts the discovery process with the configured timeout and options.
    To be notified every time an XBee device is discovered, add a IDiscoveryListener using the addDiscoveryListener(IDiscoveryListener) method before starting the discovery process.
    
    To configure the discovery timeout, use the setDiscoveryTimeout(long) method.
    
    To configure the discovery options, use the setDiscoveryOptions(Set) method.
    
    Throws:
    
    IllegalStateException - if the discovery process is already running.
    
    InterfaceNotOpenException - if the device is not open.
    
    See Also:
    
    addDiscoveryListener(IDiscoveryListener), stopDiscoveryProcess()
  - stopDiscoveryProcess
```
public void stopDiscoveryProcess()
```
    Stops the discovery process if it is running.
    Note that DigiMesh/DigiPoint devices are blocked until the discovery time configured (NT parameter) has elapsed, so if you try to get/set any parameter during the discovery process you will receive a timeout exception.
    
    See Also:
    
    isDiscoveryRunning(), removeDiscoveryListener(IDiscoveryListener), startDiscoveryProcess()
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object

Class XBeeNetwork

Method Summary

Methods inherited from class java.lang.Object

Method Detail

addDiscoveryListener

addRemoteDevice

addRemoteDevices

clearDeviceList

discoverDevice

discoverDevices

getDevice

getDevice

getDevice

getDevices

getDevices

getNumberOfDevices

isDiscoveryRunning

removeDiscoveryListener

removeRemoteDevice

setDiscoveryOptions

setDiscoveryTimeout

startDiscoveryProcess

stopDiscoveryProcess

toString