The XBee is Digi's IEEE 802.15.4 product, some of which are ZigBee compatible.

XBeePro

XBee Pro 60mW PCB Antenna - Series 1 (802.15.4) WRL-11216 37.95 ea. (SparkFun) This is what I have
ds_xbeemultipointmodules.pdf XBee Pro Spec sheet from November, 2015

The XBee Pro S1 is not ZigBee, though the XBee ZigBee modules are ZigBee compatible.

USB

The two XBee Pros that I have are plugged in to USB boards. Either one seems to work.

SparkFun XBee Explorer Dongle WRL-11697 $24.95 ea. (SparkFun) Plugs in to a Mac just fine.
- Uses the "FT231X USB-to-Serial converter"
  - There are two types of drivers: "Virtual COM Port (VCP) drivers and direct (D2XX) drivers. The VCP driver emulates a standard PC serial port such that the USB device may be communicated with as a standard RS232 device The D2XX driver allows direct access to a USB device via a DLL interface." Since we are using RxTx to communicate with a serial port, we would want the VCP driver.
UARTSBee $19.95 ea. (Seeedstudio.com) Has a compact USB connector, so it requires a cable.

Raw Serial Port Access

The Ptolemy II tree includes an implementation of RXTX (at least for MacOS) and a SerialPort actor that provides low-level access to serial port devices, including the XBee devices. If you plug in the XBee device into your USB port, two new serial devices will be discovered by the SerialPort actor. On my machine, they are called "/dev/tty.usbserial-DA01LK3S" and "/dev/cu.usbserial-DA01LK3S". I don't know what the difference is, but either worked for me.

The SerialPort actor accepts as input a unsigned byte array and produces as output an unsigned byte array. If you send to its input port a sequence of two strings (convert to unsigned byte array using StringToUnsignedByteArray) "+++" followed by "ATSH\r" within 3 seconds, then you will be returned the upper half of the address of your XBee device, per the AT command instructions (Note that these instructions are self contradictory... the second mention of the three second wait is incorrect. The first one is correct). Note that "\r" is a Windows-style return character. Using "\n" does not work. On my device, this returns "13A200" (a hex number representing the upper half of the address of the device). Adding "ATSL\r" to the commands returns "40D5FF39", the lower half of the address. So the address appears to be a 56 bit address.

Note that the SerialPort actor may produce the output in multiple firings. I.e., it may produce "40" followed by "D5FF39" or "40D" followed by "5FF39" (or any other partitioning).

X-CTU Software

The X-CTU Software runs on the Mac or other host. The software is used to configure the XBee and has a simple console application.

XBeeProfile10ee.xml The profile that was saved from X-CTU.

Oddly, I could not get X-CTU 6.3.0 Build IS 20141110-08 to work with Mac OS X 10.7.5. The problem was that clicking on Discover Devices did not find my port. The same two XBees are discovered just fine under 10.11.1.

XBCTU Under Ubuntu Studio

Connect to the SwarmBox using ssh -X -l sbuser swarmnuc001.eecs.berkeley.edu
See HOW-TO-Install-XCTU-in-Linux and download XCTU for x64 and install
sudo usermod -a -G dialout sbuser
Invoke /opt/Digi/XCTU-NG/app

XCTU: Ubuntu: Permission denied:

com.digi.xbee.exceptions.XBeeException: Error initializing XBee device parameters /dev/ttyS0: SerOpenPort failed: Permission denied

[$[Get Code]]

Solution:

  sudo usermod -a -G dialout sbuser

Then, as sbuser, log out and log back in again. As sbuser, you should see:

buser@swarmnuc001:~$ groups
admin dialout
sbuser@swarmnuc001:~$ ls -l /dev/ttyUSB1
crw-rw---- 1 root dialout 188, 1 Dec 9 15:16 /dev/ttyUSB1
sbuser@swarmnuc001:~$

[$[Get Code]]

XCTU Won't Start under Ubuntu

Under Ubuntu 14.04.3 LTS, XCTU failed to start because I accidentally downloaded the x86 version instead of the x64 version, below is the error message

sbuser@swarmnuc001:~$ /opt/Digi/XCTU-NG/app
App:
An error has occurred. See the log file
/home/sbuser/.eclipse/13786435/configuration/1449687334319.log.
sbuser@swarmnuc001:~$

[$[Get Code]]

The error message is:

java.lang.UnsatisfiedLinkError: Could not load SWT library. Reasons:
/opt/Digi/XCTU-NG/configuration/org.eclipse.osgi/bundles/146/1/.cp/libswt-pi-gtk-4236.so: libgtk-x11-2.0.so.0: cannot open shared object file: No such file or directory
no swt-pi-gtk in java.library.path
/home/sbuser/.swt/lib/linux/x86/libswt-pi-gtk-4236.so: libgtk-x11-2.0.so.0: cannot open shared object file: No such file or directory
Can't load library: /home/sbuser/.swt/lib/linux/x86/libswt-pi-gtk.so

[$[Get Code]]

Java Interfaces to XBee

As far as a Java Interface to the XBee, I see two approaches:

Use the XBeeJavaLibrary
Use our own raw serial interface

XBeeJavaLibrary

https://github.com/digidotcom/XBeeJavaLibrary - Mozilla, LGPL and MIT Licenses
- http://www.digi.com/blog/community/official-xbee-java-library/ - Announcement
- https://docs.digi.com/display/XBJLIB/XBee+Java+Library - docs
- https://github.com/digidotcom/XBeeJavaLibrary/releases - Where the Zip file is located

The docs describe how to create an Eclipse project that uses

"rxtx-2.2.jar: The RXTX library that provides serial communication in Java."
"slf4j-api-1.7.12.jar: The Simple Logging Facade for Java (SLF4J) for logging."
"slf4j-nop-1.7.12.jar: SLF4J binding for NOP, silently discarding all logging."
"RXTX native library that depends on your PC operating system and the installed Java Virtual Machine"

XBee Java Example

The Building your first XBee Java application example worked for me under Mac OS X 10.11.1.

The source code for MainApp.java is below:

package com.digi.xbee.example;

import com.digi.xbee.api.XBeeDevice;
import com.digi.xbee.api.exceptions.XBeeException;

public class MainApp {
/* Constants */
// TODO Replace with the port where your sender module is connected to.
private static final String PORT = "COM1";
// TODO Replace with the baud rate of your sender module.
private static final int BAUD_RATE = 9600;

private static final String DATA_TO_SEND = "Hello XBee World!";

public static void main(String[] args) {
XBeeDevice myDevice = new XBeeDevice(PORT, BAUD_RATE);
byte[] dataToSend = DATA_TO_SEND.getBytes();

try {
myDevice.open();

System.out.format("Sending broadcast data: '%s'", new String(dataToSend));

myDevice.sendBroadcastData(dataToSend);

System.out.println(" >> Success");

} catch (XBeeException e) {
System.out.println(" >> Error");
e.printStackTrace();
System.exit(1);
} finally {
myDevice.close();
}
}
}

[$[Get Code]]

What this does is construct an XBeeDevice, open() it and then sendBroadCastData().

The summary is that open() creates a DataReader (JavaDoc, Source) that is a Thread that reads from the serial port using IConnectionInterface (JavaDoc, Source)

XBeeDevice Javadoc, Source

See XBeeJavaAnalysis.

Using Serial Console to Communicate with an XBee

This does not totally work, but at least the XBee answers

Use XCTU to reset the XBee to the defaults.
Note the serial port that is used.
Exit XCTU so that it is not using the port
Update your Ptolemy Tree
Run $PTII/bin/vergil $PTII/ptolemy/actor/lib/io/comm/demo/SerialConsole/SerialConsole.xml
In Vergil, double click on the SerialPort actor and then select the appropriate serial port.
Run the model
Type three + signs: +++, hit Return to send the three plus signs.
The XBee should return OK. However, the ATID command does not work?

Welcome to the Ptolemy Serial Console.
>> +++
OK
>> ATID

[$[Get Code]]
See XBee AT Commands (Sparkfun) for details. Note that we have hit return to send the characters. The SerialConsole demo should probably be modified to send characters as they are typed.

XBee Java Interface and nrjavaserial

When trying to run the XBee Java example at https://docs.digi.com/display/XBJLIB/Building+your+first+XBee+Java+application with nrjavaserial, the following error appeared:

Exception in thread "main" java.lang.NoSuchMethodError:
gnu.io.CommPortIdentifier.open(Ljava/lang/String;I)Lgnu/io/CommPort;
at
com.digi.xbee.api.connection.serial.SerialPortRxTx.open(SerialPortRxTx.java:167)
at com.digi.xbee.api.XBeeDevice.open(XBeeDevice.java:195)
at ptolemy.actor.lib.jjs.modules.xbee.XBeeHello.main(XBeeHello.java:20)

[$[Get Code]]

The error message in question is:

gnu.io.CommPortIdentifier.open(Ljava/lang/String;I)Lgnu/io/CommPort;

[$[Get Code]]

http://rxtx.qbang.org/pub/rxtx/rxtx-2.1-7/src/CommPortIdentifier.java, which is similar to what is in XBeeJava has:

public synchronized CommPort open(String TheOwner, int i)

[$[Get Code]]

https://github.com/NeuronRobotics/nrjavaserial/blob/86b44454cebc7ba29c2032e904cfbe4eb098b841/src/main/java/gnu/io/CommPortIdentifier.java, which is what is in nrjavaserial has:

public RXTXPort open(String TheOwner, int i)

[$[Get Code]]

However, RXTXPort extends SerialPort which extends CommPort, so this should work (I think). For reference, Line 167 of SerialPortRxTx.java is

serialPort = (RXTXPort)portIdentifier.open(PORT_ALIAS + " " + port, receiveTimeout);

[$[Get Code]]

To recompile the XBee Java Library, I edited the pom.xml file and commented out the rxtx references and added references to nrjavaserial.

<dependencies>
<dependency>
<groupId>com.neuronrobotics</groupId>
<artifactId>nrjavaserial</artifactId>
<version>3.11.0</version>
</dependency>

[$[Get Code]]

To build:

cd ~/src/XBeeJavaLibrary/
mvn3 install
cp target/library/xbjlib-1.1.0.jar $PTII/lib/xbjlib-1.1.0.nrjavaserial.jar

[$[Get Code]]

Note that at build time for the xbjlib library, the reference to com.neuronrobotics uses an older version of nrjavaserial that does not have the Apple-specific fix needed in RxTx Hanging. However, at runtime, we use a version of nrjavaserial that has the fix.

Java Software for the XBee

https://github.com/andrewrapp/xbee-api - Old

RxTx

See RxTx for information about the RxTx Java Serial Port Interface.