com.digi.xbee.api

## Class XBeeDevice

- java.lang.Object
- - com.digi.xbee.api.AbstractXBeeDevice
  - - com.digi.xbee.api.XBeeDevice

- Direct Known Subclasses:
    DigiMeshDevice, DigiPointDevice, Raw802Device, ZigBeeDevice

      public class XBeeDevice
      extends AbstractXBeeDevice

  This class represents a local XBee device.
  See Also:
    `DigiMeshDevice`, `DigiPointDevice`, `Raw802Device`, `ZigBeeDevice`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `XBeeDevice(IConnectionInterface connectionInterface)` Class constructor.
    `XBeeDevice(String port, int baudRate)` Class constructor.
    `XBeeDevice(String port, int baudRate, int dataBits, int stopBits, int parity, int flowControl)` Class constructor.
    `XBeeDevice(String port, SerialPortParameters serialPortParameters)` Class constructor.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addDataListener(IDataReceiveListener listener)` Adds the provided listener to the list of listeners to be notified when new data is received.
    `void` | `addIOSampleListener(IIOSampleReceiveListener listener)` Adds the provided listener to the list of listeners to be notified when new IO samples are received.
    `void` | `addModemStatusListener(IModemStatusReceiveListener listener)` Adds the provided listener to the list of listeners to be notified when new Modem Status events are received.
    `void` | `addPacketListener(IPacketReceiveListener listener)` Adds the provided listener to the list of listeners to be notified when new packets are received.
    `void` | `close()` Closes the connection interface associated with this XBee device.
    `XBeeNetwork` | `getNetwork()` Returns the network associated with this XBee device.
    `OperatingMode` | `getOperatingMode()` Returns the Operating mode (AT, API or API escaped) of this XBee device.
    `int` | `getReceiveTimeout()` Returns this XBee device configured timeout for receiving packets in synchronous operations.
    `boolean` | `isOpen()` Returns whether the connection interface associated to this device is already open.
    `boolean` | `isRemote()` Always returns `false`, since this is always a local device.
    `void` | `open()` Opens the connection interface associated with this XBee device.
    `XBeeMessage` | `readData()` Reads new data received by this XBee device during the configured received timeout.
    `XBeeMessage` | `readData(int timeout)` Reads new data received by this XBee device during the provided timeout.
    `XBeeMessage` | `readDataFrom(RemoteXBeeDevice remoteXBeeDevice)` Reads new data received from the given remote XBee device during the configured received timeout.
    `XBeeMessage` | `readDataFrom(RemoteXBeeDevice remoteXBeeDevice, int timeout)` Reads new data received from the given remote XBee device during the provided timeout.
    `void` | `removeDataListener(IDataReceiveListener listener)` Removes the provided listener from the list of data listeners.
    `void` | `removeIOSampleListener(IIOSampleReceiveListener listener)` Removes the provided listener from the list of IO samples listeners.
    `void` | `removeModemStatusListener(IModemStatusReceiveListener listener)` Removes the provided listener from the list of Modem Status listeners.
    `void` | `removePacketListener(IPacketReceiveListener listener)` Removes the provided listener from the list of packets listeners.
    `void` | `reset()` Performs a software reset on this XBee device and blocks until the process is completed.
    `void` | `sendBroadcastData(byte[] data)` Sends the provided data to all the XBee nodes of the network (broadcast).
    `void` | `sendData(RemoteXBeeDevice xbeeDevice, byte[] data)` Sends the provided data to the given XBee device choosing the optimal send method depending on the protocol of the local XBee device.
    `void` | `sendDataAsync(RemoteXBeeDevice xbeeDevice, byte[] data)` Sends the provided data to the provided XBee device asynchronously.
    `XBeePacket` | `sendPacket(XBeePacket packet)` Sends the given XBee packet synchronously and blocks until the response is received or the configured receive timeout expires.
    `void` | `sendPacket(XBeePacket packet, IPacketReceiveListener packetReceiveListener)` Sends the given XBee packet and registers the given packet listener (if not `null`) to be notified when the answers is received.
    `void` | `sendPacketAsync(XBeePacket packet)` Sends the given XBee packet asynchronously.
    `void` | `setReceiveTimeout(int receiveTimeout)` Configures this XBee device timeout in milliseconds for receiving packets in synchronous operations.
    `String` | `toString()`

    - ### Methods inherited from class com.digi.xbee.api.AbstractXBeeDevice

      `applyChanges, enableApplyConfigurationChanges, executeParameter, get16BitAddress, get64BitAddress, getADCValue, getConnectionInterface, getDestinationAddress, getDIOChangeDetection, getDIOValue, getFirmwareVersion, getHardwareVersion, getIOConfiguration, getIOSamplingRate, getNodeID, getPANID, getParameter, getPowerLevel, getPWMDutyCycle, getXBeeProtocol, isApplyConfigurationChangesEnabled, readDeviceInfo, readIOSample, setDestinationAddress, setDIOChangeDetection, setDIOValue, setIOConfiguration, setIOSamplingRate, setNodeID, setPANID, setParameter, setPowerLevel, setPWMDutyCycle, updateDeviceDataFrom, writeChanges`

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### XBeeDevice

          public XBeeDevice(IConnectionInterface connectionInterface)

      Class constructor. Instantiates a new `XBeeDevice` object with the given connection interface.
      Parameters:
        `connectionInterface` - The connection interface with the physical XBee device.
      Throws:
        `NullPointerException` - if `connectionInterface == null`.
      See Also:
        `XBeeDevice(String, int)`, `XBeeDevice(String, SerialPortParameters)`, `XBeeDevice(String, int, int, int, int, int)`, `IConnectionInterface`

    - #### XBeeDevice

          public XBeeDevice(String port,
                    int baudRate)

      Class constructor. Instantiates a new `XBeeDevice` object physically connected to the given port name and configured at the provided baud rate.
      Parameters:
        `port` - Serial port name where XBee device is attached to.
        `baudRate` - Serial port baud rate to communicate with the device. Other connection parameters will be set as default (8 data bits, 1 stop bit, no parity, no flow control).
      Throws:
        `IllegalArgumentException` - if `baudRate < 0`.
        `NullPointerException` - if `port == null`.
      See Also:
        `XBeeDevice(IConnectionInterface)`, `XBeeDevice(String, SerialPortParameters)`, `XBeeDevice(String, int, int, int, int, int)`

    - #### XBeeDevice

          public XBeeDevice(String port,
                    int baudRate,
                    int dataBits,
                    int stopBits,
                    int parity,
                    int flowControl)

      Class constructor. Instantiates a new `XBeeDevice` object physically connected to the given port name and configured to communicate with the provided serial settings.
      Parameters:
        `port` - Serial port name where XBee device is attached to.
        `baudRate` - Serial port baud rate to communicate with the device.
        `dataBits` - Serial port data bits.
        `stopBits` - Serial port data bits.
        `parity` - Serial port data bits.
        `flowControl` - Serial port data bits.
      Throws:
        `IllegalArgumentException` - if `baudRate < 0` or if `dataBits < 0` or if `stopBits < 0` or if `parity < 0` or if `flowControl < 0`.
        `NullPointerException` - if `port == null`.
      See Also:
        `XBeeDevice(IConnectionInterface)`, `XBeeDevice(String, int)`, `XBeeDevice(String, SerialPortParameters)`

    - #### XBeeDevice

          public XBeeDevice(String port,
                    SerialPortParameters serialPortParameters)

      Class constructor. Instantiates a new `XBeeDevice` object physically connected to the given port name and configured to communicate with the provided serial settings.
      Parameters:
        `port` - Serial port name where XBee device is attached to.
        `serialPortParameters` - Object containing the serial port parameters.
      Throws:
        `NullPointerException` - if `port == null` or if `serialPortParameters == null`.
      See Also:
        `XBeeDevice(IConnectionInterface)`, `XBeeDevice(String, int)`, `XBeeDevice(String, int, int, int, int, int)`, `SerialPortParameters`

  - ### Method Detail

    - #### addDataListener

          public void addDataListener(IDataReceiveListener listener)

      Description copied from class: `AbstractXBeeDevice`
      Adds the provided listener to the list of listeners to be notified when new data is received.

      If the listener has been already included this method does nothing.

      Parameters:
        `listener` - Listener to be notified when new data is received.
      See Also:
        `AbstractXBeeDevice.removeDataListener(IDataReceiveListener)`, `IDataReceiveListener`

    - #### addIOSampleListener

          public void addIOSampleListener(IIOSampleReceiveListener listener)

      Description copied from class: `AbstractXBeeDevice`
      Adds the provided listener to the list of listeners to be notified when new IO samples are received.

      If the listener has been already included this method does nothing.

      Parameters:
        `listener` - Listener to be notified when new IO samples are received.
      See Also:
        `AbstractXBeeDevice.removeIOSampleListener(IIOSampleReceiveListener)`, `IIOSampleReceiveListener`

    - #### addModemStatusListener

          public void addModemStatusListener(IModemStatusReceiveListener listener)

      Description copied from class: `AbstractXBeeDevice`
      Adds the provided listener to the list of listeners to be notified when new Modem Status events are received.

      If the listener has been already included this method does nothing.

      Parameters:
        `listener` - Listener to be notified when new Modem Status events are received.
      See Also:
        `AbstractXBeeDevice.removeModemStatusListener(IModemStatusReceiveListener)`, `IModemStatusReceiveListener`

    - #### addPacketListener

          public void addPacketListener(IPacketReceiveListener listener)

      Description copied from class: `AbstractXBeeDevice`
      Adds the provided listener to the list of listeners to be notified when new packets are received.

      If the listener has been already included, this method does nothing.

      Parameters:
        `listener` - Listener to be notified when new packets are received.
      See Also:
        `AbstractXBeeDevice.removePacketListener(IPacketReceiveListener)`, `IPacketReceiveListener`

    - #### close

          public void close()

      Closes the connection interface associated with this XBee device.
      See Also:
        `isOpen()`, `open()`

    - #### getNetwork

          public XBeeNetwork getNetwork()

      Returns the network associated with this XBee device.
      Returns:
        The XBee network of the device.
      Throws:
        `InterfaceNotOpenException` - if this device connection is not open.
      See Also:
        `XBeeNetwork`

    - #### getOperatingMode

          public OperatingMode getOperatingMode()

      Returns the Operating mode (AT, API or API escaped) of this XBee device.
      Returns:
        The operating mode of this XBee device.
      See Also:
        `OperatingMode`

    - #### getReceiveTimeout

          public int getReceiveTimeout()

      Returns this XBee device configured timeout for receiving packets in synchronous operations.
      Returns:
        The current receive timeout in milliseconds.
      See Also:
        `setReceiveTimeout(int)`

    - #### isOpen

          public boolean isOpen()

      Returns whether the connection interface associated to this device is already open.
      Returns:
        `true` if the interface is open, `false` otherwise.
      See Also:
        `close()`, `open()`

    - #### isRemote

          public boolean isRemote()

      Always returns `false`, since this is always a local device.
      Specified by:
        `isRemote` in class `AbstractXBeeDevice`
      Returns:
        `false` since it is a local device.

    - #### open

          public void open()
                    throws XBeeException

      Opens the connection interface associated with this XBee device.

      When opening the device an information reading process is automatically performed. This includes:

      - 64-bit address.
      - Node Identifier.
      - Hardware version.
      - Firmware version.
      - XBee device protocol.
      - 16-bit address (not for DigiMesh modules).
      Throws:
        `InterfaceAlreadyOpenException` - if this device connection is already open.
        `XBeeException` - if there is any problem opening this device connection.
      See Also:
        `close()`, `isOpen()`

    - #### readData

          public XBeeMessage readData()

      Reads new data received by this XBee device during the configured received timeout.

      This method blocks until new data is received or the configured receive timeout expires.

      The received timeout is configured using the `setReceiveTimeout` method and can be consulted with `getReceiveTimeout` method.

      For non-blocking operations, register a `IDataReceiveListener` using the method `addDataListener(IDataReceiveListener)`.

      Returns:
        An `XBeeMessage` object containing the data and the source address of the remote node that sent the data. `null` if this did not receive new data during the configured receive timeout.
      Throws:
        `InterfaceNotOpenException` - if this device connection is not open.
      See Also:
        `readData(int)`, `getReceiveTimeout()`, `setReceiveTimeout(int)`, `readDataFrom(RemoteXBeeDevice)`, `readDataFrom(RemoteXBeeDevice, int)`, `XBeeMessage`

    - #### readData

          public XBeeMessage readData(int timeout)

      Reads new data received by this XBee device during the provided timeout.

      This method blocks until new data is received or the provided timeout expires.

      For non-blocking operations, register a `IDataReceiveListener` using the method `addDataListener(IDataReceiveListener)`.

      Parameters:
        `timeout` - The time to wait for new data in milliseconds.
      Returns:
        An `XBeeMessage` object containing the data and the source address of the remote node that sent the data. `null` if this device did not receive new data during `timeout` milliseconds.
      Throws:
        `IllegalArgumentException` - if `timeout < 0`.
        `InterfaceNotOpenException` - if this device connection is not open.
      See Also:
        `readData()`, `readDataFrom(RemoteXBeeDevice)`, `readDataFrom(RemoteXBeeDevice, int)`, `XBeeMessage`

    - #### readDataFrom

          public XBeeMessage readDataFrom(RemoteXBeeDevice remoteXBeeDevice)

      Reads new data received from the given remote XBee device during the configured received timeout.

      This method blocks until new data from the provided remote XBee device is received or the configured receive timeout expires.

      The received timeout is configured using the `setReceiveTimeout` method and can be consulted with `getReceiveTimeout` method.

      For non-blocking operations, register a `IDataReceiveListener` using the method `addDataListener(IDataReceiveListener)`.

      Parameters:
        `remoteXBeeDevice` - The remote device to read data from.
      Returns:
        An `XBeeMessage` object containing the data and the source address of the remote node that sent the data. `null` if this device did not receive new data from the provided remote XBee device during the configured receive timeout.
      Throws:
        `InterfaceNotOpenException` - if this device connection is not open.
        `NullPointerException` - if `remoteXBeeDevice == null`.
      See Also:
        `readDataFrom(RemoteXBeeDevice, int)`, `getReceiveTimeout()`, `setReceiveTimeout(int)`, `readData()`, `readData(int)`, `RemoteXBeeDevice`, `XBeeMessage`

    - #### readDataFrom

          public XBeeMessage readDataFrom(RemoteXBeeDevice remoteXBeeDevice,
                                 int timeout)

      Reads new data received from the given remote XBee device during the provided timeout.

      This method blocks until new data from the provided remote XBee device is received or the given timeout expires.

      For non-blocking operations, register a `IDataReceiveListener` using the method `addDataListener(IDataReceiveListener)`.

      Parameters:
        `remoteXBeeDevice` - The remote device to read data from.
        `timeout` - The time to wait for new data in milliseconds.
      Returns:
        An `XBeeMessage` object containing the data and the source address of the remote node that sent the data. `null` if this device did not receive new data from the provided remote XBee device during `timeout` milliseconds.
      Throws:
        `IllegalArgumentException` - if `timeout < 0`.
        `InterfaceNotOpenException` - if this device connection is not open.
        `NullPointerException` - if `remoteXBeeDevice == null`.
      See Also:
        `readDataFrom(RemoteXBeeDevice)`, `getReceiveTimeout()`, `setReceiveTimeout(int)`, `readData()`, `readData(int)`, `RemoteXBeeDevice`, `XBeeMessage`

    - #### removeDataListener

          public void removeDataListener(IDataReceiveListener listener)

      Description copied from class: `AbstractXBeeDevice`
      Removes the provided listener from the list of data listeners.

      If the listener was not in the list this method does nothing.

      Parameters:
        `listener` - Listener to be removed from the list of listeners.
      See Also:
        `AbstractXBeeDevice.addDataListener(IDataReceiveListener)`, `IDataReceiveListener`

    - #### removeIOSampleListener

          public void removeIOSampleListener(IIOSampleReceiveListener listener)

      Description copied from class: `AbstractXBeeDevice`
      Removes the provided listener from the list of IO samples listeners.

      If the listener was not in the list this method does nothing.

      Parameters:
        `listener` - Listener to be removed from the list of listeners.
      See Also:
        `AbstractXBeeDevice.addIOSampleListener(IIOSampleReceiveListener)`, `IIOSampleReceiveListener`

    - #### removeModemStatusListener

          public void removeModemStatusListener(IModemStatusReceiveListener listener)

      Description copied from class: `AbstractXBeeDevice`
      Removes the provided listener from the list of Modem Status listeners.

      If the listener was not in the list this method does nothing.

      Parameters:
        `listener` - Listener to be removed from the list of listeners.
      See Also:
        `AbstractXBeeDevice.addModemStatusListener(IModemStatusReceiveListener)`, `IModemStatusReceiveListener`

    - #### removePacketListener

          public void removePacketListener(IPacketReceiveListener listener)

      Description copied from class: `AbstractXBeeDevice`
      Removes the provided listener from the list of packets listeners.

      If the listener was not in the list this method does nothing.

      Parameters:
        `listener` - Listener to be removed from the list of listeners.
      See Also:
        `AbstractXBeeDevice.addPacketListener(IPacketReceiveListener)`, `IPacketReceiveListener`

    - #### reset

          public void reset()
                     throws TimeoutException,
                            XBeeException

      Description copied from class: `AbstractXBeeDevice`
      Performs a software reset on this XBee device and blocks until the process is completed.
      Specified by:
        `reset` in class `AbstractXBeeDevice`
      Throws:
        `TimeoutException` - if the configured time expires while waiting for the command reply.
        `XBeeException` - if there is any other XBee related exception.

    - #### sendBroadcastData

          public void sendBroadcastData(byte[] data)
                                 throws TimeoutException,
                                        XBeeException

      Sends the provided data to all the XBee nodes of the network (broadcast).

      This method blocks till a success or error transmit status arrives or the configured receive timeout expires.

      The received timeout is configured using the `setReceiveTimeout` method and can be consulted with `getReceiveTimeout` method.

      Parameters:
        `data` - Byte array containing the data to be sent.
      Throws:
        `InterfaceNotOpenException` - if this device connection is not open.
        `NullPointerException` - if `data == null`.
        `TimeoutException` - if there is a timeout sending the data.
        `XBeeException` - if there is any other XBee related exception.
      See Also:
        `getReceiveTimeout()`, `setReceiveTimeout(int)`

    - #### sendData

          public void sendData(RemoteXBeeDevice xbeeDevice,
                      byte[] data)
                        throws TimeoutException,
                               XBeeException

      Sends the provided data to the given XBee device choosing the optimal send method depending on the protocol of the local XBee device.

      This method blocks till a success or error response arrives or the configured receive timeout expires.

      The received timeout is configured using the `setReceiveTimeout` method and can be consulted with `getReceiveTimeout` method.

      For non-blocking operations use the method `sendDataAsync(RemoteXBeeDevice, byte[])`.

      Parameters:
        `xbeeDevice` - The XBee device of the network that will receive the data.
        `data` - Byte array containing the data to be sent.
      Throws:
        `InterfaceNotOpenException` - if this device connection is not open.
        `NullPointerException` - if `xbeeDevice == null` or if `data == null`.
        `TimeoutException` - if there is a timeout sending the data.
        `XBeeException` - if there is any other XBee related exception.
      See Also:
        `getReceiveTimeout()`, `setReceiveTimeout(int)`, `sendDataAsync(RemoteXBeeDevice, byte[])`

    - #### sendDataAsync

          public void sendDataAsync(RemoteXBeeDevice xbeeDevice,
                           byte[] data)
                             throws XBeeException

      Sends the provided data to the provided XBee device asynchronously.

      Asynchronous transmissions do not wait for answer from the remote device or for transmit status packet.

      Parameters:
        `xbeeDevice` - The XBee device of the network that will receive the data.
        `data` - Byte array containing the data to be sent.
      Throws:
        `InterfaceNotOpenException` - if this device connection is not open.
        `NullPointerException` - if `xbeeDevice == null` or if `data == null`.
        `XBeeException` - if there is any XBee related exception.
      See Also:
        `sendData(RemoteXBeeDevice, byte[])`, `RemoteXBeeDevice`

    - #### sendPacket

          public XBeePacket sendPacket(XBeePacket packet)
                                throws TimeoutException,
                                       XBeeException

      Sends the given XBee packet synchronously and blocks until the response is received or the configured receive timeout expires.

      The received timeout is configured using the `setReceiveTimeout` method and can be consulted with `getReceiveTimeout` method.

      Use `sendXBeePacketAsync(XBeePacket)` or `#sendXBeePacket(XBeePacket, IPacketReceiveListener)` for non-blocking operations.

      Parameters:
        `packet` - XBee packet to be sent.
      Returns:
        An `XBeePacket` object containing the response of the sent packet or `null` if there is no response.
      Throws:
        `InterfaceNotOpenException` - if this device connection is not open.
        `NullPointerException` - if `packet == null`.
        `TimeoutException` - if there is a timeout sending the XBee packet.
        `XBeeException` - if there is any other XBee related exception.
      See Also:
        `getReceiveTimeout()`, `AbstractXBeeDevice.sendXBeePacket(XBeePacket, IPacketReceiveListener)`, `AbstractXBeeDevice.sendXBeePacketAsync(XBeePacket)`, `setReceiveTimeout(int)`, `XBeePacket`

    - #### sendPacket

          public void sendPacket(XBeePacket packet,
                        IPacketReceiveListener packetReceiveListener)
                          throws XBeeException

      Sends the given XBee packet and registers the given packet listener (if not `null`) to be notified when the answers is received.

      This is a non-blocking operation. To wait for the answer use `sendPacket(XBeePacket)`.

      Parameters:
        `packet` - XBee packet to be sent.
        `packetReceiveListener` - Listener for the operation, `null` not to be notified when the answer arrives.
      Throws:
        `InterfaceNotOpenException` - if this device connection is not open.
        `NullPointerException` - if `packet == null`.
        `XBeeException` - if there is any other XBee related exception.
      See Also:
        `sendPacket(XBeePacket)`, `sendPacketAsync(XBeePacket)`, `IPacketReceiveListener`, `XBeePacket`

    - #### sendPacketAsync

          public void sendPacketAsync(XBeePacket packet)
                               throws XBeeException

      Sends the given XBee packet asynchronously.

      This is a non-blocking operation that do not wait for the answer and is never notified when it arrives.

      To be notified when the answer is received, use `AbstractXBeeDevice.sendXBeePacket(XBeePacket, IPacketReceiveListener)`.

      Parameters:
        `packet` - XBee packet to be sent asynchronously.
      Throws:
        `InterfaceNotOpenException` - if this device connection is not open.
        `NullPointerException` - if `packet == null`.
        `XBeeException` - if there is any other XBee related exception.
      See Also:
        `AbstractXBeeDevice.sendXBeePacket(XBeePacket)`, `AbstractXBeeDevice.sendXBeePacket(XBeePacket, IPacketReceiveListener)`, `XBeePacket`

    - #### setReceiveTimeout

          public void setReceiveTimeout(int receiveTimeout)

      Configures this XBee device timeout in milliseconds for receiving packets in synchronous operations.
      Parameters:
        `receiveTimeout` - The new receive timeout in milliseconds.
      Throws:
        `IllegalArgumentException` - if `receiveTimeout < 0`.
      See Also:
        `getReceiveTimeout()`

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `AbstractXBeeDevice`

© Copyright 2014–2014 Digi International Inc. All rights reserved.