com.rapplogic.xbee.api
Class XBee

java.lang.Object
  com.rapplogic.xbee.api.XBee

All Implemented Interfaces:

IXBee

public class XBee
extends java.lang.Object
implements IXBee

This is an API for communicating with Digi XBee 802.15.4 and ZigBee radios via the serial port

Author:

Andrew Rapp

XBee

public XBee()

XBee

public XBee(XBeeConfiguration conf)

open

public void open(java.lang.String port,
                 int baudRate)
          throws XBeeException

If XBeeConnection.startUpChecks is set to true (default), this method will check if the AP parameter is set correctly and attempt to update if AP=1. If AP=0 (Transparent mode), an exception will be thrown.

Specified by:

open in interface IXBee

Throws:

XBeeException

initProviderConnection

public void initProviderConnection(XBeeConnection connection)
                            throws XBeeException

Allows a protocol specific implementation of XBeeConnection to be used instead of the default RXTX connection. The connection must already be established as the interface has no means to do so.

Throws:

XBeeException

addPacketListener

public void addPacketListener(PacketListener packetListener)

Specified by:

addPacketListener in interface IXBee

removePacketListener

public void removePacketListener(PacketListener packetListener)

Specified by:

removePacketListener in interface IXBee

sendRequest

public void sendRequest(XBeeRequest request)
                 throws java.io.IOException

Throws:

java.io.IOException

sendPacket

public void sendPacket(XBeePacket packet)
                throws java.io.IOException

It's possible for packets to get interspersed if multiple threads send simultaneously. This method is not thread-safe because doing so would introduce a synchronized performance penalty for the vast majority of users that will not never need thread safety. That said, it is responsibility of the user to provide synchronization if multiple threads are sending. Not thread safe.

Specified by:

sendPacket in interface IXBee

Parameters:

packet -

Throws:

java.io.IOException

sendPacket

public void sendPacket(int[] packet)
                throws java.io.IOException

This exists solely for the XMPP project. Use sendRequest instead Not Thread Safe

Specified by:

sendPacket in interface IXBee

Parameters:

packet -

Throws:

java.lang.RuntimeException - when serial device is disconnected

java.io.IOException

sendAsynchronous

public void sendAsynchronous(XBeeRequest request)
                      throws XBeeException

Sends an XBeeRequest though the XBee interface in an asynchronous manner, such that it will return immediately, without waiting for a response. Refer to the getResponse method for obtaining a response Not thread safe

Specified by:

sendAsynchronous in interface IXBee

Parameters:

request -

Throws:

XBeeException

sendAtCommand

public AtCommandResponse sendAtCommand(AtCommand command)
                                throws XBeeException

Deprecated. Use this.sendSynchronous(command, timeout);

Uses sendSynchronous to send an AtCommand and collect the response

Timeout value is fixed at 5 seconds

Parameters:

command -

Returns:

Throws:

XBeeException

sendSynchronous

public XBeeResponse sendSynchronous(XBeeRequest xbeeRequest,
                                    int timeout)
                             throws XBeeTimeoutException,
                                    XBeeException

Synchronous method for sending an XBeeRequest and obtaining the corresponding response (response that has same frame id).

This method returns the first response object with a matching frame id, within the timeout period, so it is important to use a unique frame id (relative to previous subsequent requests).

This method must only be called with requests that receive a response of type XBeeFrameIdResponse. All other request types will timeout.

Keep in mind responses received here will also be available through the getResponse method and the packet listener. If you would prefer to not have these responses added to the response queue, you can add a ResponseQueueFilter via XBeeConfiguration to ignore packets that are sent in response to a request. Another alternative is to call clearResponseQueue prior to calling this method.

It is recommended to use a timeout of at least 5 seconds, since some responses can take a few seconds or more (e.g. if remote radio is not powered on).

This method is thread-safe

Specified by:

sendSynchronous in interface IXBee

Parameters:

xbeeRequest -

Returns:

Throws:

XBeeException

XBeeTimeoutException - thrown if no matching response is identified

sendSynchronous

public XBeeResponse sendSynchronous(XBeeRequest request)
                             throws XBeeTimeoutException,
                                    XBeeException

Uses sendSynchronous timeout defined in XBeeConfiguration (default is 5000ms)

Throws:

XBeeTimeoutException

XBeeException

getResponse

public XBeeResponse getResponse()
                         throws XBeeException

Same as getResponse(int) but does not timeout. It's highly recommend that you always use a timeout because if the serial connection dies under certain conditions, you will end up waiting forever!

Consider using the PacketListener for asynchronous (non-blocking) behavior

Specified by:

getResponse in interface IXBee

Returns:

Throws:

XBeeException

getResponse

public XBeeResponse getResponse(int timeout)
                         throws XBeeException,
                                XBeeTimeoutException

This method returns an XBeeResponse from the queue, if available, or waits up to "timeout" milliseconds for a response.

There are three possible outcomes:

1. A packet is returned within "timeout" milliseconds
2. An XBeeTimeoutException is thrown (i.e. queue was empty for duration of timeout)
3. Null is returned if timeout is 0 and queue is empty.

Specified by:

getResponse in interface IXBee

Parameters:

timeout - milliseconds to wait for a response. A value of zero disables the timeout

Returns:

Throws:

XBeeException

XBeeTimeoutException - if timeout occurs before a response is received

close

public void close()

Shuts down RXTX and packet parser thread

Specified by:

close in interface IXBee

isConnected

public boolean isConnected()

Indicates if serial port connection has been established. The open method may be called if true it returned

Specified by:

isConnected in interface IXBee

Returns:

getCurrentFrameId

public int getCurrentFrameId()

Specified by:

getCurrentFrameId in interface IXBee

getNextFrameId

public int getNextFrameId()

This is useful for obtaining a frame id when composing your XBeeRequest. It will return frame ids in a sequential manner until the maximum is reached (0xff) and it flips to 1 and starts over. Not Thread-safe

Specified by:

getNextFrameId in interface IXBee

Returns:

updateFrameId

public void updateFrameId(int val)

Updates the frame id. Any value between 1 and ff is valid

Specified by:

updateFrameId in interface IXBee

Parameters:

val - Jan 24, 2009

clearResponseQueue

public void clearResponseQueue()

Removes all packets off of the response queue

Specified by:

clearResponseQueue in interface IXBee