Skip to content

api.md

Latest commit

 

History

History
188 lines (130 loc) · 6.6 KB

api.md

File metadata and controls

188 lines (130 loc) · 6.6 KB

XBee Serial API

class xbee.XBee

Constructor

__init__(port=None, baudrate=115200, status=False, pan_id: int = 3332, mac_address: str = "" logger=None, config_file: str = None)

Configure the serial port

Note

Serial ports are not opened on object creation.


Parameters
  • port (str or None) - Port of serial device.
  • baudrate (int) - Baudrate of serial device.
  • status (bool) - Automatically receive status packets after a transmission.
  • pan_id (int) - See below
  • mac_address (str) - See below
  • logger (Logger or None) - Logger object from Logger module used to generate log files.
  • config_file (str or None) - Filename of file that contains configuration details to read from XBee modules.

See Serial Port for details on finding the correct serial port name.

baudrate should be the same for both device (XBee RF module) and serial port. XBees will be configured to 115200 by default.

pan_id and mac_address are not used within the XBee module. These parameters are provided to support the XBeeEmulator module. See the Xbee Emulator documentation for more info.

A Logger instance will be created if it is not provided. You should only create your own instance of Logger if you want to log data that is not already logged by the XBee library.

See AT_Command_List.txt for a list of some configuration details that can be read from XBee modules. If a configuration file is provided, the configurations specified will be read from the physical XBee modules and logged to the log file. It is important to note that different XBee devices may have different configurations, and you may need to create your own configuration for your device.

Example:

from xbee import XBee

PORT = "/dev/cu.usbserial-D30DWZKT"        # MacOS port example
BAUD_RATE = 115200
xbee = XBee(port=PORT, baudrate=BAUD_RATE) # status and logger will be set to False and None respectively

In this example, the port and baudrate are passed in as parameters. pan_id and mac_address are not set because they are not used within the XBee module. Because logger is not set, a Logger instance will automatically be generated by Xbee.py. Finally, the physical Xbee module's configuration will not be read because config_file is not set.

Methods

open()

Open a connection over the serial port to communicate with an XBee device.
Returns True if success, False if failure (there is already an open port)
Return Type bool
Raises SerialException if there is an error opening the serial port.

A SerialException typically occurs if:

  • The XBee module is not plugged in
  • The port/device name is incorrect
  • The port is in use (e.g. There is another program accessing the same port )
close()

Close a connection over the serial port.
Returns True if success, False if failure.
Return type bool
Raises SerialException if there is an error closing the serial port. 

transmit_data(data, address="0000000000000000", retrieveStatus: bool=False) -> x89

Send data to another XBee module(s)
Parameters
  • data (str) - String data to transmit.
  • address (str) - Address of destination XBee module. "0000000000000000" if no value is provided.
Returns Status of transmit request or None.
Return type x89 or None
Raises SerialException if serial port is not open

data can be at most 100 bytes (100 characters)

address can be set to 000000000000FFFF in order to broadcast a message

The x89 class has the following attributes: frame_type, frame_id, and status.

Returns None if no status frame is received


retrieve_data()

Checks for incoming data by retrieving one "receive packet" frame
Returns x81 or x90 objects if there is incomming data. None otherwise.
Return type x81, x90 or None

Different models of XBee devices may return different receive packet frames.

The x81 class has the following attributes: frame_type, source_address, rssi, options, data.

The x90 class has the following attributes: frame_type, address_64, address_16, receive_options, received_data


Note

The below methods are used by GCS for testing.

request_at_command_data(self, id)

Request and retrieve configuration detail of XBee device.
Parameters id (str) - Identifier of AT command
Returns AT command response.
Return type 0x88
Raises SerialException if serial port is not open 
read_config(self, filename)

Note

This method should be rewritten eventually to use a more conventional config file format such as JSON.

This method reads a config file and executes AT commands to retrieve configuration data of an XBee module. All returned data is written to a log file.
Parameters filename (str) - Filename of AT Commands to execute.
Raises SerialException if serial port is not open

Additional Resources

  • Please refer to the frame class page for frame objects returned by the XBee library.