Get started with XBee Python library¶

This getting started template describes how to set up your environment and use the XBee Python Library to communicate with your XBee devices. It explains how to configure your modules and write your beginning XBee Python lotion .
The guide is split into 3 chief sections :

Install your software¶

The follow software components are required to write and run your first XBee Python application :

• Python 3
• PySerial 3
• SRP
• XBee Python library software
• XCTU

Python 3¶

The XBee Python library requires Python 3. If you don ’ t have Python 3, you can get it from hypertext transfer protocol : //www.python.org/getit/ .
Warning
The XBee Python library is presently only compatible with Python 3 .

PySerial 3¶

You must be able to communicate with the radio modules over a serial connection. The XBee Python library uses the PySerial module for that functionality .
This module is mechanically downloaded when you install the XBee Python library .

SRP¶

The XBee Python library uses the SRP faculty to authenticate with XBee devices over Bluetooth Low Energy .
This module is mechanically downloaded when you install the XBee Python library .

XBee Python library software¶

The best direction to install the XBee Python library is with the shoot tool ( which is what Python uses to install packages ). The pip tool comes with holocene versions of Python .
To install the library, run this command in your terminal application :

$ pip install digi-xbee

The library is automatically downloaded and installed in your Python spokesperson .

Get the source code¶

The XBee Python library is actively developed on GitHub, where the code is constantly available. You can clone the repository with :

$ git clone git@github.com:digidotcom/xbee-python.git

XCTU¶

XCTU is a free multi-platform application that enables developers to interact with Digi RF modules through a simple-to-use graphic interface. It includes new tools that make it easy to set up, configure, and screen XBee RF modules .
For instructions on download and using XCTU, go to :
hypertext transfer protocol : //www.digi.com/xctu
once you have downloaded XCTU, run the installer and follow the steps to finish the initiation summons .
After you load XCTU, a message about software updates appears. We recommend you always update XCTU to the latest available translation .

Configure your XBee modules¶

You need to configure two XBee devices. One module ( the sender ) sends “ Hello XBee World ! ” using the Python application. The other device ( the receiver ) receives the message .
To communicate, both devices must be working in the same protocol ( 802.15.4, Zigbee, DigiMesh, Point-to-Multipoint, or Wi-Fi ) and must be configured to operate in the lapp network .
note
If you are getting started with cellular, you lone need to configure one device. cellular protocol devices are connected immediately to the Internet, so there is no network of remote control devices to communicate with them. For the cellular protocol, the XBee application demonstrated in the getting started guide differs from other protocols. The cellular protocol sends and reads data from an echo server .
Use XCTU to configure the devices. Plug the devices into the XBee adapters and connect them to your computer ’ mho USB or consecutive ports .
bill
For more information about XCTU, see the XCTU User Guide. You can besides access the documentation from the Help menu of the tool .
once XCTU is running, add your devices to the tool and then select them from the Radio Modules section. When XCTU is finished reading the device parameters, complete the following steps according to your device type. Repeat these steps to configure your XBee devices using XCTU .

• 802.15.4 devices
• Zigbee devices
• DigiMesh devices
• DigiPoint devices
• cellular devices
• Wi-Fi devices

802.15.4 devices¶

1. Click Load default firmware settings in the Radio Configuration
   toolbar to load the default values for the device firmware.
2. Make sure API mode (API1 or API2) is enabled. To do so, set the AP
   parameter value to 1 (API mode without escapes) or 2 (API mode
   with escapes).
3. Configure ID (PAN ID) setting to CAFE.
4. Configure CH (Channel setting) to C.
5. Click Write radio settings in the Radio Configuration toolbar to
   apply the new values to the module.
6. Once you have configured both modules, check to make sure they can see each
   other. Click Discover radio modules in the same network, the second
   button of the device panel in the Radio Modules view. The other device
   must be listed in the Discovering remote devices dialog.

note
If the other module is not listed, reboot both devices by pressing the Reset push button of the carrier board and try adding the device again. If the number is hush evacuate, see the product manual of arms for your device .

Zigbee devices¶

1. For honest-to-god Zigbee devices ( S2 and S2B ), make sure the devices are using API firmware. The firmware appears in the Function label of the device in the Radio Modules position .
   • One of the devices must be a coordinator – Function: Zigbee Coordinator
     API
   • Digi recommends the other one is a router – Function: Zigbee Router AP.

   note
   If any of the two previous conditions is not satisfy, you must change the firmware of the device. Click the Update firmware button of the Radio Configuration toolbar .

2. Click Load default firmware settings in the Radio Configuration toolbar to load the default values for the device firmware .
3. Do the adopt :
   • If the device has the AP parameter, set it to 1 (API mode without
     escapes) or 2 (API mode with escapes).
   • If the device has the CE parameter, set it to Enabled in the
     coordinator.
4. configure ID ( PAN ID ) setting to C001BEE .
5. configure SC ( Scan Channels ) setting to FFF .
6. Click Write radio settings in the Radio Configuration toolbar to apply the newfangled values to the faculty .
7. once you have configured both modules, check to make sure they can see each other. Click Discover radio modules in the same network, the second button of the device control panel in the Radio Modules view. The other device must be listed in the Discovering remote devices dialogue .

note
If the other module is not listed, reboot both devices by pressing the Reset button of the carrier board and try adding the device again. If the list is still evacuate, go to the corresponding product manual of arms for your devices .

DigiMesh devices¶

1. Click Load default firmware settings in the Radio Configuration
   toolbar to load the default values for the device firmware.
2. Ensure the API mode (API1 or API2) is enabled. To do so, the AP
   parameter value must be 1 (API mode without escapes) or 2 (API mode
   with escapes).
3. Configure ID (PAN ID) setting to CAFE.
4. Configure CH (Operating Channel) to C.
5. Click Write radio settings in the Radio Configuration toolbar to
   apply the new values to the module.
6. Once you have configured both modules, check to make sure they can see each
   other. Click Discover radio modules in the same network, the second
   button of the device panel in the Radio Modules view. The other device
   must be listed in the Discovering remote devices dialog.

bill
If the other module is not listed, reboot both devices by pressing the Reset button of the carrier display panel and try adding the device again. If the list is calm empty, go to the match merchandise manual for your devices .

DigiPoint devices¶

1. Click Load default firmware settings in the Radio Configuration
   toolbar to load the default values for the device firmware.
2. Ensure the API mode (API1 or API2) is enabled. To do so, the AP
   parameter value must be 1 (API mode without escapes) or 2 (API mode
   with escapes).
3. Configure ID (PAN ID) setting to CAFE.
4. Configure HP (Hopping Channel) to 5.
5. Click Write radio settings in the Radio Configuration toolbar to
   apply the new values to the module.
6. Once you have configured both modules, check to make sure they can see each
   other. Click Discover radio modules in the same network, the second
   button of the device panel in the Radio Modules view. The other device
   must be listed in the Discovering remote devices dialog.

notice
If the other module is not listed, reboot both devices by pressing the Reset button of the carrier board and try adding the device again. If the tilt is still vacate, go to the corresponding product manual for your devices .

Cellular devices¶

1. Click Load default firmware settings in the Radio Configuration toolbar
   to load the default values for the device firmware.
2. Ensure the API mode (API1 or API2) is enabled. To do so, the AP
   parameter value must be 1 (API mode without escapes) or 2 (API mode
   with escapes).
3. Click Write radio settings in the Radio Configuration toolbar to apply
   the new values to the module.
4. Verify the module is correctly registered and connected to the Internet.
   To do so check that the LED on the development board blinks. If it is solid
   or has a double-blink, registration has not occurred properly. Registration
   can take several minutes.

note
In summation to the LED confirmation, you can check the IP address assigned to the module by reading the MY parameter and verifying it has a value different than 0.0.0.0 .

Wi-Fi devices¶

1. Click Load default firmware settings in the Radio Configuration toolbar
   to load the default values for the device firmware.
2. Ensure the API mode (API1 or API2) is enabled. To do so, the AP
   parameter value must be 1 (API mode without escapes) or 2 (API mode
   with escapes).
3. Connect to an access point:
   1. Click the Active Scan button.
   2. Select the desired access point from the list of the Active Scan
      result dialog.
   3. If the access point requires a password, type your password.
   4. Click the Connect button and wait for the module to connect to the
      access point.
4. Click Write radio settings in the Radio Configuration toolbar to apply
   the new values to the module.
5. Verify the module is correctly connected to the access point by checking
   the IP address assigned to the module by reading the MY parameter and
   verifying it has a value different than 0.0.0.0.

Run your first XBee Python application¶

The XBee Python application demonstrated in the steer broadcasts the message Hello XBee World ! from one of the devices connected to your computer ( the sender ) to all distant devices on the lapp net as the transmitter. Once the message is sent, the receiver XBee module must receive it. You can use XCTU to verify acknowledge .
The commands to be executed depend on the protocol of the XBee devices. Follow the comparable steps depending on the protocol of your XBee devices .

• Zigbee, DigiMesh, DigiPoint or 802.15.4 devices
• Wi-Fi devices
• cellular devices

Zigbee, DigiMesh, DigiPoint or 802.15.4 devices¶

Follow these steps to send the broadcast message and verify that it is received successfully :

1. first, prepare the receiver XBee device in XCTU to verify that the circulate message sent by the transmitter device is received successfully. Follow these steps to do thus :
   1. Launch XCTU.
   2. Add the receiver module to XCTU.
   3. Click Open the serial connection with the radio module to switch to
      Consoles working mode and open the serial connection. This allows
      you to see the data when it is received.
2. Open the Python spokesperson and write the application commands .
   1. meaning the XBeeDevice classify by executing the follow dominate :

       >  from  digi.xbee.devices  import  XBeeDevice
      

   2. Instantiate a generic XBee device :

       >  device  =  XBeeDevice ( `` COM1 '',  9600 )
      

      note
      Remember to replace the COM port with the one your sender XBee device is connected to. In UNIX-based systems, the port normally starts with /dev/tty .

   3. Open the connection with the device :

       >  device. open ( )
      

   4. Send the Hello XBee World ! broadcast message .

       >  device. send_data_broadcast ( `` Hello XBee World ! '' )
      

   5. close the connection with the device :

       >  device. close ( )
      

3. Verify that the message is received by the telephone receiver XBee in XCTU. An RX (Receive) frame should be displayed in the Console log with the following information :
   

   Start delimiter	7E
   Length	Depends on the XBee protocol
   Frame type	Depends on the XBee protocol
   16/64-bit source address	XBee sender’s 16/64-bit address
   Options	02
   RF data/Received data	48 65 6C 6C 6F 20 58 42 65 65 20 57 6F 72 6C 64 21

Wi-Fi devices¶

Wi-Fi devices send broadcast data using the send_ip_data_broadcast() command rather of the send_data_broadcast() one. For that cause, you must instantiate a WiFiDevice alternatively of a generic XBeeDevice to execute the proper command .
Follow these steps to send the air message and verify that it is received successfully :

1. foremost, prepare the receiver XBee device in XCTU to verify that the air message sent by the transmitter device is received successfully by the telephone receiver device .
   1. Launch XCTU.
   2. Add the receiver module to XCTU.
   3. Click Open the serial connection with the radio module to switch to
      Consoles working mode and open the serial connection. This allows
      you to see the data when it is received.
2. Open the Python interpreter and write the application commands .
   1. import the WiFiDevice class by executing the take after command :

       >  from  digi.xbee.devices  meaning 
      Read more: How to publish your web site with Dreamweaver 
        WiFiDevice
      

   2. Instantiate a Wi-Fi XBee device :

       >  device  =  WiFiDevice ( `` COM1 '',  9600 )
      

      bill
      Remember to replace the COM port with the one your transmitter XBee device is connected to. In UNIX-based systems, the port normally starts with /dev/tty .

   3. Open the connection with the device :

       >  device. open ( )
      

   4. Send the Hello XBee World ! air message .

       >  device. send_ip_data_broadcast ( 9750,  `` Hello XBee World ! '' )
      

   5. stopping point the connection with the device :

       >  device. conclusion ( )
      

3. Verify that the message is received by the telephone receiver XBee in XCTU. An RX IPv4 frame should be displayed in the Console log with the follow information :
   

   Start delimiter	7E
   Length	00 1C
   Frame type	B0
   IPv4 source address	XBee Wi-Fi sender’s IP address
   16-bit dest port	26 16
   16-bit source port	26 16
   Protocol	00
   Status	00
   RF data	48 65 6C 6C 6F 20 58 42 65 65 20 57 6F 72 6C 64 21

Cellular devices¶

cellular devices are connected directly to the Internet, so there is no network of distant devices to communicate with them. For cellular protocol, the application demonstrated in this guide differs from other protocols .
The lotion sends and reads data from an echo waiter. Follow these steps to execute it :

1. Open the Python interpreter and write the application commands .
   1. import the CellularDevice, IPProtocol and IPv4Address classes :

       >  from  digi.xbee.devices  significance  CellularDevice
       >  from  digi.xbee.models.protocol  import  IPProtocol
       >  from  ipaddress  significance  IPv4Address
      

   2. Instantiate a cellular XBee device :

       >  device  =  CellularDevice ( `` COM1 '',  9600 )
      

      note
      Remember to replace the COM port by the one your cellular XBee device is connected to. In UNIX-based systems, the port normally starts with /dev/tty .

   3. Open the joining with the device :

       >  device. open ( )
      

   4. Send the Hello XBee World ! message to the echo waiter with IP 52.43.121.77 and port 11001 using the TCP IP protocol .

       >  device. send_ip_data ( IPv4Address ( `` 52.43.121.77 '' ),  11001,  IPProtocol. transmission control protocol,  `` Hello XBee World ! '' )
      

   5. Read and print the reaction from the echo server. If response can not be received, print ERROR .

       >  ip_message  =  device. read_ip_data ( )
       >  print ( ip_message. data. decode ( `` utf8 '' )  if  ip_message  is  not  none  else  `` error '' )
      

   6. close the connection with the device :

       >  device 
      Read more: Payment Error Codes - ISN
      . close ( )