View source for Modems/xbee

Paparazzi supports the following modem protocols:
* Standard transparent serial (pprz protocol, AT mode) - compatible with all modems and can be used to connect the autopilot directly to a PC for testing without a modem.
* Digi (formerly Maxstream) API protocol (xbee) - compatible with all Digi modems including the 9XTend and Zigbee. This protocol enables hardware addressing through API mode, allowing multiple aircraft to be managed from a single ground modem.
<br/>

== Introduction ==

=== Installation of X-CTU ===
The simplest way to configure the XBee modems is to use the [http://www.digi.com/support/productdetail?pid=3352 X-CTU] software from Digi. It runs natively under MacOS X, Windows and Linux.
To use versions before X-CTU 6 under Linux, use Wine.

==== Installation using Wine ====
'''X-CTU versions 6 and up are available natively for Linux''', so using Wine is only needed for older versions.

Under Wine make sure you have the USB serial link connecting to XBee mapped to a com port (please consult [[Installation/Linux/udev | paparazzi linux device naming]]):

* First of all you should install wine.
* Then install winetricks (X-CTU requires MS Visual C++ Redistributable package so winetricks will make things much easier to get installed).
* Then ('''!important''') run wine configuration before doing something else, so wine can create ~/.wine
* Make symlink to your modem device.

 $ sudo ln -s /dev/paparazzi/xbee ~/.wine/dosdevices/com4

* Set permissions for COM port (if you are not root):
 
 $ sudo ls -l /dev/paparazzi/xbee
 lrwxrwxrwx 1 root root 10 june 14 19:00 /dev/paparazzi/xbee -> /dev/ttyUSB0
 $ sudo chown <your_user_name_here> /dev/ttyUSB0

* Run X-CTU setup and install it.
* Then run installed application. When window opens switch to "User Com Ports" tab and add com port "COM4. Note: This procedure have to be made every time you start X-CTU on Linux.
* Click "Test/Query" button. If you get some modem information (like serial, etc.) after a little time, then you have modem link established.

If X-CTU complains on com port connectivity, try adding theese strings to ~/.wine/system.reg
 [hardware\\DEVICEMAP\\SERIALCOMM]
 "COM1"="COM1"

If your X-CTU does not update its firmware correctely from the web, follow the steps described in the chapter "Manually Update the X-CTU firmware files" of [http://wiki.openpilot.org/display/Doc/Configure+Xbee+via+Linux this page].

=== Configuring XBee AT mode using X-CTU ===
This is the recommended way to start. With this firmware the modems basically act as a serial link replacement and don't do any mesh networking. The pprz protocol is based on this mode.
<br/>
Basic approach:
# Connect your XBee to your PC. There are several vendors of [[Modems#GCS_Adaptation|USB boards]].
# Start the X-CTU programm and go to the modem configuration.
# Click on READ
# Select the appropriate function set with AT command set.
# set PAN ID, etc... depending on which XBee you use
# Set the baudrate you want to use. 57600 is the maximum baudrate setting for bidirectional transfers to work correctly. At a higher baudrate setting, transmission can only be done in one direction.
# Then write the firmware to the module.
If X-CTU asks you to reset the XBee, you have to connect the RST pin (5) to the GND pin (10) of the XBee. You can do this manually using tweezers or a short wire.

=== Configuring XBee using a terminal emulator ===

Alternatively you can configure your XBee using a text-based modem control and terminal emulation program, such as [http://en.wikipedia.org/wiki/Minicom Minicom] for Linux or [http://freeware.the-meiers.org CoolTerm] for Linux, Mac OSX, or Windows.

The xBee modules can be set to the following baud rates:

{|border="1"  cellspacing="0" style="text-align:center" cellpadding="6"
!''Baud Code''!!''Baud Rate''!!''Notes''
|-
|0||1200||
|-
|1||2400||
|-
|2||4800||
|-
|3||9600||
|-
|4||19200|| Use with fixedwing aircraft and their GCSs
|-
|5||38400||
|-
|6||57600|| Use with rotorcraft or transitioning aircraft and their GCSs
|-
|7||115200||
|}

'''Quick, I'm in a rush''':
 $ sudo screen /dev/ttyUSB0 9600
 +++
 ATBD6<enter>
 ATAP1<enter>
 ATWR<enter>


'''Minicom Instructions''':
* Connect XBee to your computer
* Setup minicom (by default XBee modems come set up for 9600 baud) 8-N-1 
* Type Ctrl-A A in minicom this will set it up to add linefeeds to the stream
* Type three '+' in quick succession resulting in "+++" string (you have 10s to type your next command otherwise the modem will revert back to transparent mode). Do NOT press enter.
** you get a confirmation: 'OK'
* Type "AT<enter>"
** you get a confirmation: 'OK'
* Type "ATBD<enter>"
** you get the current baudrate code: '3'
* To set another baudrate select one from the above table and type "ATBD <baud code><enter>":
* Type "ATAP 0 or 1 for API mode or not<enter>"
* To store the new baudrate in the rom type "ATWR<enter>"
* Now you can close minicom
* Reconnect modem
* Restart minicom with the new baudrate
* Test that the modem is setup correctly by typing "+++" and getting "OK" confirmation

'''CoolTerm Instructions''':
* Connect xBee to your computer
* Open CoolTerm and click 'Options.' From the 'Serial Port' tab select:
**Port: USB Serial (or as appropriate for your xBee carrier board)
**Baudrate: 9600
**Data Bits: 8
**Parity: None
**Stop Bits 1
*From the 'Terminal' tab enable Local Echo
*Click OK
*Click Connect
* Type three '+' in quick succession resulting in "+++" string (you have 10s to type your next command otherwise the modem will revert back to transparent mode). Do NOT press enter.
** you get a confirmation: 'OK'
* Type "AT<enter>"
** you get a confirmation: 'OK'
* Type "ATBD<enter>"
** you get the current baudrate code: '3'
* To set another baudrate select one from the above table and type "ATBD <baud code><enter>":
* To store the new baudrate in the rom type "ATWR<enter>"
* Now you can close CoolTerm.
* Reconnect modem
* Restart CoolTerm, change options to new baudrate, and connect
* Test that the modem is setup correctly by typing "+++" and getting "OK" confirmation

== XBee Pro ZB (AT command set) ==
This 2.4GHz modem uses ZigBee PRO Feature Set and is compatible with devices from other vendors using the ZigBee PRO Feature Set.

=== Flashing the airborne module ===
# Connect your XBee, start X-CTU, click READ
# Select the function set '''ZIGBEE END DEVICE AT''' (or ZIGBEE ROUTER AT).
# Set the PAN ID to any number, must be the same as the pan id of the coordinator (Ground Station).
# Set the Node Identifier (NI) to your aircraft name or any other appropriate name.
# Set the baudrate you want to use. 57600 is the maximum baudrate setting for bidirectional transfers to work correctly.
# Then write the firmware to the module.

=== Flashing the ground station module ===
# Connect your XBee, start X-CTU, click READ
# Select the function set '''ZIGBEE COORDINATOR AT'''.
# Set the PAN ID to any number, must be the same as the pan id of the end device (aircraft).
# Set the Node Identifier (NI) to PPRZ_GROUND or any other appropriate name.
# Set the baudrate you want to use. 57600 is the maximum baudrate setting for bidirectional transfers to work correctly.
# Then write the firmware to the module.

=== Pairing your Modems ===

For maximum performance you can pair the ground modem to the airborne modem. Set the "DH - Destination Address High" and "DL - Destination Address Low" to the unique serial number "SH - Serial Number High" and "SL - Serial Number Low" of the other modem. Do so both on the ground modem and on the airborne modem. Failing to properly pair your modems will likely result in poor throughput and data loss between your airframe and your ground control station. If this is the case you may see errors on the Paparazzi Center console like <tt>Failure("Pprz.values_of_payload, wrong argument: 00 08 ")</tt> or <tt>Failure("Pprz.values_of_payload, too many bytes in message PONG: 00 03 02 2a 00 00 00 00 00 00 00 00 00 00 00 00 ")</tt>. Pairing does help and the error messages will disappear. 

=== Reviving a non-responding Xbee Pro ===

To bring an apparently dead XBee Pro Series 2 back to life, do the following:

#Connect the USB device that holds the XBee to your laptop/desktop (without the XBee connected).
#Open X-CTU.
#In the tab used to program the device, select the proper modem (normally you would do a READ to get the values).
#Choose the option you want to program (i.e., "END DEVICE" or "COORDINATOR") as if you were programming it.
#With the XBee not in the device, click "WRITE". It will hang, timeout, and bring up a dialog box.
#Before you click OK to the dialog box, plug in the XBee module (carefully).
#Click OK to clear the message and it should start programming automatically.

=== Other tutorials ===

[http://pixhawk.ethz.ch/tutorials/how_to_configure_xbee PixHawk: HowTo configure XBee]

[http://wiki.openpilot.org/display/Doc/Configure+Xbee+via+Linux openpilot: XBee RF modems]

== XBee Pro ZNet 2.5 (AT command set) ==
These are legacy modems and not recommended/sold by Digi anymore.
It is recommended to upgrade these to XBee Pro ZB with the [ftp://ftp1.digi.com/support/images/ZNet%202.5%20to%20ZB%20Conversion%20Kit.zip ZNet 2.5 to ZB Conversion Kit] from Digi.
<br/>
If you want to use ZNet 2.5 feature set nevertheless, here is how to configure it:

=== Flashing the airborne module ===
# Connect your XBee, start X-CTU, click READ
# Select the function set '''ZNET 2.5 ROUTER/END DEVICE AT'''.
# Set the PAN ID to any number, must be the same as the pan id of the coordinator (Ground Station).
# Set the Node Identifier (NI) to your aircraft name or any other appropriate name.
# Set the baudrate you want to use. 57600 is the maximum baudrate setting for bidirectional transfers to work correctly.
# Then write the firmware to the module.

=== Flashing the ground station module ===
# Connect your XBee, start X-CTU, click READ
# Select the function set '''ZNET 2.5 COORDINATOR DEVICE AT'''.
# Set the Destination Address Low (DL) to FFFF.
# Set the PAN ID to any number, must be the same as the pan id of the end device (aircraft).
# Set the Node Identifier (NI) to PPRZ_GROUND or any other appropriate name.
# Set the baudrate you want to use. 57600 is the maximum baudrate setting for bidirectional transfers to work correctly.
# Then write the firmware to the module.

=== Setup ===

For the ZigBee ZNet 2.5 and ZB modules to work one of the modules has to be flashed with the coordinator firmware. All the others in the same PAN can either run as routers or end-devices.
* Flash one module (ground station) with the coordinator AT firmware
* Flash aircraft module with router or end-device AT firmware
To allow modules to join any PAN set the PAN ID to zero (default setting). Then the coordinator will generate a random PAN ID and routers and end-devices will join the first PAN they find.

If you operate in an environment with multiple zigbee PANs it is recommended to set the PAN ID explicitly:
* Set PAN ID to some unique (but same) ID on both modules
* Set a Node Identifier for each module (e.g. ground, aircraft)
<br/>

== XBee Pro DigiMesh / 802.15.4 ("Series 1") ==

=== Flashing the airborne module ===
# Connect your XBee, start X-CTU, click READ
# Leave the function set on '''XBEE PRO 802.15.4'''.
# Set the PAN ID to any number, must be the same as the pan id of the coordinator (Ground Station).
# Set the Node Identifier (NI) to your aircraft name or any other appropriate name.
# Set the baudrate you want to use. 57600 is the maximum baudrate setting for bidirectional transfers to work correctly.
# Then write the firmware to the module.

=== Flashing the ground station module ===
# Connect your XBee, start X-CTU, click READ
# Leave the function set on '''XBEE PRO 802.15.4'''.
# '''Set Coordinator Enable to "1 - COORDINATOR".'''
# Set the PAN ID to any number, must be the same as the pan id of the end device (aircraft).
# Set the Node Identifier (NI) to PPRZ_GROUND or any other appropriate name.
# Set the baudrate you want to use. 57600 is the maximum baudrate setting for bidirectional transfers to work correctly.
# Then write the firmware to the module.

(Tested on XBP24 Firmwareversion 10E6)

== XBee Pro 868 MHZ ==

=== Getting Them Working ===
Even with the xbee868.xml telemetry file, XBee868s will not last over 6 minutes. There is a special 868 build flag (in slayer1.xml), and matching option for the datalink but I could not get this to work. Eventually, I got them to work for about 20 minutes, which happily is the flight endurance of a heavily overloaded GWS Formosa.

I did this using a command window, but you could use X-CTU if you are a wuss or have Windows handy.

#Attach Xbee and start serial comm program (I use <code>screen /dev/ttyUSB0 &lt;baud rate, just a number, no angled brackets&gt;</code>, you can also use pico- or microcom)
#Type AT and enter. You should get an OK back.
#ATMT and enter. You should get a number&mdash;this represents the number of extra times each packet will be broadcast. We now need to change this to zero.
#ATMT0 and enter => OK
#ATRR and enter. This number is the number of retries that will be sent if an ACK is not received. Disabling this will also have the side effect of disabling ACKs, giving us more packets to play with.
#ATRR0 and enter => OK
#Type ATWR to store the new stuff in the firmware. You should get an OK.
#Set the datalink to transparent mode both in your airframe file and on the datalink.

You may also want to drop the power level to 1mW for testing, or it won't actually work - they are just too damn powerful to talk to each other at a range of a couple of feet. I also used 1mW for flying - never lost the link, even after a mile. Didn't get round to range testing them though. 

You probably want to do this to both XBees (at least I did). I personally had the baud rate at 57600 for legacy reasons, but it should work just as well at any other baud rate. '''Thanks to CheBuzz for this info''', and for helping me work all this out at 11pm the night before EMAV09.

== XBee 868LF ==

These relativly new modems use the whole spectrum allowed in your country to avoid Duty Cycle restrictions.

== XBee Pro XSC (900MHZ) ==

== Configuring XBee API mode (xbee protocol) ==

[[Category:Hardware]] [[Category:User_Documentation]]