com.rapplogic.xbee.api
Class XBee

java.lang.Object
  extended by 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

Constructor Summary
XBee()
           
XBee(XBeeConfiguration conf)
           
 
Method Summary
 void addPacketListener(PacketListener packetListener)
           
 void clearResponseQueue()
          Removes all packets off of the response queue
 void close()
          Shuts down RXTX and packet parser thread
 int getCurrentFrameId()
           
 int getNextFrameId()
          This is useful for obtaining a frame id when composing your XBeeRequest.
 XBeeResponse getResponse()
          Same as getResponse(int) but does not timeout.
 XBeeResponse getResponse(int timeout)
          This method returns an XBeeResponse from the queue, if available, or waits up to "timeout" milliseconds for a response.
 void initProviderConnection(XBeeConnection connection)
          Allows a protocol specific implementation of XBeeConnection to be used instead of the default RXTX connection.
 boolean isConnected()
          Indicates if serial port connection has been established.
 void open(java.lang.String port, int baudRate)
          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.
 void removePacketListener(PacketListener packetListener)
           
 void sendAsynchronous(XBeeRequest request)
          Sends an XBeeRequest though the XBee interface in an asynchronous manner, such that it will return immediately, without waiting for a response.
 AtCommandResponse sendAtCommand(AtCommand command)
          Deprecated. Use this.sendSynchronous(command, timeout);
 void sendPacket(int[] packet)
          This exists solely for the XMPP project.
 void sendPacket(XBeePacket packet)
          It's possible for packets to get interspersed if multiple threads send simultaneously.
 void sendRequest(XBeeRequest request)
           
 XBeeResponse sendSynchronous(XBeeRequest request)
          Uses sendSynchronous timeout defined in XBeeConfiguration (default is 5000ms)
 XBeeResponse sendSynchronous(XBeeRequest xbeeRequest, int timeout)
          Synchronous method for sending an XBeeRequest and obtaining the corresponding response (response that has same frame id).
 void updateFrameId(int val)
          Updates the frame id.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

XBee

public XBee()

XBee

public XBee(XBeeConfiguration conf)
Method Detail

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