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

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