digi.xbee.serial module

class digi.xbee.serial.FlowControl

Bases: enum.Enum

This class represents all available flow controls.

class digi.xbee.serial.XBeeSerialPort(baud_rate, port, data_bits=<sphinx.ext.autodoc.importer._MockObject object>, stop_bits=<sphinx.ext.autodoc.importer._MockObject object>, parity=<sphinx.ext.autodoc.importer._MockObject object>, flow_control=<FlowControl.NONE: None>, timeout=0.1)

Bases: sphinx.ext.autodoc.importer._MockObject, digi.xbee.comm_interface.XBeeCommunicationInterface

This class extends the functionality of Serial class (PySerial).

It also introduces a minor change in its behaviour: the serial port is not automatically open when instantiated, only when calling open().

See also

_PySerial: https://github.com/pyserial/pyserial

Class constructor. Instantiates a new XBeeSerialPort object with the given port parameters.

Parameters:

• baud_rate (Integer) – Serial port baud rate.
• port (String) – Serial port name to use.
• data_bits (Integer, optional, default=8) – Serial data bits.
• stop_bits (Float, optional, default=1) – sSerial stop bits.
• parity (Char, optional, default=`N`) – Parity. Default to ‘N’ (None).
• flow_control (Integer, optional, default=`None`) – Flow control.
• timeout (Integer, optional, default=0.1) – Read timeout (seconds).

See also

_PySerial: https://github.com/pyserial/pyserial

is_interface_open

Returns whether the underlying hardware communication interface is active.

Returns:Boolean. True if the interface is active, False otherwise.

write_frame(frame)

Writes an XBee frame to the underlying hardware interface.

Subclasses may throw specific exceptions to signal implementation specific hardware errors.

Parameters:frame (Bytearray) – The XBee API frame packet to write. If the bytearray does not correctly represent an XBee frame, the behaviour is undefined.

read_byte()

Synchronous. Reads one byte from serial port.

Returns:The read byte. Return type:Integer Raises:TimeoutException – If there is no bytes ins serial port buffer.

read_bytes(num_bytes)

Synchronous. Reads the specified number of bytes from the serial port.

Parameters:num_bytes (Integer) – the number of bytes to read. Returns:the read bytes. Return type:Bytearray Raises:TimeoutException – if the number of bytes read is less than num_bytes.

quit_reading()

Makes the thread (if any) blocking on wait_for_frame return.

If a thread was blocked on wait_for_frame, this method blocks (for a maximum of ‘timeout’ seconds) until the blocked thread is resumed.

wait_for_frame(operating_mode)

Reads the next packet. Starts to read when finds the start delimiter. The last byte read is the checksum.

If there is something in the COM buffer after the start delimiter, this method discards it.

If the method can’t read a complete and correct packet, it will return None.

Parameters:operating_mode (OperatingMode) – The operating mode in which the packet should be read. Returns:

The read packet as bytearray if a packet is read, None

otherwise.

Return type:Bytearray

read_existing()

Asynchronous. Reads all bytes in the serial port buffer. May read 0 bytes.

Returns:The bytes read. Return type:Bytearray

get_read_timeout()

Returns the serial port read timeout.

Returns:Read timeout in seconds. Return type:Integer

set_read_timeout(read_timeout)

Sets the serial port read timeout in seconds.

Parameters:read_timeout (Integer) – The new serial port read timeout in seconds.

set_baudrate(new_baudrate)

Changes the serial port baudrate.

Parameters:new_baudrate (Integer) – The new baudrate to set.

purge_port()

Purges the serial port by cleaning the input and output buffers.

apply_profile(xbee, profile_path, timeout=None, progress_callback=None)

Applies the given XBee profile to the XBee device.

Parameters:

• xbee (AbstractXBeeDevice) – Local or remote XBee node to be updated.
• profile_path (String) – Path of the XBee profile file to apply.
• timeout (Integer, optional) – Maximum time to wait for target read operations during the apply profile.
• progress_callback (Function, optional) –

  Function to execute to receive progress information. Receives two arguments:

  • The current apply profile task as a String
  • The current apply profile task percentage as an Integer

Raises:

• XBeeException – If the local XBee is not open.
• InvalidOperatingModeException – If the local XBee operating mode is invalid.
• UpdateProfileException – If there is any error applying the XBee profile.
• OperationNotSupportedException – If XBee profiles are not supported in the XBee.

close()

Terminates the underlying hardware communication interface.

Subclasses may throw specific exceptions to signal implementation specific hardware errors.

get_local_xbee_info()

Returns a tuple with the local XBee information.

This is used when opening the local XBee. If this information is provided, it is used as internal XBee data, if not provided, the data is requested to the XBee.

Returns:

Tuple with local XBee information: operation mode (int),

hardware version (int), firmware version (int), 64-bit address (string), 16-bit address (string), node identifier (string), and role (int).

Return type:Tuple

get_network(local_xbee)

Returns the XBeeNetwork object associated to the XBeeDevice associated to this XBeeCommunicationInterface.

Some XBeeCommunicationInterface implementations may need to handle the `XBeeNetwork associated to the XBeeDevice themselves. If that is the case, a implementation-specific XBeeNetwork object that complains to the generic XBeeNetwork class will be returned. Otherwise, this method returns None and the associated XBeeNetwork is handled as for a serial-connected XBeeDevice.

Parameters:local_xbee (XBeeDevice) – The local XBee device. Returns:

class: .XBeeNetwork: None if the XBeeNetwork should handled as

usual, otherwise a XBeeNetwork object.

open()

Establishes the underlying hardware communication interface.

Subclasses may throw specific exceptions to signal implementation specific errors.

supports_apply_profile()

Returns if the interface supports the apply profile feature.

Returns:True if it is supported, False otherwise. Return type:Boolean

supports_update_firmware()

Returns if the interface supports the firmware update feature.

Returns:True if it is supported, False otherwise. Return type:Boolean

timeout

Returns the read timeout.

Returns:Read timeout in seconds. Return type:Integer

update_firmware(xbee, xml_fw_file, xbee_fw_file=None, bootloader_fw_file=None, timeout=None, progress_callback=None)

Performs a firmware update operation of the provided XBee.

Parameters:

• xbee (AbstractXBeeDevice) – Local or remote XBee node to be updated.
• xml_fw_file (String) – Path of the XML file that describes the firmware to upload.
• xbee_fw_file (String, optional) – Location of the XBee binary firmware file.
• bootloader_fw_file (String, optional) – Location of the bootloader binary firmware file.
• timeout (Integer, optional) – Maximum time to wait for target read operations during the update process.
• progress_callback (Function, optional) –

  Function to execute to receive progress information. Receives two arguments:

  • The current update task as a String
  • The current update task percentage as an Integer

Raises:

• XBeeException – If the local XBee is not open.
• InvalidOperatingModeException – If the local XBee operating mode is invalid.
• OperationNotSupportedException – If the firmware update is not supported in the XBee.
• FirmwareUpdateException – If there is any error performing the firmware update.