digi.xbee.devices module
- class digi.xbee.devices.AbstractXBeeDevice(local_xbee_device=None, serial_port=None, sync_ops_timeout=4, comm_iface=None)[source]
Bases:
objectThis class provides common functionality for all XBee devices.
Class constructor. Instantiates a new
AbstractXBeeDeviceobject with the provided parameters.- Parameters:
local_xbee_device (
XBeeDevice, optional, default=`None`) – Only necessary if XBee is remote. The local XBee to be the connection interface to communicate with the remote XBee one.serial_port (
XBeeSerialPort, optional, default=`None`) – Only necessary if the XBee device is local. The serial port to communicate with this XBee.(Integer (sync_ops_timeout) –
AbstractXBeeDevice._DEFAULT_TIMEOUT_SYNC_OPERATIONS): Timeout (in seconds) for all synchronous operations.optional –
AbstractXBeeDevice._DEFAULT_TIMEOUT_SYNC_OPERATIONS): Timeout (in seconds) for all synchronous operations.default –
AbstractXBeeDevice._DEFAULT_TIMEOUT_SYNC_OPERATIONS): Timeout (in seconds) for all synchronous operations.comm_iface (
XBeeCommunicationInterface, optional, default=`None`) – Only necessary if the XBee is local. The hardware interface to communicate with this XBee.
See also
- update_device_data_from(device)[source]
Updates the current node information with provided data. This is only for internal use.
- Parameters:
device (
AbstractXBeeDevice) – XBee to get the data from.- Returns:
True if the node data has been updated, False otherwise.
- Return type:
Boolean
- get_parameter(parameter, parameter_value=None, apply=None)[source]
Returns the value of the provided parameter via an AT Command.
- Parameters:
or (parameter (String) – class: .ATStringCommand): Parameter to get.
parameter_value (Bytearray, optional, default=`None`) – Value of the parameter to execute (if any).
apply (Boolean, optional, default=`None`) – True to apply changes in XBee configuration, False not to apply them, None to use is_apply_changes_enabled() returned value.
- Returns:
Parameter value.
- Return type:
Bytearray
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- set_parameter(parameter, value, apply=None)[source]
Sets the value of a parameter via an AT Command.
Any parameter changes are applied automatically, if apply is True or if it is None and apply flag is enabled (is_apply_changes_enabled())
You can set this flag via the method
AbstractXBeeDevice.enable_apply_changes().This only applies modified values in the XBee configuration, to save changed parameters permanently (between resets), use
AbstractXBeeDevice.write_changes().- Parameters:
or (parameter (String) – class: .ATStringCommand): Parameter to set.
value (Bytearray) – Value of the parameter.
apply (Boolean, optional, default=`None`) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If parameter is None or value is None.
- execute_command(parameter, value=None, apply=None)[source]
Executes the provided command.
- Parameters:
or (parameter (String) – class: .ATStringCommand): AT command to execute.
value (bytearray, optional, default=`None`) – Command value (if any).
apply (Boolean, optional, default=`None`) – True to apply changes in XBee configuration, False not to apply them, None to use is_apply_changes_enabled() returned value.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- apply_changes()[source]
Applies changes via ‘AC’ command.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- write_changes()[source]
Writes configurable parameter values to the non-volatile memory of the XBee so that parameter modifications persist through subsequent resets.
Parameters values remain in the device’s memory until overwritten by subsequent use of this method.
If changes are made without writing them, the XBee reverts back to previously saved parameters the next time the module is powered-on.
Writing the parameter modifications does not mean those values are immediately applied, this depends on the status of the ‘apply configuration changes’ option. Use method
is_apply_changes_enabled()to get its status andenable_apply_changes()to enable/disable the option. Methodapply_changes()can be used in order to manually apply the changes.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- abstract reset()[source]
Performs a software reset on this XBee and blocks until the process is completed.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- read_device_info(init=True, fire_event=True)[source]
Updates all instance parameters reading them from the XBee.
- Parameters:
init (Boolean, optional, default=`True`) – If False only not initialized parameters are read, all if True.
fire_event (Boolean, optional, default=`True`) – True to throw and update event if any parameter changed, False otherwise.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- determine_protocol(hardware_version, firmware_version)[source]
Determines the XBee protocol based on the given hardware and firmware versions.
- Parameters:
hardware_version (Integer) – Hardware version to get its protocol.
firmware_version (Bytearray) – Firmware version to get its protocol.
- Returns:
- XBee protocol corresponding to the given
hardware and firmware versions.
- Return type:
- is_device_info_complete()[source]
Returns whether XBee node information is complete.
- Returns:
True if node information is complete, False otherwise.
- Return type:
Boolean
- get_node_id()[source]
Returns the node identifier (‘NI’) value of the XBee.
- Returns:
Node identifier (‘NI’) of the XBee.
- Return type:
String
- set_node_id(node_id)[source]
Sets the node identifier (‘NI`) value of the XBee.
- Parameters:
node_id (String) – New node identifier (‘NI’) of the XBee.
- Raises:
ValueError – If node_id is None or its length is greater than 20.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- get_hardware_version()[source]
Returns the hardware version of the XBee.
- Returns:
Hardware version of the XBee.
- Return type:
See also
- get_firmware_version()[source]
Returns the firmware version of the XBee.
- Returns:
Firmware version of the XBee.
- Return type:
Bytearray
- get_protocol()[source]
Returns the current protocol of the XBee.
- Returns:
Current protocol of the XBee.
- Return type:
See also
- get_16bit_addr()[source]
Returns the 16-bit address of the XBee.
- Returns:
16-bit address of the XBee.
- Return type:
See also
- set_16bit_addr(value)[source]
Sets the 16-bit address of the XBee.
- Parameters:
value (
XBee16BitAddress) – New 16-bit address of the XBee.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If the protocol is not 802.15.4.
- get_64bit_addr()[source]
Returns the 64-bit address of the XBee.
- Returns:
64-bit address of the XBee.
- Return type:
See also
- get_current_frame_id()[source]
Returns the last used frame ID.
- Returns:
Last used frame ID.
- Return type:
Integer
- enable_apply_changes(value)[source]
Sets apply changes flag.
- Parameters:
value (Boolean) – True to enable apply changes flag, False to disable it.
- is_apply_changes_enabled()[source]
Returns whether apply changes flag is enabled.
- Returns:
True if apply changes flag is enabled, False otherwise.
- Return type:
Boolean
- abstract is_remote()[source]
Determines whether XBee is remote.
- Returns:
True if the XBee is remote, False otherwise.
- Return type:
Boolean
- set_sync_ops_timeout(sync_ops_timeout)[source]
Sets the serial port read timeout.
- Parameters:
sync_ops_timeout (Integer) – Read timeout in seconds.
- get_sync_ops_timeout()[source]
Returns the serial port read timeout.
- Returns:
Serial port read timeout in seconds.
- Return type:
Integer
- get_dest_address()[source]
Returns the 64-bit address of the XBee that is data destination.
- Returns:
64-bit address of destination XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_dest_address(addr)[source]
Sets the 64-bit address of the XBee that is data destination.
- Parameters:
addr (
XBee64BitAddressorRemoteXBeeDevice) – Address itself or remote XBee to be data destination.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If addr is None.
See also
- get_pan_id()[source]
Returns the operating PAN ID of the XBee.
- Returns:
Operating PAN ID of the XBee.
- Return type:
Bytearray
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_pan_id(value)[source]
Sets the operating PAN ID of the XBee.
- Parameters:
value (Bytearray) – New operating PAN ID of the XBee. Must have only 1 or 2 bytes.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_power_level()[source]
Returns the power level of the XBee.
- Returns:
Power level of the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_power_level(power_level)[source]
Sets the power level of the XBee.
- Parameters:
power_level (
PowerLevel) – New power level of the XBee.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_io_configuration(io_line, io_mode)[source]
Sets the configuration of the provided IO line.
- Parameters:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_io_configuration(io_line)[source]
Returns the configuration of the provided IO line.
- Parameters:
io_line (
IOLine) – IO line to get its configuration.- Returns:
IO mode of the IO line provided.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_io_sampling_rate()[source]
Returns the IO sampling rate of the XBee.
- Returns:
IO sampling rate of XBee.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_io_sampling_rate(rate)[source]
Sets the IO sampling rate of the XBee in seconds. A sample rate of 0 means the IO sampling feature is disabled.
- Parameters:
rate (Integer) – New IO sampling rate of the XBee in seconds.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- read_io_sample()[source]
Returns an IO sample from the XBee containing the value of all enabled digital IO and analog input channels.
- Returns:
IO sample read from the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_adc_value(io_line)[source]
Returns the analog value of the provided IO line.
The provided IO line must be previously configured as ADC. To do so, use
AbstractXBeeDevice.set_io_configuration()andIOMode.ADC.- Parameters:
io_line (
IOLine) – IO line to get its ADC value.- Returns:
Analog value corresponding to the provided IO line.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If response does not contain the value for the given IO line.
See also
- set_pwm_duty_cycle(io_line, cycle)[source]
Sets the duty cycle in % of the provided IO line.
The provided IO line must be PWM-capable, previously configured as PWM output.
- Parameters:
io_line (
IOLine) – IO Line to be assigned.cycle (Integer) – Duty cycle in % to be assigned. Must be between 0 and 100.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If the given IO line does not have PWM capability or cycle is not between 0 and 100.
See also
- get_pwm_duty_cycle(io_line)[source]
Returns the PWM duty cycle in % corresponding to the provided IO line.
- Parameters:
io_line (
IOLine) – IO line to get its PWM duty cycle.- Returns:
PWM duty cycle of the given IO line.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If io_line has no PWM capability.
See also
- get_dio_value(io_line)[source]
Returns the digital value of the provided IO line.
The provided IO line must be previously configured as digital I/O. To do so, use
AbstractXBeeDevice.set_io_configuration().- Parameters:
io_line (
IOLine) – the DIO line to gets its digital value.- Returns:
current value of the provided IO line.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If response does not contain the value for the given IO line.
See also
- set_dio_value(io_line, io_value)[source]
Sets the digital value (high or low) to the provided IO line.
- Parameters:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- set_dio_change_detection(io_lines_set)[source]
Sets the digital IO lines to be monitored and sampled whenever their status changes. A None set of lines disables this feature.
- Parameters:
io_lines_set – Set of
IOLine.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_api_output_mode()[source]
Deprecated since version 1.3: Use
get_api_output_mode_value()Returns the API output mode of the XBee.
The API output mode determines the format of the data through the serial interface of the XBee.
- Returns:
API output mode of the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_api_output_mode_value()[source]
Returns the API output mode of the XBee.
The API output mode determines the format that the received data is output through the serial interface of the XBee.
- Returns:
the parameter value.
- Return type:
Bytearray
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
- set_api_output_mode(api_output_mode)[source]
Deprecated since version 1.3: Use
set_api_output_mode_value()Sets the API output mode of the XBee.
- Parameters:
api_output_mode (
APIOutputMode) – New API output mode.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
See also
- set_api_output_mode_value(api_output_mode)[source]
Sets the API output mode of the XBee.
- Parameters:
api_output_mode (Integer) – New API output mode options. Calculate this value using the method
APIOutputModeBit.calculate_api_output_mode_value()with a set ofAPIOutputModeBit.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
See also
- enable_bluetooth()[source]
Enables the Bluetooth interface of this XBee.
To work with this interface, you must also configure the Bluetooth password if not done previously. Use method
AbstractXBeeDevice.update_bluetooth_password().Note that your XBee must include Bluetooth Low Energy support.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- disable_bluetooth()[source]
Disables the Bluetooth interface of this XBee.
Note that your device must include Bluetooth Low Energy support.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- get_bluetooth_mac_addr()[source]
Reads and returns the EUI-48 Bluetooth MAC address of this XBee following the format 00112233AABB.
Note that your device must include Bluetooth Low Energy support.
- Returns:
The Bluetooth MAC address.
- Return type:
String
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- update_bluetooth_password(new_password, apply=True, save=True)[source]
Changes the Bluetooth password of this XBee with the new one provided.
Note that your device must include Bluetooth Low Energy support.
- Parameters:
new_password (String) – New Bluetooth password.
apply (Boolean, optional, default=`True`) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
save (Boolean, optional, default=`True`) – True to save changes, False otherwise.
- Raises:
ValueError – If new_password is invalid.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- update_bluetooth_salt_verifier(salt, verifier, apply=True, save=True)[source]
Changes the Bluetooth password of this XBee with the new one provided.
Note that your device must include Bluetooth Low Energy support.
- Parameters:
salt (bytes) – New Bluetooth password.
verifier (bytes) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
apply (Boolean, optional, default=`True`) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
save (Boolean, optional, default=`True`) – True to save changes, False otherwise.
- Raises:
ValueError – If salt or verifier are invalid.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- update_firmware(xml_firmware_file, xbee_firmware_file=None, bootloader_firmware_file=None, timeout=None, progress_callback=None)[source]
Performs a firmware update operation of the XBee.
- Parameters:
xml_firmware_file (String) – Path of the XML file that describes the firmware to upload.
xbee_firmware_file (String, optional, default=`None`) – Location of the XBee binary firmware file.
bootloader_firmware_file (String, optional, default=`None`) – Location of the bootloader binary firmware file.
timeout (Integer, optional, default=`None`) – Maximum time to wait for target read operations during the update process (seconds).
progress_callback (Function, optional, default=`None`) –
Function to 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 XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
OperationNotSupportedException – If XBee does not support firmware update.
FirmwareUpdateException – If there is any error during the firmware update.
- apply_profile(profile_path, timeout=None, progress_callback=None)[source]
Applies the given XBee profile to the XBee.
- Parameters:
profile_path (String) – Path of the XBee profile file to apply.
timeout (Integer, optional, default=`None`) – Maximum time to wait for target read operations during the apply profile (seconds).
progress_callback (Function, optional, default=`None`) –
Function 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 XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
UpdateProfileException – If there is any error applying the XBee profile.
- get_file_manager()[source]
Returns the file system manager for the XBee.
- Returns:
The file system manager.
- Return type:
- Raises:
FileSystemNotSupportedException – If the XBee does not support filesystem.
- property reachable
Returns whether the XBee is reachable.
- Returns:
True if the device is reachable, False otherwise.
- Return type:
Boolean
- property scan_counter
Returns the scan counter for this node.
- Returns:
The scan counter for this node.
- Return type:
Integer
- property log
Returns the XBee logger.
- Returns:
The XBee device logger.
- Return type:
Logger
- property br
Returns the BR value of the device.
- Returns:
The BR value of the device.
- Return type:
Integer
- class digi.xbee.devices.XBeeDevice(port=None, baud_rate=None, data_bits=serial.EIGHTBITS, stop_bits=serial.STOPBITS_ONE, parity=serial.PARITY_NONE, flow_control=FlowControl.NONE, _sync_ops_timeout=4, exclusive=True, comm_iface=None)[source]
Bases:
AbstractXBeeDeviceThis class represents a non-remote generic XBee.
This class has fields that are events. Its recommended to use only the append() and remove() method on them, or -= and += operators. If you do something more with them, it’s for your own risk.
Class constructor. Instantiates a new
XBeeDevicewith the provided parameters.- Parameters:
port (String) – Serial port identifier. Depends on operating system. e.g. ‘/dev/ttyUSB0’ on ‘GNU/Linux’ or ‘COM3’ on Windows.
baud_rate (Integer, optional, default=`None`) – Serial port baud rate.
(Integer (_sync_ops_timeout) –
serial.EIGHTBITS): Port bitsize.default –
serial.EIGHTBITS): Port bitsize.(Integer –
serial.STOPBITS_ONE): Port stop bits.default –
serial.STOPBITS_ONE): Port stop bits.(Character (parity) –
serial.PARITY_NONE): Port parity.default –
serial.PARITY_NONE): Port parity.(Integer –
FlowControl.NONE): Port flow control.default –
FlowControl.NONE): Port flow control.(Integer – 4): Read timeout (in seconds).
default – 4): Read timeout (in seconds).
exclusive (Boolean, optional, default=`True`) – Set serial port exclusive access mode (POSIX only).
comm_iface (
XBeeCommunicationInterface) – Communication interface.
- Raises:
All exceptions raised by PySerial's Serial class constructor. –
See also
PySerial documentation: http://pyserial.sourceforge.net- TIMEOUT_READ_PACKET = 3
Timeout to read packets.
- classmethod create_xbee_device(comm_port_data)[source]
Creates and returns an
XBeeDevicefrom data of the port to which is connected.- Parameters:
comm_port_data (Dictionary) – Dictionary with all comm port data needed.
are (The dictionary keys) –
“baudRate” –> Baud rate.”port” –> Port number.”bitSize” –> Bit size.”stopBits” –> Stop bits.”parity” –> Parity.”flowControl” –> Flow control.”timeout” for –> Timeout for synchronous operations (in seconds).
- Returns:
XBee object created.
- Return type:
- Raises:
SerialException – If the port to open does not exist or is already opened.
See also
- open(force_settings=False)[source]
Opens the communication with the XBee and loads information about it.
- Parameters:
force_settings (Boolean, optional, default=`False`) – True to open the device ensuring/forcing that the specified serial settings are applied even if the current configuration is different, False to open the device with the current configuration.
- Raises:
TimeoutException – If there is any problem with the communication.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the XBee is already opened.
- close()[source]
Closes the communication with the XBee.
This method guarantees that all threads running are stopped and the serial port is closed.
- property serial_port
Returns the serial port associated to the XBee, if any.
- Returns:
- Serial port of the XBee. None if the
local XBee does not use serial communication.
- Return type:
See also
- property comm_iface
Returns the hardware interface associated to the XBee.
- Returns:
Hardware interface of the XBee.
- Return type:
See also
- property operating_mode
Returns the operating mode of this XBee.
- Returns:
OperatingMode. This XBee operating mode.
- property stats
Gets the statistics for this XBee.
- Returns:
Statistics. XBee statistics.
- send_data(remote_xbee, data, transmit_options=0)[source]
Blocking method. This method sends data to a remote XBee synchronously.
This method will wait for the packet response. The default timeout is
XBeeDevice._DEFAULT_TIMEOUT_SYNC_OPERATIONS.- Parameters:
remote_xbee (
RemoteXBeeDevice) – Remote XBee to send data to.data (String or Bytearray) – Raw data to send.
transmit_options (Integer, optional) – Transmit options, bitfield of
TransmitOptions. Default to TransmitOptions.NONE.value.
- Returns:
The response.
- Return type:
- Raises:
ValueError – If remote_xbee is None.
TimeoutException – If response is not received before the read timeout expires.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
TransmitException – If the status of the response received is not OK.
XBeeException – If the XBee’s communication interface is closed.
See also
- send_data_async(remote_xbee, data, transmit_options=0)[source]
Non-blocking method. This method sends data to a remote XBee.
This method does not wait for a response.
- Parameters:
remote_xbee (
RemoteXBeeDevice) – the remote XBee to send data to.data (String or Bytearray) – Raw data to send.
transmit_options (Integer, optional) – Transmit options, bitfield of
TransmitOptions. Default to TransmitOptions.NONE.value.
- Raises:
ValueError – If remote_xbee is None.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the XBee’s communication interface is closed.
See also
- send_data_broadcast(data, transmit_options=0)[source]
Sends the provided data to all the XBee nodes of the network (broadcast).
This method blocks until a success or error transmit status arrives or the configured receive timeout expires.
The received timeout is configured using method
AbstractXBeeDevice.set_sync_ops_timeout()and can be consulted withAbstractXBeeDevice.get_sync_ops_timeout()method.- Parameters:
data (String or Bytearray) – Data to send.
transmit_options (Integer, optional) – Transmit options, bitfield of
TransmitOptions. Default to TransmitOptions.NONE.value.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
TransmitException – If the status of the response received is not OK.
XBeeException – If the XBee’s communication interface is closed.
- send_user_data_relay(local_interface, data)[source]
Sends the given data to the given XBee local interface.
- Parameters:
local_interface (
XBeeLocalInterface) – Destination XBee local interface.data (Bytearray) – Data to send.
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ValueError – If local_interface is None.
XBeeException – If there is any problem sending the User Data Relay.
See also
- send_bluetooth_data(data)[source]
Sends the given data to the Bluetooth interface using a User Data Relay frame.
- Parameters:
data (Bytearray) – Data to send.
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If there is any problem sending the data.
- send_micropython_data(data)[source]
Sends the given data to the MicroPython interface using a User Data Relay frame.
- Parameters:
data (Bytearray) – Data to send.
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If there is any problem sending the data.
- read_data(timeout=None)[source]
Reads new data received by this XBee.
If timeout is specified, this method blocks until new data is received or the timeout expires, throwing a
TimeoutExceptionin this case.- Parameters:
timeout (Integer, optional) – Read timeout in seconds. If None, this method is non-blocking and returns None if no data is available.
- Returns:
- Read message or None if this XBee did not
receive new data.
- Return type:
- Raises:
ValueError – If a timeout is specified and is less than 0.
TimeoutException – If a timeout is specified and no data was received during that time.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the XBee’s communication interface is closed.
See also
- read_data_from(remote_xbee, timeout=None)[source]
Reads new data received from the given remote XBee.
If timeout is specified, this method blocks until new data is received or the timeout expires, throwing a
TimeoutExceptionin this case.- Parameters:
remote_xbee (
RemoteXBeeDevice) – Remote XBee that sent the data.timeout (Integer, optional) – Read timeout in seconds. If None, this method is non-blocking and returns None if no data is available.
- Returns:
- Read message sent by remote_xbee or None
if this XBee did not receive new data.
- Return type:
- Raises:
ValueError – If a timeout is specified and is less than 0.
TimeoutException – If a timeout is specified and no data was received during that time.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the XBee’s communication interface is closed.
See also
- has_packets()[source]
Returns if there are pending packets to read. This does not include explicit packets.
- Returns:
True if there are pending packets, False otherwise.
- Return type:
Boolean
See also
- has_explicit_packets()[source]
Returns if there are pending explicit packets to read. This does not include non-explicit packets.
- Returns:
True if there are pending packets, False otherwise.
- Return type:
Boolean
See also
- add_packet_received_callback(callback)[source]
Adds a callback for the event
PacketReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The received packet as a
XBeeAPIPacket.
- add_data_received_callback(callback)[source]
Adds a callback for the event
DataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The data received as an
XBeeMessage.
- add_modem_status_received_callback(callback)[source]
Adds a callback for the event
ModemStatusReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The modem status as a
ModemStatus.
- add_io_sample_received_callback(callback)[source]
Adds a callback for the event
IOSampleReceived.- Parameters:
callback (Function) –
The callback. Receives three arguments.
The received IO sample as an
IOSample.The remote XBee which sent the packet as a
RemoteXBeeDevice.The time in which the packet was received as an Integer.
- add_expl_data_received_callback(callback)[source]
Adds a callback for the event
ExplicitDataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The explicit data received as a
ExplicitXBeeMessage.
- add_user_data_relay_received_callback(callback)[source]
Adds a callback for the event
RelayDataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The relay data as a
UserDataRelayMessage.
- add_bluetooth_data_received_callback(callback)[source]
Adds a callback for the event
BluetoothDataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The Bluetooth data as a Bytearray.
- add_micropython_data_received_callback(callback)[source]
Adds a callback for the event
MicroPythonDataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The MicroPython data as a Bytearray.
- add_socket_state_received_callback(callback)[source]
Adds a callback for the event
SocketStateReceived.- Parameters:
callback (Function) –
The callback. Receives two arguments.
The socket ID as an Integer.
The state received as a
SocketState.
- add_socket_data_received_callback(callback)[source]
Adds a callback for the event
SocketDataReceived.- Parameters:
callback (Function) –
The callback. Receives two arguments.
The socket ID as an Integer.
The data received as Bytearray.
- add_socket_data_received_from_callback(callback)[source]
Adds a callback for the event
SocketDataReceivedFrom.- Parameters:
callback (Function) –
The callback. Receives three arguments.
The socket ID as an Integer.
- Source address pair (host, port) where host is a string
representing an IPv4 address like ‘100.50.200.5’, and port is an integer.
The data received as Bytearray.
- add_fs_frame_received_callback(callback)[source]
Adds a callback for the event
FileSystemFrameReceived.- Parameters:
callback (Function) –
The callback. Receives four arguments.
Source (
AbstractXBeeDevice): The node that sent the file system frame.Frame id (Integer): The received frame id.
Command (
FSCmd): The file system command.Receive options (Integer): Bitfield indicating receive options.
See also
- del_packet_received_callback(callback)[source]
Deletes a callback for the callback list of
PacketReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_data_received_callback(callback)[source]
Deletes a callback for the callback list of
DataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_modem_status_received_callback(callback)[source]
Deletes a callback for the callback list of
ModemStatusReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_io_sample_received_callback(callback)[source]
Deletes a callback for the callback list of
IOSampleReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_expl_data_received_callback(callback)[source]
Deletes a callback for the callback list of
ExplicitDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_user_data_relay_received_callback(callback)[source]
Deletes a callback for the callback list of
RelayDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_bluetooth_data_received_callback(callback)[source]
Deletes a callback for the callback list of
BluetoothDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_micropython_data_received_callback(callback)[source]
Deletes a callback for the callback list of
MicroPythonDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_socket_state_received_callback(callback)[source]
Deletes a callback for the callback list of
SocketStateReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_socket_data_received_callback(callback)[source]
Deletes a callback for the callback list of
SocketDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_socket_data_received_from_callback(callback)[source]
Deletes a callback for the callback list of
SocketDataReceivedFromevent.- Parameters:
callback (Function) – The callback to delete.
- del_fs_frame_received_callback(callback)[source]
Deletes a callback for the callback list of
FileSystemFrameReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- get_xbee_device_callbacks()[source]
Returns this XBee internal callbacks for process received packets.
This method is called by the PacketListener associated with this XBee to get its callbacks. These callbacks are executed before user callbacks.
- Returns:
- is_open()[source]
Returns whether this XBee is open.
- Returns:
Boolean. True if this XBee is open, False otherwise.
- read_expl_data(timeout=None)[source]
Reads new explicit data received by this XBee.
If timeout is specified, this method blocks until new data is received or the timeout expires, throwing a
TimeoutExceptionin this case.- Parameters:
timeout (Integer, optional) – Read timeout in seconds. If None, this method is non-blocking and returns None if there is no explicit data available.
- Returns:
- Read message or None if this XBee
did not receive new explicit data.
- Return type:
- Raises:
ValueError – If a timeout is specified and is less than 0.
TimeoutException – If a timeout is specified and no explicit data was received during that time.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the XBee’s communication interface is closed.
See also
- read_expl_data_from(remote_xbee, timeout=None)[source]
Reads new explicit data received from the given remote XBee.
If timeout is specified, this method blocks until new data is received or the timeout expires, throwing a
TimeoutExceptionin this case.- Parameters:
remote_xbee (
RemoteXBeeDevice) – Remote XBee that sent the explicit data.timeout (Integer, optional) – Read timeout in seconds. If None, this method is non-blocking and returns None if there is no data available.
- Returns:
- Read message sent by remote_xbee
or None if this XBee did not receive new data from that node.
- Return type:
- Raises:
ValueError – If a timeout is specified and is less than 0.
TimeoutException – If a timeout is specified and no explicit data was received during that time.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the XBee’s communication interface is closed.
See also
- send_expl_data(remote_xbee, data, src_endpoint, dest_endpoint, cluster_id, profile_id, transmit_options=0)[source]
Blocking method. Sends the provided explicit data to the given XBee, source and destination end points, cluster and profile ids.
This method blocks until a success or error response arrives or the configured receive timeout expires. The default timeout is
XBeeDevice._DEFAULT_TIMEOUT_SYNC_OPERATIONS.- Parameters:
remote_xbee (
RemoteXBeeDevice) – Remote XBee to send data to.data (String or Bytearray) – Raw data to send.
src_endpoint (Integer) – Source endpoint of the transmission. 1 byte.
dest_endpoint (Integer) – Destination endpoint of the transmission. 1 byte.
cluster_id (Integer) – Cluster ID of the transmission (between 0x0 and 0xFFFF)
profile_id (Integer) – Profile ID of the transmission (between 0x0 and 0xFFFF)
transmit_options (Integer, optional) – Transmit options, bitfield of
TransmitOptions. Default to TransmitOptions.NONE.value.
- Returns:
Response packet obtained after sending data.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
TransmitException – If the status of the response received is not OK.
XBeeException – If the XBee’s communication interface is closed.
ValueError – if cluster_id or profile_id is less than 0x0 or greater than 0xFFFF.
See also
- send_expl_data_broadcast(data, src_endpoint, dest_endpoint, cluster_id, profile_id, transmit_options=0)[source]
Sends the provided explicit data to all the XBee nodes of the network (broadcast) using provided source and destination end points, cluster and profile ids.
This method blocks until a success or error transmit status arrives or the configured receive timeout expires. The received timeout is configured using the
AbstractXBeeDevice.set_sync_ops_timeout()method and can be consulted with methodAbstractXBeeDevice.get_sync_ops_timeout().- Parameters:
data (String or Bytearray) – Raw data to send.
src_endpoint (Integer) – Source endpoint of the transmission. 1 byte.
dest_endpoint (Integer) – Destination endpoint of the transmission. 1 byte.
cluster_id (Integer) – Cluster ID of the transmission (between 0x0 and 0xFFFF)
profile_id (Integer) – Profile ID of the transmission (between 0x0 and 0xFFFF)
transmit_options (Integer, optional) – Transmit options, bitfield of
TransmitOptions. Default to TransmitOptions.NONE.value.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
TransmitException – If the status of the response received is not OK.
XBeeException – If the XBee’s communication interface is closed.
ValueError – if cluster_id or profile_id is less than 0x0 or greater than 0xFFFF.
See also
XBeeDevice._send_expl_data()
- send_expl_data_async(remote_xbee, data, src_endpoint, dest_endpoint, cluster_id, profile_id, transmit_options=0)[source]
Non-blocking method. Sends the provided explicit data to the given XBee, source and destination end points, cluster and profile ids.
- Parameters:
remote_xbee (
RemoteXBeeDevice) – Remote XBee to send data to.data (String or Bytearray) – Raw data to send.
src_endpoint (Integer) – Source endpoint of the transmission. 1 byte.
dest_endpoint (Integer) – Destination endpoint of the transmission. 1 byte.
cluster_id (Integer) – Cluster ID of the transmission (between 0x0 and 0xFFFF)
profile_id (Integer) – Profile ID of the transmission (between 0x0 and 0xFFFF)
transmit_options (Integer, optional) – Transmit options, bitfield of
TransmitOptions. Default to TransmitOptions.NONE.value.
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the XBee’s communication interface is closed.
ValueError – if cluster_id or profile_id is less than 0x0 or greater than 0xFFFF.
See also
- send_packet_sync_and_get_response(packet_to_send, timeout=None)[source]
Sends the packet and waits for its corresponding response.
- Parameters:
packet_to_send (
XBeePacket) – The packet to transmit.timeout (Integer, optional, default=`None`) – Number of seconds to wait. -1 to wait indefinitely.
- Returns:
Received response packet.
- Return type:
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
TimeoutException – If response is not received in the configured timeout.
XBeeException – If the XBee’s communication interface is closed.
See also
- send_packet(packet, sync=False)[source]
Sends the packet and waits for the response. The packet to send is escaped depending on the current operating mode.
This method can be synchronous or asynchronous.
If synchronous, this method discards all response packets until it finds the one that has the appropriate frame ID, that is, the sent packet’s frame ID.
If asynchronous, this method does not wait for any response and returns None.
- Parameters:
packet (
XBeePacket) – The packet to send.sync (Boolean) – True to wait for the response of the sent packet and return it, False otherwise.
- Returns:
- Response packet if sync is True, None
otherwise.
- Return type:
- Raises:
TimeoutException – If sync is True and the response packet for the sent one cannot be read.
InvalidOperatingModeException – If the XBee operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the packet listener is not running or the XBee’s communication interface is closed.
See also
- get_next_frame_id()[source]
Returns the next frame ID of the XBee.
- Returns:
The next frame ID of the XBee.
- Return type:
Integer
- add_route_received_callback(callback)[source]
Adds a callback for the event
RouteReceived. This works for Zigbee and Digimesh devices.- Parameters:
callback (Function) –
The callback. Receives three arguments.
source (
XBeeDevice): The source node.destination (
RemoteXBeeDevice): The destination node.- hops (List): List of intermediate hops from closest to source
to closest to destination (
RemoteXBeeDevice).
- del_route_received_callback(callback)[source]
Deletes a callback for the callback list of
RouteReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- get_route_to_node(remote, timeout=10, force=True)[source]
Gets the route from this XBee to the given remote node.
- For Zigbee:
‘AR’ parameter of the local node must be configured with a value different from ‘FF’.
Set force to True to force the Zigbee remote node to return its route independently of the local node configuration as high or low RAM concentrator (‘DO’ of the local value)
- Parameters:
remote (
RemoteXBeeDevice) – The remote node.timeout (Float, optional, default=10) – Maximum number of seconds to wait for the route.
force (Boolean) – True to force asking for the route, False otherwise. Only for Zigbee.
- Returns:
- Tuple containing route data:
status (
TransmitStatus): The transmit status.Tuple with route data (None if the route was not read in the provided timeout):
source (
RemoteXBeeDevice): The source node of the route.destination (
RemoteXBeeDevice): The destination node of the route.hops (List): List of intermediate nodes (
RemoteXBeeDevice) ordered from closest to source to closest to destination node (source and destination not included).
- Return type:
Tuple
- apply_changes()
Applies changes via ‘AC’ command.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- apply_profile(profile_path, timeout=None, progress_callback=None)
Applies the given XBee profile to the XBee.
- Parameters:
profile_path (String) – Path of the XBee profile file to apply.
timeout (Integer, optional, default=`None`) – Maximum time to wait for target read operations during the apply profile (seconds).
progress_callback (Function, optional, default=`None`) –
Function 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 XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
UpdateProfileException – If there is any error applying the XBee profile.
- property br
Returns the BR value of the device.
- Returns:
The BR value of the device.
- Return type:
Integer
- determine_protocol(hardware_version, firmware_version)
Determines the XBee protocol based on the given hardware and firmware versions.
- Parameters:
hardware_version (Integer) – Hardware version to get its protocol.
firmware_version (Bytearray) – Firmware version to get its protocol.
- Returns:
- XBee protocol corresponding to the given
hardware and firmware versions.
- Return type:
- disable_bluetooth()
Disables the Bluetooth interface of this XBee.
Note that your device must include Bluetooth Low Energy support.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- enable_apply_changes(value)
Sets apply changes flag.
- Parameters:
value (Boolean) – True to enable apply changes flag, False to disable it.
- enable_bluetooth()
Enables the Bluetooth interface of this XBee.
To work with this interface, you must also configure the Bluetooth password if not done previously. Use method
AbstractXBeeDevice.update_bluetooth_password().Note that your XBee must include Bluetooth Low Energy support.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- execute_command(parameter, value=None, apply=None)
Executes the provided command.
- Parameters:
or (parameter (String) – class: .ATStringCommand): AT command to execute.
value (bytearray, optional, default=`None`) – Command value (if any).
apply (Boolean, optional, default=`None`) – True to apply changes in XBee configuration, False not to apply them, None to use is_apply_changes_enabled() returned value.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- get_16bit_addr()
Returns the 16-bit address of the XBee.
- Returns:
16-bit address of the XBee.
- Return type:
See also
- get_64bit_addr()
Returns the 64-bit address of the XBee.
- Returns:
64-bit address of the XBee.
- Return type:
See also
- get_adc_value(io_line)
Returns the analog value of the provided IO line.
The provided IO line must be previously configured as ADC. To do so, use
AbstractXBeeDevice.set_io_configuration()andIOMode.ADC.- Parameters:
io_line (
IOLine) – IO line to get its ADC value.- Returns:
Analog value corresponding to the provided IO line.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If response does not contain the value for the given IO line.
See also
- get_api_output_mode()
Deprecated since version 1.3: Use
get_api_output_mode_value()Returns the API output mode of the XBee.
The API output mode determines the format of the data through the serial interface of the XBee.
- Returns:
API output mode of the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_api_output_mode_value()
Returns the API output mode of the XBee.
The API output mode determines the format that the received data is output through the serial interface of the XBee.
- Returns:
the parameter value.
- Return type:
Bytearray
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
- get_bluetooth_mac_addr()
Reads and returns the EUI-48 Bluetooth MAC address of this XBee following the format 00112233AABB.
Note that your device must include Bluetooth Low Energy support.
- Returns:
The Bluetooth MAC address.
- Return type:
String
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- get_current_frame_id()
Returns the last used frame ID.
- Returns:
Last used frame ID.
- Return type:
Integer
- get_dest_address()
Returns the 64-bit address of the XBee that is data destination.
- Returns:
64-bit address of destination XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_dio_value(io_line)
Returns the digital value of the provided IO line.
The provided IO line must be previously configured as digital I/O. To do so, use
AbstractXBeeDevice.set_io_configuration().- Parameters:
io_line (
IOLine) – the DIO line to gets its digital value.- Returns:
current value of the provided IO line.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If response does not contain the value for the given IO line.
See also
- get_file_manager()
Returns the file system manager for the XBee.
- Returns:
The file system manager.
- Return type:
- Raises:
FileSystemNotSupportedException – If the XBee does not support filesystem.
- get_firmware_version()
Returns the firmware version of the XBee.
- Returns:
Firmware version of the XBee.
- Return type:
Bytearray
- get_hardware_version()
Returns the hardware version of the XBee.
- Returns:
Hardware version of the XBee.
- Return type:
See also
- get_io_configuration(io_line)
Returns the configuration of the provided IO line.
- Parameters:
io_line (
IOLine) – IO line to get its configuration.- Returns:
IO mode of the IO line provided.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_io_sampling_rate()
Returns the IO sampling rate of the XBee.
- Returns:
IO sampling rate of XBee.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_node_id()
Returns the node identifier (‘NI’) value of the XBee.
- Returns:
Node identifier (‘NI’) of the XBee.
- Return type:
String
- get_pan_id()
Returns the operating PAN ID of the XBee.
- Returns:
Operating PAN ID of the XBee.
- Return type:
Bytearray
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_power_level()
Returns the power level of the XBee.
- Returns:
Power level of the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_protocol()
Returns the current protocol of the XBee.
- Returns:
Current protocol of the XBee.
- Return type:
See also
- get_pwm_duty_cycle(io_line)
Returns the PWM duty cycle in % corresponding to the provided IO line.
- Parameters:
io_line (
IOLine) – IO line to get its PWM duty cycle.- Returns:
PWM duty cycle of the given IO line.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If io_line has no PWM capability.
See also
- get_sync_ops_timeout()
Returns the serial port read timeout.
- Returns:
Serial port read timeout in seconds.
- Return type:
Integer
- is_apply_changes_enabled()
Returns whether apply changes flag is enabled.
- Returns:
True if apply changes flag is enabled, False otherwise.
- Return type:
Boolean
- is_device_info_complete()
Returns whether XBee node information is complete.
- Returns:
True if node information is complete, False otherwise.
- Return type:
Boolean
- property log
Returns the XBee logger.
- Returns:
The XBee device logger.
- Return type:
Logger
- property reachable
Returns whether the XBee is reachable.
- Returns:
True if the device is reachable, False otherwise.
- Return type:
Boolean
- read_device_info(init=True, fire_event=True)
Updates all instance parameters reading them from the XBee.
- Parameters:
init (Boolean, optional, default=`True`) – If False only not initialized parameters are read, all if True.
fire_event (Boolean, optional, default=`True`) – True to throw and update event if any parameter changed, False otherwise.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- read_io_sample()
Returns an IO sample from the XBee containing the value of all enabled digital IO and analog input channels.
- Returns:
IO sample read from the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- property scan_counter
Returns the scan counter for this node.
- Returns:
The scan counter for this node.
- Return type:
Integer
- set_16bit_addr(value)
Sets the 16-bit address of the XBee.
- Parameters:
value (
XBee16BitAddress) – New 16-bit address of the XBee.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If the protocol is not 802.15.4.
- set_api_output_mode(api_output_mode)
Deprecated since version 1.3: Use
set_api_output_mode_value()Sets the API output mode of the XBee.
- Parameters:
api_output_mode (
APIOutputMode) – New API output mode.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
See also
- set_api_output_mode_value(api_output_mode)
Sets the API output mode of the XBee.
- Parameters:
api_output_mode (Integer) – New API output mode options. Calculate this value using the method
APIOutputModeBit.calculate_api_output_mode_value()with a set ofAPIOutputModeBit.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
See also
- set_dest_address(addr)
Sets the 64-bit address of the XBee that is data destination.
- Parameters:
addr (
XBee64BitAddressorRemoteXBeeDevice) – Address itself or remote XBee to be data destination.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If addr is None.
See also
- set_dio_change_detection(io_lines_set)
Sets the digital IO lines to be monitored and sampled whenever their status changes. A None set of lines disables this feature.
- Parameters:
io_lines_set – Set of
IOLine.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_dio_value(io_line, io_value)
Sets the digital value (high or low) to the provided IO line.
- Parameters:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- set_io_configuration(io_line, io_mode)
Sets the configuration of the provided IO line.
- Parameters:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_io_sampling_rate(rate)
Sets the IO sampling rate of the XBee in seconds. A sample rate of 0 means the IO sampling feature is disabled.
- Parameters:
rate (Integer) – New IO sampling rate of the XBee in seconds.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_node_id(node_id)
Sets the node identifier (‘NI`) value of the XBee.
- Parameters:
node_id (String) – New node identifier (‘NI’) of the XBee.
- Raises:
ValueError – If node_id is None or its length is greater than 20.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- set_pan_id(value)
Sets the operating PAN ID of the XBee.
- Parameters:
value (Bytearray) – New operating PAN ID of the XBee. Must have only 1 or 2 bytes.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_power_level(power_level)
Sets the power level of the XBee.
- Parameters:
power_level (
PowerLevel) – New power level of the XBee.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_pwm_duty_cycle(io_line, cycle)
Sets the duty cycle in % of the provided IO line.
The provided IO line must be PWM-capable, previously configured as PWM output.
- Parameters:
io_line (
IOLine) – IO Line to be assigned.cycle (Integer) – Duty cycle in % to be assigned. Must be between 0 and 100.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If the given IO line does not have PWM capability or cycle is not between 0 and 100.
See also
- set_sync_ops_timeout(sync_ops_timeout)
Sets the serial port read timeout.
- Parameters:
sync_ops_timeout (Integer) – Read timeout in seconds.
- update_bluetooth_password(new_password, apply=True, save=True)
Changes the Bluetooth password of this XBee with the new one provided.
Note that your device must include Bluetooth Low Energy support.
- Parameters:
new_password (String) – New Bluetooth password.
apply (Boolean, optional, default=`True`) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
save (Boolean, optional, default=`True`) – True to save changes, False otherwise.
- Raises:
ValueError – If new_password is invalid.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- update_bluetooth_salt_verifier(salt, verifier, apply=True, save=True)
Changes the Bluetooth password of this XBee with the new one provided.
Note that your device must include Bluetooth Low Energy support.
- Parameters:
salt (bytes) – New Bluetooth password.
verifier (bytes) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
apply (Boolean, optional, default=`True`) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
save (Boolean, optional, default=`True`) – True to save changes, False otherwise.
- Raises:
ValueError – If salt or verifier are invalid.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- update_device_data_from(device)
Updates the current node information with provided data. This is only for internal use.
- Parameters:
device (
AbstractXBeeDevice) – XBee to get the data from.- Returns:
True if the node data has been updated, False otherwise.
- Return type:
Boolean
- update_firmware(xml_firmware_file, xbee_firmware_file=None, bootloader_firmware_file=None, timeout=None, progress_callback=None)
Performs a firmware update operation of the XBee.
- Parameters:
xml_firmware_file (String) – Path of the XML file that describes the firmware to upload.
xbee_firmware_file (String, optional, default=`None`) – Location of the XBee binary firmware file.
bootloader_firmware_file (String, optional, default=`None`) – Location of the bootloader binary firmware file.
timeout (Integer, optional, default=`None`) – Maximum time to wait for target read operations during the update process (seconds).
progress_callback (Function, optional, default=`None`) –
Function to 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 XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
OperationNotSupportedException – If XBee does not support firmware update.
FirmwareUpdateException – If there is any error during the firmware update.
- write_changes()
Writes configurable parameter values to the non-volatile memory of the XBee so that parameter modifications persist through subsequent resets.
Parameters values remain in the device’s memory until overwritten by subsequent use of this method.
If changes are made without writing them, the XBee reverts back to previously saved parameters the next time the module is powered-on.
Writing the parameter modifications does not mean those values are immediately applied, this depends on the status of the ‘apply configuration changes’ option. Use method
is_apply_changes_enabled()to get its status andenable_apply_changes()to enable/disable the option. Methodapply_changes()can be used in order to manually apply the changes.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- class digi.xbee.devices.Raw802Device(port=None, baud_rate=None, data_bits=serial.EIGHTBITS, stop_bits=serial.STOPBITS_ONE, parity=serial.PARITY_NONE, flow_control=FlowControl.NONE, _sync_ops_timeout=4, comm_iface=None)[source]
Bases:
XBeeDeviceThis class represents a local 802.15.4 XBee.
Class constructor. Instantiates a new
Raw802Devicewith the provided parameters.- Parameters:
port (String) – Serial port identifier. Depends on operating system. e.g. ‘/dev/ttyUSB0’ on ‘GNU/Linux’ or ‘COM3’ on Windows.
baud_rate (Integer) – Serial port baud rate.
(Integer (flow_control) –
serial.EIGHTBITS): Port bitsize.default –
serial.EIGHTBITS): Port bitsize.(Integer –
serial.STOPBITS_ONE): Port stop bits.default –
serial.STOPBITS_ONE): Port stop bits.(Character (parity) –
serial.PARITY_NONE): Port parity.default –
serial.PARITY_NONE): Port parity.(Integer –
FlowControl.NONE): Port flow control.default –
FlowControl.NONE): Port flow control.- _sync_ops_timeout (Integer, default: 3): Read timeout (in seconds).
comm_iface (
XBeeCommunicationInterface): Communication interface.
:raises All exceptions raised by
XBeeDevice.__init__()constructor.:See also
XBeeDevice.__init__()- get_ai_status()[source]
Returns the current association status of this XBee. It indicates occurrences of errors during the modem initialization and connection.
- Returns:
- The XBee association
indication status.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- send_data_64(x64addr, data, transmit_options=0)[source]
Blocking method. This method sends data to a remote XBee with the given 64-bit address.
This method waits for the packet response. The default timeout is
XBeeDevice._DEFAULT_TIMEOUT_SYNC_OPERATIONS.- Parameters:
x64addr (
XBee64BitAddress) – 64-bit address of the destination XBee.data (String or Bytearray) – Raw data to send.
transmit_options (Integer, optional) – Transmit options, bitfield of
TransmitOptions. Default to TransmitOptions.NONE.value.
- Returns:
The response.
- Return type:
- Raises:
ValueError – If x64addr or data is None.
TimeoutException – If response is not received before the read timeout expires.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
TransmitException – If the status of the response received is not OK.
XBeeException – If the XBee’s communication interface is closed.
See also
- send_data_async_64(x64addr, data, transmit_options=0)[source]
Non-blocking method. This method sends data to a remote XBee with the given 64-bit address.
This method does not wait for a response.
- Parameters:
x64addr (
XBee64BitAddress) – 64-bit address of the destination XBee.data (String or Bytearray) – Raw data to send.
transmit_options (Integer, optional) – Transmit options, bitfield of
TransmitOptions. Default to TransmitOptions.NONE.value.
- Raises:
ValueError – If x64addr or data is None.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the XBee’s communication interface is closed.
See also
- send_data_16(x16addr, data, transmit_options=0)[source]
Blocking method. This method sends data to a remote XBee with the given 16-bit address.
This method will wait for the packet response. The default timeout is
XBeeDevice._DEFAULT_TIMEOUT_SYNC_OPERATIONS.- Parameters:
x16addr (
XBee16BitAddress) – 16-bit address of the destination XBee.data (String or Bytearray) – Raw data to send.
transmit_options (Integer, optional) – Transmit options, bitfield of
TransmitOptions. Default to TransmitOptions.NONE.value.
- Returns:
The response.
- Return type:
- Raises:
ValueError – If x16addr or data is None.
TimeoutException – If response is not received before the read timeout expires.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
TransmitException – If the status of the response received is not OK.
XBeeException – If the XBee’s communication interface is closed.
See also
- send_data_async_16(x16addr, data, transmit_options=0)[source]
Non-blocking method. This method sends data to a remote XBee with the given 16-bit address.
This method does not wait for a response.
- Parameters:
x16addr (
XBee16BitAddress) – 16-bit address of the destination XBee.data (String or Bytearray) – Raw data to send.
transmit_options (Integer, optional) – Transmit options, bitfield of
TransmitOptions. Default to TransmitOptions.NONE.value.
- Raises:
ValueError – If x16addr or data is None.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the XBee’s communication interface is closed.
See also
- TIMEOUT_READ_PACKET = 3
Timeout to read packets.
- add_bluetooth_data_received_callback(callback)
Adds a callback for the event
BluetoothDataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The Bluetooth data as a Bytearray.
- add_data_received_callback(callback)
Adds a callback for the event
DataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The data received as an
XBeeMessage.
- add_expl_data_received_callback(callback)
Adds a callback for the event
ExplicitDataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The explicit data received as a
ExplicitXBeeMessage.
- add_fs_frame_received_callback(callback)
Adds a callback for the event
FileSystemFrameReceived.- Parameters:
callback (Function) –
The callback. Receives four arguments.
Source (
AbstractXBeeDevice): The node that sent the file system frame.Frame id (Integer): The received frame id.
Command (
FSCmd): The file system command.Receive options (Integer): Bitfield indicating receive options.
See also
- add_io_sample_received_callback(callback)
Adds a callback for the event
IOSampleReceived.- Parameters:
callback (Function) –
The callback. Receives three arguments.
The received IO sample as an
IOSample.The remote XBee which sent the packet as a
RemoteXBeeDevice.The time in which the packet was received as an Integer.
- add_micropython_data_received_callback(callback)
Adds a callback for the event
MicroPythonDataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The MicroPython data as a Bytearray.
- add_modem_status_received_callback(callback)
Adds a callback for the event
ModemStatusReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The modem status as a
ModemStatus.
- add_packet_received_callback(callback)
Adds a callback for the event
PacketReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The received packet as a
XBeeAPIPacket.
- add_route_received_callback(callback)
Adds a callback for the event
RouteReceived. This works for Zigbee and Digimesh devices.- Parameters:
callback (Function) –
The callback. Receives three arguments.
source (
XBeeDevice): The source node.destination (
RemoteXBeeDevice): The destination node.- hops (List): List of intermediate hops from closest to source
to closest to destination (
RemoteXBeeDevice).
- add_socket_data_received_callback(callback)
Adds a callback for the event
SocketDataReceived.- Parameters:
callback (Function) –
The callback. Receives two arguments.
The socket ID as an Integer.
The data received as Bytearray.
- add_socket_data_received_from_callback(callback)
Adds a callback for the event
SocketDataReceivedFrom.- Parameters:
callback (Function) –
The callback. Receives three arguments.
The socket ID as an Integer.
- Source address pair (host, port) where host is a string
representing an IPv4 address like ‘100.50.200.5’, and port is an integer.
The data received as Bytearray.
- add_socket_state_received_callback(callback)
Adds a callback for the event
SocketStateReceived.- Parameters:
callback (Function) –
The callback. Receives two arguments.
The socket ID as an Integer.
The state received as a
SocketState.
- add_user_data_relay_received_callback(callback)
Adds a callback for the event
RelayDataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The relay data as a
UserDataRelayMessage.
- apply_changes()
Applies changes via ‘AC’ command.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- apply_profile(profile_path, timeout=None, progress_callback=None)
Applies the given XBee profile to the XBee.
- Parameters:
profile_path (String) – Path of the XBee profile file to apply.
timeout (Integer, optional, default=`None`) – Maximum time to wait for target read operations during the apply profile (seconds).
progress_callback (Function, optional, default=`None`) –
Function 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 XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
UpdateProfileException – If there is any error applying the XBee profile.
- property br
Returns the BR value of the device.
- Returns:
The BR value of the device.
- Return type:
Integer
- close()
Closes the communication with the XBee.
This method guarantees that all threads running are stopped and the serial port is closed.
- property comm_iface
Returns the hardware interface associated to the XBee.
- Returns:
Hardware interface of the XBee.
- Return type:
See also
- classmethod create_xbee_device(comm_port_data)
Creates and returns an
XBeeDevicefrom data of the port to which is connected.- Parameters:
comm_port_data (Dictionary) – Dictionary with all comm port data needed.
are (The dictionary keys) –
“baudRate” –> Baud rate.”port” –> Port number.”bitSize” –> Bit size.”stopBits” –> Stop bits.”parity” –> Parity.”flowControl” –> Flow control.”timeout” for –> Timeout for synchronous operations (in seconds).
- Returns:
XBee object created.
- Return type:
- Raises:
SerialException – If the port to open does not exist or is already opened.
See also
- del_bluetooth_data_received_callback(callback)
Deletes a callback for the callback list of
BluetoothDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_data_received_callback(callback)
Deletes a callback for the callback list of
DataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_expl_data_received_callback(callback)
Deletes a callback for the callback list of
ExplicitDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_fs_frame_received_callback(callback)
Deletes a callback for the callback list of
FileSystemFrameReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_io_sample_received_callback(callback)
Deletes a callback for the callback list of
IOSampleReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_micropython_data_received_callback(callback)
Deletes a callback for the callback list of
MicroPythonDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_modem_status_received_callback(callback)
Deletes a callback for the callback list of
ModemStatusReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_packet_received_callback(callback)
Deletes a callback for the callback list of
PacketReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_route_received_callback(callback)
Deletes a callback for the callback list of
RouteReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_socket_data_received_callback(callback)
Deletes a callback for the callback list of
SocketDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_socket_data_received_from_callback(callback)
Deletes a callback for the callback list of
SocketDataReceivedFromevent.- Parameters:
callback (Function) – The callback to delete.
- del_socket_state_received_callback(callback)
Deletes a callback for the callback list of
SocketStateReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_user_data_relay_received_callback(callback)
Deletes a callback for the callback list of
RelayDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- determine_protocol(hardware_version, firmware_version)
Determines the XBee protocol based on the given hardware and firmware versions.
- Parameters:
hardware_version (Integer) – Hardware version to get its protocol.
firmware_version (Bytearray) – Firmware version to get its protocol.
- Returns:
- XBee protocol corresponding to the given
hardware and firmware versions.
- Return type:
- disable_bluetooth()
Disables the Bluetooth interface of this XBee.
Note that your device must include Bluetooth Low Energy support.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- enable_apply_changes(value)
Sets apply changes flag.
- Parameters:
value (Boolean) – True to enable apply changes flag, False to disable it.
- enable_bluetooth()
Enables the Bluetooth interface of this XBee.
To work with this interface, you must also configure the Bluetooth password if not done previously. Use method
AbstractXBeeDevice.update_bluetooth_password().Note that your XBee must include Bluetooth Low Energy support.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- execute_command(parameter, value=None, apply=None)
Executes the provided command.
- Parameters:
or (parameter (String) – class: .ATStringCommand): AT command to execute.
value (bytearray, optional, default=`None`) – Command value (if any).
apply (Boolean, optional, default=`None`) – True to apply changes in XBee configuration, False not to apply them, None to use is_apply_changes_enabled() returned value.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- flush_queues()
Flushes the packets queue.
- get_16bit_addr()
Returns the 16-bit address of the XBee.
- Returns:
16-bit address of the XBee.
- Return type:
See also
- get_64bit_addr()
Returns the 64-bit address of the XBee.
- Returns:
64-bit address of the XBee.
- Return type:
See also
- get_adc_value(io_line)
Returns the analog value of the provided IO line.
The provided IO line must be previously configured as ADC. To do so, use
AbstractXBeeDevice.set_io_configuration()andIOMode.ADC.- Parameters:
io_line (
IOLine) – IO line to get its ADC value.- Returns:
Analog value corresponding to the provided IO line.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If response does not contain the value for the given IO line.
See also
- get_api_output_mode()
Deprecated since version 1.3: Use
get_api_output_mode_value()Returns the API output mode of the XBee.
The API output mode determines the format of the data through the serial interface of the XBee.
- Returns:
API output mode of the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_api_output_mode_value()
Returns the API output mode of the XBee.
The API output mode determines the format that the received data is output through the serial interface of the XBee.
- Returns:
the parameter value.
- Return type:
Bytearray
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
- get_bluetooth_mac_addr()
Reads and returns the EUI-48 Bluetooth MAC address of this XBee following the format 00112233AABB.
Note that your device must include Bluetooth Low Energy support.
- Returns:
The Bluetooth MAC address.
- Return type:
String
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- get_current_frame_id()
Returns the last used frame ID.
- Returns:
Last used frame ID.
- Return type:
Integer
- get_dest_address()
Returns the 64-bit address of the XBee that is data destination.
- Returns:
64-bit address of destination XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_dio_value(io_line)
Returns the digital value of the provided IO line.
The provided IO line must be previously configured as digital I/O. To do so, use
AbstractXBeeDevice.set_io_configuration().- Parameters:
io_line (
IOLine) – the DIO line to gets its digital value.- Returns:
current value of the provided IO line.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If response does not contain the value for the given IO line.
See also
- get_file_manager()
Returns the file system manager for the XBee.
- Returns:
The file system manager.
- Return type:
- Raises:
FileSystemNotSupportedException – If the XBee does not support filesystem.
- get_firmware_version()
Returns the firmware version of the XBee.
- Returns:
Firmware version of the XBee.
- Return type:
Bytearray
- get_hardware_version()
Returns the hardware version of the XBee.
- Returns:
Hardware version of the XBee.
- Return type:
See also
- get_io_configuration(io_line)
Returns the configuration of the provided IO line.
- Parameters:
io_line (
IOLine) – IO line to get its configuration.- Returns:
IO mode of the IO line provided.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_io_sampling_rate()
Returns the IO sampling rate of the XBee.
- Returns:
IO sampling rate of XBee.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_network()
Returns the network of this XBee.
- Returns:
The XBee network.
- Return type:
- get_next_frame_id()
Returns the next frame ID of the XBee.
- Returns:
The next frame ID of the XBee.
- Return type:
Integer
- get_node_id()
Returns the node identifier (‘NI’) value of the XBee.
- Returns:
Node identifier (‘NI’) of the XBee.
- Return type:
String
- get_pan_id()
Returns the operating PAN ID of the XBee.
- Returns:
Operating PAN ID of the XBee.
- Return type:
Bytearray
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_parameter(parameter, parameter_value=None, apply=None)
Override.
See also
- get_power_level()
Returns the power level of the XBee.
- Returns:
Power level of the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_pwm_duty_cycle(io_line)
Returns the PWM duty cycle in % corresponding to the provided IO line.
- Parameters:
io_line (
IOLine) – IO line to get its PWM duty cycle.- Returns:
PWM duty cycle of the given IO line.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If io_line has no PWM capability.
See also
- get_route_to_node(remote, timeout=10, force=True)
Gets the route from this XBee to the given remote node.
- For Zigbee:
‘AR’ parameter of the local node must be configured with a value different from ‘FF’.
Set force to True to force the Zigbee remote node to return its route independently of the local node configuration as high or low RAM concentrator (‘DO’ of the local value)
- Parameters:
remote (
RemoteXBeeDevice) – The remote node.timeout (Float, optional, default=10) – Maximum number of seconds to wait for the route.
force (Boolean) – True to force asking for the route, False otherwise. Only for Zigbee.
- Returns:
- Tuple containing route data:
status (
TransmitStatus): The transmit status.Tuple with route data (None if the route was not read in the provided timeout):
source (
RemoteXBeeDevice): The source node of the route.destination (
RemoteXBeeDevice): The destination node of the route.hops (List): List of intermediate nodes (
RemoteXBeeDevice) ordered from closest to source to closest to destination node (source and destination not included).
- Return type:
Tuple
- get_sync_ops_timeout()
Returns the serial port read timeout.
- Returns:
Serial port read timeout in seconds.
- Return type:
Integer
- get_xbee_device_callbacks()
Returns this XBee internal callbacks for process received packets.
This method is called by the PacketListener associated with this XBee to get its callbacks. These callbacks are executed before user callbacks.
- Returns:
- has_explicit_packets()
Returns if there are pending explicit packets to read. This does not include non-explicit packets.
- Returns:
True if there are pending packets, False otherwise.
- Return type:
Boolean
See also
- has_packets()
Returns if there are pending packets to read. This does not include explicit packets.
- Returns:
True if there are pending packets, False otherwise.
- Return type:
Boolean
See also
- is_apply_changes_enabled()
Returns whether apply changes flag is enabled.
- Returns:
True if apply changes flag is enabled, False otherwise.
- Return type:
Boolean
- is_device_info_complete()
Returns whether XBee node information is complete.
- Returns:
True if node information is complete, False otherwise.
- Return type:
Boolean
- is_open()
Returns whether this XBee is open.
- Returns:
Boolean. True if this XBee is open, False otherwise.
- is_remote()
Override method.
See also
- property log
Returns the XBee logger.
- Returns:
The XBee device logger.
- Return type:
Logger
- property operating_mode
Returns the operating mode of this XBee.
- Returns:
OperatingMode. This XBee operating mode.
- property reachable
Returns whether the XBee is reachable.
- Returns:
True if the device is reachable, False otherwise.
- Return type:
Boolean
- read_data(timeout=None)
Reads new data received by this XBee.
If timeout is specified, this method blocks until new data is received or the timeout expires, throwing a
TimeoutExceptionin this case.- Parameters:
timeout (Integer, optional) – Read timeout in seconds. If None, this method is non-blocking and returns None if no data is available.
- Returns:
- Read message or None if this XBee did not
receive new data.
- Return type:
- Raises:
ValueError – If a timeout is specified and is less than 0.
TimeoutException – If a timeout is specified and no data was received during that time.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the XBee’s communication interface is closed.
See also
- read_data_from(remote_xbee, timeout=None)
Reads new data received from the given remote XBee.
If timeout is specified, this method blocks until new data is received or the timeout expires, throwing a
TimeoutExceptionin this case.- Parameters:
remote_xbee (
RemoteXBeeDevice) – Remote XBee that sent the data.timeout (Integer, optional) – Read timeout in seconds. If None, this method is non-blocking and returns None if no data is available.
- Returns:
- Read message sent by remote_xbee or None
if this XBee did not receive new data.
- Return type:
- Raises:
ValueError – If a timeout is specified and is less than 0.
TimeoutException – If a timeout is specified and no data was received during that time.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the XBee’s communication interface is closed.
See also
- read_device_info(init=True, fire_event=True)
Updates all instance parameters reading them from the XBee.
- Parameters:
init (Boolean, optional, default=`True`) – If False only not initialized parameters are read, all if True.
fire_event (Boolean, optional, default=`True`) – True to throw and update event if any parameter changed, False otherwise.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- read_expl_data(timeout=None)
Reads new explicit data received by this XBee.
If timeout is specified, this method blocks until new data is received or the timeout expires, throwing a
TimeoutExceptionin this case.- Parameters:
timeout (Integer, optional) – Read timeout in seconds. If None, this method is non-blocking and returns None if there is no explicit data available.
- Returns:
- Read message or None if this XBee
did not receive new explicit data.
- Return type:
- Raises:
ValueError – If a timeout is specified and is less than 0.
TimeoutException – If a timeout is specified and no explicit data was received during that time.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the XBee’s communication interface is closed.
See also
- read_expl_data_from(remote_xbee, timeout=None)
Reads new explicit data received from the given remote XBee.
If timeout is specified, this method blocks until new data is received or the timeout expires, throwing a
TimeoutExceptionin this case.- Parameters:
remote_xbee (
RemoteXBeeDevice) – Remote XBee that sent the explicit data.timeout (Integer, optional) – Read timeout in seconds. If None, this method is non-blocking and returns None if there is no data available.
- Returns:
- Read message sent by remote_xbee
or None if this XBee did not receive new data from that node.
- Return type:
- Raises:
ValueError – If a timeout is specified and is less than 0.
TimeoutException – If a timeout is specified and no explicit data was received during that time.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the XBee’s communication interface is closed.
See also
- read_io_sample()
Returns an IO sample from the XBee containing the value of all enabled digital IO and analog input channels.
- Returns:
IO sample read from the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- reset()
Override method.
See also
- property scan_counter
Returns the scan counter for this node.
- Returns:
The scan counter for this node.
- Return type:
Integer
- send_bluetooth_data(data)
Sends the given data to the Bluetooth interface using a User Data Relay frame.
- Parameters:
data (Bytearray) – Data to send.
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If there is any problem sending the data.
- send_data(remote_xbee, data, transmit_options=0)
Blocking method. This method sends data to a remote XBee synchronously.
This method will wait for the packet response. The default timeout is
XBeeDevice._DEFAULT_TIMEOUT_SYNC_OPERATIONS.- Parameters:
remote_xbee (
RemoteXBeeDevice) – Remote XBee to send data to.data (String or Bytearray) – Raw data to send.
transmit_options (Integer, optional) – Transmit options, bitfield of
TransmitOptions. Default to TransmitOptions.NONE.value.
- Returns:
The response.
- Return type:
- Raises:
ValueError – If remote_xbee is None.
TimeoutException – If response is not received before the read timeout expires.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
TransmitException – If the status of the response received is not OK.
XBeeException – If the XBee’s communication interface is closed.
See also
- send_data_async(remote_xbee, data, transmit_options=0)
Non-blocking method. This method sends data to a remote XBee.
This method does not wait for a response.
- Parameters:
remote_xbee (
RemoteXBeeDevice) – the remote XBee to send data to.data (String or Bytearray) – Raw data to send.
transmit_options (Integer, optional) – Transmit options, bitfield of
TransmitOptions. Default to TransmitOptions.NONE.value.
- Raises:
ValueError – If remote_xbee is None.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the XBee’s communication interface is closed.
See also
- send_data_broadcast(data, transmit_options=0)
Sends the provided data to all the XBee nodes of the network (broadcast).
This method blocks until a success or error transmit status arrives or the configured receive timeout expires.
The received timeout is configured using method
AbstractXBeeDevice.set_sync_ops_timeout()and can be consulted withAbstractXBeeDevice.get_sync_ops_timeout()method.- Parameters:
data (String or Bytearray) – Data to send.
transmit_options (Integer, optional) – Transmit options, bitfield of
TransmitOptions. Default to TransmitOptions.NONE.value.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
TransmitException – If the status of the response received is not OK.
XBeeException – If the XBee’s communication interface is closed.
- send_expl_data(remote_xbee, data, src_endpoint, dest_endpoint, cluster_id, profile_id, transmit_options=0)
Blocking method. Sends the provided explicit data to the given XBee, source and destination end points, cluster and profile ids.
This method blocks until a success or error response arrives or the configured receive timeout expires. The default timeout is
XBeeDevice._DEFAULT_TIMEOUT_SYNC_OPERATIONS.- Parameters:
remote_xbee (
RemoteXBeeDevice) – Remote XBee to send data to.data (String or Bytearray) – Raw data to send.
src_endpoint (Integer) – Source endpoint of the transmission. 1 byte.
dest_endpoint (Integer) – Destination endpoint of the transmission. 1 byte.
cluster_id (Integer) – Cluster ID of the transmission (between 0x0 and 0xFFFF)
profile_id (Integer) – Profile ID of the transmission (between 0x0 and 0xFFFF)
transmit_options (Integer, optional) – Transmit options, bitfield of
TransmitOptions. Default to TransmitOptions.NONE.value.
- Returns:
Response packet obtained after sending data.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
TransmitException – If the status of the response received is not OK.
XBeeException – If the XBee’s communication interface is closed.
ValueError – if cluster_id or profile_id is less than 0x0 or greater than 0xFFFF.
See also
- send_expl_data_async(remote_xbee, data, src_endpoint, dest_endpoint, cluster_id, profile_id, transmit_options=0)
Non-blocking method. Sends the provided explicit data to the given XBee, source and destination end points, cluster and profile ids.
- Parameters:
remote_xbee (
RemoteXBeeDevice) – Remote XBee to send data to.data (String or Bytearray) – Raw data to send.
src_endpoint (Integer) – Source endpoint of the transmission. 1 byte.
dest_endpoint (Integer) – Destination endpoint of the transmission. 1 byte.
cluster_id (Integer) – Cluster ID of the transmission (between 0x0 and 0xFFFF)
profile_id (Integer) – Profile ID of the transmission (between 0x0 and 0xFFFF)
transmit_options (Integer, optional) – Transmit options, bitfield of
TransmitOptions. Default to TransmitOptions.NONE.value.
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the XBee’s communication interface is closed.
ValueError – if cluster_id or profile_id is less than 0x0 or greater than 0xFFFF.
See also
- send_expl_data_broadcast(data, src_endpoint, dest_endpoint, cluster_id, profile_id, transmit_options=0)
Sends the provided explicit data to all the XBee nodes of the network (broadcast) using provided source and destination end points, cluster and profile ids.
This method blocks until a success or error transmit status arrives or the configured receive timeout expires. The received timeout is configured using the
AbstractXBeeDevice.set_sync_ops_timeout()method and can be consulted with methodAbstractXBeeDevice.get_sync_ops_timeout().- Parameters:
data (String or Bytearray) – Raw data to send.
src_endpoint (Integer) – Source endpoint of the transmission. 1 byte.
dest_endpoint (Integer) – Destination endpoint of the transmission. 1 byte.
cluster_id (Integer) – Cluster ID of the transmission (between 0x0 and 0xFFFF)
profile_id (Integer) – Profile ID of the transmission (between 0x0 and 0xFFFF)
transmit_options (Integer, optional) – Transmit options, bitfield of
TransmitOptions. Default to TransmitOptions.NONE.value.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
TransmitException – If the status of the response received is not OK.
XBeeException – If the XBee’s communication interface is closed.
ValueError – if cluster_id or profile_id is less than 0x0 or greater than 0xFFFF.
See also
XBeeDevice._send_expl_data()
- send_micropython_data(data)
Sends the given data to the MicroPython interface using a User Data Relay frame.
- Parameters:
data (Bytearray) – Data to send.
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If there is any problem sending the data.
- send_packet(packet, sync=False)
Sends the packet and waits for the response. The packet to send is escaped depending on the current operating mode.
This method can be synchronous or asynchronous.
If synchronous, this method discards all response packets until it finds the one that has the appropriate frame ID, that is, the sent packet’s frame ID.
If asynchronous, this method does not wait for any response and returns None.
- Parameters:
packet (
XBeePacket) – The packet to send.sync (Boolean) – True to wait for the response of the sent packet and return it, False otherwise.
- Returns:
- Response packet if sync is True, None
otherwise.
- Return type:
- Raises:
TimeoutException – If sync is True and the response packet for the sent one cannot be read.
InvalidOperatingModeException – If the XBee operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the packet listener is not running or the XBee’s communication interface is closed.
See also
- send_packet_sync_and_get_response(packet_to_send, timeout=None)
Sends the packet and waits for its corresponding response.
- Parameters:
packet_to_send (
XBeePacket) – The packet to transmit.timeout (Integer, optional, default=`None`) – Number of seconds to wait. -1 to wait indefinitely.
- Returns:
Received response packet.
- Return type:
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
TimeoutException – If response is not received in the configured timeout.
XBeeException – If the XBee’s communication interface is closed.
See also
- send_user_data_relay(local_interface, data)
Sends the given data to the given XBee local interface.
- Parameters:
local_interface (
XBeeLocalInterface) – Destination XBee local interface.data (Bytearray) – Data to send.
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ValueError – If local_interface is None.
XBeeException – If there is any problem sending the User Data Relay.
See also
- property serial_port
Returns the serial port associated to the XBee, if any.
- Returns:
- Serial port of the XBee. None if the
local XBee does not use serial communication.
- Return type:
See also
- set_16bit_addr(value)
Sets the 16-bit address of the XBee.
- Parameters:
value (
XBee16BitAddress) – New 16-bit address of the XBee.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If the protocol is not 802.15.4.
- set_api_output_mode(api_output_mode)
Deprecated since version 1.3: Use
set_api_output_mode_value()Sets the API output mode of the XBee.
- Parameters:
api_output_mode (
APIOutputMode) – New API output mode.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
See also
- set_api_output_mode_value(api_output_mode)
Sets the API output mode of the XBee.
- Parameters:
api_output_mode (Integer) – New API output mode options. Calculate this value using the method
APIOutputModeBit.calculate_api_output_mode_value()with a set ofAPIOutputModeBit.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
See also
- set_dest_address(addr)
Sets the 64-bit address of the XBee that is data destination.
- Parameters:
addr (
XBee64BitAddressorRemoteXBeeDevice) – Address itself or remote XBee to be data destination.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If addr is None.
See also
- set_dio_change_detection(io_lines_set)
Sets the digital IO lines to be monitored and sampled whenever their status changes. A None set of lines disables this feature.
- Parameters:
io_lines_set – Set of
IOLine.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_dio_value(io_line, io_value)
Sets the digital value (high or low) to the provided IO line.
- Parameters:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- set_io_configuration(io_line, io_mode)
Sets the configuration of the provided IO line.
- Parameters:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_io_sampling_rate(rate)
Sets the IO sampling rate of the XBee in seconds. A sample rate of 0 means the IO sampling feature is disabled.
- Parameters:
rate (Integer) – New IO sampling rate of the XBee in seconds.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_node_id(node_id)
Sets the node identifier (‘NI`) value of the XBee.
- Parameters:
node_id (String) – New node identifier (‘NI’) of the XBee.
- Raises:
ValueError – If node_id is None or its length is greater than 20.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- set_pan_id(value)
Sets the operating PAN ID of the XBee.
- Parameters:
value (Bytearray) – New operating PAN ID of the XBee. Must have only 1 or 2 bytes.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_parameter(parameter, value, apply=None)
Override.
- set_power_level(power_level)
Sets the power level of the XBee.
- Parameters:
power_level (
PowerLevel) – New power level of the XBee.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_pwm_duty_cycle(io_line, cycle)
Sets the duty cycle in % of the provided IO line.
The provided IO line must be PWM-capable, previously configured as PWM output.
- Parameters:
io_line (
IOLine) – IO Line to be assigned.cycle (Integer) – Duty cycle in % to be assigned. Must be between 0 and 100.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If the given IO line does not have PWM capability or cycle is not between 0 and 100.
See also
- set_sync_ops_timeout(sync_ops_timeout)
Sets the serial port read timeout.
- Parameters:
sync_ops_timeout (Integer) – Read timeout in seconds.
- property stats
Gets the statistics for this XBee.
- Returns:
Statistics. XBee statistics.
- update_bluetooth_password(new_password, apply=True, save=True)
Changes the Bluetooth password of this XBee with the new one provided.
Note that your device must include Bluetooth Low Energy support.
- Parameters:
new_password (String) – New Bluetooth password.
apply (Boolean, optional, default=`True`) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
save (Boolean, optional, default=`True`) – True to save changes, False otherwise.
- Raises:
ValueError – If new_password is invalid.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- update_bluetooth_salt_verifier(salt, verifier, apply=True, save=True)
Changes the Bluetooth password of this XBee with the new one provided.
Note that your device must include Bluetooth Low Energy support.
- Parameters:
salt (bytes) – New Bluetooth password.
verifier (bytes) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
apply (Boolean, optional, default=`True`) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
save (Boolean, optional, default=`True`) – True to save changes, False otherwise.
- Raises:
ValueError – If salt or verifier are invalid.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- update_device_data_from(device)
Updates the current node information with provided data. This is only for internal use.
- Parameters:
device (
AbstractXBeeDevice) – XBee to get the data from.- Returns:
True if the node data has been updated, False otherwise.
- Return type:
Boolean
- update_firmware(xml_firmware_file, xbee_firmware_file=None, bootloader_firmware_file=None, timeout=None, progress_callback=None)
Performs a firmware update operation of the XBee.
- Parameters:
xml_firmware_file (String) – Path of the XML file that describes the firmware to upload.
xbee_firmware_file (String, optional, default=`None`) – Location of the XBee binary firmware file.
bootloader_firmware_file (String, optional, default=`None`) – Location of the bootloader binary firmware file.
timeout (Integer, optional, default=`None`) – Maximum time to wait for target read operations during the update process (seconds).
progress_callback (Function, optional, default=`None`) –
Function to 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 XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
OperationNotSupportedException – If XBee does not support firmware update.
FirmwareUpdateException – If there is any error during the firmware update.
- write_changes()
Writes configurable parameter values to the non-volatile memory of the XBee so that parameter modifications persist through subsequent resets.
Parameters values remain in the device’s memory until overwritten by subsequent use of this method.
If changes are made without writing them, the XBee reverts back to previously saved parameters the next time the module is powered-on.
Writing the parameter modifications does not mean those values are immediately applied, this depends on the status of the ‘apply configuration changes’ option. Use method
is_apply_changes_enabled()to get its status andenable_apply_changes()to enable/disable the option. Methodapply_changes()can be used in order to manually apply the changes.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- class digi.xbee.devices.DigiMeshDevice(port=None, baud_rate=None, data_bits=serial.EIGHTBITS, stop_bits=serial.STOPBITS_ONE, parity=serial.PARITY_NONE, flow_control=FlowControl.NONE, _sync_ops_timeout=4, comm_iface=None)[source]
Bases:
XBeeDeviceThis class represents a local DigiMesh XBee.
Class constructor. Instantiates a new
DigiMeshDevicewith the provided parameters.- Parameters:
port (String) – serial port identifier. Depends on operating system. e.g. ‘/dev/ttyUSB0’ on ‘GNU/Linux’ or ‘COM3’ on Windows.
baud_rate (Integer) – Serial port baud rate.
(Integer (flow_control) –
serial.EIGHTBITS): Port bitsize.default –
serial.EIGHTBITS): Port bitsize.(Integer –
serial.STOPBITS_ONE): Port stop bits.default –
serial.STOPBITS_ONE): Port stop bits.(Character (parity) –
serial.PARITY_NONE): Port parity.default –
serial.PARITY_NONE): Port parity.(Integer –
FlowControl.NONE): port flow control.default –
FlowControl.NONE): port flow control.- _sync_ops_timeout (Integer, default: 3): Read timeout (in seconds).
comm_iface (
XBeeCommunicationInterface): Communication interface.
:raises All exceptions raised by
XBeeDevice.__init__()constructor.:See also
XBeeDevice.__init__()- build_aggregate_routes()[source]
Forces all nodes in the network to automatically build routes to this node. The receiving node establishes a route back to this node.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- send_data_64(x64addr, data, transmit_options=0)[source]
Blocking method. This method sends data to a remote XBee with the given 64-bit address.
This method waits for the packet response. The default timeout is
XBeeDevice._DEFAULT_TIMEOUT_SYNC_OPERATIONS.- Parameters:
x64addr (
XBee64BitAddress) – 64-bit address of the destination XBee.data (String or Bytearray) – Raw data to send.
transmit_options (Integer, optional) – Transmit options, bitfield of
TransmitOptions. Default to TransmitOptions.NONE.value.
- Returns:
The response.
- Return type:
- Raises:
ValueError – If x64addr or data is None.
TimeoutException – If response is not received before the read timeout expires.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
TransmitException – If the status of the response received is not OK.
XBeeException – If the XBee’s communication interface is closed.
See also
- send_data_async_64(x64addr, data, transmit_options=0)[source]
Non-blocking method. This method sends data to a remote XBee with the given 64-bit address.
This method does not wait for a response.
- Parameters:
x64addr (
XBee64BitAddress) – 64-bit address of the destination XBee.data (String or Bytearray) – Raw data to send.
transmit_options (Integer, optional) – Transmit options, bitfield of
TransmitOptions. Default to TransmitOptions.NONE.value.
- Raises:
ValueError – If x64addr or data is None.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the XBee’s communication interface is closed.
See also
- get_neighbors(neighbor_cb=None, finished_cb=None, timeout=None)[source]
Returns the neighbors of this XBee. If neighbor_cb is not defined, the process blocks during the specified timeout.
- Parameters:
neighbor_cb (Function, optional, default=`None`) –
Method called when a new neighbor is received. Receives two arguments:
The XBee that owns this new neighbor.
The new neighbor.
finished_cb (Function, optional, default=`None`) –
Method to execute when the process finishes. Receives two arguments:
The XBee that is searching for its neighbors.
A list with the discovered neighbors.
An error message if something went wrong.
timeout (Float, optional, default=`NeighborFinder.DEFAULT_TIMEOUT`) – The timeout in seconds.
- Returns:
- List of
Neighborwhen neighbor_cb is not defined, None otherwise (in this case neighbors are received in the callback).
- List of
- Return type:
List
- Raises:
OperationNotSupportedException – If XBee protocol is not DigiMesh.
See also
com.digi.models.zdo.Neighbor
- TIMEOUT_READ_PACKET = 3
Timeout to read packets.
- add_bluetooth_data_received_callback(callback)
Adds a callback for the event
BluetoothDataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The Bluetooth data as a Bytearray.
- add_data_received_callback(callback)
Adds a callback for the event
DataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The data received as an
XBeeMessage.
- add_expl_data_received_callback(callback)
Adds a callback for the event
ExplicitDataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The explicit data received as a
ExplicitXBeeMessage.
- add_fs_frame_received_callback(callback)
Adds a callback for the event
FileSystemFrameReceived.- Parameters:
callback (Function) –
The callback. Receives four arguments.
Source (
AbstractXBeeDevice): The node that sent the file system frame.Frame id (Integer): The received frame id.
Command (
FSCmd): The file system command.Receive options (Integer): Bitfield indicating receive options.
See also
- add_io_sample_received_callback(callback)
Adds a callback for the event
IOSampleReceived.- Parameters:
callback (Function) –
The callback. Receives three arguments.
The received IO sample as an
IOSample.The remote XBee which sent the packet as a
RemoteXBeeDevice.The time in which the packet was received as an Integer.
- add_micropython_data_received_callback(callback)
Adds a callback for the event
MicroPythonDataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The MicroPython data as a Bytearray.
- add_modem_status_received_callback(callback)
Adds a callback for the event
ModemStatusReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The modem status as a
ModemStatus.
- add_packet_received_callback(callback)
Adds a callback for the event
PacketReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The received packet as a
XBeeAPIPacket.
- add_route_received_callback(callback)
Adds a callback for the event
RouteReceived. This works for Zigbee and Digimesh devices.- Parameters:
callback (Function) –
The callback. Receives three arguments.
source (
XBeeDevice): The source node.destination (
RemoteXBeeDevice): The destination node.- hops (List): List of intermediate hops from closest to source
to closest to destination (
RemoteXBeeDevice).
- add_socket_data_received_callback(callback)
Adds a callback for the event
SocketDataReceived.- Parameters:
callback (Function) –
The callback. Receives two arguments.
The socket ID as an Integer.
The data received as Bytearray.
- add_socket_data_received_from_callback(callback)
Adds a callback for the event
SocketDataReceivedFrom.- Parameters:
callback (Function) –
The callback. Receives three arguments.
The socket ID as an Integer.
- Source address pair (host, port) where host is a string
representing an IPv4 address like ‘100.50.200.5’, and port is an integer.
The data received as Bytearray.
- add_socket_state_received_callback(callback)
Adds a callback for the event
SocketStateReceived.- Parameters:
callback (Function) –
The callback. Receives two arguments.
The socket ID as an Integer.
The state received as a
SocketState.
- add_user_data_relay_received_callback(callback)
Adds a callback for the event
RelayDataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The relay data as a
UserDataRelayMessage.
- apply_changes()
Applies changes via ‘AC’ command.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- apply_profile(profile_path, timeout=None, progress_callback=None)
Applies the given XBee profile to the XBee.
- Parameters:
profile_path (String) – Path of the XBee profile file to apply.
timeout (Integer, optional, default=`None`) – Maximum time to wait for target read operations during the apply profile (seconds).
progress_callback (Function, optional, default=`None`) –
Function 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 XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
UpdateProfileException – If there is any error applying the XBee profile.
- property br
Returns the BR value of the device.
- Returns:
The BR value of the device.
- Return type:
Integer
- close()
Closes the communication with the XBee.
This method guarantees that all threads running are stopped and the serial port is closed.
- property comm_iface
Returns the hardware interface associated to the XBee.
- Returns:
Hardware interface of the XBee.
- Return type:
See also
- classmethod create_xbee_device(comm_port_data)
Creates and returns an
XBeeDevicefrom data of the port to which is connected.- Parameters:
comm_port_data (Dictionary) – Dictionary with all comm port data needed.
are (The dictionary keys) –
“baudRate” –> Baud rate.”port” –> Port number.”bitSize” –> Bit size.”stopBits” –> Stop bits.”parity” –> Parity.”flowControl” –> Flow control.”timeout” for –> Timeout for synchronous operations (in seconds).
- Returns:
XBee object created.
- Return type:
- Raises:
SerialException – If the port to open does not exist or is already opened.
See also
- del_bluetooth_data_received_callback(callback)
Deletes a callback for the callback list of
BluetoothDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_data_received_callback(callback)
Deletes a callback for the callback list of
DataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_expl_data_received_callback(callback)
Deletes a callback for the callback list of
ExplicitDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_fs_frame_received_callback(callback)
Deletes a callback for the callback list of
FileSystemFrameReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_io_sample_received_callback(callback)
Deletes a callback for the callback list of
IOSampleReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_micropython_data_received_callback(callback)
Deletes a callback for the callback list of
MicroPythonDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_modem_status_received_callback(callback)
Deletes a callback for the callback list of
ModemStatusReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_packet_received_callback(callback)
Deletes a callback for the callback list of
PacketReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_route_received_callback(callback)
Deletes a callback for the callback list of
RouteReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_socket_data_received_callback(callback)
Deletes a callback for the callback list of
SocketDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_socket_data_received_from_callback(callback)
Deletes a callback for the callback list of
SocketDataReceivedFromevent.- Parameters:
callback (Function) – The callback to delete.
- del_socket_state_received_callback(callback)
Deletes a callback for the callback list of
SocketStateReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_user_data_relay_received_callback(callback)
Deletes a callback for the callback list of
RelayDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- determine_protocol(hardware_version, firmware_version)
Determines the XBee protocol based on the given hardware and firmware versions.
- Parameters:
hardware_version (Integer) – Hardware version to get its protocol.
firmware_version (Bytearray) – Firmware version to get its protocol.
- Returns:
- XBee protocol corresponding to the given
hardware and firmware versions.
- Return type:
- disable_bluetooth()
Disables the Bluetooth interface of this XBee.
Note that your device must include Bluetooth Low Energy support.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- enable_apply_changes(value)
Sets apply changes flag.
- Parameters:
value (Boolean) – True to enable apply changes flag, False to disable it.
- enable_bluetooth()
Enables the Bluetooth interface of this XBee.
To work with this interface, you must also configure the Bluetooth password if not done previously. Use method
AbstractXBeeDevice.update_bluetooth_password().Note that your XBee must include Bluetooth Low Energy support.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- execute_command(parameter, value=None, apply=None)
Executes the provided command.
- Parameters:
or (parameter (String) – class: .ATStringCommand): AT command to execute.
value (bytearray, optional, default=`None`) – Command value (if any).
apply (Boolean, optional, default=`None`) – True to apply changes in XBee configuration, False not to apply them, None to use is_apply_changes_enabled() returned value.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- flush_queues()
Flushes the packets queue.
- get_16bit_addr()
Returns the 16-bit address of the XBee.
- Returns:
16-bit address of the XBee.
- Return type:
See also
- get_64bit_addr()
Returns the 64-bit address of the XBee.
- Returns:
64-bit address of the XBee.
- Return type:
See also
- get_adc_value(io_line)
Returns the analog value of the provided IO line.
The provided IO line must be previously configured as ADC. To do so, use
AbstractXBeeDevice.set_io_configuration()andIOMode.ADC.- Parameters:
io_line (
IOLine) – IO line to get its ADC value.- Returns:
Analog value corresponding to the provided IO line.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If response does not contain the value for the given IO line.
See also
- get_api_output_mode()
Deprecated since version 1.3: Use
get_api_output_mode_value()Returns the API output mode of the XBee.
The API output mode determines the format of the data through the serial interface of the XBee.
- Returns:
API output mode of the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_api_output_mode_value()
Returns the API output mode of the XBee.
The API output mode determines the format that the received data is output through the serial interface of the XBee.
- Returns:
the parameter value.
- Return type:
Bytearray
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
- get_bluetooth_mac_addr()
Reads and returns the EUI-48 Bluetooth MAC address of this XBee following the format 00112233AABB.
Note that your device must include Bluetooth Low Energy support.
- Returns:
The Bluetooth MAC address.
- Return type:
String
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- get_current_frame_id()
Returns the last used frame ID.
- Returns:
Last used frame ID.
- Return type:
Integer
- get_dest_address()
Returns the 64-bit address of the XBee that is data destination.
- Returns:
64-bit address of destination XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_dio_value(io_line)
Returns the digital value of the provided IO line.
The provided IO line must be previously configured as digital I/O. To do so, use
AbstractXBeeDevice.set_io_configuration().- Parameters:
io_line (
IOLine) – the DIO line to gets its digital value.- Returns:
current value of the provided IO line.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If response does not contain the value for the given IO line.
See also
- get_file_manager()
Returns the file system manager for the XBee.
- Returns:
The file system manager.
- Return type:
- Raises:
FileSystemNotSupportedException – If the XBee does not support filesystem.
- get_firmware_version()
Returns the firmware version of the XBee.
- Returns:
Firmware version of the XBee.
- Return type:
Bytearray
- get_hardware_version()
Returns the hardware version of the XBee.
- Returns:
Hardware version of the XBee.
- Return type:
See also
- get_io_configuration(io_line)
Returns the configuration of the provided IO line.
- Parameters:
io_line (
IOLine) – IO line to get its configuration.- Returns:
IO mode of the IO line provided.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_io_sampling_rate()
Returns the IO sampling rate of the XBee.
- Returns:
IO sampling rate of XBee.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_network()
Returns the network of this XBee.
- Returns:
The XBee network.
- Return type:
- get_next_frame_id()
Returns the next frame ID of the XBee.
- Returns:
The next frame ID of the XBee.
- Return type:
Integer
- get_node_id()
Returns the node identifier (‘NI’) value of the XBee.
- Returns:
Node identifier (‘NI’) of the XBee.
- Return type:
String
- get_pan_id()
Returns the operating PAN ID of the XBee.
- Returns:
Operating PAN ID of the XBee.
- Return type:
Bytearray
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_parameter(parameter, parameter_value=None, apply=None)
Override.
See also
- get_power_level()
Returns the power level of the XBee.
- Returns:
Power level of the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_pwm_duty_cycle(io_line)
Returns the PWM duty cycle in % corresponding to the provided IO line.
- Parameters:
io_line (
IOLine) – IO line to get its PWM duty cycle.- Returns:
PWM duty cycle of the given IO line.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If io_line has no PWM capability.
See also
- get_route_to_node(remote, timeout=10, force=True)
Gets the route from this XBee to the given remote node.
- For Zigbee:
‘AR’ parameter of the local node must be configured with a value different from ‘FF’.
Set force to True to force the Zigbee remote node to return its route independently of the local node configuration as high or low RAM concentrator (‘DO’ of the local value)
- Parameters:
remote (
RemoteXBeeDevice) – The remote node.timeout (Float, optional, default=10) – Maximum number of seconds to wait for the route.
force (Boolean) – True to force asking for the route, False otherwise. Only for Zigbee.
- Returns:
- Tuple containing route data:
status (
TransmitStatus): The transmit status.Tuple with route data (None if the route was not read in the provided timeout):
source (
RemoteXBeeDevice): The source node of the route.destination (
RemoteXBeeDevice): The destination node of the route.hops (List): List of intermediate nodes (
RemoteXBeeDevice) ordered from closest to source to closest to destination node (source and destination not included).
- Return type:
Tuple
- get_sync_ops_timeout()
Returns the serial port read timeout.
- Returns:
Serial port read timeout in seconds.
- Return type:
Integer
- get_xbee_device_callbacks()
Returns this XBee internal callbacks for process received packets.
This method is called by the PacketListener associated with this XBee to get its callbacks. These callbacks are executed before user callbacks.
- Returns:
- has_explicit_packets()
Returns if there are pending explicit packets to read. This does not include non-explicit packets.
- Returns:
True if there are pending packets, False otherwise.
- Return type:
Boolean
See also
- has_packets()
Returns if there are pending packets to read. This does not include explicit packets.
- Returns:
True if there are pending packets, False otherwise.
- Return type:
Boolean
See also
- is_apply_changes_enabled()
Returns whether apply changes flag is enabled.
- Returns:
True if apply changes flag is enabled, False otherwise.
- Return type:
Boolean
- is_device_info_complete()
Returns whether XBee node information is complete.
- Returns:
True if node information is complete, False otherwise.
- Return type:
Boolean
- is_open()
Returns whether this XBee is open.
- Returns:
Boolean. True if this XBee is open, False otherwise.
- is_remote()
Override method.
See also
- property log
Returns the XBee logger.
- Returns:
The XBee device logger.
- Return type:
Logger
- property operating_mode
Returns the operating mode of this XBee.
- Returns:
OperatingMode. This XBee operating mode.
- property reachable
Returns whether the XBee is reachable.
- Returns:
True if the device is reachable, False otherwise.
- Return type:
Boolean
- read_data(timeout=None)
Reads new data received by this XBee.
If timeout is specified, this method blocks until new data is received or the timeout expires, throwing a
TimeoutExceptionin this case.- Parameters:
timeout (Integer, optional) – Read timeout in seconds. If None, this method is non-blocking and returns None if no data is available.
- Returns:
- Read message or None if this XBee did not
receive new data.
- Return type:
- Raises:
ValueError – If a timeout is specified and is less than 0.
TimeoutException – If a timeout is specified and no data was received during that time.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the XBee’s communication interface is closed.
See also
- read_data_from(remote_xbee, timeout=None)
Reads new data received from the given remote XBee.
If timeout is specified, this method blocks until new data is received or the timeout expires, throwing a
TimeoutExceptionin this case.- Parameters:
remote_xbee (
RemoteXBeeDevice) – Remote XBee that sent the data.timeout (Integer, optional) – Read timeout in seconds. If None, this method is non-blocking and returns None if no data is available.
- Returns:
- Read message sent by remote_xbee or None
if this XBee did not receive new data.
- Return type:
- Raises:
ValueError – If a timeout is specified and is less than 0.
TimeoutException – If a timeout is specified and no data was received during that time.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the XBee’s communication interface is closed.
See also
- read_device_info(init=True, fire_event=True)
Updates all instance parameters reading them from the XBee.
- Parameters:
init (Boolean, optional, default=`True`) – If False only not initialized parameters are read, all if True.
fire_event (Boolean, optional, default=`True`) – True to throw and update event if any parameter changed, False otherwise.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- read_expl_data(timeout=None)
Reads new explicit data received by this XBee.
If timeout is specified, this method blocks until new data is received or the timeout expires, throwing a
TimeoutExceptionin this case.- Parameters:
timeout (Integer, optional) – Read timeout in seconds. If None, this method is non-blocking and returns None if there is no explicit data available.
- Returns:
- Read message or None if this XBee
did not receive new explicit data.
- Return type:
- Raises:
ValueError – If a timeout is specified and is less than 0.
TimeoutException – If a timeout is specified and no explicit data was received during that time.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the XBee’s communication interface is closed.
See also
- read_expl_data_from(remote_xbee, timeout=None)
Reads new explicit data received from the given remote XBee.
If timeout is specified, this method blocks until new data is received or the timeout expires, throwing a
TimeoutExceptionin this case.- Parameters:
remote_xbee (
RemoteXBeeDevice) – Remote XBee that sent the explicit data.timeout (Integer, optional) – Read timeout in seconds. If None, this method is non-blocking and returns None if there is no data available.
- Returns:
- Read message sent by remote_xbee
or None if this XBee did not receive new data from that node.
- Return type:
- Raises:
ValueError – If a timeout is specified and is less than 0.
TimeoutException – If a timeout is specified and no explicit data was received during that time.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the XBee’s communication interface is closed.
See also
- read_io_sample()
Returns an IO sample from the XBee containing the value of all enabled digital IO and analog input channels.
- Returns:
IO sample read from the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- reset()
Override method.
See also
- property scan_counter
Returns the scan counter for this node.
- Returns:
The scan counter for this node.
- Return type:
Integer
- send_bluetooth_data(data)
Sends the given data to the Bluetooth interface using a User Data Relay frame.
- Parameters:
data (Bytearray) – Data to send.
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If there is any problem sending the data.
- send_data(remote_xbee, data, transmit_options=0)
Blocking method. This method sends data to a remote XBee synchronously.
This method will wait for the packet response. The default timeout is
XBeeDevice._DEFAULT_TIMEOUT_SYNC_OPERATIONS.- Parameters:
remote_xbee (
RemoteXBeeDevice) – Remote XBee to send data to.data (String or Bytearray) – Raw data to send.
transmit_options (Integer, optional) – Transmit options, bitfield of
TransmitOptions. Default to TransmitOptions.NONE.value.
- Returns:
The response.
- Return type:
- Raises:
ValueError – If remote_xbee is None.
TimeoutException – If response is not received before the read timeout expires.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
TransmitException – If the status of the response received is not OK.
XBeeException – If the XBee’s communication interface is closed.
See also
- send_data_async(remote_xbee, data, transmit_options=0)
Non-blocking method. This method sends data to a remote XBee.
This method does not wait for a response.
- Parameters:
remote_xbee (
RemoteXBeeDevice) – the remote XBee to send data to.data (String or Bytearray) – Raw data to send.
transmit_options (Integer, optional) – Transmit options, bitfield of
TransmitOptions. Default to TransmitOptions.NONE.value.
- Raises:
ValueError – If remote_xbee is None.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the XBee’s communication interface is closed.
See also
- send_data_broadcast(data, transmit_options=0)
Sends the provided data to all the XBee nodes of the network (broadcast).
This method blocks until a success or error transmit status arrives or the configured receive timeout expires.
The received timeout is configured using method
AbstractXBeeDevice.set_sync_ops_timeout()and can be consulted withAbstractXBeeDevice.get_sync_ops_timeout()method.- Parameters:
data (String or Bytearray) – Data to send.
transmit_options (Integer, optional) – Transmit options, bitfield of
TransmitOptions. Default to TransmitOptions.NONE.value.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
TransmitException – If the status of the response received is not OK.
XBeeException – If the XBee’s communication interface is closed.
- send_expl_data(remote_xbee, data, src_endpoint, dest_endpoint, cluster_id, profile_id, transmit_options=0)
Blocking method. Sends the provided explicit data to the given XBee, source and destination end points, cluster and profile ids.
This method blocks until a success or error response arrives or the configured receive timeout expires. The default timeout is
XBeeDevice._DEFAULT_TIMEOUT_SYNC_OPERATIONS.- Parameters:
remote_xbee (
RemoteXBeeDevice) – Remote XBee to send data to.data (String or Bytearray) – Raw data to send.
src_endpoint (Integer) – Source endpoint of the transmission. 1 byte.
dest_endpoint (Integer) – Destination endpoint of the transmission. 1 byte.
cluster_id (Integer) – Cluster ID of the transmission (between 0x0 and 0xFFFF)
profile_id (Integer) – Profile ID of the transmission (between 0x0 and 0xFFFF)
transmit_options (Integer, optional) – Transmit options, bitfield of
TransmitOptions. Default to TransmitOptions.NONE.value.
- Returns:
Response packet obtained after sending data.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
TransmitException – If the status of the response received is not OK.
XBeeException – If the XBee’s communication interface is closed.
ValueError – if cluster_id or profile_id is less than 0x0 or greater than 0xFFFF.
See also
- send_expl_data_async(remote_xbee, data, src_endpoint, dest_endpoint, cluster_id, profile_id, transmit_options=0)
Non-blocking method. Sends the provided explicit data to the given XBee, source and destination end points, cluster and profile ids.
- Parameters:
remote_xbee (
RemoteXBeeDevice) – Remote XBee to send data to.data (String or Bytearray) – Raw data to send.
src_endpoint (Integer) – Source endpoint of the transmission. 1 byte.
dest_endpoint (Integer) – Destination endpoint of the transmission. 1 byte.
cluster_id (Integer) – Cluster ID of the transmission (between 0x0 and 0xFFFF)
profile_id (Integer) – Profile ID of the transmission (between 0x0 and 0xFFFF)
transmit_options (Integer, optional) – Transmit options, bitfield of
TransmitOptions. Default to TransmitOptions.NONE.value.
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the XBee’s communication interface is closed.
ValueError – if cluster_id or profile_id is less than 0x0 or greater than 0xFFFF.
See also
- send_expl_data_broadcast(data, src_endpoint, dest_endpoint, cluster_id, profile_id, transmit_options=0)
Sends the provided explicit data to all the XBee nodes of the network (broadcast) using provided source and destination end points, cluster and profile ids.
This method blocks until a success or error transmit status arrives or the configured receive timeout expires. The received timeout is configured using the
AbstractXBeeDevice.set_sync_ops_timeout()method and can be consulted with methodAbstractXBeeDevice.get_sync_ops_timeout().- Parameters:
data (String or Bytearray) – Raw data to send.
src_endpoint (Integer) – Source endpoint of the transmission. 1 byte.
dest_endpoint (Integer) – Destination endpoint of the transmission. 1 byte.
cluster_id (Integer) – Cluster ID of the transmission (between 0x0 and 0xFFFF)
profile_id (Integer) – Profile ID of the transmission (between 0x0 and 0xFFFF)
transmit_options (Integer, optional) – Transmit options, bitfield of
TransmitOptions. Default to TransmitOptions.NONE.value.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
TransmitException – If the status of the response received is not OK.
XBeeException – If the XBee’s communication interface is closed.
ValueError – if cluster_id or profile_id is less than 0x0 or greater than 0xFFFF.
See also
XBeeDevice._send_expl_data()
- send_micropython_data(data)
Sends the given data to the MicroPython interface using a User Data Relay frame.
- Parameters:
data (Bytearray) – Data to send.
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If there is any problem sending the data.
- send_packet(packet, sync=False)
Sends the packet and waits for the response. The packet to send is escaped depending on the current operating mode.
This method can be synchronous or asynchronous.
If synchronous, this method discards all response packets until it finds the one that has the appropriate frame ID, that is, the sent packet’s frame ID.
If asynchronous, this method does not wait for any response and returns None.
- Parameters:
packet (
XBeePacket) – The packet to send.sync (Boolean) – True to wait for the response of the sent packet and return it, False otherwise.
- Returns:
- Response packet if sync is True, None
otherwise.
- Return type:
- Raises:
TimeoutException – If sync is True and the response packet for the sent one cannot be read.
InvalidOperatingModeException – If the XBee operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the packet listener is not running or the XBee’s communication interface is closed.
See also
- send_packet_sync_and_get_response(packet_to_send, timeout=None)
Sends the packet and waits for its corresponding response.
- Parameters:
packet_to_send (
XBeePacket) – The packet to transmit.timeout (Integer, optional, default=`None`) – Number of seconds to wait. -1 to wait indefinitely.
- Returns:
Received response packet.
- Return type:
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
TimeoutException – If response is not received in the configured timeout.
XBeeException – If the XBee’s communication interface is closed.
See also
- send_user_data_relay(local_interface, data)
Sends the given data to the given XBee local interface.
- Parameters:
local_interface (
XBeeLocalInterface) – Destination XBee local interface.data (Bytearray) – Data to send.
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ValueError – If local_interface is None.
XBeeException – If there is any problem sending the User Data Relay.
See also
- property serial_port
Returns the serial port associated to the XBee, if any.
- Returns:
- Serial port of the XBee. None if the
local XBee does not use serial communication.
- Return type:
See also
- set_16bit_addr(value)
Sets the 16-bit address of the XBee.
- Parameters:
value (
XBee16BitAddress) – New 16-bit address of the XBee.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If the protocol is not 802.15.4.
- set_api_output_mode(api_output_mode)
Deprecated since version 1.3: Use
set_api_output_mode_value()Sets the API output mode of the XBee.
- Parameters:
api_output_mode (
APIOutputMode) – New API output mode.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
See also
- set_api_output_mode_value(api_output_mode)
Sets the API output mode of the XBee.
- Parameters:
api_output_mode (Integer) – New API output mode options. Calculate this value using the method
APIOutputModeBit.calculate_api_output_mode_value()with a set ofAPIOutputModeBit.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
See also
- set_dest_address(addr)
Sets the 64-bit address of the XBee that is data destination.
- Parameters:
addr (
XBee64BitAddressorRemoteXBeeDevice) – Address itself or remote XBee to be data destination.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If addr is None.
See also
- set_dio_change_detection(io_lines_set)
Sets the digital IO lines to be monitored and sampled whenever their status changes. A None set of lines disables this feature.
- Parameters:
io_lines_set – Set of
IOLine.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_dio_value(io_line, io_value)
Sets the digital value (high or low) to the provided IO line.
- Parameters:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- set_io_configuration(io_line, io_mode)
Sets the configuration of the provided IO line.
- Parameters:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_io_sampling_rate(rate)
Sets the IO sampling rate of the XBee in seconds. A sample rate of 0 means the IO sampling feature is disabled.
- Parameters:
rate (Integer) – New IO sampling rate of the XBee in seconds.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_node_id(node_id)
Sets the node identifier (‘NI`) value of the XBee.
- Parameters:
node_id (String) – New node identifier (‘NI’) of the XBee.
- Raises:
ValueError – If node_id is None or its length is greater than 20.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- set_pan_id(value)
Sets the operating PAN ID of the XBee.
- Parameters:
value (Bytearray) – New operating PAN ID of the XBee. Must have only 1 or 2 bytes.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_parameter(parameter, value, apply=None)
Override.
- set_power_level(power_level)
Sets the power level of the XBee.
- Parameters:
power_level (
PowerLevel) – New power level of the XBee.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_pwm_duty_cycle(io_line, cycle)
Sets the duty cycle in % of the provided IO line.
The provided IO line must be PWM-capable, previously configured as PWM output.
- Parameters:
io_line (
IOLine) – IO Line to be assigned.cycle (Integer) – Duty cycle in % to be assigned. Must be between 0 and 100.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If the given IO line does not have PWM capability or cycle is not between 0 and 100.
See also
- set_sync_ops_timeout(sync_ops_timeout)
Sets the serial port read timeout.
- Parameters:
sync_ops_timeout (Integer) – Read timeout in seconds.
- property stats
Gets the statistics for this XBee.
- Returns:
Statistics. XBee statistics.
- update_bluetooth_password(new_password, apply=True, save=True)
Changes the Bluetooth password of this XBee with the new one provided.
Note that your device must include Bluetooth Low Energy support.
- Parameters:
new_password (String) – New Bluetooth password.
apply (Boolean, optional, default=`True`) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
save (Boolean, optional, default=`True`) – True to save changes, False otherwise.
- Raises:
ValueError – If new_password is invalid.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- update_bluetooth_salt_verifier(salt, verifier, apply=True, save=True)
Changes the Bluetooth password of this XBee with the new one provided.
Note that your device must include Bluetooth Low Energy support.
- Parameters:
salt (bytes) – New Bluetooth password.
verifier (bytes) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
apply (Boolean, optional, default=`True`) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
save (Boolean, optional, default=`True`) – True to save changes, False otherwise.
- Raises:
ValueError – If salt or verifier are invalid.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- update_device_data_from(device)
Updates the current node information with provided data. This is only for internal use.
- Parameters:
device (
AbstractXBeeDevice) – XBee to get the data from.- Returns:
True if the node data has been updated, False otherwise.
- Return type:
Boolean
- update_firmware(xml_firmware_file, xbee_firmware_file=None, bootloader_firmware_file=None, timeout=None, progress_callback=None)
Performs a firmware update operation of the XBee.
- Parameters:
xml_firmware_file (String) – Path of the XML file that describes the firmware to upload.
xbee_firmware_file (String, optional, default=`None`) – Location of the XBee binary firmware file.
bootloader_firmware_file (String, optional, default=`None`) – Location of the bootloader binary firmware file.
timeout (Integer, optional, default=`None`) – Maximum time to wait for target read operations during the update process (seconds).
progress_callback (Function, optional, default=`None`) –
Function to 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 XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
OperationNotSupportedException – If XBee does not support firmware update.
FirmwareUpdateException – If there is any error during the firmware update.
- write_changes()
Writes configurable parameter values to the non-volatile memory of the XBee so that parameter modifications persist through subsequent resets.
Parameters values remain in the device’s memory until overwritten by subsequent use of this method.
If changes are made without writing them, the XBee reverts back to previously saved parameters the next time the module is powered-on.
Writing the parameter modifications does not mean those values are immediately applied, this depends on the status of the ‘apply configuration changes’ option. Use method
is_apply_changes_enabled()to get its status andenable_apply_changes()to enable/disable the option. Methodapply_changes()can be used in order to manually apply the changes.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- class digi.xbee.devices.DigiPointDevice(port=None, baud_rate=None, data_bits=serial.EIGHTBITS, stop_bits=serial.STOPBITS_ONE, parity=serial.PARITY_NONE, flow_control=FlowControl.NONE, _sync_ops_timeout=4, comm_iface=None)[source]
Bases:
XBeeDeviceThis class represents a local DigiPoint XBee.
Class constructor. Instantiates a new
DigiPointDevicewith the provided parameters.- Parameters:
port (String) – Serial port identifier. Depends on operating system. e.g. ‘/dev/ttyUSB0’ on ‘GNU/Linux’ or ‘COM3’ on Windows.
baud_rate (Integer) – Serial port baud rate.
(Integer (_sync_ops_timeout) –
serial.EIGHTBITS): Port bitsize.default –
serial.EIGHTBITS): Port bitsize.(Integer –
serial.STOPBITS_ONE): Port stop bits.default –
serial.STOPBITS_ONE): Port stop bits.(Character (parity) –
serial.PARITY_NONE): Port parity.default –
serial.PARITY_NONE): Port parity.(Integer –
FlowControl.NONE): Port flow control.default –
FlowControl.NONE): Port flow control.(Integer – 3): Read timeout (in seconds).
default – 3): Read timeout (in seconds).
comm_iface (
XBeeCommunicationInterface) – Communication interface.
:raises All exceptions raised by
XBeeDevice.__init__()constructor.:See also
XBeeDevice.__init__()- send_data_64_16(x64addr, x16addr, data, transmit_options=0)[source]
Blocking method. This method sends data to the remote XBee with the given 64-bit/16-bit address.
This method waits for the packet response. The default timeout is
XBeeDevice._DEFAULT_TIMEOUT_SYNC_OPERATIONS.- Parameters:
x64addr (
XBee64BitAddress) – 64-bit address of the destination XBee.x16addr (
XBee16BitAddress) – 16-bit address of the destination XBee,XBee16BitAddress.UNKNOWN_ADDRESSif unknown.data (String or Bytearray) – Raw data to send.
transmit_options (Integer, optional) – Transmit options, bitfield of
TransmitOptions. Default to TransmitOptions.NONE.value.
- Returns:
The response.
- Return type:
- Raises:
ValueError – If x64addr, x16addr or data is None.
TimeoutException – If response is not received before the read timeout expires.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
TransmitException – If the status of the response received is not OK.
XBeeException – If the XBee’s communication interface is closed.
See also
- send_data_async_64_16(x64addr, x16addr, data, transmit_options=0)[source]
Non-blocking method. This method sends data to a remote XBee with the given 64-bit/16-bit address.
This method does not wait for a response.
- Parameters:
x64addr (
XBee64BitAddress) – 64-bit address of the destination XBee.x16addr (
XBee16BitAddress) – 16-bit address of the destination XBee,XBee16BitAddress.UNKNOWN_ADDRESSif unknown.data (String or Bytearray) – Raw data to send.
transmit_options (Integer, optional) – Transmit options, bitfield of
TransmitOptions. Default to TransmitOptions.NONE.value.
- Raises:
ValueError – If x64addr, x16addr or data is None.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the XBee’s communication interface is closed.
See also
- TIMEOUT_READ_PACKET = 3
Timeout to read packets.
- add_bluetooth_data_received_callback(callback)
Adds a callback for the event
BluetoothDataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The Bluetooth data as a Bytearray.
- add_data_received_callback(callback)
Adds a callback for the event
DataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The data received as an
XBeeMessage.
- add_expl_data_received_callback(callback)
Adds a callback for the event
ExplicitDataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The explicit data received as a
ExplicitXBeeMessage.
- add_fs_frame_received_callback(callback)
Adds a callback for the event
FileSystemFrameReceived.- Parameters:
callback (Function) –
The callback. Receives four arguments.
Source (
AbstractXBeeDevice): The node that sent the file system frame.Frame id (Integer): The received frame id.
Command (
FSCmd): The file system command.Receive options (Integer): Bitfield indicating receive options.
See also
- add_io_sample_received_callback(callback)
Adds a callback for the event
IOSampleReceived.- Parameters:
callback (Function) –
The callback. Receives three arguments.
The received IO sample as an
IOSample.The remote XBee which sent the packet as a
RemoteXBeeDevice.The time in which the packet was received as an Integer.
- add_micropython_data_received_callback(callback)
Adds a callback for the event
MicroPythonDataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The MicroPython data as a Bytearray.
- add_modem_status_received_callback(callback)
Adds a callback for the event
ModemStatusReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The modem status as a
ModemStatus.
- add_packet_received_callback(callback)
Adds a callback for the event
PacketReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The received packet as a
XBeeAPIPacket.
- add_route_received_callback(callback)
Adds a callback for the event
RouteReceived. This works for Zigbee and Digimesh devices.- Parameters:
callback (Function) –
The callback. Receives three arguments.
source (
XBeeDevice): The source node.destination (
RemoteXBeeDevice): The destination node.- hops (List): List of intermediate hops from closest to source
to closest to destination (
RemoteXBeeDevice).
- add_socket_data_received_callback(callback)
Adds a callback for the event
SocketDataReceived.- Parameters:
callback (Function) –
The callback. Receives two arguments.
The socket ID as an Integer.
The data received as Bytearray.
- add_socket_data_received_from_callback(callback)
Adds a callback for the event
SocketDataReceivedFrom.- Parameters:
callback (Function) –
The callback. Receives three arguments.
The socket ID as an Integer.
- Source address pair (host, port) where host is a string
representing an IPv4 address like ‘100.50.200.5’, and port is an integer.
The data received as Bytearray.
- add_socket_state_received_callback(callback)
Adds a callback for the event
SocketStateReceived.- Parameters:
callback (Function) –
The callback. Receives two arguments.
The socket ID as an Integer.
The state received as a
SocketState.
- add_user_data_relay_received_callback(callback)
Adds a callback for the event
RelayDataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The relay data as a
UserDataRelayMessage.
- apply_changes()
Applies changes via ‘AC’ command.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- apply_profile(profile_path, timeout=None, progress_callback=None)
Applies the given XBee profile to the XBee.
- Parameters:
profile_path (String) – Path of the XBee profile file to apply.
timeout (Integer, optional, default=`None`) – Maximum time to wait for target read operations during the apply profile (seconds).
progress_callback (Function, optional, default=`None`) –
Function 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 XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
UpdateProfileException – If there is any error applying the XBee profile.
- property br
Returns the BR value of the device.
- Returns:
The BR value of the device.
- Return type:
Integer
- close()
Closes the communication with the XBee.
This method guarantees that all threads running are stopped and the serial port is closed.
- property comm_iface
Returns the hardware interface associated to the XBee.
- Returns:
Hardware interface of the XBee.
- Return type:
See also
- classmethod create_xbee_device(comm_port_data)
Creates and returns an
XBeeDevicefrom data of the port to which is connected.- Parameters:
comm_port_data (Dictionary) – Dictionary with all comm port data needed.
are (The dictionary keys) –
“baudRate” –> Baud rate.”port” –> Port number.”bitSize” –> Bit size.”stopBits” –> Stop bits.”parity” –> Parity.”flowControl” –> Flow control.”timeout” for –> Timeout for synchronous operations (in seconds).
- Returns:
XBee object created.
- Return type:
- Raises:
SerialException – If the port to open does not exist or is already opened.
See also
- del_bluetooth_data_received_callback(callback)
Deletes a callback for the callback list of
BluetoothDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_data_received_callback(callback)
Deletes a callback for the callback list of
DataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_expl_data_received_callback(callback)
Deletes a callback for the callback list of
ExplicitDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_fs_frame_received_callback(callback)
Deletes a callback for the callback list of
FileSystemFrameReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_io_sample_received_callback(callback)
Deletes a callback for the callback list of
IOSampleReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_micropython_data_received_callback(callback)
Deletes a callback for the callback list of
MicroPythonDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_modem_status_received_callback(callback)
Deletes a callback for the callback list of
ModemStatusReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_packet_received_callback(callback)
Deletes a callback for the callback list of
PacketReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_route_received_callback(callback)
Deletes a callback for the callback list of
RouteReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_socket_data_received_callback(callback)
Deletes a callback for the callback list of
SocketDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_socket_data_received_from_callback(callback)
Deletes a callback for the callback list of
SocketDataReceivedFromevent.- Parameters:
callback (Function) – The callback to delete.
- del_socket_state_received_callback(callback)
Deletes a callback for the callback list of
SocketStateReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_user_data_relay_received_callback(callback)
Deletes a callback for the callback list of
RelayDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- determine_protocol(hardware_version, firmware_version)
Determines the XBee protocol based on the given hardware and firmware versions.
- Parameters:
hardware_version (Integer) – Hardware version to get its protocol.
firmware_version (Bytearray) – Firmware version to get its protocol.
- Returns:
- XBee protocol corresponding to the given
hardware and firmware versions.
- Return type:
- disable_bluetooth()
Disables the Bluetooth interface of this XBee.
Note that your device must include Bluetooth Low Energy support.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- enable_apply_changes(value)
Sets apply changes flag.
- Parameters:
value (Boolean) – True to enable apply changes flag, False to disable it.
- enable_bluetooth()
Enables the Bluetooth interface of this XBee.
To work with this interface, you must also configure the Bluetooth password if not done previously. Use method
AbstractXBeeDevice.update_bluetooth_password().Note that your XBee must include Bluetooth Low Energy support.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- execute_command(parameter, value=None, apply=None)
Executes the provided command.
- Parameters:
or (parameter (String) – class: .ATStringCommand): AT command to execute.
value (bytearray, optional, default=`None`) – Command value (if any).
apply (Boolean, optional, default=`None`) – True to apply changes in XBee configuration, False not to apply them, None to use is_apply_changes_enabled() returned value.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- flush_queues()
Flushes the packets queue.
- get_16bit_addr()
Returns the 16-bit address of the XBee.
- Returns:
16-bit address of the XBee.
- Return type:
See also
- get_64bit_addr()
Returns the 64-bit address of the XBee.
- Returns:
64-bit address of the XBee.
- Return type:
See also
- get_adc_value(io_line)
Returns the analog value of the provided IO line.
The provided IO line must be previously configured as ADC. To do so, use
AbstractXBeeDevice.set_io_configuration()andIOMode.ADC.- Parameters:
io_line (
IOLine) – IO line to get its ADC value.- Returns:
Analog value corresponding to the provided IO line.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If response does not contain the value for the given IO line.
See also
- get_api_output_mode()
Deprecated since version 1.3: Use
get_api_output_mode_value()Returns the API output mode of the XBee.
The API output mode determines the format of the data through the serial interface of the XBee.
- Returns:
API output mode of the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_api_output_mode_value()
Returns the API output mode of the XBee.
The API output mode determines the format that the received data is output through the serial interface of the XBee.
- Returns:
the parameter value.
- Return type:
Bytearray
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
- get_bluetooth_mac_addr()
Reads and returns the EUI-48 Bluetooth MAC address of this XBee following the format 00112233AABB.
Note that your device must include Bluetooth Low Energy support.
- Returns:
The Bluetooth MAC address.
- Return type:
String
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- get_current_frame_id()
Returns the last used frame ID.
- Returns:
Last used frame ID.
- Return type:
Integer
- get_dest_address()
Returns the 64-bit address of the XBee that is data destination.
- Returns:
64-bit address of destination XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_dio_value(io_line)
Returns the digital value of the provided IO line.
The provided IO line must be previously configured as digital I/O. To do so, use
AbstractXBeeDevice.set_io_configuration().- Parameters:
io_line (
IOLine) – the DIO line to gets its digital value.- Returns:
current value of the provided IO line.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If response does not contain the value for the given IO line.
See also
- get_file_manager()
Returns the file system manager for the XBee.
- Returns:
The file system manager.
- Return type:
- Raises:
FileSystemNotSupportedException – If the XBee does not support filesystem.
- get_firmware_version()
Returns the firmware version of the XBee.
- Returns:
Firmware version of the XBee.
- Return type:
Bytearray
- get_hardware_version()
Returns the hardware version of the XBee.
- Returns:
Hardware version of the XBee.
- Return type:
See also
- get_io_configuration(io_line)
Returns the configuration of the provided IO line.
- Parameters:
io_line (
IOLine) – IO line to get its configuration.- Returns:
IO mode of the IO line provided.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_io_sampling_rate()
Returns the IO sampling rate of the XBee.
- Returns:
IO sampling rate of XBee.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_network()
Returns the network of this XBee.
- Returns:
The XBee network.
- Return type:
- get_next_frame_id()
Returns the next frame ID of the XBee.
- Returns:
The next frame ID of the XBee.
- Return type:
Integer
- get_node_id()
Returns the node identifier (‘NI’) value of the XBee.
- Returns:
Node identifier (‘NI’) of the XBee.
- Return type:
String
- get_pan_id()
Returns the operating PAN ID of the XBee.
- Returns:
Operating PAN ID of the XBee.
- Return type:
Bytearray
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_parameter(parameter, parameter_value=None, apply=None)
Override.
See also
- get_power_level()
Returns the power level of the XBee.
- Returns:
Power level of the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_pwm_duty_cycle(io_line)
Returns the PWM duty cycle in % corresponding to the provided IO line.
- Parameters:
io_line (
IOLine) – IO line to get its PWM duty cycle.- Returns:
PWM duty cycle of the given IO line.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If io_line has no PWM capability.
See also
- get_route_to_node(remote, timeout=10, force=True)
Gets the route from this XBee to the given remote node.
- For Zigbee:
‘AR’ parameter of the local node must be configured with a value different from ‘FF’.
Set force to True to force the Zigbee remote node to return its route independently of the local node configuration as high or low RAM concentrator (‘DO’ of the local value)
- Parameters:
remote (
RemoteXBeeDevice) – The remote node.timeout (Float, optional, default=10) – Maximum number of seconds to wait for the route.
force (Boolean) – True to force asking for the route, False otherwise. Only for Zigbee.
- Returns:
- Tuple containing route data:
status (
TransmitStatus): The transmit status.Tuple with route data (None if the route was not read in the provided timeout):
source (
RemoteXBeeDevice): The source node of the route.destination (
RemoteXBeeDevice): The destination node of the route.hops (List): List of intermediate nodes (
RemoteXBeeDevice) ordered from closest to source to closest to destination node (source and destination not included).
- Return type:
Tuple
- get_sync_ops_timeout()
Returns the serial port read timeout.
- Returns:
Serial port read timeout in seconds.
- Return type:
Integer
- get_xbee_device_callbacks()
Returns this XBee internal callbacks for process received packets.
This method is called by the PacketListener associated with this XBee to get its callbacks. These callbacks are executed before user callbacks.
- Returns:
- has_explicit_packets()
Returns if there are pending explicit packets to read. This does not include non-explicit packets.
- Returns:
True if there are pending packets, False otherwise.
- Return type:
Boolean
See also
- has_packets()
Returns if there are pending packets to read. This does not include explicit packets.
- Returns:
True if there are pending packets, False otherwise.
- Return type:
Boolean
See also
- is_apply_changes_enabled()
Returns whether apply changes flag is enabled.
- Returns:
True if apply changes flag is enabled, False otherwise.
- Return type:
Boolean
- is_device_info_complete()
Returns whether XBee node information is complete.
- Returns:
True if node information is complete, False otherwise.
- Return type:
Boolean
- is_open()
Returns whether this XBee is open.
- Returns:
Boolean. True if this XBee is open, False otherwise.
- is_remote()
Override method.
See also
- property log
Returns the XBee logger.
- Returns:
The XBee device logger.
- Return type:
Logger
- property operating_mode
Returns the operating mode of this XBee.
- Returns:
OperatingMode. This XBee operating mode.
- property reachable
Returns whether the XBee is reachable.
- Returns:
True if the device is reachable, False otherwise.
- Return type:
Boolean
- read_data(timeout=None)
Reads new data received by this XBee.
If timeout is specified, this method blocks until new data is received or the timeout expires, throwing a
TimeoutExceptionin this case.- Parameters:
timeout (Integer, optional) – Read timeout in seconds. If None, this method is non-blocking and returns None if no data is available.
- Returns:
- Read message or None if this XBee did not
receive new data.
- Return type:
- Raises:
ValueError – If a timeout is specified and is less than 0.
TimeoutException – If a timeout is specified and no data was received during that time.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the XBee’s communication interface is closed.
See also
- read_data_from(remote_xbee, timeout=None)
Reads new data received from the given remote XBee.
If timeout is specified, this method blocks until new data is received or the timeout expires, throwing a
TimeoutExceptionin this case.- Parameters:
remote_xbee (
RemoteXBeeDevice) – Remote XBee that sent the data.timeout (Integer, optional) – Read timeout in seconds. If None, this method is non-blocking and returns None if no data is available.
- Returns:
- Read message sent by remote_xbee or None
if this XBee did not receive new data.
- Return type:
- Raises:
ValueError – If a timeout is specified and is less than 0.
TimeoutException – If a timeout is specified and no data was received during that time.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the XBee’s communication interface is closed.
See also
- read_device_info(init=True, fire_event=True)
Updates all instance parameters reading them from the XBee.
- Parameters:
init (Boolean, optional, default=`True`) – If False only not initialized parameters are read, all if True.
fire_event (Boolean, optional, default=`True`) – True to throw and update event if any parameter changed, False otherwise.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- read_expl_data(timeout=None)
Reads new explicit data received by this XBee.
If timeout is specified, this method blocks until new data is received or the timeout expires, throwing a
TimeoutExceptionin this case.- Parameters:
timeout (Integer, optional) – Read timeout in seconds. If None, this method is non-blocking and returns None if there is no explicit data available.
- Returns:
- Read message or None if this XBee
did not receive new explicit data.
- Return type:
- Raises:
ValueError – If a timeout is specified and is less than 0.
TimeoutException – If a timeout is specified and no explicit data was received during that time.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the XBee’s communication interface is closed.
See also
- read_expl_data_from(remote_xbee, timeout=None)
Reads new explicit data received from the given remote XBee.
If timeout is specified, this method blocks until new data is received or the timeout expires, throwing a
TimeoutExceptionin this case.- Parameters:
remote_xbee (
RemoteXBeeDevice) – Remote XBee that sent the explicit data.timeout (Integer, optional) – Read timeout in seconds. If None, this method is non-blocking and returns None if there is no data available.
- Returns:
- Read message sent by remote_xbee
or None if this XBee did not receive new data from that node.
- Return type:
- Raises:
ValueError – If a timeout is specified and is less than 0.
TimeoutException – If a timeout is specified and no explicit data was received during that time.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the XBee’s communication interface is closed.
See also
- read_io_sample()
Returns an IO sample from the XBee containing the value of all enabled digital IO and analog input channels.
- Returns:
IO sample read from the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- reset()
Override method.
See also
- property scan_counter
Returns the scan counter for this node.
- Returns:
The scan counter for this node.
- Return type:
Integer
- send_bluetooth_data(data)
Sends the given data to the Bluetooth interface using a User Data Relay frame.
- Parameters:
data (Bytearray) – Data to send.
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If there is any problem sending the data.
- send_data(remote_xbee, data, transmit_options=0)
Blocking method. This method sends data to a remote XBee synchronously.
This method will wait for the packet response. The default timeout is
XBeeDevice._DEFAULT_TIMEOUT_SYNC_OPERATIONS.- Parameters:
remote_xbee (
RemoteXBeeDevice) – Remote XBee to send data to.data (String or Bytearray) – Raw data to send.
transmit_options (Integer, optional) – Transmit options, bitfield of
TransmitOptions. Default to TransmitOptions.NONE.value.
- Returns:
The response.
- Return type:
- Raises:
ValueError – If remote_xbee is None.
TimeoutException – If response is not received before the read timeout expires.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
TransmitException – If the status of the response received is not OK.
XBeeException – If the XBee’s communication interface is closed.
See also
- send_data_async(remote_xbee, data, transmit_options=0)
Non-blocking method. This method sends data to a remote XBee.
This method does not wait for a response.
- Parameters:
remote_xbee (
RemoteXBeeDevice) – the remote XBee to send data to.data (String or Bytearray) – Raw data to send.
transmit_options (Integer, optional) – Transmit options, bitfield of
TransmitOptions. Default to TransmitOptions.NONE.value.
- Raises:
ValueError – If remote_xbee is None.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the XBee’s communication interface is closed.
See also
- send_data_broadcast(data, transmit_options=0)
Sends the provided data to all the XBee nodes of the network (broadcast).
This method blocks until a success or error transmit status arrives or the configured receive timeout expires.
The received timeout is configured using method
AbstractXBeeDevice.set_sync_ops_timeout()and can be consulted withAbstractXBeeDevice.get_sync_ops_timeout()method.- Parameters:
data (String or Bytearray) – Data to send.
transmit_options (Integer, optional) – Transmit options, bitfield of
TransmitOptions. Default to TransmitOptions.NONE.value.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
TransmitException – If the status of the response received is not OK.
XBeeException – If the XBee’s communication interface is closed.
- send_expl_data(remote_xbee, data, src_endpoint, dest_endpoint, cluster_id, profile_id, transmit_options=0)
Blocking method. Sends the provided explicit data to the given XBee, source and destination end points, cluster and profile ids.
This method blocks until a success or error response arrives or the configured receive timeout expires. The default timeout is
XBeeDevice._DEFAULT_TIMEOUT_SYNC_OPERATIONS.- Parameters:
remote_xbee (
RemoteXBeeDevice) – Remote XBee to send data to.data (String or Bytearray) – Raw data to send.
src_endpoint (Integer) – Source endpoint of the transmission. 1 byte.
dest_endpoint (Integer) – Destination endpoint of the transmission. 1 byte.
cluster_id (Integer) – Cluster ID of the transmission (between 0x0 and 0xFFFF)
profile_id (Integer) – Profile ID of the transmission (between 0x0 and 0xFFFF)
transmit_options (Integer, optional) – Transmit options, bitfield of
TransmitOptions. Default to TransmitOptions.NONE.value.
- Returns:
Response packet obtained after sending data.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
TransmitException – If the status of the response received is not OK.
XBeeException – If the XBee’s communication interface is closed.
ValueError – if cluster_id or profile_id is less than 0x0 or greater than 0xFFFF.
See also
- send_expl_data_async(remote_xbee, data, src_endpoint, dest_endpoint, cluster_id, profile_id, transmit_options=0)
Non-blocking method. Sends the provided explicit data to the given XBee, source and destination end points, cluster and profile ids.
- Parameters:
remote_xbee (
RemoteXBeeDevice) – Remote XBee to send data to.data (String or Bytearray) – Raw data to send.
src_endpoint (Integer) – Source endpoint of the transmission. 1 byte.
dest_endpoint (Integer) – Destination endpoint of the transmission. 1 byte.
cluster_id (Integer) – Cluster ID of the transmission (between 0x0 and 0xFFFF)
profile_id (Integer) – Profile ID of the transmission (between 0x0 and 0xFFFF)
transmit_options (Integer, optional) – Transmit options, bitfield of
TransmitOptions. Default to TransmitOptions.NONE.value.
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the XBee’s communication interface is closed.
ValueError – if cluster_id or profile_id is less than 0x0 or greater than 0xFFFF.
See also
- send_expl_data_broadcast(data, src_endpoint, dest_endpoint, cluster_id, profile_id, transmit_options=0)
Sends the provided explicit data to all the XBee nodes of the network (broadcast) using provided source and destination end points, cluster and profile ids.
This method blocks until a success or error transmit status arrives or the configured receive timeout expires. The received timeout is configured using the
AbstractXBeeDevice.set_sync_ops_timeout()method and can be consulted with methodAbstractXBeeDevice.get_sync_ops_timeout().- Parameters:
data (String or Bytearray) – Raw data to send.
src_endpoint (Integer) – Source endpoint of the transmission. 1 byte.
dest_endpoint (Integer) – Destination endpoint of the transmission. 1 byte.
cluster_id (Integer) – Cluster ID of the transmission (between 0x0 and 0xFFFF)
profile_id (Integer) – Profile ID of the transmission (between 0x0 and 0xFFFF)
transmit_options (Integer, optional) – Transmit options, bitfield of
TransmitOptions. Default to TransmitOptions.NONE.value.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
TransmitException – If the status of the response received is not OK.
XBeeException – If the XBee’s communication interface is closed.
ValueError – if cluster_id or profile_id is less than 0x0 or greater than 0xFFFF.
See also
XBeeDevice._send_expl_data()
- send_micropython_data(data)
Sends the given data to the MicroPython interface using a User Data Relay frame.
- Parameters:
data (Bytearray) – Data to send.
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If there is any problem sending the data.
- send_packet(packet, sync=False)
Sends the packet and waits for the response. The packet to send is escaped depending on the current operating mode.
This method can be synchronous or asynchronous.
If synchronous, this method discards all response packets until it finds the one that has the appropriate frame ID, that is, the sent packet’s frame ID.
If asynchronous, this method does not wait for any response and returns None.
- Parameters:
packet (
XBeePacket) – The packet to send.sync (Boolean) – True to wait for the response of the sent packet and return it, False otherwise.
- Returns:
- Response packet if sync is True, None
otherwise.
- Return type:
- Raises:
TimeoutException – If sync is True and the response packet for the sent one cannot be read.
InvalidOperatingModeException – If the XBee operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the packet listener is not running or the XBee’s communication interface is closed.
See also
- send_packet_sync_and_get_response(packet_to_send, timeout=None)
Sends the packet and waits for its corresponding response.
- Parameters:
packet_to_send (
XBeePacket) – The packet to transmit.timeout (Integer, optional, default=`None`) – Number of seconds to wait. -1 to wait indefinitely.
- Returns:
Received response packet.
- Return type:
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
TimeoutException – If response is not received in the configured timeout.
XBeeException – If the XBee’s communication interface is closed.
See also
- send_user_data_relay(local_interface, data)
Sends the given data to the given XBee local interface.
- Parameters:
local_interface (
XBeeLocalInterface) – Destination XBee local interface.data (Bytearray) – Data to send.
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ValueError – If local_interface is None.
XBeeException – If there is any problem sending the User Data Relay.
See also
- property serial_port
Returns the serial port associated to the XBee, if any.
- Returns:
- Serial port of the XBee. None if the
local XBee does not use serial communication.
- Return type:
See also
- set_16bit_addr(value)
Sets the 16-bit address of the XBee.
- Parameters:
value (
XBee16BitAddress) – New 16-bit address of the XBee.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If the protocol is not 802.15.4.
- set_api_output_mode(api_output_mode)
Deprecated since version 1.3: Use
set_api_output_mode_value()Sets the API output mode of the XBee.
- Parameters:
api_output_mode (
APIOutputMode) – New API output mode.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
See also
- set_api_output_mode_value(api_output_mode)
Sets the API output mode of the XBee.
- Parameters:
api_output_mode (Integer) – New API output mode options. Calculate this value using the method
APIOutputModeBit.calculate_api_output_mode_value()with a set ofAPIOutputModeBit.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
See also
- set_dest_address(addr)
Sets the 64-bit address of the XBee that is data destination.
- Parameters:
addr (
XBee64BitAddressorRemoteXBeeDevice) – Address itself or remote XBee to be data destination.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If addr is None.
See also
- set_dio_change_detection(io_lines_set)
Sets the digital IO lines to be monitored and sampled whenever their status changes. A None set of lines disables this feature.
- Parameters:
io_lines_set – Set of
IOLine.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_dio_value(io_line, io_value)
Sets the digital value (high or low) to the provided IO line.
- Parameters:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- set_io_configuration(io_line, io_mode)
Sets the configuration of the provided IO line.
- Parameters:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_io_sampling_rate(rate)
Sets the IO sampling rate of the XBee in seconds. A sample rate of 0 means the IO sampling feature is disabled.
- Parameters:
rate (Integer) – New IO sampling rate of the XBee in seconds.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_node_id(node_id)
Sets the node identifier (‘NI`) value of the XBee.
- Parameters:
node_id (String) – New node identifier (‘NI’) of the XBee.
- Raises:
ValueError – If node_id is None or its length is greater than 20.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- set_pan_id(value)
Sets the operating PAN ID of the XBee.
- Parameters:
value (Bytearray) – New operating PAN ID of the XBee. Must have only 1 or 2 bytes.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_parameter(parameter, value, apply=None)
Override.
- set_power_level(power_level)
Sets the power level of the XBee.
- Parameters:
power_level (
PowerLevel) – New power level of the XBee.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_pwm_duty_cycle(io_line, cycle)
Sets the duty cycle in % of the provided IO line.
The provided IO line must be PWM-capable, previously configured as PWM output.
- Parameters:
io_line (
IOLine) – IO Line to be assigned.cycle (Integer) – Duty cycle in % to be assigned. Must be between 0 and 100.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If the given IO line does not have PWM capability or cycle is not between 0 and 100.
See also
- set_sync_ops_timeout(sync_ops_timeout)
Sets the serial port read timeout.
- Parameters:
sync_ops_timeout (Integer) – Read timeout in seconds.
- property stats
Gets the statistics for this XBee.
- Returns:
Statistics. XBee statistics.
- update_bluetooth_password(new_password, apply=True, save=True)
Changes the Bluetooth password of this XBee with the new one provided.
Note that your device must include Bluetooth Low Energy support.
- Parameters:
new_password (String) – New Bluetooth password.
apply (Boolean, optional, default=`True`) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
save (Boolean, optional, default=`True`) – True to save changes, False otherwise.
- Raises:
ValueError – If new_password is invalid.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- update_bluetooth_salt_verifier(salt, verifier, apply=True, save=True)
Changes the Bluetooth password of this XBee with the new one provided.
Note that your device must include Bluetooth Low Energy support.
- Parameters:
salt (bytes) – New Bluetooth password.
verifier (bytes) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
apply (Boolean, optional, default=`True`) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
save (Boolean, optional, default=`True`) – True to save changes, False otherwise.
- Raises:
ValueError – If salt or verifier are invalid.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- update_device_data_from(device)
Updates the current node information with provided data. This is only for internal use.
- Parameters:
device (
AbstractXBeeDevice) – XBee to get the data from.- Returns:
True if the node data has been updated, False otherwise.
- Return type:
Boolean
- update_firmware(xml_firmware_file, xbee_firmware_file=None, bootloader_firmware_file=None, timeout=None, progress_callback=None)
Performs a firmware update operation of the XBee.
- Parameters:
xml_firmware_file (String) – Path of the XML file that describes the firmware to upload.
xbee_firmware_file (String, optional, default=`None`) – Location of the XBee binary firmware file.
bootloader_firmware_file (String, optional, default=`None`) – Location of the bootloader binary firmware file.
timeout (Integer, optional, default=`None`) – Maximum time to wait for target read operations during the update process (seconds).
progress_callback (Function, optional, default=`None`) –
Function to 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 XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
OperationNotSupportedException – If XBee does not support firmware update.
FirmwareUpdateException – If there is any error during the firmware update.
- write_changes()
Writes configurable parameter values to the non-volatile memory of the XBee so that parameter modifications persist through subsequent resets.
Parameters values remain in the device’s memory until overwritten by subsequent use of this method.
If changes are made without writing them, the XBee reverts back to previously saved parameters the next time the module is powered-on.
Writing the parameter modifications does not mean those values are immediately applied, this depends on the status of the ‘apply configuration changes’ option. Use method
is_apply_changes_enabled()to get its status andenable_apply_changes()to enable/disable the option. Methodapply_changes()can be used in order to manually apply the changes.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- class digi.xbee.devices.ZigBeeDevice(port=None, baud_rate=None, data_bits=serial.EIGHTBITS, stop_bits=serial.STOPBITS_ONE, parity=serial.PARITY_NONE, flow_control=FlowControl.NONE, _sync_ops_timeout=4, comm_iface=None)[source]
Bases:
XBeeDeviceThis class represents a local Zigbee XBee.
Class constructor. Instantiates a new
ZigBeeDevicewith the provided parameters.- Parameters:
port (String) – Serial port identifier. Depends on operating system. e.g. ‘/dev/ttyUSB0’ on ‘GNU/Linux’ or ‘COM3’ on Windows.
baud_rate (Integer) – Serial port baud rate.
(Integer (flow_control) –
serial.EIGHTBITS): Port bitsize.default –
serial.EIGHTBITS): Port bitsize.(Integer –
serial.STOPBITS_ONE): Port stop bits.default –
serial.STOPBITS_ONE): Port stop bits.(Character (parity) –
serial.PARITY_NONE): Port parity.default –
serial.PARITY_NONE): Port parity.(Integer –
FlowControl.NONE): Port flow control.default –
FlowControl.NONE): Port flow control.- _sync_ops_timeout (Integer, default: 3): Read timeout (in seconds).
comm_iface (
XBeeCommunicationInterface): Communication interface.
:raises All exceptions raised by
XBeeDevice.__init__()constructor.:See also
XBeeDevice.__init__()- get_ai_status()[source]
Returns the current association status of this XBee. It indicates occurrences of errors during the modem initialization and connection.
- Returns:
- The XBee association
indication status.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- force_disassociate()[source]
Forces this XBee to immediately disassociate from the network and re-attempt to associate.
Only valid for End Devices.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- get_many_to_one_broadcasting_time()[source]
Returns the time between aggregation route broadcast in tenths of a second.
- Returns:
- The number of tenths of a second between aggregation route
broadcasts. -1 if it is disabled.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- set_many_to_one_broadcasting_time(tenths_second)[source]
Configures the time between aggregation route broadcast in tenths of a second.
- Parameters:
tenths_second (Integer) – The number of tenths of a second between aggregation route broadcasts. -1 to disable. 0 to only send one broadcast.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If tenths_second is None or is lower than -1, or bigger than 254.
- send_data_64_16(x64addr, x16addr, data, transmit_options=0)[source]
Blocking method. This method sends data to the remote XBee with the given 64-bit/16-bit address.
This method waits for the packet response. The default timeout is
XBeeDevice._DEFAULT_TIMEOUT_SYNC_OPERATIONS.- Parameters:
x64addr (
XBee64BitAddress) – 64-bit address of the destination XBee.x16addr (
XBee16BitAddress) – 16-bit address of the destination XBee,XBee16BitAddress.UNKNOWN_ADDRESSif unknown.data (String or Bytearray) – Raw data to send.
transmit_options (Integer, optional) – Transmit options, bitfield of
TransmitOptions. Default to TransmitOptions.NONE.value.
- Returns:
The response.
- Return type:
- Raises:
ValueError – If x64addr, x16addr or data is None.
TimeoutException – If response is not received before the read timeout expires.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
TransmitException – If the status of the response received is not OK.
XBeeException – If the XBee’s communication interface is closed.
See also
- send_data_async_64_16(x64addr, x16addr, data, transmit_options=0)[source]
Non-blocking method. This method sends data to a remote XBee with the given 64-bit/16-bit address.
This method does not wait for a response.
- Parameters:
x64addr (
XBee64BitAddress) – 64-bit address of the destination XBee.x16addr (
XBee16BitAddress) – 16-bit address of the destination XBee,XBee16BitAddress.UNKNOWN_ADDRESSif unknown.data (String or Bytearray) – Raw data to send.
transmit_options (Integer, optional) – Transmit options, bitfield of
TransmitOptions. Default to TransmitOptions.NONE.value.
- Raises:
ValueError – If x64addr, x16addr or data is None.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the XBee’s communication interface is closed.
See also
- send_multicast_data(group_id, data, src_endpoint, dest_endpoint, cluster_id, profile_id)[source]
Blocking method. This method sends multicast data to the provided group ID synchronously.
This method will wait for the packet response. The default timeout for this method is
XBeeDevice._DEFAULT_TIMEOUT_SYNC_OPERATIONS.- Parameters:
group_id (
XBee16BitAddress) – 16-bit address of the multicast group.data (Bytearray) – Raw data to send.
src_endpoint (Integer) – Source endpoint of the transmission. 1 byte.
dest_endpoint (Integer) – Destination endpoint of the transmission. 1 byte.
cluster_id (Integer) – Cluster ID of the transmission (between 0x0 and 0xFFFF)
profile_id (Integer) – Profile ID of the transmission (between 0x0 and 0xFFFF)
- Returns:
the response packet.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the XBee’s communication interface is closed.
See also
XBee16BitAddressXBeePacket
- send_multicast_data_async(group_id, data, src_endpoint, dest_endpoint, cluster_id, profile_id)[source]
Non-blocking method. This method sends multicast data to the provided group ID.
This method does not wait for a response.
- Parameters:
group_id (
XBee16BitAddress) – 16-bit address of the multicast group.data (Bytearray) – Raw data to send.
src_endpoint (Integer) – Source endpoint of the transmission. 1 byte.
dest_endpoint (Integer) – Destination endpoint of the transmission. 1 byte.
cluster_id (Integer) – Cluster ID of the transmission (between 0x0 and 0xFFFF)
profile_id (Integer) – Profile ID of the transmission (between 0x0 and 0xFFFF)
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the XBee’s communication interface is closed.
See also
XBee16BitAddress
- register_joining_device(registrant_address, options, key)[source]
Securely registers a joining device to a trust center. Registration is the process by which a node is authorized to join the network using a preconfigured link key or installation code that is conveyed to the trust center out-of-band (using a physical interface and not over-the-air).
This method is synchronous, it sends the register joining device request and waits for the answer of the operation. Then, returns the corresponding status.
- Parameters:
registrant_address (
XBee64BitAddress) – 64-bit address of the device to register.options (RegisterKeyOptions) – Register options indicating the key source.
key (Bytearray) – Key of the device to register.
- Returns:
- Register device operation status or
None if the answer is not a RegisterDeviceStatusPacket.
- Return type:
- Raises:
TimeoutException – If the answer is not received in the configured timeout.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the XBee’s communication interface is closed.
ValueError – If registrant_address or options is None.
See also
RegisterKeyOptionsXBee64BitAddressZigbeeRegisterStatus
- register_joining_device_async(registrant_address, options, key)[source]
Securely registers a joining device to a trust center. Registration is the process by which a node is authorized to join the network using a preconfigured link key or installation code that is conveyed to the trust center out-of-band (using a physical interface and not over-the-air).
This method is asynchronous, which means that it does not wait for an answer after sending the request.
- Parameters:
registrant_address (
XBee64BitAddress) – 64-bit address of the device to register.options (RegisterKeyOptions) – Register options indicating the key source.
key (Bytearray) – Key of the device to register.
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the XBee’s communication interface is closed.
ValueError – if registrant_address or options is None.
See also
RegisterKeyOptionsXBee64BitAddress
- unregister_joining_device(unregistrant_address)[source]
Unregisters a joining device from a trust center.
This method is synchronous, it sends the unregister joining device request and waits for the answer of the operation. Then, returns the corresponding status.
- Parameters:
unregistrant_address (
XBee64BitAddress) – 64-bit address of the device to unregister.- Returns:
- Unregister device operation status
or None if the answer is not a RegisterDeviceStatusPacket.
- Return type:
- Raises:
TimeoutException – If the answer is not received in the configured timeout.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the XBee’s communication interface is closed.
ValueError – If registrant_address is None.
See also
XBee64BitAddressZigbeeRegisterStatus
- unregister_joining_device_async(unregistrant_address)[source]
Unregisters a joining device from a trust center.
This method is asynchronous, which means that it will not wait for an answer after sending the unregister request.
- Parameters:
unregistrant_address (
XBee64BitAddress) – 64-bit address of the device to unregister.- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the XBee’s communication interface is closed.
ValueError – If registrant_address is None.
See also
XBee64BitAddress
- get_routes(route_cb=None, finished_cb=None, timeout=None)[source]
Returns the routes of this XBee. If route_cb is not defined, the process blocks until the complete routing table is read.
- Parameters:
route_cb (Function, optional, default=`None`) –
Method called when a new route is received. Receives two arguments:
The XBee that owns this new route.
The new route.
finished_cb (Function, optional, default=`None`) –
Method to execute when the process finishes. Receives three arguments:
The XBee that executed the ZDO command.
A list with the discovered routes.
An error message if something went wrong.
timeout (Float, optional, default=`RouteTableReader.DEFAULT_TIMEOUT`) – The ZDO command timeout in seconds.
- Returns:
- List of
Routewhen route_cb is not defined, None otherwise (in this case routes are received in the callback).
- List of
- Return type:
List
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
OperationNotSupportedException – If XBee is not Zigbee or Smart Energy.
XBeeException – If the XBee’s communication interface is closed.
See also
com.digi.models.zdo.Route
- get_neighbors(neighbor_cb=None, finished_cb=None, timeout=None)[source]
Returns the neighbors of this XBee. If neighbor_cb is not defined, the process blocks until the complete neighbor table is read.
- Parameters:
neighbor_cb (Function, optional, default=`None`) –
Method called when a new neighbor is received. Receives two arguments:
The XBee that owns this new neighbor.
The new neighbor.
finished_cb (Function, optional, default=`None`) –
Method to execute when the process finishes. Receives three arguments:
The XBee that executed the ZDO command.
A list with the discovered neighbors.
An error message if something went wrong.
timeout (Float, optional, default=`NeighborTableReader.DEFAULT_TIMEOUT`) – The ZDO command timeout in seconds.
- Returns:
- List of
Neighborwhen neighbor_cb is not defined, None otherwise (in this case neighbors are received in the callback).
- List of
- Return type:
List
- Raises:
OperationNotSupportedException – If XBee is not Zigbee or Smart Energy.
See also
com.digi.models.zdo.Neighbor
- create_source_route(dest_node, hops)[source]
Creates a source route for the provided destination node. A source route specifies the complete route a packet traverses to get from source to destination.
For best results, use source routing with many-to-one routing.
- Parameters:
dest_node (
RemoteXBeeDevice) – The destination node.hops (List) – List of intermediate nodes (
RemoteXBeeDevice) ordered from closest to source to closest to destination node (source and destination excluded).
- Raises:
ValueError – If dest_node is None, or if it is a local node, or if its protocol is not Zigbee based, or if its 64-bit address or 16-bit address is None, unknown, or invalid.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the packet listener is not running or the XBee’s communication interface is closed.
- TIMEOUT_READ_PACKET = 3
Timeout to read packets.
- add_bluetooth_data_received_callback(callback)
Adds a callback for the event
BluetoothDataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The Bluetooth data as a Bytearray.
- add_data_received_callback(callback)
Adds a callback for the event
DataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The data received as an
XBeeMessage.
- add_expl_data_received_callback(callback)
Adds a callback for the event
ExplicitDataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The explicit data received as a
ExplicitXBeeMessage.
- add_fs_frame_received_callback(callback)
Adds a callback for the event
FileSystemFrameReceived.- Parameters:
callback (Function) –
The callback. Receives four arguments.
Source (
AbstractXBeeDevice): The node that sent the file system frame.Frame id (Integer): The received frame id.
Command (
FSCmd): The file system command.Receive options (Integer): Bitfield indicating receive options.
See also
- add_io_sample_received_callback(callback)
Adds a callback for the event
IOSampleReceived.- Parameters:
callback (Function) –
The callback. Receives three arguments.
The received IO sample as an
IOSample.The remote XBee which sent the packet as a
RemoteXBeeDevice.The time in which the packet was received as an Integer.
- add_micropython_data_received_callback(callback)
Adds a callback for the event
MicroPythonDataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The MicroPython data as a Bytearray.
- add_modem_status_received_callback(callback)
Adds a callback for the event
ModemStatusReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The modem status as a
ModemStatus.
- add_packet_received_callback(callback)
Adds a callback for the event
PacketReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The received packet as a
XBeeAPIPacket.
- add_route_received_callback(callback)
Adds a callback for the event
RouteReceived. This works for Zigbee and Digimesh devices.- Parameters:
callback (Function) –
The callback. Receives three arguments.
source (
XBeeDevice): The source node.destination (
RemoteXBeeDevice): The destination node.- hops (List): List of intermediate hops from closest to source
to closest to destination (
RemoteXBeeDevice).
- add_socket_data_received_callback(callback)
Adds a callback for the event
SocketDataReceived.- Parameters:
callback (Function) –
The callback. Receives two arguments.
The socket ID as an Integer.
The data received as Bytearray.
- add_socket_data_received_from_callback(callback)
Adds a callback for the event
SocketDataReceivedFrom.- Parameters:
callback (Function) –
The callback. Receives three arguments.
The socket ID as an Integer.
- Source address pair (host, port) where host is a string
representing an IPv4 address like ‘100.50.200.5’, and port is an integer.
The data received as Bytearray.
- add_socket_state_received_callback(callback)
Adds a callback for the event
SocketStateReceived.- Parameters:
callback (Function) –
The callback. Receives two arguments.
The socket ID as an Integer.
The state received as a
SocketState.
- add_user_data_relay_received_callback(callback)
Adds a callback for the event
RelayDataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The relay data as a
UserDataRelayMessage.
- apply_changes()
Applies changes via ‘AC’ command.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- apply_profile(profile_path, timeout=None, progress_callback=None)
Applies the given XBee profile to the XBee.
- Parameters:
profile_path (String) – Path of the XBee profile file to apply.
timeout (Integer, optional, default=`None`) – Maximum time to wait for target read operations during the apply profile (seconds).
progress_callback (Function, optional, default=`None`) –
Function 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 XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
UpdateProfileException – If there is any error applying the XBee profile.
- property br
Returns the BR value of the device.
- Returns:
The BR value of the device.
- Return type:
Integer
- close()
Closes the communication with the XBee.
This method guarantees that all threads running are stopped and the serial port is closed.
- property comm_iface
Returns the hardware interface associated to the XBee.
- Returns:
Hardware interface of the XBee.
- Return type:
See also
- classmethod create_xbee_device(comm_port_data)
Creates and returns an
XBeeDevicefrom data of the port to which is connected.- Parameters:
comm_port_data (Dictionary) – Dictionary with all comm port data needed.
are (The dictionary keys) –
“baudRate” –> Baud rate.”port” –> Port number.”bitSize” –> Bit size.”stopBits” –> Stop bits.”parity” –> Parity.”flowControl” –> Flow control.”timeout” for –> Timeout for synchronous operations (in seconds).
- Returns:
XBee object created.
- Return type:
- Raises:
SerialException – If the port to open does not exist or is already opened.
See also
- del_bluetooth_data_received_callback(callback)
Deletes a callback for the callback list of
BluetoothDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_data_received_callback(callback)
Deletes a callback for the callback list of
DataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_expl_data_received_callback(callback)
Deletes a callback for the callback list of
ExplicitDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_fs_frame_received_callback(callback)
Deletes a callback for the callback list of
FileSystemFrameReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_io_sample_received_callback(callback)
Deletes a callback for the callback list of
IOSampleReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_micropython_data_received_callback(callback)
Deletes a callback for the callback list of
MicroPythonDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_modem_status_received_callback(callback)
Deletes a callback for the callback list of
ModemStatusReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_packet_received_callback(callback)
Deletes a callback for the callback list of
PacketReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_route_received_callback(callback)
Deletes a callback for the callback list of
RouteReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_socket_data_received_callback(callback)
Deletes a callback for the callback list of
SocketDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_socket_data_received_from_callback(callback)
Deletes a callback for the callback list of
SocketDataReceivedFromevent.- Parameters:
callback (Function) – The callback to delete.
- del_socket_state_received_callback(callback)
Deletes a callback for the callback list of
SocketStateReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_user_data_relay_received_callback(callback)
Deletes a callback for the callback list of
RelayDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- determine_protocol(hardware_version, firmware_version)
Determines the XBee protocol based on the given hardware and firmware versions.
- Parameters:
hardware_version (Integer) – Hardware version to get its protocol.
firmware_version (Bytearray) – Firmware version to get its protocol.
- Returns:
- XBee protocol corresponding to the given
hardware and firmware versions.
- Return type:
- disable_bluetooth()
Disables the Bluetooth interface of this XBee.
Note that your device must include Bluetooth Low Energy support.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- enable_apply_changes(value)
Sets apply changes flag.
- Parameters:
value (Boolean) – True to enable apply changes flag, False to disable it.
- enable_bluetooth()
Enables the Bluetooth interface of this XBee.
To work with this interface, you must also configure the Bluetooth password if not done previously. Use method
AbstractXBeeDevice.update_bluetooth_password().Note that your XBee must include Bluetooth Low Energy support.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- execute_command(parameter, value=None, apply=None)
Executes the provided command.
- Parameters:
or (parameter (String) – class: .ATStringCommand): AT command to execute.
value (bytearray, optional, default=`None`) – Command value (if any).
apply (Boolean, optional, default=`None`) – True to apply changes in XBee configuration, False not to apply them, None to use is_apply_changes_enabled() returned value.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- flush_queues()
Flushes the packets queue.
- get_16bit_addr()
Returns the 16-bit address of the XBee.
- Returns:
16-bit address of the XBee.
- Return type:
See also
- get_64bit_addr()
Returns the 64-bit address of the XBee.
- Returns:
64-bit address of the XBee.
- Return type:
See also
- get_adc_value(io_line)
Returns the analog value of the provided IO line.
The provided IO line must be previously configured as ADC. To do so, use
AbstractXBeeDevice.set_io_configuration()andIOMode.ADC.- Parameters:
io_line (
IOLine) – IO line to get its ADC value.- Returns:
Analog value corresponding to the provided IO line.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If response does not contain the value for the given IO line.
See also
- get_api_output_mode()
Deprecated since version 1.3: Use
get_api_output_mode_value()Returns the API output mode of the XBee.
The API output mode determines the format of the data through the serial interface of the XBee.
- Returns:
API output mode of the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_api_output_mode_value()
Returns the API output mode of the XBee.
The API output mode determines the format that the received data is output through the serial interface of the XBee.
- Returns:
the parameter value.
- Return type:
Bytearray
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
- get_bluetooth_mac_addr()
Reads and returns the EUI-48 Bluetooth MAC address of this XBee following the format 00112233AABB.
Note that your device must include Bluetooth Low Energy support.
- Returns:
The Bluetooth MAC address.
- Return type:
String
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- get_current_frame_id()
Returns the last used frame ID.
- Returns:
Last used frame ID.
- Return type:
Integer
- get_dest_address()
Returns the 64-bit address of the XBee that is data destination.
- Returns:
64-bit address of destination XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_dio_value(io_line)
Returns the digital value of the provided IO line.
The provided IO line must be previously configured as digital I/O. To do so, use
AbstractXBeeDevice.set_io_configuration().- Parameters:
io_line (
IOLine) – the DIO line to gets its digital value.- Returns:
current value of the provided IO line.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If response does not contain the value for the given IO line.
See also
- get_file_manager()
Returns the file system manager for the XBee.
- Returns:
The file system manager.
- Return type:
- Raises:
FileSystemNotSupportedException – If the XBee does not support filesystem.
- get_firmware_version()
Returns the firmware version of the XBee.
- Returns:
Firmware version of the XBee.
- Return type:
Bytearray
- get_hardware_version()
Returns the hardware version of the XBee.
- Returns:
Hardware version of the XBee.
- Return type:
See also
- get_io_configuration(io_line)
Returns the configuration of the provided IO line.
- Parameters:
io_line (
IOLine) – IO line to get its configuration.- Returns:
IO mode of the IO line provided.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_io_sampling_rate()
Returns the IO sampling rate of the XBee.
- Returns:
IO sampling rate of XBee.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_network()
Returns the network of this XBee.
- Returns:
The XBee network.
- Return type:
- get_next_frame_id()
Returns the next frame ID of the XBee.
- Returns:
The next frame ID of the XBee.
- Return type:
Integer
- get_node_id()
Returns the node identifier (‘NI’) value of the XBee.
- Returns:
Node identifier (‘NI’) of the XBee.
- Return type:
String
- get_pan_id()
Returns the operating PAN ID of the XBee.
- Returns:
Operating PAN ID of the XBee.
- Return type:
Bytearray
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_parameter(parameter, parameter_value=None, apply=None)
Override.
See also
- get_power_level()
Returns the power level of the XBee.
- Returns:
Power level of the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_pwm_duty_cycle(io_line)
Returns the PWM duty cycle in % corresponding to the provided IO line.
- Parameters:
io_line (
IOLine) – IO line to get its PWM duty cycle.- Returns:
PWM duty cycle of the given IO line.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If io_line has no PWM capability.
See also
- get_route_to_node(remote, timeout=10, force=True)
Gets the route from this XBee to the given remote node.
- For Zigbee:
‘AR’ parameter of the local node must be configured with a value different from ‘FF’.
Set force to True to force the Zigbee remote node to return its route independently of the local node configuration as high or low RAM concentrator (‘DO’ of the local value)
- Parameters:
remote (
RemoteXBeeDevice) – The remote node.timeout (Float, optional, default=10) – Maximum number of seconds to wait for the route.
force (Boolean) – True to force asking for the route, False otherwise. Only for Zigbee.
- Returns:
- Tuple containing route data:
status (
TransmitStatus): The transmit status.Tuple with route data (None if the route was not read in the provided timeout):
source (
RemoteXBeeDevice): The source node of the route.destination (
RemoteXBeeDevice): The destination node of the route.hops (List): List of intermediate nodes (
RemoteXBeeDevice) ordered from closest to source to closest to destination node (source and destination not included).
- Return type:
Tuple
- get_sync_ops_timeout()
Returns the serial port read timeout.
- Returns:
Serial port read timeout in seconds.
- Return type:
Integer
- get_xbee_device_callbacks()
Returns this XBee internal callbacks for process received packets.
This method is called by the PacketListener associated with this XBee to get its callbacks. These callbacks are executed before user callbacks.
- Returns:
- has_explicit_packets()
Returns if there are pending explicit packets to read. This does not include non-explicit packets.
- Returns:
True if there are pending packets, False otherwise.
- Return type:
Boolean
See also
- has_packets()
Returns if there are pending packets to read. This does not include explicit packets.
- Returns:
True if there are pending packets, False otherwise.
- Return type:
Boolean
See also
- is_apply_changes_enabled()
Returns whether apply changes flag is enabled.
- Returns:
True if apply changes flag is enabled, False otherwise.
- Return type:
Boolean
- is_device_info_complete()
Returns whether XBee node information is complete.
- Returns:
True if node information is complete, False otherwise.
- Return type:
Boolean
- is_open()
Returns whether this XBee is open.
- Returns:
Boolean. True if this XBee is open, False otherwise.
- is_remote()
Override method.
See also
- property log
Returns the XBee logger.
- Returns:
The XBee device logger.
- Return type:
Logger
- property operating_mode
Returns the operating mode of this XBee.
- Returns:
OperatingMode. This XBee operating mode.
- property reachable
Returns whether the XBee is reachable.
- Returns:
True if the device is reachable, False otherwise.
- Return type:
Boolean
- read_data(timeout=None)
Reads new data received by this XBee.
If timeout is specified, this method blocks until new data is received or the timeout expires, throwing a
TimeoutExceptionin this case.- Parameters:
timeout (Integer, optional) – Read timeout in seconds. If None, this method is non-blocking and returns None if no data is available.
- Returns:
- Read message or None if this XBee did not
receive new data.
- Return type:
- Raises:
ValueError – If a timeout is specified and is less than 0.
TimeoutException – If a timeout is specified and no data was received during that time.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the XBee’s communication interface is closed.
See also
- read_data_from(remote_xbee, timeout=None)
Reads new data received from the given remote XBee.
If timeout is specified, this method blocks until new data is received or the timeout expires, throwing a
TimeoutExceptionin this case.- Parameters:
remote_xbee (
RemoteXBeeDevice) – Remote XBee that sent the data.timeout (Integer, optional) – Read timeout in seconds. If None, this method is non-blocking and returns None if no data is available.
- Returns:
- Read message sent by remote_xbee or None
if this XBee did not receive new data.
- Return type:
- Raises:
ValueError – If a timeout is specified and is less than 0.
TimeoutException – If a timeout is specified and no data was received during that time.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the XBee’s communication interface is closed.
See also
- read_device_info(init=True, fire_event=True)
Updates all instance parameters reading them from the XBee.
- Parameters:
init (Boolean, optional, default=`True`) – If False only not initialized parameters are read, all if True.
fire_event (Boolean, optional, default=`True`) – True to throw and update event if any parameter changed, False otherwise.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- read_expl_data(timeout=None)
Reads new explicit data received by this XBee.
If timeout is specified, this method blocks until new data is received or the timeout expires, throwing a
TimeoutExceptionin this case.- Parameters:
timeout (Integer, optional) – Read timeout in seconds. If None, this method is non-blocking and returns None if there is no explicit data available.
- Returns:
- Read message or None if this XBee
did not receive new explicit data.
- Return type:
- Raises:
ValueError – If a timeout is specified and is less than 0.
TimeoutException – If a timeout is specified and no explicit data was received during that time.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the XBee’s communication interface is closed.
See also
- read_expl_data_from(remote_xbee, timeout=None)
Reads new explicit data received from the given remote XBee.
If timeout is specified, this method blocks until new data is received or the timeout expires, throwing a
TimeoutExceptionin this case.- Parameters:
remote_xbee (
RemoteXBeeDevice) – Remote XBee that sent the explicit data.timeout (Integer, optional) – Read timeout in seconds. If None, this method is non-blocking and returns None if there is no data available.
- Returns:
- Read message sent by remote_xbee
or None if this XBee did not receive new data from that node.
- Return type:
- Raises:
ValueError – If a timeout is specified and is less than 0.
TimeoutException – If a timeout is specified and no explicit data was received during that time.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the XBee’s communication interface is closed.
See also
- read_io_sample()
Returns an IO sample from the XBee containing the value of all enabled digital IO and analog input channels.
- Returns:
IO sample read from the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- reset()
Override method.
See also
- property scan_counter
Returns the scan counter for this node.
- Returns:
The scan counter for this node.
- Return type:
Integer
- send_bluetooth_data(data)
Sends the given data to the Bluetooth interface using a User Data Relay frame.
- Parameters:
data (Bytearray) – Data to send.
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If there is any problem sending the data.
- send_data(remote_xbee, data, transmit_options=0)
Blocking method. This method sends data to a remote XBee synchronously.
This method will wait for the packet response. The default timeout is
XBeeDevice._DEFAULT_TIMEOUT_SYNC_OPERATIONS.- Parameters:
remote_xbee (
RemoteXBeeDevice) – Remote XBee to send data to.data (String or Bytearray) – Raw data to send.
transmit_options (Integer, optional) – Transmit options, bitfield of
TransmitOptions. Default to TransmitOptions.NONE.value.
- Returns:
The response.
- Return type:
- Raises:
ValueError – If remote_xbee is None.
TimeoutException – If response is not received before the read timeout expires.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
TransmitException – If the status of the response received is not OK.
XBeeException – If the XBee’s communication interface is closed.
See also
- send_data_async(remote_xbee, data, transmit_options=0)
Non-blocking method. This method sends data to a remote XBee.
This method does not wait for a response.
- Parameters:
remote_xbee (
RemoteXBeeDevice) – the remote XBee to send data to.data (String or Bytearray) – Raw data to send.
transmit_options (Integer, optional) – Transmit options, bitfield of
TransmitOptions. Default to TransmitOptions.NONE.value.
- Raises:
ValueError – If remote_xbee is None.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the XBee’s communication interface is closed.
See also
- send_data_broadcast(data, transmit_options=0)
Sends the provided data to all the XBee nodes of the network (broadcast).
This method blocks until a success or error transmit status arrives or the configured receive timeout expires.
The received timeout is configured using method
AbstractXBeeDevice.set_sync_ops_timeout()and can be consulted withAbstractXBeeDevice.get_sync_ops_timeout()method.- Parameters:
data (String or Bytearray) – Data to send.
transmit_options (Integer, optional) – Transmit options, bitfield of
TransmitOptions. Default to TransmitOptions.NONE.value.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
TransmitException – If the status of the response received is not OK.
XBeeException – If the XBee’s communication interface is closed.
- send_expl_data(remote_xbee, data, src_endpoint, dest_endpoint, cluster_id, profile_id, transmit_options=0)
Blocking method. Sends the provided explicit data to the given XBee, source and destination end points, cluster and profile ids.
This method blocks until a success or error response arrives or the configured receive timeout expires. The default timeout is
XBeeDevice._DEFAULT_TIMEOUT_SYNC_OPERATIONS.- Parameters:
remote_xbee (
RemoteXBeeDevice) – Remote XBee to send data to.data (String or Bytearray) – Raw data to send.
src_endpoint (Integer) – Source endpoint of the transmission. 1 byte.
dest_endpoint (Integer) – Destination endpoint of the transmission. 1 byte.
cluster_id (Integer) – Cluster ID of the transmission (between 0x0 and 0xFFFF)
profile_id (Integer) – Profile ID of the transmission (between 0x0 and 0xFFFF)
transmit_options (Integer, optional) – Transmit options, bitfield of
TransmitOptions. Default to TransmitOptions.NONE.value.
- Returns:
Response packet obtained after sending data.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
TransmitException – If the status of the response received is not OK.
XBeeException – If the XBee’s communication interface is closed.
ValueError – if cluster_id or profile_id is less than 0x0 or greater than 0xFFFF.
See also
- send_expl_data_async(remote_xbee, data, src_endpoint, dest_endpoint, cluster_id, profile_id, transmit_options=0)
Non-blocking method. Sends the provided explicit data to the given XBee, source and destination end points, cluster and profile ids.
- Parameters:
remote_xbee (
RemoteXBeeDevice) – Remote XBee to send data to.data (String or Bytearray) – Raw data to send.
src_endpoint (Integer) – Source endpoint of the transmission. 1 byte.
dest_endpoint (Integer) – Destination endpoint of the transmission. 1 byte.
cluster_id (Integer) – Cluster ID of the transmission (between 0x0 and 0xFFFF)
profile_id (Integer) – Profile ID of the transmission (between 0x0 and 0xFFFF)
transmit_options (Integer, optional) – Transmit options, bitfield of
TransmitOptions. Default to TransmitOptions.NONE.value.
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the XBee’s communication interface is closed.
ValueError – if cluster_id or profile_id is less than 0x0 or greater than 0xFFFF.
See also
- send_expl_data_broadcast(data, src_endpoint, dest_endpoint, cluster_id, profile_id, transmit_options=0)
Sends the provided explicit data to all the XBee nodes of the network (broadcast) using provided source and destination end points, cluster and profile ids.
This method blocks until a success or error transmit status arrives or the configured receive timeout expires. The received timeout is configured using the
AbstractXBeeDevice.set_sync_ops_timeout()method and can be consulted with methodAbstractXBeeDevice.get_sync_ops_timeout().- Parameters:
data (String or Bytearray) – Raw data to send.
src_endpoint (Integer) – Source endpoint of the transmission. 1 byte.
dest_endpoint (Integer) – Destination endpoint of the transmission. 1 byte.
cluster_id (Integer) – Cluster ID of the transmission (between 0x0 and 0xFFFF)
profile_id (Integer) – Profile ID of the transmission (between 0x0 and 0xFFFF)
transmit_options (Integer, optional) – Transmit options, bitfield of
TransmitOptions. Default to TransmitOptions.NONE.value.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
TransmitException – If the status of the response received is not OK.
XBeeException – If the XBee’s communication interface is closed.
ValueError – if cluster_id or profile_id is less than 0x0 or greater than 0xFFFF.
See also
XBeeDevice._send_expl_data()
- send_micropython_data(data)
Sends the given data to the MicroPython interface using a User Data Relay frame.
- Parameters:
data (Bytearray) – Data to send.
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If there is any problem sending the data.
- send_packet(packet, sync=False)
Sends the packet and waits for the response. The packet to send is escaped depending on the current operating mode.
This method can be synchronous or asynchronous.
If synchronous, this method discards all response packets until it finds the one that has the appropriate frame ID, that is, the sent packet’s frame ID.
If asynchronous, this method does not wait for any response and returns None.
- Parameters:
packet (
XBeePacket) – The packet to send.sync (Boolean) – True to wait for the response of the sent packet and return it, False otherwise.
- Returns:
- Response packet if sync is True, None
otherwise.
- Return type:
- Raises:
TimeoutException – If sync is True and the response packet for the sent one cannot be read.
InvalidOperatingModeException – If the XBee operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the packet listener is not running or the XBee’s communication interface is closed.
See also
- send_packet_sync_and_get_response(packet_to_send, timeout=None)
Sends the packet and waits for its corresponding response.
- Parameters:
packet_to_send (
XBeePacket) – The packet to transmit.timeout (Integer, optional, default=`None`) – Number of seconds to wait. -1 to wait indefinitely.
- Returns:
Received response packet.
- Return type:
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
TimeoutException – If response is not received in the configured timeout.
XBeeException – If the XBee’s communication interface is closed.
See also
- send_user_data_relay(local_interface, data)
Sends the given data to the given XBee local interface.
- Parameters:
local_interface (
XBeeLocalInterface) – Destination XBee local interface.data (Bytearray) – Data to send.
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ValueError – If local_interface is None.
XBeeException – If there is any problem sending the User Data Relay.
See also
- property serial_port
Returns the serial port associated to the XBee, if any.
- Returns:
- Serial port of the XBee. None if the
local XBee does not use serial communication.
- Return type:
See also
- set_16bit_addr(value)
Sets the 16-bit address of the XBee.
- Parameters:
value (
XBee16BitAddress) – New 16-bit address of the XBee.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If the protocol is not 802.15.4.
- set_api_output_mode(api_output_mode)
Deprecated since version 1.3: Use
set_api_output_mode_value()Sets the API output mode of the XBee.
- Parameters:
api_output_mode (
APIOutputMode) – New API output mode.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
See also
- set_api_output_mode_value(api_output_mode)
Sets the API output mode of the XBee.
- Parameters:
api_output_mode (Integer) – New API output mode options. Calculate this value using the method
APIOutputModeBit.calculate_api_output_mode_value()with a set ofAPIOutputModeBit.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
See also
- set_dest_address(addr)
Sets the 64-bit address of the XBee that is data destination.
- Parameters:
addr (
XBee64BitAddressorRemoteXBeeDevice) – Address itself or remote XBee to be data destination.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If addr is None.
See also
- set_dio_change_detection(io_lines_set)
Sets the digital IO lines to be monitored and sampled whenever their status changes. A None set of lines disables this feature.
- Parameters:
io_lines_set – Set of
IOLine.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_dio_value(io_line, io_value)
Sets the digital value (high or low) to the provided IO line.
- Parameters:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- set_io_configuration(io_line, io_mode)
Sets the configuration of the provided IO line.
- Parameters:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_io_sampling_rate(rate)
Sets the IO sampling rate of the XBee in seconds. A sample rate of 0 means the IO sampling feature is disabled.
- Parameters:
rate (Integer) – New IO sampling rate of the XBee in seconds.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_node_id(node_id)
Sets the node identifier (‘NI`) value of the XBee.
- Parameters:
node_id (String) – New node identifier (‘NI’) of the XBee.
- Raises:
ValueError – If node_id is None or its length is greater than 20.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- set_pan_id(value)
Sets the operating PAN ID of the XBee.
- Parameters:
value (Bytearray) – New operating PAN ID of the XBee. Must have only 1 or 2 bytes.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_parameter(parameter, value, apply=None)
Override.
- set_power_level(power_level)
Sets the power level of the XBee.
- Parameters:
power_level (
PowerLevel) – New power level of the XBee.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_pwm_duty_cycle(io_line, cycle)
Sets the duty cycle in % of the provided IO line.
The provided IO line must be PWM-capable, previously configured as PWM output.
- Parameters:
io_line (
IOLine) – IO Line to be assigned.cycle (Integer) – Duty cycle in % to be assigned. Must be between 0 and 100.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If the given IO line does not have PWM capability or cycle is not between 0 and 100.
See also
- set_sync_ops_timeout(sync_ops_timeout)
Sets the serial port read timeout.
- Parameters:
sync_ops_timeout (Integer) – Read timeout in seconds.
- property stats
Gets the statistics for this XBee.
- Returns:
Statistics. XBee statistics.
- update_bluetooth_password(new_password, apply=True, save=True)
Changes the Bluetooth password of this XBee with the new one provided.
Note that your device must include Bluetooth Low Energy support.
- Parameters:
new_password (String) – New Bluetooth password.
apply (Boolean, optional, default=`True`) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
save (Boolean, optional, default=`True`) – True to save changes, False otherwise.
- Raises:
ValueError – If new_password is invalid.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- update_bluetooth_salt_verifier(salt, verifier, apply=True, save=True)
Changes the Bluetooth password of this XBee with the new one provided.
Note that your device must include Bluetooth Low Energy support.
- Parameters:
salt (bytes) – New Bluetooth password.
verifier (bytes) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
apply (Boolean, optional, default=`True`) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
save (Boolean, optional, default=`True`) – True to save changes, False otherwise.
- Raises:
ValueError – If salt or verifier are invalid.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- update_device_data_from(device)
Updates the current node information with provided data. This is only for internal use.
- Parameters:
device (
AbstractXBeeDevice) – XBee to get the data from.- Returns:
True if the node data has been updated, False otherwise.
- Return type:
Boolean
- update_firmware(xml_firmware_file, xbee_firmware_file=None, bootloader_firmware_file=None, timeout=None, progress_callback=None)
Performs a firmware update operation of the XBee.
- Parameters:
xml_firmware_file (String) – Path of the XML file that describes the firmware to upload.
xbee_firmware_file (String, optional, default=`None`) – Location of the XBee binary firmware file.
bootloader_firmware_file (String, optional, default=`None`) – Location of the bootloader binary firmware file.
timeout (Integer, optional, default=`None`) – Maximum time to wait for target read operations during the update process (seconds).
progress_callback (Function, optional, default=`None`) –
Function to 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 XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
OperationNotSupportedException – If XBee does not support firmware update.
FirmwareUpdateException – If there is any error during the firmware update.
- write_changes()
Writes configurable parameter values to the non-volatile memory of the XBee so that parameter modifications persist through subsequent resets.
Parameters values remain in the device’s memory until overwritten by subsequent use of this method.
If changes are made without writing them, the XBee reverts back to previously saved parameters the next time the module is powered-on.
Writing the parameter modifications does not mean those values are immediately applied, this depends on the status of the ‘apply configuration changes’ option. Use method
is_apply_changes_enabled()to get its status andenable_apply_changes()to enable/disable the option. Methodapply_changes()can be used in order to manually apply the changes.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- class digi.xbee.devices.BluDevice(port=None, baud_rate=None, data_bits=serial.EIGHTBITS, stop_bits=serial.STOPBITS_ONE, parity=serial.PARITY_NONE, flow_control=FlowControl.NONE, _sync_ops_timeout=4, comm_iface=None)[source]
Bases:
XBeeDeviceThis class represents a local Blu device.
Class constructor. Instantiates a new
BluDevicewith the provided parameters.- Parameters:
port (String) – Serial port identifier. Depends on operating system. e.g. ‘/dev/ttyUSB0’ on ‘GNU/Linux’ or ‘COM3’ on Windows.
baud_rate (Integer) – Serial port baud rate.
(Integer (_sync_ops_timeout) –
serial.EIGHTBITS): Port bitsize.default –
serial.EIGHTBITS): Port bitsize.(Integer –
serial.STOPBITS_ONE): Port stop bits.default –
serial.STOPBITS_ONE): Port stop bits.(Character (parity) –
serial.PARITY_NONE): Port parity.default –
serial.PARITY_NONE): Port parity.(Integer –
FlowControl.NONE): Port flow control.default –
FlowControl.NONE): Port flow control.(Integer – 3): Read timeout (in seconds).
default – 3): Read timeout (in seconds).
comm_iface (
XBeeCommunicationInterface) – Communication interface.
:raises All exceptions raised by
XBeeDevice.__init__()constructor.:See also
XBeeDevice.__init__()- get_ble_manager()[source]
Returns the BLE manager for the XBee.
- Returns:
The BLE manager.
- Return type:
- get_dest_address()[source]
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- set_dest_address(addr)[source]
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- get_pan_id()[source]
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- set_pan_id(value)[source]
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- add_data_received_callback(callback)[source]
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- del_data_received_callback(callback)[source]
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- add_expl_data_received_callback(callback)[source]
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- del_expl_data_received_callback(callback)[source]
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- read_data(timeout=None)[source]
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- read_data_from(remote_xbee, timeout=None)[source]
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- send_data_broadcast(data, transmit_options=0)[source]
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- send_data(remote_xbee, data, transmit_options=0)[source]
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- send_data_async(remote_xbee, data, transmit_options=0)[source]
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- read_expl_data(timeout=None)[source]
Override.
Operation not supported in this protocol. This method raises an
AttributeError.
- read_expl_data_from(remote_xbee, timeout=None)[source]
Override.
Operation not supported in this protocol. This method raises an
AttributeError.
- send_expl_data(remote_xbee, data, src_endpoint, dest_endpoint, cluster_id, profile_id, transmit_options=0)[source]
Override.
Operation not supported in this protocol. This method raises an
AttributeError.
- send_expl_data_broadcast(data, src_endpoint, dest_endpoint, cluster_id, profile_id, transmit_options=0)[source]
Override.
Operation not supported in this protocol. This method raises an
AttributeError.
- send_expl_data_async(remote_xbee, data, src_endpoint, dest_endpoint, cluster_id, profile_id, transmit_options=0)[source]
Override.
Operation not supported in this protocol. This method raises an
AttributeError.
- add_io_sample_received_callback(callback)[source]
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- del_io_sample_received_callback(callback)[source]
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- set_dio_change_detection(io_lines_set)[source]
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- get_io_sampling_rate()[source]
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- set_io_sampling_rate(rate)[source]
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- get_power_level()[source]
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- set_power_level(power_level)[source]
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- TIMEOUT_READ_PACKET = 3
Timeout to read packets.
- add_bluetooth_data_received_callback(callback)
Adds a callback for the event
BluetoothDataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The Bluetooth data as a Bytearray.
- add_fs_frame_received_callback(callback)
Adds a callback for the event
FileSystemFrameReceived.- Parameters:
callback (Function) –
The callback. Receives four arguments.
Source (
AbstractXBeeDevice): The node that sent the file system frame.Frame id (Integer): The received frame id.
Command (
FSCmd): The file system command.Receive options (Integer): Bitfield indicating receive options.
See also
- add_micropython_data_received_callback(callback)
Adds a callback for the event
MicroPythonDataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The MicroPython data as a Bytearray.
- add_modem_status_received_callback(callback)
Adds a callback for the event
ModemStatusReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The modem status as a
ModemStatus.
- add_packet_received_callback(callback)
Adds a callback for the event
PacketReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The received packet as a
XBeeAPIPacket.
- add_route_received_callback(callback)
Adds a callback for the event
RouteReceived. This works for Zigbee and Digimesh devices.- Parameters:
callback (Function) –
The callback. Receives three arguments.
source (
XBeeDevice): The source node.destination (
RemoteXBeeDevice): The destination node.- hops (List): List of intermediate hops from closest to source
to closest to destination (
RemoteXBeeDevice).
- add_socket_data_received_callback(callback)
Adds a callback for the event
SocketDataReceived.- Parameters:
callback (Function) –
The callback. Receives two arguments.
The socket ID as an Integer.
The data received as Bytearray.
- add_socket_data_received_from_callback(callback)
Adds a callback for the event
SocketDataReceivedFrom.- Parameters:
callback (Function) –
The callback. Receives three arguments.
The socket ID as an Integer.
- Source address pair (host, port) where host is a string
representing an IPv4 address like ‘100.50.200.5’, and port is an integer.
The data received as Bytearray.
- add_socket_state_received_callback(callback)
Adds a callback for the event
SocketStateReceived.- Parameters:
callback (Function) –
The callback. Receives two arguments.
The socket ID as an Integer.
The state received as a
SocketState.
- add_user_data_relay_received_callback(callback)
Adds a callback for the event
RelayDataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The relay data as a
UserDataRelayMessage.
- apply_changes()
Applies changes via ‘AC’ command.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- apply_profile(profile_path, timeout=None, progress_callback=None)
Applies the given XBee profile to the XBee.
- Parameters:
profile_path (String) – Path of the XBee profile file to apply.
timeout (Integer, optional, default=`None`) – Maximum time to wait for target read operations during the apply profile (seconds).
progress_callback (Function, optional, default=`None`) –
Function 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 XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
UpdateProfileException – If there is any error applying the XBee profile.
- property br
Returns the BR value of the device.
- Returns:
The BR value of the device.
- Return type:
Integer
- property comm_iface
Returns the hardware interface associated to the XBee.
- Returns:
Hardware interface of the XBee.
- Return type:
See also
- classmethod create_xbee_device(comm_port_data)
Creates and returns an
XBeeDevicefrom data of the port to which is connected.- Parameters:
comm_port_data (Dictionary) – Dictionary with all comm port data needed.
are (The dictionary keys) –
“baudRate” –> Baud rate.”port” –> Port number.”bitSize” –> Bit size.”stopBits” –> Stop bits.”parity” –> Parity.”flowControl” –> Flow control.”timeout” for –> Timeout for synchronous operations (in seconds).
- Returns:
XBee object created.
- Return type:
- Raises:
SerialException – If the port to open does not exist or is already opened.
See also
- del_bluetooth_data_received_callback(callback)
Deletes a callback for the callback list of
BluetoothDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_fs_frame_received_callback(callback)
Deletes a callback for the callback list of
FileSystemFrameReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_micropython_data_received_callback(callback)
Deletes a callback for the callback list of
MicroPythonDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_modem_status_received_callback(callback)
Deletes a callback for the callback list of
ModemStatusReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_packet_received_callback(callback)
Deletes a callback for the callback list of
PacketReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_route_received_callback(callback)
Deletes a callback for the callback list of
RouteReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_socket_data_received_callback(callback)
Deletes a callback for the callback list of
SocketDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_socket_data_received_from_callback(callback)
Deletes a callback for the callback list of
SocketDataReceivedFromevent.- Parameters:
callback (Function) – The callback to delete.
- del_socket_state_received_callback(callback)
Deletes a callback for the callback list of
SocketStateReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_user_data_relay_received_callback(callback)
Deletes a callback for the callback list of
RelayDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- determine_protocol(hardware_version, firmware_version)
Determines the XBee protocol based on the given hardware and firmware versions.
- Parameters:
hardware_version (Integer) – Hardware version to get its protocol.
firmware_version (Bytearray) – Firmware version to get its protocol.
- Returns:
- XBee protocol corresponding to the given
hardware and firmware versions.
- Return type:
- disable_bluetooth()
Disables the Bluetooth interface of this XBee.
Note that your device must include Bluetooth Low Energy support.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- enable_apply_changes(value)
Sets apply changes flag.
- Parameters:
value (Boolean) – True to enable apply changes flag, False to disable it.
- enable_bluetooth()
Enables the Bluetooth interface of this XBee.
To work with this interface, you must also configure the Bluetooth password if not done previously. Use method
AbstractXBeeDevice.update_bluetooth_password().Note that your XBee must include Bluetooth Low Energy support.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- execute_command(parameter, value=None, apply=None)
Executes the provided command.
- Parameters:
or (parameter (String) – class: .ATStringCommand): AT command to execute.
value (bytearray, optional, default=`None`) – Command value (if any).
apply (Boolean, optional, default=`None`) – True to apply changes in XBee configuration, False not to apply them, None to use is_apply_changes_enabled() returned value.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- flush_queues()
Flushes the packets queue.
- get_64bit_addr()
Returns the 64-bit address of the XBee.
- Returns:
64-bit address of the XBee.
- Return type:
See also
- get_adc_value(io_line)
Returns the analog value of the provided IO line.
The provided IO line must be previously configured as ADC. To do so, use
AbstractXBeeDevice.set_io_configuration()andIOMode.ADC.- Parameters:
io_line (
IOLine) – IO line to get its ADC value.- Returns:
Analog value corresponding to the provided IO line.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If response does not contain the value for the given IO line.
See also
- get_api_output_mode()
Deprecated since version 1.3: Use
get_api_output_mode_value()Returns the API output mode of the XBee.
The API output mode determines the format of the data through the serial interface of the XBee.
- Returns:
API output mode of the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_api_output_mode_value()
Returns the API output mode of the XBee.
The API output mode determines the format that the received data is output through the serial interface of the XBee.
- Returns:
the parameter value.
- Return type:
Bytearray
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
- get_bluetooth_mac_addr()
Reads and returns the EUI-48 Bluetooth MAC address of this XBee following the format 00112233AABB.
Note that your device must include Bluetooth Low Energy support.
- Returns:
The Bluetooth MAC address.
- Return type:
String
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- get_current_frame_id()
Returns the last used frame ID.
- Returns:
Last used frame ID.
- Return type:
Integer
- get_dio_value(io_line)
Returns the digital value of the provided IO line.
The provided IO line must be previously configured as digital I/O. To do so, use
AbstractXBeeDevice.set_io_configuration().- Parameters:
io_line (
IOLine) – the DIO line to gets its digital value.- Returns:
current value of the provided IO line.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If response does not contain the value for the given IO line.
See also
- get_file_manager()
Returns the file system manager for the XBee.
- Returns:
The file system manager.
- Return type:
- Raises:
FileSystemNotSupportedException – If the XBee does not support filesystem.
- get_firmware_version()
Returns the firmware version of the XBee.
- Returns:
Firmware version of the XBee.
- Return type:
Bytearray
- get_hardware_version()
Returns the hardware version of the XBee.
- Returns:
Hardware version of the XBee.
- Return type:
See also
- get_io_configuration(io_line)
Returns the configuration of the provided IO line.
- Parameters:
io_line (
IOLine) – IO line to get its configuration.- Returns:
IO mode of the IO line provided.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_next_frame_id()
Returns the next frame ID of the XBee.
- Returns:
The next frame ID of the XBee.
- Return type:
Integer
- get_node_id()
Returns the node identifier (‘NI’) value of the XBee.
- Returns:
Node identifier (‘NI’) of the XBee.
- Return type:
String
- get_parameter(parameter, parameter_value=None, apply=None)
Override.
See also
- get_pwm_duty_cycle(io_line)
Returns the PWM duty cycle in % corresponding to the provided IO line.
- Parameters:
io_line (
IOLine) – IO line to get its PWM duty cycle.- Returns:
PWM duty cycle of the given IO line.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If io_line has no PWM capability.
See also
- get_route_to_node(remote, timeout=10, force=True)
Gets the route from this XBee to the given remote node.
- For Zigbee:
‘AR’ parameter of the local node must be configured with a value different from ‘FF’.
Set force to True to force the Zigbee remote node to return its route independently of the local node configuration as high or low RAM concentrator (‘DO’ of the local value)
- Parameters:
remote (
RemoteXBeeDevice) – The remote node.timeout (Float, optional, default=10) – Maximum number of seconds to wait for the route.
force (Boolean) – True to force asking for the route, False otherwise. Only for Zigbee.
- Returns:
- Tuple containing route data:
status (
TransmitStatus): The transmit status.Tuple with route data (None if the route was not read in the provided timeout):
source (
RemoteXBeeDevice): The source node of the route.destination (
RemoteXBeeDevice): The destination node of the route.hops (List): List of intermediate nodes (
RemoteXBeeDevice) ordered from closest to source to closest to destination node (source and destination not included).
- Return type:
Tuple
- get_sync_ops_timeout()
Returns the serial port read timeout.
- Returns:
Serial port read timeout in seconds.
- Return type:
Integer
- get_xbee_device_callbacks()
Returns this XBee internal callbacks for process received packets.
This method is called by the PacketListener associated with this XBee to get its callbacks. These callbacks are executed before user callbacks.
- Returns:
- has_explicit_packets()
Returns if there are pending explicit packets to read. This does not include non-explicit packets.
- Returns:
True if there are pending packets, False otherwise.
- Return type:
Boolean
See also
- has_packets()
Returns if there are pending packets to read. This does not include explicit packets.
- Returns:
True if there are pending packets, False otherwise.
- Return type:
Boolean
See also
- is_apply_changes_enabled()
Returns whether apply changes flag is enabled.
- Returns:
True if apply changes flag is enabled, False otherwise.
- Return type:
Boolean
- is_device_info_complete()
Returns whether XBee node information is complete.
- Returns:
True if node information is complete, False otherwise.
- Return type:
Boolean
- is_open()
Returns whether this XBee is open.
- Returns:
Boolean. True if this XBee is open, False otherwise.
- is_remote()
Override method.
See also
- property log
Returns the XBee logger.
- Returns:
The XBee device logger.
- Return type:
Logger
- property operating_mode
Returns the operating mode of this XBee.
- Returns:
OperatingMode. This XBee operating mode.
- property reachable
Returns whether the XBee is reachable.
- Returns:
True if the device is reachable, False otherwise.
- Return type:
Boolean
- read_device_info(init=True, fire_event=True)
Updates all instance parameters reading them from the XBee.
- Parameters:
init (Boolean, optional, default=`True`) – If False only not initialized parameters are read, all if True.
fire_event (Boolean, optional, default=`True`) – True to throw and update event if any parameter changed, False otherwise.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- read_io_sample()
Returns an IO sample from the XBee containing the value of all enabled digital IO and analog input channels.
- Returns:
IO sample read from the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- reset()
Override method.
See also
- property scan_counter
Returns the scan counter for this node.
- Returns:
The scan counter for this node.
- Return type:
Integer
- send_bluetooth_data(data)
Sends the given data to the Bluetooth interface using a User Data Relay frame.
- Parameters:
data (Bytearray) – Data to send.
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If there is any problem sending the data.
- send_micropython_data(data)
Sends the given data to the MicroPython interface using a User Data Relay frame.
- Parameters:
data (Bytearray) – Data to send.
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If there is any problem sending the data.
- send_packet(packet, sync=False)
Sends the packet and waits for the response. The packet to send is escaped depending on the current operating mode.
This method can be synchronous or asynchronous.
If synchronous, this method discards all response packets until it finds the one that has the appropriate frame ID, that is, the sent packet’s frame ID.
If asynchronous, this method does not wait for any response and returns None.
- Parameters:
packet (
XBeePacket) – The packet to send.sync (Boolean) – True to wait for the response of the sent packet and return it, False otherwise.
- Returns:
- Response packet if sync is True, None
otherwise.
- Return type:
- Raises:
TimeoutException – If sync is True and the response packet for the sent one cannot be read.
InvalidOperatingModeException – If the XBee operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the packet listener is not running or the XBee’s communication interface is closed.
See also
- send_packet_sync_and_get_response(packet_to_send, timeout=None)
Sends the packet and waits for its corresponding response.
- Parameters:
packet_to_send (
XBeePacket) – The packet to transmit.timeout (Integer, optional, default=`None`) – Number of seconds to wait. -1 to wait indefinitely.
- Returns:
Received response packet.
- Return type:
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
TimeoutException – If response is not received in the configured timeout.
XBeeException – If the XBee’s communication interface is closed.
See also
- send_user_data_relay(local_interface, data)
Sends the given data to the given XBee local interface.
- Parameters:
local_interface (
XBeeLocalInterface) – Destination XBee local interface.data (Bytearray) – Data to send.
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ValueError – If local_interface is None.
XBeeException – If there is any problem sending the User Data Relay.
See also
- property serial_port
Returns the serial port associated to the XBee, if any.
- Returns:
- Serial port of the XBee. None if the
local XBee does not use serial communication.
- Return type:
See also
- set_16bit_addr(value)
Sets the 16-bit address of the XBee.
- Parameters:
value (
XBee16BitAddress) – New 16-bit address of the XBee.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If the protocol is not 802.15.4.
- set_api_output_mode(api_output_mode)
Deprecated since version 1.3: Use
set_api_output_mode_value()Sets the API output mode of the XBee.
- Parameters:
api_output_mode (
APIOutputMode) – New API output mode.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
See also
- set_api_output_mode_value(api_output_mode)
Sets the API output mode of the XBee.
- Parameters:
api_output_mode (Integer) – New API output mode options. Calculate this value using the method
APIOutputModeBit.calculate_api_output_mode_value()with a set ofAPIOutputModeBit.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
See also
- set_dio_value(io_line, io_value)
Sets the digital value (high or low) to the provided IO line.
- Parameters:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- set_io_configuration(io_line, io_mode)
Sets the configuration of the provided IO line.
- Parameters:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_node_id(node_id)
Sets the node identifier (‘NI`) value of the XBee.
- Parameters:
node_id (String) – New node identifier (‘NI’) of the XBee.
- Raises:
ValueError – If node_id is None or its length is greater than 20.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- set_parameter(parameter, value, apply=None)
Override.
- set_pwm_duty_cycle(io_line, cycle)
Sets the duty cycle in % of the provided IO line.
The provided IO line must be PWM-capable, previously configured as PWM output.
- Parameters:
io_line (
IOLine) – IO Line to be assigned.cycle (Integer) – Duty cycle in % to be assigned. Must be between 0 and 100.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If the given IO line does not have PWM capability or cycle is not between 0 and 100.
See also
- set_sync_ops_timeout(sync_ops_timeout)
Sets the serial port read timeout.
- Parameters:
sync_ops_timeout (Integer) – Read timeout in seconds.
- property stats
Gets the statistics for this XBee.
- Returns:
Statistics. XBee statistics.
- update_bluetooth_password(new_password, apply=True, save=True)
Changes the Bluetooth password of this XBee with the new one provided.
Note that your device must include Bluetooth Low Energy support.
- Parameters:
new_password (String) – New Bluetooth password.
apply (Boolean, optional, default=`True`) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
save (Boolean, optional, default=`True`) – True to save changes, False otherwise.
- Raises:
ValueError – If new_password is invalid.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- update_bluetooth_salt_verifier(salt, verifier, apply=True, save=True)
Changes the Bluetooth password of this XBee with the new one provided.
Note that your device must include Bluetooth Low Energy support.
- Parameters:
salt (bytes) – New Bluetooth password.
verifier (bytes) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
apply (Boolean, optional, default=`True`) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
save (Boolean, optional, default=`True`) – True to save changes, False otherwise.
- Raises:
ValueError – If salt or verifier are invalid.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- update_device_data_from(device)
Updates the current node information with provided data. This is only for internal use.
- Parameters:
device (
AbstractXBeeDevice) – XBee to get the data from.- Returns:
True if the node data has been updated, False otherwise.
- Return type:
Boolean
- update_firmware(xml_firmware_file, xbee_firmware_file=None, bootloader_firmware_file=None, timeout=None, progress_callback=None)
Performs a firmware update operation of the XBee.
- Parameters:
xml_firmware_file (String) – Path of the XML file that describes the firmware to upload.
xbee_firmware_file (String, optional, default=`None`) – Location of the XBee binary firmware file.
bootloader_firmware_file (String, optional, default=`None`) – Location of the bootloader binary firmware file.
timeout (Integer, optional, default=`None`) – Maximum time to wait for target read operations during the update process (seconds).
progress_callback (Function, optional, default=`None`) –
Function to 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 XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
OperationNotSupportedException – If XBee does not support firmware update.
FirmwareUpdateException – If there is any error during the firmware update.
- write_changes()
Writes configurable parameter values to the non-volatile memory of the XBee so that parameter modifications persist through subsequent resets.
Parameters values remain in the device’s memory until overwritten by subsequent use of this method.
If changes are made without writing them, the XBee reverts back to previously saved parameters the next time the module is powered-on.
Writing the parameter modifications does not mean those values are immediately applied, this depends on the status of the ‘apply configuration changes’ option. Use method
is_apply_changes_enabled()to get its status andenable_apply_changes()to enable/disable the option. Methodapply_changes()can be used in order to manually apply the changes.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- class digi.xbee.devices.IPDevice(port=None, baud_rate=None, data_bits=serial.EIGHTBITS, stop_bits=serial.STOPBITS_ONE, parity=serial.PARITY_NONE, flow_control=FlowControl.NONE, _sync_ops_timeout=4, comm_iface=None)[source]
Bases:
XBeeDeviceThis class provides common functionality for XBee IP devices.
Class constructor. Instantiates a new
IPDevicewith the provided parameters.- Parameters:
port (String) – Serial port identifier. Depends on operating system. e.g. ‘/dev/ttyUSB0’ on ‘GNU/Linux’ or ‘COM3’ on Windows.
baud_rate (Integer) – Serial port baud rate.
(Integer (_sync_ops_timeout) –
serial.EIGHTBITS): Port bitsize.default –
serial.EIGHTBITS): Port bitsize.(Integer –
serial.STOPBITS_ONE): Port stop bits.default –
serial.STOPBITS_ONE): Port stop bits.(Character (parity) –
serial.PARITY_NONE): Port parity.default –
serial.PARITY_NONE): Port parity.(Integer –
FlowControl.NONE): Port flow control.default –
FlowControl.NONE): Port flow control.(Integer – 3): Read timeout (in seconds).
default – 3): Read timeout (in seconds).
comm_iface (
XBeeCommunicationInterface) – Communication interface.
:raises All exceptions raised by
XBeeDevice.__init__()constructor.:See also
XBeeDevice.__init__()- get_ip_addr()[source]
Returns the IP address of this IP XBee.
To refresh this value use the method
IPDevice.read_device_info().- Returns:
The IP address of this IP device.
- Return type:
ipaddress.IPv4Address
See also
ipaddress.IPv4Address
- set_dest_ip_addr(address)[source]
Sets the destination IP address.
- Parameters:
address (
ipaddress.IPv4Address) – Destination IP address.- Raises:
ValueError – If address is None.
TimeoutException – If there is a timeout setting the destination IP address.
XBeeException – If there is any other XBee related exception.
See also
ipaddress.IPv4Address
- get_dest_ip_addr()[source]
Returns the destination IP address.
- Returns:
Configured destination IP address.
- Return type:
ipaddress.IPv4Address- Raises:
TimeoutException – If there is a timeout getting the destination IP address.
XBeeException – If there is any other XBee related exception.
See also
ipaddress.IPv4Address
- add_ip_data_received_callback(callback)[source]
Adds a callback for the event
IPDataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The data received as an
IPMessage
- del_ip_data_received_callback(callback)[source]
Deletes a callback for the callback list of
IPDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- start_listening(src_port)[source]
Starts listening for incoming IP transmissions in the provided port.
- Parameters:
src_port (Integer) – Port to listen for incoming transmissions.
- Raises:
ValueError – If source_port is less than 0 or greater than 65535.
TimeoutException – If there is a timeout setting the source port.
XBeeException – If there is any other XBee related exception.
- stop_listening()[source]
Stops listening for incoming IP transmissions.
- Raises:
TimeoutException – If there is a timeout processing the operation.
XBeeException – If there is any other XBee related exception.
- send_ip_data(ip_addr, dest_port, protocol, data, close_socket=False)[source]
Sends the provided IP data to the given IP address and port using the specified IP protocol. For TCP and TCP SSL protocols, you can also indicate if the socket should be closed when data is sent.
This method blocks until a success or error response arrives or the configured receive timeout expires.
- Parameters:
ip_addr (
ipaddress.IPv4Address) – The IP address to send IP data to.dest_port (Integer) – The destination port of the transmission.
protocol (
IPProtocol) – The IP protocol used for the transmission.data (String or Bytearray) – The IP data to be sent.
close_socket (Boolean, optional, default=`False`) – True to close the socket just after the transmission. False to keep it open.
- Raises:
ValueError – If ip_addr or protocol or data is None or dest_port is less than 0 or greater than 65535.
OperationNotSupportedException – If the XBee is remote.
TimeoutException – If there is a timeout sending the data.
XBeeException – If there is any other XBee related exception.
- send_ip_data_async(ip_addr, dest_port, protocol, data, close_socket=False)[source]
Sends the provided IP data to the given IP address and port asynchronously using the specified IP protocol. For TCP and TCP SSL protocols, you can also indicate if the socket should be closed when data is sent.
Asynchronous transmissions do not wait for answer from the remote device or for transmit status packet.
- Parameters:
ip_addr (
ipaddress.IPv4Address) – The IP address to send IP data to.dest_port (Integer) – The destination port of the transmission.
protocol (
IPProtocol) – The IP protocol used for the transmission.data (String or Bytearray) – The IP data to be sent.
close_socket (Boolean, optional, default=`False`) – True to close the socket just after the transmission. False to keep it open.
- Raises:
ValueError – If ip_addr or protocol or data is None or dest_port is less than 0 or greater than 65535.
OperationNotSupportedException – If the XBee is remote.
XBeeException – If there is any other XBee related exception.
- send_ip_data_broadcast(dest_port, data)[source]
Sends the provided IP data to all clients.
This method blocks until a success or error transmit status arrives or the configured receive timeout expires.
- Parameters:
dest_port (Integer) – The destination port of the transmission.
data (String or Bytearray) – The IP data to be sent.
- Raises:
ValueError – If data is None or dest_port is less than 0 or greater than 65535.
TimeoutException – If there is a timeout sending the data.
XBeeException – If there is any other XBee related exception.
- read_ip_data(timeout=3)[source]
Reads new IP data received by this XBee during the provided timeout.
This method blocks until new IP data is received or the provided timeout expires.
For non-blocking operations, register a callback and use the method
IPDevice.add_ip_data_received_callback().Before reading IP data you need to start listening for incoming IP data at a specific port. Use the method
IPDevice.start_listening()for that purpose. When finished, you can use the methodIPDevice.stop_listening()to stop listening for incoming IP data.- Parameters:
timeout (Integer, optional) – The time to wait for new IP data in seconds.
- Returns:
IP message, None if this device did not receive new data.
- Return type:
- Raises:
ValueError – If timeout is less than 0.
- read_ip_data_from(ip_addr, timeout=3)[source]
Reads new IP data received from the given IP address during the provided timeout.
This method blocks until new IP data from the provided IP address is received or the given timeout expires.
For non-blocking operations, register a callback and use the method
IPDevice.add_ip_data_received_callback().Before reading IP data you need to start listening for incoming IP data at a specific port. Use the method
IPDevice.start_listening()for that purpose. When finished, you can use the methodIPDevice.stop_listening()to stop listening for incoming IP data.- Parameters:
ip_addr (
ipaddress.IPv4Address) – The IP address to read data from.timeout (Integer, optional) – The time to wait for new IP data in seconds.
- Returns:
- IP message, None if this device did not
receive new data from the provided IP address.
- Return type:
- Raises:
ValueError – If timeout is less than 0.
- get_dest_address()[source]
Deprecated.
Operation not supported in this protocol. Use
IPDevice.get_dest_ip_addr()instead. This method raises anAttributeError.
- set_dest_address(addr)[source]
Deprecated.
Operation not supported in this protocol. Use
IPDevice.set_dest_ip_addr()instead. This method raises anAttributeError.
- get_pan_id()[source]
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- set_pan_id(value)[source]
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- add_data_received_callback(callback)[source]
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- del_data_received_callback(callback)[source]
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- add_expl_data_received_callback(callback)[source]
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- del_expl_data_received_callback(callback)[source]
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- read_data(timeout=None)[source]
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- read_data_from(remote_xbee, timeout=None)[source]
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- send_data_broadcast(data, transmit_options=0)[source]
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- send_data(remote_xbee, data, transmit_options=0)[source]
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- send_data_async(remote_xbee, data, transmit_options=0)[source]
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- read_expl_data(timeout=None)[source]
Override.
Operation not supported in this protocol. This method raises an
AttributeError.
- read_expl_data_from(remote_xbee, timeout=None)[source]
Override.
Operation not supported in this protocol. This method raises an
AttributeError.
- send_expl_data(remote_xbee, data, src_endpoint, dest_endpoint, cluster_id, profile_id, transmit_options=0)[source]
Override.
Operation not supported in this protocol. This method raises an
AttributeError.
- send_expl_data_broadcast(data, src_endpoint, dest_endpoint, cluster_id, profile_id, transmit_options=0)[source]
Override.
Operation not supported in this protocol. This method raises an
AttributeError.
- send_expl_data_async(remote_xbee, data, src_endpoint, dest_endpoint, cluster_id, profile_id, transmit_options=0)[source]
Override.
Operation not supported in this protocol. This method raises an
AttributeError.
- TIMEOUT_READ_PACKET = 3
Timeout to read packets.
- add_bluetooth_data_received_callback(callback)
Adds a callback for the event
BluetoothDataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The Bluetooth data as a Bytearray.
- add_fs_frame_received_callback(callback)
Adds a callback for the event
FileSystemFrameReceived.- Parameters:
callback (Function) –
The callback. Receives four arguments.
Source (
AbstractXBeeDevice): The node that sent the file system frame.Frame id (Integer): The received frame id.
Command (
FSCmd): The file system command.Receive options (Integer): Bitfield indicating receive options.
See also
- add_io_sample_received_callback(callback)
Adds a callback for the event
IOSampleReceived.- Parameters:
callback (Function) –
The callback. Receives three arguments.
The received IO sample as an
IOSample.The remote XBee which sent the packet as a
RemoteXBeeDevice.The time in which the packet was received as an Integer.
- add_micropython_data_received_callback(callback)
Adds a callback for the event
MicroPythonDataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The MicroPython data as a Bytearray.
- add_modem_status_received_callback(callback)
Adds a callback for the event
ModemStatusReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The modem status as a
ModemStatus.
- add_packet_received_callback(callback)
Adds a callback for the event
PacketReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The received packet as a
XBeeAPIPacket.
- add_route_received_callback(callback)
Adds a callback for the event
RouteReceived. This works for Zigbee and Digimesh devices.- Parameters:
callback (Function) –
The callback. Receives three arguments.
source (
XBeeDevice): The source node.destination (
RemoteXBeeDevice): The destination node.- hops (List): List of intermediate hops from closest to source
to closest to destination (
RemoteXBeeDevice).
- add_socket_data_received_callback(callback)
Adds a callback for the event
SocketDataReceived.- Parameters:
callback (Function) –
The callback. Receives two arguments.
The socket ID as an Integer.
The data received as Bytearray.
- add_socket_data_received_from_callback(callback)
Adds a callback for the event
SocketDataReceivedFrom.- Parameters:
callback (Function) –
The callback. Receives three arguments.
The socket ID as an Integer.
- Source address pair (host, port) where host is a string
representing an IPv4 address like ‘100.50.200.5’, and port is an integer.
The data received as Bytearray.
- add_socket_state_received_callback(callback)
Adds a callback for the event
SocketStateReceived.- Parameters:
callback (Function) –
The callback. Receives two arguments.
The socket ID as an Integer.
The state received as a
SocketState.
- add_user_data_relay_received_callback(callback)
Adds a callback for the event
RelayDataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The relay data as a
UserDataRelayMessage.
- apply_changes()
Applies changes via ‘AC’ command.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- apply_profile(profile_path, timeout=None, progress_callback=None)
Applies the given XBee profile to the XBee.
- Parameters:
profile_path (String) – Path of the XBee profile file to apply.
timeout (Integer, optional, default=`None`) – Maximum time to wait for target read operations during the apply profile (seconds).
progress_callback (Function, optional, default=`None`) –
Function 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 XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
UpdateProfileException – If there is any error applying the XBee profile.
- property br
Returns the BR value of the device.
- Returns:
The BR value of the device.
- Return type:
Integer
- close()
Closes the communication with the XBee.
This method guarantees that all threads running are stopped and the serial port is closed.
- property comm_iface
Returns the hardware interface associated to the XBee.
- Returns:
Hardware interface of the XBee.
- Return type:
See also
- classmethod create_xbee_device(comm_port_data)
Creates and returns an
XBeeDevicefrom data of the port to which is connected.- Parameters:
comm_port_data (Dictionary) – Dictionary with all comm port data needed.
are (The dictionary keys) –
“baudRate” –> Baud rate.”port” –> Port number.”bitSize” –> Bit size.”stopBits” –> Stop bits.”parity” –> Parity.”flowControl” –> Flow control.”timeout” for –> Timeout for synchronous operations (in seconds).
- Returns:
XBee object created.
- Return type:
- Raises:
SerialException – If the port to open does not exist or is already opened.
See also
- del_bluetooth_data_received_callback(callback)
Deletes a callback for the callback list of
BluetoothDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_fs_frame_received_callback(callback)
Deletes a callback for the callback list of
FileSystemFrameReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_io_sample_received_callback(callback)
Deletes a callback for the callback list of
IOSampleReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_micropython_data_received_callback(callback)
Deletes a callback for the callback list of
MicroPythonDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_modem_status_received_callback(callback)
Deletes a callback for the callback list of
ModemStatusReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_packet_received_callback(callback)
Deletes a callback for the callback list of
PacketReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_route_received_callback(callback)
Deletes a callback for the callback list of
RouteReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_socket_data_received_callback(callback)
Deletes a callback for the callback list of
SocketDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_socket_data_received_from_callback(callback)
Deletes a callback for the callback list of
SocketDataReceivedFromevent.- Parameters:
callback (Function) – The callback to delete.
- del_socket_state_received_callback(callback)
Deletes a callback for the callback list of
SocketStateReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_user_data_relay_received_callback(callback)
Deletes a callback for the callback list of
RelayDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- determine_protocol(hardware_version, firmware_version)
Determines the XBee protocol based on the given hardware and firmware versions.
- Parameters:
hardware_version (Integer) – Hardware version to get its protocol.
firmware_version (Bytearray) – Firmware version to get its protocol.
- Returns:
- XBee protocol corresponding to the given
hardware and firmware versions.
- Return type:
- disable_bluetooth()
Disables the Bluetooth interface of this XBee.
Note that your device must include Bluetooth Low Energy support.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- enable_apply_changes(value)
Sets apply changes flag.
- Parameters:
value (Boolean) – True to enable apply changes flag, False to disable it.
- enable_bluetooth()
Enables the Bluetooth interface of this XBee.
To work with this interface, you must also configure the Bluetooth password if not done previously. Use method
AbstractXBeeDevice.update_bluetooth_password().Note that your XBee must include Bluetooth Low Energy support.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- execute_command(parameter, value=None, apply=None)
Executes the provided command.
- Parameters:
or (parameter (String) – class: .ATStringCommand): AT command to execute.
value (bytearray, optional, default=`None`) – Command value (if any).
apply (Boolean, optional, default=`None`) – True to apply changes in XBee configuration, False not to apply them, None to use is_apply_changes_enabled() returned value.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- flush_queues()
Flushes the packets queue.
- get_64bit_addr()
Returns the 64-bit address of the XBee.
- Returns:
64-bit address of the XBee.
- Return type:
See also
- get_adc_value(io_line)
Returns the analog value of the provided IO line.
The provided IO line must be previously configured as ADC. To do so, use
AbstractXBeeDevice.set_io_configuration()andIOMode.ADC.- Parameters:
io_line (
IOLine) – IO line to get its ADC value.- Returns:
Analog value corresponding to the provided IO line.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If response does not contain the value for the given IO line.
See also
- get_api_output_mode()
Deprecated since version 1.3: Use
get_api_output_mode_value()Returns the API output mode of the XBee.
The API output mode determines the format of the data through the serial interface of the XBee.
- Returns:
API output mode of the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_api_output_mode_value()
Returns the API output mode of the XBee.
The API output mode determines the format that the received data is output through the serial interface of the XBee.
- Returns:
the parameter value.
- Return type:
Bytearray
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
- get_bluetooth_mac_addr()
Reads and returns the EUI-48 Bluetooth MAC address of this XBee following the format 00112233AABB.
Note that your device must include Bluetooth Low Energy support.
- Returns:
The Bluetooth MAC address.
- Return type:
String
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- get_current_frame_id()
Returns the last used frame ID.
- Returns:
Last used frame ID.
- Return type:
Integer
- get_dio_value(io_line)
Returns the digital value of the provided IO line.
The provided IO line must be previously configured as digital I/O. To do so, use
AbstractXBeeDevice.set_io_configuration().- Parameters:
io_line (
IOLine) – the DIO line to gets its digital value.- Returns:
current value of the provided IO line.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If response does not contain the value for the given IO line.
See also
- get_file_manager()
Returns the file system manager for the XBee.
- Returns:
The file system manager.
- Return type:
- Raises:
FileSystemNotSupportedException – If the XBee does not support filesystem.
- get_firmware_version()
Returns the firmware version of the XBee.
- Returns:
Firmware version of the XBee.
- Return type:
Bytearray
- get_hardware_version()
Returns the hardware version of the XBee.
- Returns:
Hardware version of the XBee.
- Return type:
See also
- get_io_configuration(io_line)
Returns the configuration of the provided IO line.
- Parameters:
io_line (
IOLine) – IO line to get its configuration.- Returns:
IO mode of the IO line provided.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_io_sampling_rate()
Returns the IO sampling rate of the XBee.
- Returns:
IO sampling rate of XBee.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_next_frame_id()
Returns the next frame ID of the XBee.
- Returns:
The next frame ID of the XBee.
- Return type:
Integer
- get_node_id()
Returns the node identifier (‘NI’) value of the XBee.
- Returns:
Node identifier (‘NI’) of the XBee.
- Return type:
String
- get_parameter(parameter, parameter_value=None, apply=None)
Override.
See also
- get_power_level()
Returns the power level of the XBee.
- Returns:
Power level of the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_protocol()
Returns the current protocol of the XBee.
- Returns:
Current protocol of the XBee.
- Return type:
See also
- get_pwm_duty_cycle(io_line)
Returns the PWM duty cycle in % corresponding to the provided IO line.
- Parameters:
io_line (
IOLine) – IO line to get its PWM duty cycle.- Returns:
PWM duty cycle of the given IO line.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If io_line has no PWM capability.
See also
- get_route_to_node(remote, timeout=10, force=True)
Gets the route from this XBee to the given remote node.
- For Zigbee:
‘AR’ parameter of the local node must be configured with a value different from ‘FF’.
Set force to True to force the Zigbee remote node to return its route independently of the local node configuration as high or low RAM concentrator (‘DO’ of the local value)
- Parameters:
remote (
RemoteXBeeDevice) – The remote node.timeout (Float, optional, default=10) – Maximum number of seconds to wait for the route.
force (Boolean) – True to force asking for the route, False otherwise. Only for Zigbee.
- Returns:
- Tuple containing route data:
status (
TransmitStatus): The transmit status.Tuple with route data (None if the route was not read in the provided timeout):
source (
RemoteXBeeDevice): The source node of the route.destination (
RemoteXBeeDevice): The destination node of the route.hops (List): List of intermediate nodes (
RemoteXBeeDevice) ordered from closest to source to closest to destination node (source and destination not included).
- Return type:
Tuple
- get_sync_ops_timeout()
Returns the serial port read timeout.
- Returns:
Serial port read timeout in seconds.
- Return type:
Integer
- get_xbee_device_callbacks()
Returns this XBee internal callbacks for process received packets.
This method is called by the PacketListener associated with this XBee to get its callbacks. These callbacks are executed before user callbacks.
- Returns:
- has_explicit_packets()
Returns if there are pending explicit packets to read. This does not include non-explicit packets.
- Returns:
True if there are pending packets, False otherwise.
- Return type:
Boolean
See also
- has_packets()
Returns if there are pending packets to read. This does not include explicit packets.
- Returns:
True if there are pending packets, False otherwise.
- Return type:
Boolean
See also
- is_apply_changes_enabled()
Returns whether apply changes flag is enabled.
- Returns:
True if apply changes flag is enabled, False otherwise.
- Return type:
Boolean
- is_open()
Returns whether this XBee is open.
- Returns:
Boolean. True if this XBee is open, False otherwise.
- is_remote()
Override method.
See also
- property log
Returns the XBee logger.
- Returns:
The XBee device logger.
- Return type:
Logger
- open(force_settings=False)
Opens the communication with the XBee and loads information about it.
- Parameters:
force_settings (Boolean, optional, default=`False`) – True to open the device ensuring/forcing that the specified serial settings are applied even if the current configuration is different, False to open the device with the current configuration.
- Raises:
TimeoutException – If there is any problem with the communication.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the XBee is already opened.
- property operating_mode
Returns the operating mode of this XBee.
- Returns:
OperatingMode. This XBee operating mode.
- property reachable
Returns whether the XBee is reachable.
- Returns:
True if the device is reachable, False otherwise.
- Return type:
Boolean
- read_device_info(init=True, fire_event=True)
Updates all instance parameters reading them from the XBee.
- Parameters:
init (Boolean, optional, default=`True`) – If False only not initialized parameters are read, all if True.
fire_event (Boolean, optional, default=`True`) – True to throw and update event if any parameter changed, False otherwise.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- read_io_sample()
Returns an IO sample from the XBee containing the value of all enabled digital IO and analog input channels.
- Returns:
IO sample read from the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- reset()
Override method.
See also
- property scan_counter
Returns the scan counter for this node.
- Returns:
The scan counter for this node.
- Return type:
Integer
- send_bluetooth_data(data)
Sends the given data to the Bluetooth interface using a User Data Relay frame.
- Parameters:
data (Bytearray) – Data to send.
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If there is any problem sending the data.
- send_micropython_data(data)
Sends the given data to the MicroPython interface using a User Data Relay frame.
- Parameters:
data (Bytearray) – Data to send.
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If there is any problem sending the data.
- send_packet(packet, sync=False)
Sends the packet and waits for the response. The packet to send is escaped depending on the current operating mode.
This method can be synchronous or asynchronous.
If synchronous, this method discards all response packets until it finds the one that has the appropriate frame ID, that is, the sent packet’s frame ID.
If asynchronous, this method does not wait for any response and returns None.
- Parameters:
packet (
XBeePacket) – The packet to send.sync (Boolean) – True to wait for the response of the sent packet and return it, False otherwise.
- Returns:
- Response packet if sync is True, None
otherwise.
- Return type:
- Raises:
TimeoutException – If sync is True and the response packet for the sent one cannot be read.
InvalidOperatingModeException – If the XBee operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the packet listener is not running or the XBee’s communication interface is closed.
See also
- send_packet_sync_and_get_response(packet_to_send, timeout=None)
Sends the packet and waits for its corresponding response.
- Parameters:
packet_to_send (
XBeePacket) – The packet to transmit.timeout (Integer, optional, default=`None`) – Number of seconds to wait. -1 to wait indefinitely.
- Returns:
Received response packet.
- Return type:
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
TimeoutException – If response is not received in the configured timeout.
XBeeException – If the XBee’s communication interface is closed.
See also
- send_user_data_relay(local_interface, data)
Sends the given data to the given XBee local interface.
- Parameters:
local_interface (
XBeeLocalInterface) – Destination XBee local interface.data (Bytearray) – Data to send.
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ValueError – If local_interface is None.
XBeeException – If there is any problem sending the User Data Relay.
See also
- property serial_port
Returns the serial port associated to the XBee, if any.
- Returns:
- Serial port of the XBee. None if the
local XBee does not use serial communication.
- Return type:
See also
- set_16bit_addr(value)
Sets the 16-bit address of the XBee.
- Parameters:
value (
XBee16BitAddress) – New 16-bit address of the XBee.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If the protocol is not 802.15.4.
- set_api_output_mode(api_output_mode)
Deprecated since version 1.3: Use
set_api_output_mode_value()Sets the API output mode of the XBee.
- Parameters:
api_output_mode (
APIOutputMode) – New API output mode.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
See also
- set_api_output_mode_value(api_output_mode)
Sets the API output mode of the XBee.
- Parameters:
api_output_mode (Integer) – New API output mode options. Calculate this value using the method
APIOutputModeBit.calculate_api_output_mode_value()with a set ofAPIOutputModeBit.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
See also
- set_dio_change_detection(io_lines_set)
Sets the digital IO lines to be monitored and sampled whenever their status changes. A None set of lines disables this feature.
- Parameters:
io_lines_set – Set of
IOLine.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_dio_value(io_line, io_value)
Sets the digital value (high or low) to the provided IO line.
- Parameters:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- set_io_configuration(io_line, io_mode)
Sets the configuration of the provided IO line.
- Parameters:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_io_sampling_rate(rate)
Sets the IO sampling rate of the XBee in seconds. A sample rate of 0 means the IO sampling feature is disabled.
- Parameters:
rate (Integer) – New IO sampling rate of the XBee in seconds.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_node_id(node_id)
Sets the node identifier (‘NI`) value of the XBee.
- Parameters:
node_id (String) – New node identifier (‘NI’) of the XBee.
- Raises:
ValueError – If node_id is None or its length is greater than 20.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- set_parameter(parameter, value, apply=None)
Override.
- set_power_level(power_level)
Sets the power level of the XBee.
- Parameters:
power_level (
PowerLevel) – New power level of the XBee.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_pwm_duty_cycle(io_line, cycle)
Sets the duty cycle in % of the provided IO line.
The provided IO line must be PWM-capable, previously configured as PWM output.
- Parameters:
io_line (
IOLine) – IO Line to be assigned.cycle (Integer) – Duty cycle in % to be assigned. Must be between 0 and 100.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If the given IO line does not have PWM capability or cycle is not between 0 and 100.
See also
- set_sync_ops_timeout(sync_ops_timeout)
Sets the serial port read timeout.
- Parameters:
sync_ops_timeout (Integer) – Read timeout in seconds.
- property stats
Gets the statistics for this XBee.
- Returns:
Statistics. XBee statistics.
- update_bluetooth_password(new_password, apply=True, save=True)
Changes the Bluetooth password of this XBee with the new one provided.
Note that your device must include Bluetooth Low Energy support.
- Parameters:
new_password (String) – New Bluetooth password.
apply (Boolean, optional, default=`True`) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
save (Boolean, optional, default=`True`) – True to save changes, False otherwise.
- Raises:
ValueError – If new_password is invalid.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- update_bluetooth_salt_verifier(salt, verifier, apply=True, save=True)
Changes the Bluetooth password of this XBee with the new one provided.
Note that your device must include Bluetooth Low Energy support.
- Parameters:
salt (bytes) – New Bluetooth password.
verifier (bytes) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
apply (Boolean, optional, default=`True`) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
save (Boolean, optional, default=`True`) – True to save changes, False otherwise.
- Raises:
ValueError – If salt or verifier are invalid.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- update_device_data_from(device)
Updates the current node information with provided data. This is only for internal use.
- Parameters:
device (
AbstractXBeeDevice) – XBee to get the data from.- Returns:
True if the node data has been updated, False otherwise.
- Return type:
Boolean
- update_firmware(xml_firmware_file, xbee_firmware_file=None, bootloader_firmware_file=None, timeout=None, progress_callback=None)
Performs a firmware update operation of the XBee.
- Parameters:
xml_firmware_file (String) – Path of the XML file that describes the firmware to upload.
xbee_firmware_file (String, optional, default=`None`) – Location of the XBee binary firmware file.
bootloader_firmware_file (String, optional, default=`None`) – Location of the bootloader binary firmware file.
timeout (Integer, optional, default=`None`) – Maximum time to wait for target read operations during the update process (seconds).
progress_callback (Function, optional, default=`None`) –
Function to 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 XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
OperationNotSupportedException – If XBee does not support firmware update.
FirmwareUpdateException – If there is any error during the firmware update.
- write_changes()
Writes configurable parameter values to the non-volatile memory of the XBee so that parameter modifications persist through subsequent resets.
Parameters values remain in the device’s memory until overwritten by subsequent use of this method.
If changes are made without writing them, the XBee reverts back to previously saved parameters the next time the module is powered-on.
Writing the parameter modifications does not mean those values are immediately applied, this depends on the status of the ‘apply configuration changes’ option. Use method
is_apply_changes_enabled()to get its status andenable_apply_changes()to enable/disable the option. Methodapply_changes()can be used in order to manually apply the changes.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- class digi.xbee.devices.CellularDevice(port=None, baud_rate=None, data_bits=serial.EIGHTBITS, stop_bits=serial.STOPBITS_ONE, parity=serial.PARITY_NONE, flow_control=FlowControl.NONE, _sync_ops_timeout=4, comm_iface=None)[source]
Bases:
IPDeviceThis class represents a local Cellular device.
Class constructor. Instantiates a new
CellularDevicewith the provided parameters.- Parameters:
port (String) – Serial port identifier. Depends on operating system. e.g. ‘/dev/ttyUSB0’ on ‘GNU/Linux’ or ‘COM3’ on Windows.
baud_rate (Integer) – Serial port baud rate.
(Integer (_sync_ops_timeout) –
serial.EIGHTBITS): Port bitsize.default –
serial.EIGHTBITS): Port bitsize.(Integer –
serial.STOPBITS_ONE): Port stop bits.default –
serial.STOPBITS_ONE): Port stop bits.(Character (parity) –
serial.PARITY_NONE): Port parity.default –
serial.PARITY_NONE): Port parity.(Integer –
FlowControl.NONE): Port flow control.default –
FlowControl.NONE): Port flow control.(Integer – 3): Read timeout (in seconds).
default – 3): Read timeout (in seconds).
comm_iface (
XBeeCommunicationInterface) – Communication interface.
:raises All exceptions raised by
XBeeDevice.__init__()constructor.:See also
XBeeDevice.__init__()- is_connected()[source]
Returns whether the device is connected to the Internet.
- Returns:
True if connected to the Internet, False otherwise.
- Return type:
Boolean
- Raises:
TimeoutException – If there is a timeout getting the association indication status.
XBeeException – If there is any other XBee related exception.
- get_cellular_ai_status()[source]
Returns the current association status of this Cellular device.
It indicates occurrences of errors during the modem initialization and connection.
- Returns:
- The association
indication status of the Cellular device.
- Return type:
- Raises:
TimeoutException – If there is a timeout getting the association indication status.
XBeeException – If there is any other XBee related exception.
- add_sms_callback(callback)[source]
Adds a callback for the event
SMSReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The data received as an
SMSMessage
- del_sms_callback(callback)[source]
Deletes a callback for the callback list of
SMSReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- get_imei_addr()[source]
Returns the IMEI address of this Cellular device.
To refresh this value use the method
CellularDevice.read_device_info().- Returns:
The IMEI address of this Cellular device.
- Return type:
- send_sms(phone_number, data)[source]
Sends the provided SMS message to the given phone number.
This method blocks until a success or error response arrives or the configured receive timeout expires.
For non-blocking operations use the method
CellularDevice.send_sms_async().- Parameters:
phone_number (String) – The phone number to send the SMS to.
data (String) – Text of the SMS.
- Raises:
ValueError – If phone_number or data is None.
OperationNotSupportedException – If the device is remote.
TimeoutException – If there is a timeout sending the SMS.
XBeeException – If there is any other XBee related exception.
- send_sms_async(phone_number, data)[source]
Sends asynchronously the provided SMS to the given phone number.
Asynchronous transmissions do not wait for answer or for transmit status packet.
- Parameters:
phone_number (String) – The phone number to send the SMS to.
data (String) – Text of the SMS.
- Raises:
ValueError – If phone_number or data is None.
OperationNotSupportedException – If the device is remote.
XBeeException – If there is any other XBee related exception.
- get_sockets_list()[source]
Returns a list with the IDs of all active (open) sockets.
- Returns:
- list with the IDs of all active (open) sockets, or empty list
if there is not any active socket.
- Return type:
List
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
TimeoutException – If the response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
- get_socket_info(socket_id)[source]
Returns the information of the socket with the given socket ID.
- Parameters:
socket_id (Integer) – ID of the socket.
- Returns:
- The socket information, or None if the
socket with that ID does not exist.
- Return type:
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
TimeoutException – If the response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
See also
- add_io_sample_received_callback(callback)[source]
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- del_io_sample_received_callback(callback)[source]
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- set_dio_change_detection(io_lines_set)[source]
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- get_io_sampling_rate()[source]
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- set_io_sampling_rate(rate)[source]
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- get_node_id()[source]
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- set_node_id(node_id)[source]
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- get_power_level()[source]
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- set_power_level(power_level)[source]
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- TIMEOUT_READ_PACKET = 3
Timeout to read packets.
- add_bluetooth_data_received_callback(callback)
Adds a callback for the event
BluetoothDataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The Bluetooth data as a Bytearray.
- add_data_received_callback(callback)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- add_expl_data_received_callback(callback)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- add_fs_frame_received_callback(callback)
Adds a callback for the event
FileSystemFrameReceived.- Parameters:
callback (Function) –
The callback. Receives four arguments.
Source (
AbstractXBeeDevice): The node that sent the file system frame.Frame id (Integer): The received frame id.
Command (
FSCmd): The file system command.Receive options (Integer): Bitfield indicating receive options.
See also
- add_ip_data_received_callback(callback)
Adds a callback for the event
IPDataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The data received as an
IPMessage
- add_micropython_data_received_callback(callback)
Adds a callback for the event
MicroPythonDataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The MicroPython data as a Bytearray.
- add_modem_status_received_callback(callback)
Adds a callback for the event
ModemStatusReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The modem status as a
ModemStatus.
- add_packet_received_callback(callback)
Adds a callback for the event
PacketReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The received packet as a
XBeeAPIPacket.
- add_route_received_callback(callback)
Adds a callback for the event
RouteReceived. This works for Zigbee and Digimesh devices.- Parameters:
callback (Function) –
The callback. Receives three arguments.
source (
XBeeDevice): The source node.destination (
RemoteXBeeDevice): The destination node.- hops (List): List of intermediate hops from closest to source
to closest to destination (
RemoteXBeeDevice).
- add_socket_data_received_callback(callback)
Adds a callback for the event
SocketDataReceived.- Parameters:
callback (Function) –
The callback. Receives two arguments.
The socket ID as an Integer.
The data received as Bytearray.
- add_socket_data_received_from_callback(callback)
Adds a callback for the event
SocketDataReceivedFrom.- Parameters:
callback (Function) –
The callback. Receives three arguments.
The socket ID as an Integer.
- Source address pair (host, port) where host is a string
representing an IPv4 address like ‘100.50.200.5’, and port is an integer.
The data received as Bytearray.
- add_socket_state_received_callback(callback)
Adds a callback for the event
SocketStateReceived.- Parameters:
callback (Function) –
The callback. Receives two arguments.
The socket ID as an Integer.
The state received as a
SocketState.
- add_user_data_relay_received_callback(callback)
Adds a callback for the event
RelayDataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The relay data as a
UserDataRelayMessage.
- apply_changes()
Applies changes via ‘AC’ command.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- apply_profile(profile_path, timeout=None, progress_callback=None)
Applies the given XBee profile to the XBee.
- Parameters:
profile_path (String) – Path of the XBee profile file to apply.
timeout (Integer, optional, default=`None`) – Maximum time to wait for target read operations during the apply profile (seconds).
progress_callback (Function, optional, default=`None`) –
Function 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 XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
UpdateProfileException – If there is any error applying the XBee profile.
- property br
Returns the BR value of the device.
- Returns:
The BR value of the device.
- Return type:
Integer
- close()
Closes the communication with the XBee.
This method guarantees that all threads running are stopped and the serial port is closed.
- property comm_iface
Returns the hardware interface associated to the XBee.
- Returns:
Hardware interface of the XBee.
- Return type:
See also
- classmethod create_xbee_device(comm_port_data)
Creates and returns an
XBeeDevicefrom data of the port to which is connected.- Parameters:
comm_port_data (Dictionary) – Dictionary with all comm port data needed.
are (The dictionary keys) –
“baudRate” –> Baud rate.”port” –> Port number.”bitSize” –> Bit size.”stopBits” –> Stop bits.”parity” –> Parity.”flowControl” –> Flow control.”timeout” for –> Timeout for synchronous operations (in seconds).
- Returns:
XBee object created.
- Return type:
- Raises:
SerialException – If the port to open does not exist or is already opened.
See also
- del_bluetooth_data_received_callback(callback)
Deletes a callback for the callback list of
BluetoothDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_data_received_callback(callback)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- del_expl_data_received_callback(callback)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- del_fs_frame_received_callback(callback)
Deletes a callback for the callback list of
FileSystemFrameReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_ip_data_received_callback(callback)
Deletes a callback for the callback list of
IPDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_micropython_data_received_callback(callback)
Deletes a callback for the callback list of
MicroPythonDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_modem_status_received_callback(callback)
Deletes a callback for the callback list of
ModemStatusReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_packet_received_callback(callback)
Deletes a callback for the callback list of
PacketReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_route_received_callback(callback)
Deletes a callback for the callback list of
RouteReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_socket_data_received_callback(callback)
Deletes a callback for the callback list of
SocketDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_socket_data_received_from_callback(callback)
Deletes a callback for the callback list of
SocketDataReceivedFromevent.- Parameters:
callback (Function) – The callback to delete.
- del_socket_state_received_callback(callback)
Deletes a callback for the callback list of
SocketStateReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_user_data_relay_received_callback(callback)
Deletes a callback for the callback list of
RelayDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- determine_protocol(hardware_version, firmware_version)
Determines the XBee protocol based on the given hardware and firmware versions.
- Parameters:
hardware_version (Integer) – Hardware version to get its protocol.
firmware_version (Bytearray) – Firmware version to get its protocol.
- Returns:
- XBee protocol corresponding to the given
hardware and firmware versions.
- Return type:
- disable_bluetooth()
Disables the Bluetooth interface of this XBee.
Note that your device must include Bluetooth Low Energy support.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- enable_apply_changes(value)
Sets apply changes flag.
- Parameters:
value (Boolean) – True to enable apply changes flag, False to disable it.
- enable_bluetooth()
Enables the Bluetooth interface of this XBee.
To work with this interface, you must also configure the Bluetooth password if not done previously. Use method
AbstractXBeeDevice.update_bluetooth_password().Note that your XBee must include Bluetooth Low Energy support.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- execute_command(parameter, value=None, apply=None)
Executes the provided command.
- Parameters:
or (parameter (String) – class: .ATStringCommand): AT command to execute.
value (bytearray, optional, default=`None`) – Command value (if any).
apply (Boolean, optional, default=`None`) – True to apply changes in XBee configuration, False not to apply them, None to use is_apply_changes_enabled() returned value.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- flush_queues()
Flushes the packets queue.
- get_16bit_addr()
Deprecated.
This protocol does not have an associated 16-bit address.
- get_adc_value(io_line)
Returns the analog value of the provided IO line.
The provided IO line must be previously configured as ADC. To do so, use
AbstractXBeeDevice.set_io_configuration()andIOMode.ADC.- Parameters:
io_line (
IOLine) – IO line to get its ADC value.- Returns:
Analog value corresponding to the provided IO line.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If response does not contain the value for the given IO line.
See also
- get_api_output_mode()
Deprecated since version 1.3: Use
get_api_output_mode_value()Returns the API output mode of the XBee.
The API output mode determines the format of the data through the serial interface of the XBee.
- Returns:
API output mode of the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_api_output_mode_value()
Returns the API output mode of the XBee.
The API output mode determines the format that the received data is output through the serial interface of the XBee.
- Returns:
the parameter value.
- Return type:
Bytearray
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
- get_bluetooth_mac_addr()
Reads and returns the EUI-48 Bluetooth MAC address of this XBee following the format 00112233AABB.
Note that your device must include Bluetooth Low Energy support.
- Returns:
The Bluetooth MAC address.
- Return type:
String
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- get_current_frame_id()
Returns the last used frame ID.
- Returns:
Last used frame ID.
- Return type:
Integer
- get_dest_address()
Deprecated.
Operation not supported in this protocol. Use
IPDevice.get_dest_ip_addr()instead. This method raises anAttributeError.
- get_dest_ip_addr()
Returns the destination IP address.
- Returns:
Configured destination IP address.
- Return type:
ipaddress.IPv4Address- Raises:
TimeoutException – If there is a timeout getting the destination IP address.
XBeeException – If there is any other XBee related exception.
See also
ipaddress.IPv4Address
- get_dio_value(io_line)
Returns the digital value of the provided IO line.
The provided IO line must be previously configured as digital I/O. To do so, use
AbstractXBeeDevice.set_io_configuration().- Parameters:
io_line (
IOLine) – the DIO line to gets its digital value.- Returns:
current value of the provided IO line.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If response does not contain the value for the given IO line.
See also
- get_file_manager()
Returns the file system manager for the XBee.
- Returns:
The file system manager.
- Return type:
- Raises:
FileSystemNotSupportedException – If the XBee does not support filesystem.
- get_firmware_version()
Returns the firmware version of the XBee.
- Returns:
Firmware version of the XBee.
- Return type:
Bytearray
- get_hardware_version()
Returns the hardware version of the XBee.
- Returns:
Hardware version of the XBee.
- Return type:
See also
- get_io_configuration(io_line)
Returns the configuration of the provided IO line.
- Parameters:
io_line (
IOLine) – IO line to get its configuration.- Returns:
IO mode of the IO line provided.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_ip_addr()
Returns the IP address of this IP XBee.
To refresh this value use the method
IPDevice.read_device_info().- Returns:
The IP address of this IP device.
- Return type:
ipaddress.IPv4Address
See also
ipaddress.IPv4Address
- get_network()
Deprecated.
This protocol does not support the network functionality.
- get_next_frame_id()
Returns the next frame ID of the XBee.
- Returns:
The next frame ID of the XBee.
- Return type:
Integer
- get_pan_id()
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- get_parameter(parameter, parameter_value=None, apply=None)
Override.
See also
- get_pwm_duty_cycle(io_line)
Returns the PWM duty cycle in % corresponding to the provided IO line.
- Parameters:
io_line (
IOLine) – IO line to get its PWM duty cycle.- Returns:
PWM duty cycle of the given IO line.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If io_line has no PWM capability.
See also
- get_route_to_node(remote, timeout=10, force=True)
Gets the route from this XBee to the given remote node.
- For Zigbee:
‘AR’ parameter of the local node must be configured with a value different from ‘FF’.
Set force to True to force the Zigbee remote node to return its route independently of the local node configuration as high or low RAM concentrator (‘DO’ of the local value)
- Parameters:
remote (
RemoteXBeeDevice) – The remote node.timeout (Float, optional, default=10) – Maximum number of seconds to wait for the route.
force (Boolean) – True to force asking for the route, False otherwise. Only for Zigbee.
- Returns:
- Tuple containing route data:
status (
TransmitStatus): The transmit status.Tuple with route data (None if the route was not read in the provided timeout):
source (
RemoteXBeeDevice): The source node of the route.destination (
RemoteXBeeDevice): The destination node of the route.hops (List): List of intermediate nodes (
RemoteXBeeDevice) ordered from closest to source to closest to destination node (source and destination not included).
- Return type:
Tuple
- get_sync_ops_timeout()
Returns the serial port read timeout.
- Returns:
Serial port read timeout in seconds.
- Return type:
Integer
- get_xbee_device_callbacks()
Returns this XBee internal callbacks for process received packets.
This method is called by the PacketListener associated with this XBee to get its callbacks. These callbacks are executed before user callbacks.
- Returns:
- has_explicit_packets()
Returns if there are pending explicit packets to read. This does not include non-explicit packets.
- Returns:
True if there are pending packets, False otherwise.
- Return type:
Boolean
See also
- has_packets()
Returns if there are pending packets to read. This does not include explicit packets.
- Returns:
True if there are pending packets, False otherwise.
- Return type:
Boolean
See also
- is_apply_changes_enabled()
Returns whether apply changes flag is enabled.
- Returns:
True if apply changes flag is enabled, False otherwise.
- Return type:
Boolean
- is_open()
Returns whether this XBee is open.
- Returns:
Boolean. True if this XBee is open, False otherwise.
- is_remote()
Override method.
See also
- property log
Returns the XBee logger.
- Returns:
The XBee device logger.
- Return type:
Logger
- property operating_mode
Returns the operating mode of this XBee.
- Returns:
OperatingMode. This XBee operating mode.
- property reachable
Returns whether the XBee is reachable.
- Returns:
True if the device is reachable, False otherwise.
- Return type:
Boolean
- read_data(timeout=None)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- read_data_from(remote_xbee, timeout=None)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- read_device_info(init=True, fire_event=True)
Updates all instance parameters reading them from the XBee.
- Parameters:
init (Boolean, optional, default=`True`) – If False only not initialized parameters are read, all if True.
fire_event (Boolean, optional, default=`True`) – True to throw and update event if any parameter changed, False otherwise.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- read_expl_data(timeout=None)
Override.
Operation not supported in this protocol. This method raises an
AttributeError.
- read_expl_data_from(remote_xbee, timeout=None)
Override.
Operation not supported in this protocol. This method raises an
AttributeError.
- read_io_sample()
Returns an IO sample from the XBee containing the value of all enabled digital IO and analog input channels.
- Returns:
IO sample read from the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- read_ip_data(timeout=3)
Reads new IP data received by this XBee during the provided timeout.
This method blocks until new IP data is received or the provided timeout expires.
For non-blocking operations, register a callback and use the method
IPDevice.add_ip_data_received_callback().Before reading IP data you need to start listening for incoming IP data at a specific port. Use the method
IPDevice.start_listening()for that purpose. When finished, you can use the methodIPDevice.stop_listening()to stop listening for incoming IP data.- Parameters:
timeout (Integer, optional) – The time to wait for new IP data in seconds.
- Returns:
IP message, None if this device did not receive new data.
- Return type:
- Raises:
ValueError – If timeout is less than 0.
- read_ip_data_from(ip_addr, timeout=3)
Reads new IP data received from the given IP address during the provided timeout.
This method blocks until new IP data from the provided IP address is received or the given timeout expires.
For non-blocking operations, register a callback and use the method
IPDevice.add_ip_data_received_callback().Before reading IP data you need to start listening for incoming IP data at a specific port. Use the method
IPDevice.start_listening()for that purpose. When finished, you can use the methodIPDevice.stop_listening()to stop listening for incoming IP data.- Parameters:
ip_addr (
ipaddress.IPv4Address) – The IP address to read data from.timeout (Integer, optional) – The time to wait for new IP data in seconds.
- Returns:
- IP message, None if this device did not
receive new data from the provided IP address.
- Return type:
- Raises:
ValueError – If timeout is less than 0.
- reset()
Override method.
See also
- property scan_counter
Returns the scan counter for this node.
- Returns:
The scan counter for this node.
- Return type:
Integer
- send_bluetooth_data(data)
Sends the given data to the Bluetooth interface using a User Data Relay frame.
- Parameters:
data (Bytearray) – Data to send.
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If there is any problem sending the data.
- send_data(remote_xbee, data, transmit_options=0)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- send_data_async(remote_xbee, data, transmit_options=0)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- send_data_broadcast(data, transmit_options=0)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- send_expl_data(remote_xbee, data, src_endpoint, dest_endpoint, cluster_id, profile_id, transmit_options=0)
Override.
Operation not supported in this protocol. This method raises an
AttributeError.
- send_expl_data_async(remote_xbee, data, src_endpoint, dest_endpoint, cluster_id, profile_id, transmit_options=0)
Override.
Operation not supported in this protocol. This method raises an
AttributeError.
- send_expl_data_broadcast(data, src_endpoint, dest_endpoint, cluster_id, profile_id, transmit_options=0)
Override.
Operation not supported in this protocol. This method raises an
AttributeError.
- send_ip_data(ip_addr, dest_port, protocol, data, close_socket=False)
Sends the provided IP data to the given IP address and port using the specified IP protocol. For TCP and TCP SSL protocols, you can also indicate if the socket should be closed when data is sent.
This method blocks until a success or error response arrives or the configured receive timeout expires.
- Parameters:
ip_addr (
ipaddress.IPv4Address) – The IP address to send IP data to.dest_port (Integer) – The destination port of the transmission.
protocol (
IPProtocol) – The IP protocol used for the transmission.data (String or Bytearray) – The IP data to be sent.
close_socket (Boolean, optional, default=`False`) – True to close the socket just after the transmission. False to keep it open.
- Raises:
ValueError – If ip_addr or protocol or data is None or dest_port is less than 0 or greater than 65535.
OperationNotSupportedException – If the XBee is remote.
TimeoutException – If there is a timeout sending the data.
XBeeException – If there is any other XBee related exception.
- send_ip_data_async(ip_addr, dest_port, protocol, data, close_socket=False)
Sends the provided IP data to the given IP address and port asynchronously using the specified IP protocol. For TCP and TCP SSL protocols, you can also indicate if the socket should be closed when data is sent.
Asynchronous transmissions do not wait for answer from the remote device or for transmit status packet.
- Parameters:
ip_addr (
ipaddress.IPv4Address) – The IP address to send IP data to.dest_port (Integer) – The destination port of the transmission.
protocol (
IPProtocol) – The IP protocol used for the transmission.data (String or Bytearray) – The IP data to be sent.
close_socket (Boolean, optional, default=`False`) – True to close the socket just after the transmission. False to keep it open.
- Raises:
ValueError – If ip_addr or protocol or data is None or dest_port is less than 0 or greater than 65535.
OperationNotSupportedException – If the XBee is remote.
XBeeException – If there is any other XBee related exception.
- send_ip_data_broadcast(dest_port, data)
Sends the provided IP data to all clients.
This method blocks until a success or error transmit status arrives or the configured receive timeout expires.
- Parameters:
dest_port (Integer) – The destination port of the transmission.
data (String or Bytearray) – The IP data to be sent.
- Raises:
ValueError – If data is None or dest_port is less than 0 or greater than 65535.
TimeoutException – If there is a timeout sending the data.
XBeeException – If there is any other XBee related exception.
- send_micropython_data(data)
Sends the given data to the MicroPython interface using a User Data Relay frame.
- Parameters:
data (Bytearray) – Data to send.
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If there is any problem sending the data.
- send_packet(packet, sync=False)
Sends the packet and waits for the response. The packet to send is escaped depending on the current operating mode.
This method can be synchronous or asynchronous.
If synchronous, this method discards all response packets until it finds the one that has the appropriate frame ID, that is, the sent packet’s frame ID.
If asynchronous, this method does not wait for any response and returns None.
- Parameters:
packet (
XBeePacket) – The packet to send.sync (Boolean) – True to wait for the response of the sent packet and return it, False otherwise.
- Returns:
- Response packet if sync is True, None
otherwise.
- Return type:
- Raises:
TimeoutException – If sync is True and the response packet for the sent one cannot be read.
InvalidOperatingModeException – If the XBee operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the packet listener is not running or the XBee’s communication interface is closed.
See also
- send_packet_sync_and_get_response(packet_to_send, timeout=None)
Sends the packet and waits for its corresponding response.
- Parameters:
packet_to_send (
XBeePacket) – The packet to transmit.timeout (Integer, optional, default=`None`) – Number of seconds to wait. -1 to wait indefinitely.
- Returns:
Received response packet.
- Return type:
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
TimeoutException – If response is not received in the configured timeout.
XBeeException – If the XBee’s communication interface is closed.
See also
- send_user_data_relay(local_interface, data)
Sends the given data to the given XBee local interface.
- Parameters:
local_interface (
XBeeLocalInterface) – Destination XBee local interface.data (Bytearray) – Data to send.
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ValueError – If local_interface is None.
XBeeException – If there is any problem sending the User Data Relay.
See also
- property serial_port
Returns the serial port associated to the XBee, if any.
- Returns:
- Serial port of the XBee. None if the
local XBee does not use serial communication.
- Return type:
See also
- set_16bit_addr(value)
Sets the 16-bit address of the XBee.
- Parameters:
value (
XBee16BitAddress) – New 16-bit address of the XBee.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If the protocol is not 802.15.4.
- set_api_output_mode(api_output_mode)
Deprecated since version 1.3: Use
set_api_output_mode_value()Sets the API output mode of the XBee.
- Parameters:
api_output_mode (
APIOutputMode) – New API output mode.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
See also
- set_api_output_mode_value(api_output_mode)
Sets the API output mode of the XBee.
- Parameters:
api_output_mode (Integer) – New API output mode options. Calculate this value using the method
APIOutputModeBit.calculate_api_output_mode_value()with a set ofAPIOutputModeBit.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
See also
- set_dest_address(addr)
Deprecated.
Operation not supported in this protocol. Use
IPDevice.set_dest_ip_addr()instead. This method raises anAttributeError.
- set_dest_ip_addr(address)
Sets the destination IP address.
- Parameters:
address (
ipaddress.IPv4Address) – Destination IP address.- Raises:
ValueError – If address is None.
TimeoutException – If there is a timeout setting the destination IP address.
XBeeException – If there is any other XBee related exception.
See also
ipaddress.IPv4Address
- set_dio_value(io_line, io_value)
Sets the digital value (high or low) to the provided IO line.
- Parameters:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- set_io_configuration(io_line, io_mode)
Sets the configuration of the provided IO line.
- Parameters:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_pan_id(value)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- set_parameter(parameter, value, apply=None)
Override.
- set_pwm_duty_cycle(io_line, cycle)
Sets the duty cycle in % of the provided IO line.
The provided IO line must be PWM-capable, previously configured as PWM output.
- Parameters:
io_line (
IOLine) – IO Line to be assigned.cycle (Integer) – Duty cycle in % to be assigned. Must be between 0 and 100.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If the given IO line does not have PWM capability or cycle is not between 0 and 100.
See also
- set_sync_ops_timeout(sync_ops_timeout)
Sets the serial port read timeout.
- Parameters:
sync_ops_timeout (Integer) – Read timeout in seconds.
- start_listening(src_port)
Starts listening for incoming IP transmissions in the provided port.
- Parameters:
src_port (Integer) – Port to listen for incoming transmissions.
- Raises:
ValueError – If source_port is less than 0 or greater than 65535.
TimeoutException – If there is a timeout setting the source port.
XBeeException – If there is any other XBee related exception.
- property stats
Gets the statistics for this XBee.
- Returns:
Statistics. XBee statistics.
- stop_listening()
Stops listening for incoming IP transmissions.
- Raises:
TimeoutException – If there is a timeout processing the operation.
XBeeException – If there is any other XBee related exception.
- update_bluetooth_password(new_password, apply=True, save=True)
Changes the Bluetooth password of this XBee with the new one provided.
Note that your device must include Bluetooth Low Energy support.
- Parameters:
new_password (String) – New Bluetooth password.
apply (Boolean, optional, default=`True`) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
save (Boolean, optional, default=`True`) – True to save changes, False otherwise.
- Raises:
ValueError – If new_password is invalid.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- update_bluetooth_salt_verifier(salt, verifier, apply=True, save=True)
Changes the Bluetooth password of this XBee with the new one provided.
Note that your device must include Bluetooth Low Energy support.
- Parameters:
salt (bytes) – New Bluetooth password.
verifier (bytes) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
apply (Boolean, optional, default=`True`) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
save (Boolean, optional, default=`True`) – True to save changes, False otherwise.
- Raises:
ValueError – If salt or verifier are invalid.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- update_device_data_from(device)
Updates the current node information with provided data. This is only for internal use.
- Parameters:
device (
AbstractXBeeDevice) – XBee to get the data from.- Returns:
True if the node data has been updated, False otherwise.
- Return type:
Boolean
- update_firmware(xml_firmware_file, xbee_firmware_file=None, bootloader_firmware_file=None, timeout=None, progress_callback=None)
Performs a firmware update operation of the XBee.
- Parameters:
xml_firmware_file (String) – Path of the XML file that describes the firmware to upload.
xbee_firmware_file (String, optional, default=`None`) – Location of the XBee binary firmware file.
bootloader_firmware_file (String, optional, default=`None`) – Location of the bootloader binary firmware file.
timeout (Integer, optional, default=`None`) – Maximum time to wait for target read operations during the update process (seconds).
progress_callback (Function, optional, default=`None`) –
Function to 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 XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
OperationNotSupportedException – If XBee does not support firmware update.
FirmwareUpdateException – If there is any error during the firmware update.
- write_changes()
Writes configurable parameter values to the non-volatile memory of the XBee so that parameter modifications persist through subsequent resets.
Parameters values remain in the device’s memory until overwritten by subsequent use of this method.
If changes are made without writing them, the XBee reverts back to previously saved parameters the next time the module is powered-on.
Writing the parameter modifications does not mean those values are immediately applied, this depends on the status of the ‘apply configuration changes’ option. Use method
is_apply_changes_enabled()to get its status andenable_apply_changes()to enable/disable the option. Methodapply_changes()can be used in order to manually apply the changes.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- class digi.xbee.devices.LPWANDevice(port=None, baud_rate=None, data_bits=serial.EIGHTBITS, stop_bits=serial.STOPBITS_ONE, parity=serial.PARITY_NONE, flow_control=FlowControl.NONE, _sync_ops_timeout=4, comm_iface=None)[source]
Bases:
CellularDeviceThis class provides common functionality for XBee Low-Power Wide-Area Network devices.
Class constructor. Instantiates a new
LPWANDevicewith the provided parameters.- Parameters:
port (String) – Serial port identifier. Depends on operating system. e.g. ‘/dev/ttyUSB0’ on ‘GNU/Linux’ or ‘COM3’ on Windows.
baud_rate (Integer) – Serial port baud rate.
(Integer (_sync_ops_timeout) –
serial.EIGHTBITS): Port bitsize.default –
serial.EIGHTBITS): Port bitsize.(Integer –
serial.STOPBITS_ONE): Port stop bits.default –
serial.STOPBITS_ONE): Port stop bits.(Character (parity) –
serial.PARITY_NONE): Port parity.default –
serial.PARITY_NONE): Port parity.(Integer –
FlowControl.NONE): Port flow control.default –
FlowControl.NONE): Port flow control.(Integer – 3): Read timeout (in seconds).
default – 3): Read timeout (in seconds).
comm_iface (
XBeeCommunicationInterface) – Communication interface.
:raises All exceptions raised by
XBeeDevice.__init__()constructor.:See also
CellularDevice.__init__()- send_ip_data(ip_addr, dest_port, protocol, data, close_socket=False)[source]
Sends the provided IP data to the given IP address and port using the specified IP protocol.
This method blocks until a success or error response arrives or the configured receive timeout expires.
- Parameters:
ip_addr (
ipaddress.IPv4Address) – The IP address to send IP data to.dest_port (Integer) – The destination port of the transmission.
protocol (
IPProtocol) – The IP protocol used for the transmission.data (String or Bytearray) – The IP data to be sent.
close_socket (Boolean, optional) – Must be False.
- Raises:
ValueError – If protocol is not UDP.
- send_ip_data_async(ip_addr, dest_port, protocol, data, close_socket=False)[source]
Sends the provided IP data to the given IP address and port asynchronously using the specified IP protocol.
Asynchronous transmissions do not wait for answer from the remote device or for transmit status packet.
- Parameters:
ip_addr (
ipaddress.IPv4Address) – The IP address to send IP data to.dest_port (Integer) – The destination port of the transmission.
protocol (
IPProtocol) – The IP protocol used for the transmission.data (String or Bytearray) – The IP data to be sent.
close_socket (Boolean, optional) – Must be False.
- Raises:
ValueError – If protocol is not UDP.
- add_sms_callback(callback)[source]
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- del_sms_callback(callback)[source]
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- send_sms(phone_number, data)[source]
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- send_sms_async(phone_number, data)[source]
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- TIMEOUT_READ_PACKET = 3
Timeout to read packets.
- add_bluetooth_data_received_callback(callback)
Adds a callback for the event
BluetoothDataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The Bluetooth data as a Bytearray.
- add_data_received_callback(callback)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- add_expl_data_received_callback(callback)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- add_fs_frame_received_callback(callback)
Adds a callback for the event
FileSystemFrameReceived.- Parameters:
callback (Function) –
The callback. Receives four arguments.
Source (
AbstractXBeeDevice): The node that sent the file system frame.Frame id (Integer): The received frame id.
Command (
FSCmd): The file system command.Receive options (Integer): Bitfield indicating receive options.
See also
- add_io_sample_received_callback(callback)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- add_ip_data_received_callback(callback)
Adds a callback for the event
IPDataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The data received as an
IPMessage
- add_micropython_data_received_callback(callback)
Adds a callback for the event
MicroPythonDataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The MicroPython data as a Bytearray.
- add_modem_status_received_callback(callback)
Adds a callback for the event
ModemStatusReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The modem status as a
ModemStatus.
- add_packet_received_callback(callback)
Adds a callback for the event
PacketReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The received packet as a
XBeeAPIPacket.
- add_route_received_callback(callback)
Adds a callback for the event
RouteReceived. This works for Zigbee and Digimesh devices.- Parameters:
callback (Function) –
The callback. Receives three arguments.
source (
XBeeDevice): The source node.destination (
RemoteXBeeDevice): The destination node.- hops (List): List of intermediate hops from closest to source
to closest to destination (
RemoteXBeeDevice).
- add_socket_data_received_callback(callback)
Adds a callback for the event
SocketDataReceived.- Parameters:
callback (Function) –
The callback. Receives two arguments.
The socket ID as an Integer.
The data received as Bytearray.
- add_socket_data_received_from_callback(callback)
Adds a callback for the event
SocketDataReceivedFrom.- Parameters:
callback (Function) –
The callback. Receives three arguments.
The socket ID as an Integer.
- Source address pair (host, port) where host is a string
representing an IPv4 address like ‘100.50.200.5’, and port is an integer.
The data received as Bytearray.
- add_socket_state_received_callback(callback)
Adds a callback for the event
SocketStateReceived.- Parameters:
callback (Function) –
The callback. Receives two arguments.
The socket ID as an Integer.
The state received as a
SocketState.
- add_user_data_relay_received_callback(callback)
Adds a callback for the event
RelayDataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The relay data as a
UserDataRelayMessage.
- apply_changes()
Applies changes via ‘AC’ command.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- apply_profile(profile_path, timeout=None, progress_callback=None)
Applies the given XBee profile to the XBee.
- Parameters:
profile_path (String) – Path of the XBee profile file to apply.
timeout (Integer, optional, default=`None`) – Maximum time to wait for target read operations during the apply profile (seconds).
progress_callback (Function, optional, default=`None`) –
Function 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 XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
UpdateProfileException – If there is any error applying the XBee profile.
- property br
Returns the BR value of the device.
- Returns:
The BR value of the device.
- Return type:
Integer
- close()
Closes the communication with the XBee.
This method guarantees that all threads running are stopped and the serial port is closed.
- property comm_iface
Returns the hardware interface associated to the XBee.
- Returns:
Hardware interface of the XBee.
- Return type:
See also
- classmethod create_xbee_device(comm_port_data)
Creates and returns an
XBeeDevicefrom data of the port to which is connected.- Parameters:
comm_port_data (Dictionary) – Dictionary with all comm port data needed.
are (The dictionary keys) –
“baudRate” –> Baud rate.”port” –> Port number.”bitSize” –> Bit size.”stopBits” –> Stop bits.”parity” –> Parity.”flowControl” –> Flow control.”timeout” for –> Timeout for synchronous operations (in seconds).
- Returns:
XBee object created.
- Return type:
- Raises:
SerialException – If the port to open does not exist or is already opened.
See also
- del_bluetooth_data_received_callback(callback)
Deletes a callback for the callback list of
BluetoothDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_data_received_callback(callback)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- del_expl_data_received_callback(callback)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- del_fs_frame_received_callback(callback)
Deletes a callback for the callback list of
FileSystemFrameReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_io_sample_received_callback(callback)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- del_ip_data_received_callback(callback)
Deletes a callback for the callback list of
IPDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_micropython_data_received_callback(callback)
Deletes a callback for the callback list of
MicroPythonDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_modem_status_received_callback(callback)
Deletes a callback for the callback list of
ModemStatusReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_packet_received_callback(callback)
Deletes a callback for the callback list of
PacketReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_route_received_callback(callback)
Deletes a callback for the callback list of
RouteReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_socket_data_received_callback(callback)
Deletes a callback for the callback list of
SocketDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_socket_data_received_from_callback(callback)
Deletes a callback for the callback list of
SocketDataReceivedFromevent.- Parameters:
callback (Function) – The callback to delete.
- del_socket_state_received_callback(callback)
Deletes a callback for the callback list of
SocketStateReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_user_data_relay_received_callback(callback)
Deletes a callback for the callback list of
RelayDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- determine_protocol(hardware_version, firmware_version)
Determines the XBee protocol based on the given hardware and firmware versions.
- Parameters:
hardware_version (Integer) – Hardware version to get its protocol.
firmware_version (Bytearray) – Firmware version to get its protocol.
- Returns:
- XBee protocol corresponding to the given
hardware and firmware versions.
- Return type:
- disable_bluetooth()
Disables the Bluetooth interface of this XBee.
Note that your device must include Bluetooth Low Energy support.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- enable_apply_changes(value)
Sets apply changes flag.
- Parameters:
value (Boolean) – True to enable apply changes flag, False to disable it.
- enable_bluetooth()
Enables the Bluetooth interface of this XBee.
To work with this interface, you must also configure the Bluetooth password if not done previously. Use method
AbstractXBeeDevice.update_bluetooth_password().Note that your XBee must include Bluetooth Low Energy support.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- execute_command(parameter, value=None, apply=None)
Executes the provided command.
- Parameters:
or (parameter (String) – class: .ATStringCommand): AT command to execute.
value (bytearray, optional, default=`None`) – Command value (if any).
apply (Boolean, optional, default=`None`) – True to apply changes in XBee configuration, False not to apply them, None to use is_apply_changes_enabled() returned value.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- flush_queues()
Flushes the packets queue.
- get_16bit_addr()
Deprecated.
This protocol does not have an associated 16-bit address.
- get_64bit_addr()
Deprecated.
Cellular protocol does not have an associated 64-bit address.
- get_adc_value(io_line)
Returns the analog value of the provided IO line.
The provided IO line must be previously configured as ADC. To do so, use
AbstractXBeeDevice.set_io_configuration()andIOMode.ADC.- Parameters:
io_line (
IOLine) – IO line to get its ADC value.- Returns:
Analog value corresponding to the provided IO line.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If response does not contain the value for the given IO line.
See also
- get_api_output_mode()
Deprecated since version 1.3: Use
get_api_output_mode_value()Returns the API output mode of the XBee.
The API output mode determines the format of the data through the serial interface of the XBee.
- Returns:
API output mode of the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_api_output_mode_value()
Returns the API output mode of the XBee.
The API output mode determines the format that the received data is output through the serial interface of the XBee.
- Returns:
the parameter value.
- Return type:
Bytearray
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
- get_bluetooth_mac_addr()
Reads and returns the EUI-48 Bluetooth MAC address of this XBee following the format 00112233AABB.
Note that your device must include Bluetooth Low Energy support.
- Returns:
The Bluetooth MAC address.
- Return type:
String
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- get_cellular_ai_status()
Returns the current association status of this Cellular device.
It indicates occurrences of errors during the modem initialization and connection.
- Returns:
- The association
indication status of the Cellular device.
- Return type:
- Raises:
TimeoutException – If there is a timeout getting the association indication status.
XBeeException – If there is any other XBee related exception.
- get_current_frame_id()
Returns the last used frame ID.
- Returns:
Last used frame ID.
- Return type:
Integer
- get_dest_address()
Deprecated.
Operation not supported in this protocol. Use
IPDevice.get_dest_ip_addr()instead. This method raises anAttributeError.
- get_dest_ip_addr()
Returns the destination IP address.
- Returns:
Configured destination IP address.
- Return type:
ipaddress.IPv4Address- Raises:
TimeoutException – If there is a timeout getting the destination IP address.
XBeeException – If there is any other XBee related exception.
See also
ipaddress.IPv4Address
- get_dio_value(io_line)
Returns the digital value of the provided IO line.
The provided IO line must be previously configured as digital I/O. To do so, use
AbstractXBeeDevice.set_io_configuration().- Parameters:
io_line (
IOLine) – the DIO line to gets its digital value.- Returns:
current value of the provided IO line.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If response does not contain the value for the given IO line.
See also
- get_file_manager()
Returns the file system manager for the XBee.
- Returns:
The file system manager.
- Return type:
- Raises:
FileSystemNotSupportedException – If the XBee does not support filesystem.
- get_firmware_version()
Returns the firmware version of the XBee.
- Returns:
Firmware version of the XBee.
- Return type:
Bytearray
- get_hardware_version()
Returns the hardware version of the XBee.
- Returns:
Hardware version of the XBee.
- Return type:
See also
- get_imei_addr()
Returns the IMEI address of this Cellular device.
To refresh this value use the method
CellularDevice.read_device_info().- Returns:
The IMEI address of this Cellular device.
- Return type:
- get_io_configuration(io_line)
Returns the configuration of the provided IO line.
- Parameters:
io_line (
IOLine) – IO line to get its configuration.- Returns:
IO mode of the IO line provided.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_io_sampling_rate()
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- get_ip_addr()
Returns the IP address of this IP XBee.
To refresh this value use the method
IPDevice.read_device_info().- Returns:
The IP address of this IP device.
- Return type:
ipaddress.IPv4Address
See also
ipaddress.IPv4Address
- get_network()
Deprecated.
This protocol does not support the network functionality.
- get_next_frame_id()
Returns the next frame ID of the XBee.
- Returns:
The next frame ID of the XBee.
- Return type:
Integer
- get_node_id()
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- get_pan_id()
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- get_parameter(parameter, parameter_value=None, apply=None)
Override.
See also
- get_power_level()
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- get_protocol()
Override.
See also
- get_pwm_duty_cycle(io_line)
Returns the PWM duty cycle in % corresponding to the provided IO line.
- Parameters:
io_line (
IOLine) – IO line to get its PWM duty cycle.- Returns:
PWM duty cycle of the given IO line.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If io_line has no PWM capability.
See also
- get_route_to_node(remote, timeout=10, force=True)
Gets the route from this XBee to the given remote node.
- For Zigbee:
‘AR’ parameter of the local node must be configured with a value different from ‘FF’.
Set force to True to force the Zigbee remote node to return its route independently of the local node configuration as high or low RAM concentrator (‘DO’ of the local value)
- Parameters:
remote (
RemoteXBeeDevice) – The remote node.timeout (Float, optional, default=10) – Maximum number of seconds to wait for the route.
force (Boolean) – True to force asking for the route, False otherwise. Only for Zigbee.
- Returns:
- Tuple containing route data:
status (
TransmitStatus): The transmit status.Tuple with route data (None if the route was not read in the provided timeout):
source (
RemoteXBeeDevice): The source node of the route.destination (
RemoteXBeeDevice): The destination node of the route.hops (List): List of intermediate nodes (
RemoteXBeeDevice) ordered from closest to source to closest to destination node (source and destination not included).
- Return type:
Tuple
- get_socket_info(socket_id)
Returns the information of the socket with the given socket ID.
- Parameters:
socket_id (Integer) – ID of the socket.
- Returns:
- The socket information, or None if the
socket with that ID does not exist.
- Return type:
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
TimeoutException – If the response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
See also
- get_sockets_list()
Returns a list with the IDs of all active (open) sockets.
- Returns:
- list with the IDs of all active (open) sockets, or empty list
if there is not any active socket.
- Return type:
List
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
TimeoutException – If the response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
- get_sync_ops_timeout()
Returns the serial port read timeout.
- Returns:
Serial port read timeout in seconds.
- Return type:
Integer
- get_xbee_device_callbacks()
Returns this XBee internal callbacks for process received packets.
This method is called by the PacketListener associated with this XBee to get its callbacks. These callbacks are executed before user callbacks.
- Returns:
- has_explicit_packets()
Returns if there are pending explicit packets to read. This does not include non-explicit packets.
- Returns:
True if there are pending packets, False otherwise.
- Return type:
Boolean
See also
- has_packets()
Returns if there are pending packets to read. This does not include explicit packets.
- Returns:
True if there are pending packets, False otherwise.
- Return type:
Boolean
See also
- is_apply_changes_enabled()
Returns whether apply changes flag is enabled.
- Returns:
True if apply changes flag is enabled, False otherwise.
- Return type:
Boolean
- is_connected()
Returns whether the device is connected to the Internet.
- Returns:
True if connected to the Internet, False otherwise.
- Return type:
Boolean
- Raises:
TimeoutException – If there is a timeout getting the association indication status.
XBeeException – If there is any other XBee related exception.
- is_device_info_complete()
Override.
- is_open()
Returns whether this XBee is open.
- Returns:
Boolean. True if this XBee is open, False otherwise.
- is_remote()
Override method.
See also
- property log
Returns the XBee logger.
- Returns:
The XBee device logger.
- Return type:
Logger
- open(force_settings=False)
Override.
See also
- property operating_mode
Returns the operating mode of this XBee.
- Returns:
OperatingMode. This XBee operating mode.
- property reachable
Returns whether the XBee is reachable.
- Returns:
True if the device is reachable, False otherwise.
- Return type:
Boolean
- read_data(timeout=None)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- read_data_from(remote_xbee, timeout=None)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- read_device_info(init=True, fire_event=True)
Updates all instance parameters reading them from the XBee.
- Parameters:
init (Boolean, optional, default=`True`) – If False only not initialized parameters are read, all if True.
fire_event (Boolean, optional, default=`True`) – True to throw and update event if any parameter changed, False otherwise.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- read_expl_data(timeout=None)
Override.
Operation not supported in this protocol. This method raises an
AttributeError.
- read_expl_data_from(remote_xbee, timeout=None)
Override.
Operation not supported in this protocol. This method raises an
AttributeError.
- read_io_sample()
Returns an IO sample from the XBee containing the value of all enabled digital IO and analog input channels.
- Returns:
IO sample read from the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- read_ip_data(timeout=3)
Reads new IP data received by this XBee during the provided timeout.
This method blocks until new IP data is received or the provided timeout expires.
For non-blocking operations, register a callback and use the method
IPDevice.add_ip_data_received_callback().Before reading IP data you need to start listening for incoming IP data at a specific port. Use the method
IPDevice.start_listening()for that purpose. When finished, you can use the methodIPDevice.stop_listening()to stop listening for incoming IP data.- Parameters:
timeout (Integer, optional) – The time to wait for new IP data in seconds.
- Returns:
IP message, None if this device did not receive new data.
- Return type:
- Raises:
ValueError – If timeout is less than 0.
- read_ip_data_from(ip_addr, timeout=3)
Reads new IP data received from the given IP address during the provided timeout.
This method blocks until new IP data from the provided IP address is received or the given timeout expires.
For non-blocking operations, register a callback and use the method
IPDevice.add_ip_data_received_callback().Before reading IP data you need to start listening for incoming IP data at a specific port. Use the method
IPDevice.start_listening()for that purpose. When finished, you can use the methodIPDevice.stop_listening()to stop listening for incoming IP data.- Parameters:
ip_addr (
ipaddress.IPv4Address) – The IP address to read data from.timeout (Integer, optional) – The time to wait for new IP data in seconds.
- Returns:
- IP message, None if this device did not
receive new data from the provided IP address.
- Return type:
- Raises:
ValueError – If timeout is less than 0.
- reset()
Override method.
See also
- property scan_counter
Returns the scan counter for this node.
- Returns:
The scan counter for this node.
- Return type:
Integer
- send_bluetooth_data(data)
Sends the given data to the Bluetooth interface using a User Data Relay frame.
- Parameters:
data (Bytearray) – Data to send.
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If there is any problem sending the data.
- send_data(remote_xbee, data, transmit_options=0)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- send_data_async(remote_xbee, data, transmit_options=0)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- send_data_broadcast(data, transmit_options=0)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- send_expl_data(remote_xbee, data, src_endpoint, dest_endpoint, cluster_id, profile_id, transmit_options=0)
Override.
Operation not supported in this protocol. This method raises an
AttributeError.
- send_expl_data_async(remote_xbee, data, src_endpoint, dest_endpoint, cluster_id, profile_id, transmit_options=0)
Override.
Operation not supported in this protocol. This method raises an
AttributeError.
- send_expl_data_broadcast(data, src_endpoint, dest_endpoint, cluster_id, profile_id, transmit_options=0)
Override.
Operation not supported in this protocol. This method raises an
AttributeError.
- send_ip_data_broadcast(dest_port, data)
Sends the provided IP data to all clients.
This method blocks until a success or error transmit status arrives or the configured receive timeout expires.
- Parameters:
dest_port (Integer) – The destination port of the transmission.
data (String or Bytearray) – The IP data to be sent.
- Raises:
ValueError – If data is None or dest_port is less than 0 or greater than 65535.
TimeoutException – If there is a timeout sending the data.
XBeeException – If there is any other XBee related exception.
- send_micropython_data(data)
Sends the given data to the MicroPython interface using a User Data Relay frame.
- Parameters:
data (Bytearray) – Data to send.
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If there is any problem sending the data.
- send_packet(packet, sync=False)
Sends the packet and waits for the response. The packet to send is escaped depending on the current operating mode.
This method can be synchronous or asynchronous.
If synchronous, this method discards all response packets until it finds the one that has the appropriate frame ID, that is, the sent packet’s frame ID.
If asynchronous, this method does not wait for any response and returns None.
- Parameters:
packet (
XBeePacket) – The packet to send.sync (Boolean) – True to wait for the response of the sent packet and return it, False otherwise.
- Returns:
- Response packet if sync is True, None
otherwise.
- Return type:
- Raises:
TimeoutException – If sync is True and the response packet for the sent one cannot be read.
InvalidOperatingModeException – If the XBee operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the packet listener is not running or the XBee’s communication interface is closed.
See also
- send_packet_sync_and_get_response(packet_to_send, timeout=None)
Sends the packet and waits for its corresponding response.
- Parameters:
packet_to_send (
XBeePacket) – The packet to transmit.timeout (Integer, optional, default=`None`) – Number of seconds to wait. -1 to wait indefinitely.
- Returns:
Received response packet.
- Return type:
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
TimeoutException – If response is not received in the configured timeout.
XBeeException – If the XBee’s communication interface is closed.
See also
- send_user_data_relay(local_interface, data)
Sends the given data to the given XBee local interface.
- Parameters:
local_interface (
XBeeLocalInterface) – Destination XBee local interface.data (Bytearray) – Data to send.
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ValueError – If local_interface is None.
XBeeException – If there is any problem sending the User Data Relay.
See also
- property serial_port
Returns the serial port associated to the XBee, if any.
- Returns:
- Serial port of the XBee. None if the
local XBee does not use serial communication.
- Return type:
See also
- set_16bit_addr(value)
Sets the 16-bit address of the XBee.
- Parameters:
value (
XBee16BitAddress) – New 16-bit address of the XBee.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If the protocol is not 802.15.4.
- set_api_output_mode(api_output_mode)
Deprecated since version 1.3: Use
set_api_output_mode_value()Sets the API output mode of the XBee.
- Parameters:
api_output_mode (
APIOutputMode) – New API output mode.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
See also
- set_api_output_mode_value(api_output_mode)
Sets the API output mode of the XBee.
- Parameters:
api_output_mode (Integer) – New API output mode options. Calculate this value using the method
APIOutputModeBit.calculate_api_output_mode_value()with a set ofAPIOutputModeBit.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
See also
- set_dest_address(addr)
Deprecated.
Operation not supported in this protocol. Use
IPDevice.set_dest_ip_addr()instead. This method raises anAttributeError.
- set_dest_ip_addr(address)
Sets the destination IP address.
- Parameters:
address (
ipaddress.IPv4Address) – Destination IP address.- Raises:
ValueError – If address is None.
TimeoutException – If there is a timeout setting the destination IP address.
XBeeException – If there is any other XBee related exception.
See also
ipaddress.IPv4Address
- set_dio_change_detection(io_lines_set)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- set_dio_value(io_line, io_value)
Sets the digital value (high or low) to the provided IO line.
- Parameters:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- set_io_configuration(io_line, io_mode)
Sets the configuration of the provided IO line.
- Parameters:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_io_sampling_rate(rate)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- set_node_id(node_id)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- set_pan_id(value)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- set_parameter(parameter, value, apply=None)
Override.
- set_power_level(power_level)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- set_pwm_duty_cycle(io_line, cycle)
Sets the duty cycle in % of the provided IO line.
The provided IO line must be PWM-capable, previously configured as PWM output.
- Parameters:
io_line (
IOLine) – IO Line to be assigned.cycle (Integer) – Duty cycle in % to be assigned. Must be between 0 and 100.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If the given IO line does not have PWM capability or cycle is not between 0 and 100.
See also
- set_sync_ops_timeout(sync_ops_timeout)
Sets the serial port read timeout.
- Parameters:
sync_ops_timeout (Integer) – Read timeout in seconds.
- start_listening(src_port)
Starts listening for incoming IP transmissions in the provided port.
- Parameters:
src_port (Integer) – Port to listen for incoming transmissions.
- Raises:
ValueError – If source_port is less than 0 or greater than 65535.
TimeoutException – If there is a timeout setting the source port.
XBeeException – If there is any other XBee related exception.
- property stats
Gets the statistics for this XBee.
- Returns:
Statistics. XBee statistics.
- stop_listening()
Stops listening for incoming IP transmissions.
- Raises:
TimeoutException – If there is a timeout processing the operation.
XBeeException – If there is any other XBee related exception.
- update_bluetooth_password(new_password, apply=True, save=True)
Changes the Bluetooth password of this XBee with the new one provided.
Note that your device must include Bluetooth Low Energy support.
- Parameters:
new_password (String) – New Bluetooth password.
apply (Boolean, optional, default=`True`) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
save (Boolean, optional, default=`True`) – True to save changes, False otherwise.
- Raises:
ValueError – If new_password is invalid.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- update_bluetooth_salt_verifier(salt, verifier, apply=True, save=True)
Changes the Bluetooth password of this XBee with the new one provided.
Note that your device must include Bluetooth Low Energy support.
- Parameters:
salt (bytes) – New Bluetooth password.
verifier (bytes) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
apply (Boolean, optional, default=`True`) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
save (Boolean, optional, default=`True`) – True to save changes, False otherwise.
- Raises:
ValueError – If salt or verifier are invalid.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- update_device_data_from(device)
Updates the current node information with provided data. This is only for internal use.
- Parameters:
device (
AbstractXBeeDevice) – XBee to get the data from.- Returns:
True if the node data has been updated, False otherwise.
- Return type:
Boolean
- update_firmware(xml_firmware_file, xbee_firmware_file=None, bootloader_firmware_file=None, timeout=None, progress_callback=None)
Performs a firmware update operation of the XBee.
- Parameters:
xml_firmware_file (String) – Path of the XML file that describes the firmware to upload.
xbee_firmware_file (String, optional, default=`None`) – Location of the XBee binary firmware file.
bootloader_firmware_file (String, optional, default=`None`) – Location of the bootloader binary firmware file.
timeout (Integer, optional, default=`None`) – Maximum time to wait for target read operations during the update process (seconds).
progress_callback (Function, optional, default=`None`) –
Function to 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 XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
OperationNotSupportedException – If XBee does not support firmware update.
FirmwareUpdateException – If there is any error during the firmware update.
- write_changes()
Writes configurable parameter values to the non-volatile memory of the XBee so that parameter modifications persist through subsequent resets.
Parameters values remain in the device’s memory until overwritten by subsequent use of this method.
If changes are made without writing them, the XBee reverts back to previously saved parameters the next time the module is powered-on.
Writing the parameter modifications does not mean those values are immediately applied, this depends on the status of the ‘apply configuration changes’ option. Use method
is_apply_changes_enabled()to get its status andenable_apply_changes()to enable/disable the option. Methodapply_changes()can be used in order to manually apply the changes.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- class digi.xbee.devices.NBIoTDevice(port=None, baud_rate=None, data_bits=serial.EIGHTBITS, stop_bits=serial.STOPBITS_ONE, parity=serial.PARITY_NONE, flow_control=FlowControl.NONE, _sync_ops_timeout=4, comm_iface=None)[source]
Bases:
LPWANDeviceThis class represents a local NB-IoT device.
Class constructor. Instantiates a new
NBIoTDevicewith the provided parameters.- Parameters:
port (String) – Serial port identifier. Depends on operating system. e.g. ‘/dev/ttyUSB0’ on ‘GNU/Linux’ or ‘COM3’ on Windows.
baud_rate (Integer) – Serial port baud rate.
(Integer (_sync_ops_timeout) –
serial.EIGHTBITS): Port bitsize.default –
serial.EIGHTBITS): Port bitsize.(Integer –
serial.STOPBITS_ONE): Port stop bits.default –
serial.STOPBITS_ONE): Port stop bits.(Character (parity) –
serial.PARITY_NONE): Port parity.default –
serial.PARITY_NONE): Port parity.(Integer –
FlowControl.NONE): Port flow control.default –
FlowControl.NONE): Port flow control.(Integer – 3): Read timeout (in seconds).
default – 3): Read timeout (in seconds).
comm_iface (
XBeeCommunicationInterface) – Communication interface.
:raises All exceptions raised by
XBeeDevice.__init__()constructor.:See also
LPWANDevice.__init__()- TIMEOUT_READ_PACKET = 3
Timeout to read packets.
- add_bluetooth_data_received_callback(callback)
Adds a callback for the event
BluetoothDataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The Bluetooth data as a Bytearray.
- add_data_received_callback(callback)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- add_expl_data_received_callback(callback)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- add_fs_frame_received_callback(callback)
Adds a callback for the event
FileSystemFrameReceived.- Parameters:
callback (Function) –
The callback. Receives four arguments.
Source (
AbstractXBeeDevice): The node that sent the file system frame.Frame id (Integer): The received frame id.
Command (
FSCmd): The file system command.Receive options (Integer): Bitfield indicating receive options.
See also
- add_io_sample_received_callback(callback)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- add_ip_data_received_callback(callback)
Adds a callback for the event
IPDataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The data received as an
IPMessage
- add_micropython_data_received_callback(callback)
Adds a callback for the event
MicroPythonDataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The MicroPython data as a Bytearray.
- add_modem_status_received_callback(callback)
Adds a callback for the event
ModemStatusReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The modem status as a
ModemStatus.
- add_packet_received_callback(callback)
Adds a callback for the event
PacketReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The received packet as a
XBeeAPIPacket.
- add_route_received_callback(callback)
Adds a callback for the event
RouteReceived. This works for Zigbee and Digimesh devices.- Parameters:
callback (Function) –
The callback. Receives three arguments.
source (
XBeeDevice): The source node.destination (
RemoteXBeeDevice): The destination node.- hops (List): List of intermediate hops from closest to source
to closest to destination (
RemoteXBeeDevice).
- add_sms_callback(callback)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- add_socket_data_received_callback(callback)
Adds a callback for the event
SocketDataReceived.- Parameters:
callback (Function) –
The callback. Receives two arguments.
The socket ID as an Integer.
The data received as Bytearray.
- add_socket_data_received_from_callback(callback)
Adds a callback for the event
SocketDataReceivedFrom.- Parameters:
callback (Function) –
The callback. Receives three arguments.
The socket ID as an Integer.
- Source address pair (host, port) where host is a string
representing an IPv4 address like ‘100.50.200.5’, and port is an integer.
The data received as Bytearray.
- add_socket_state_received_callback(callback)
Adds a callback for the event
SocketStateReceived.- Parameters:
callback (Function) –
The callback. Receives two arguments.
The socket ID as an Integer.
The state received as a
SocketState.
- add_user_data_relay_received_callback(callback)
Adds a callback for the event
RelayDataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The relay data as a
UserDataRelayMessage.
- apply_changes()
Applies changes via ‘AC’ command.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- apply_profile(profile_path, timeout=None, progress_callback=None)
Applies the given XBee profile to the XBee.
- Parameters:
profile_path (String) – Path of the XBee profile file to apply.
timeout (Integer, optional, default=`None`) – Maximum time to wait for target read operations during the apply profile (seconds).
progress_callback (Function, optional, default=`None`) –
Function 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 XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
UpdateProfileException – If there is any error applying the XBee profile.
- property br
Returns the BR value of the device.
- Returns:
The BR value of the device.
- Return type:
Integer
- close()
Closes the communication with the XBee.
This method guarantees that all threads running are stopped and the serial port is closed.
- property comm_iface
Returns the hardware interface associated to the XBee.
- Returns:
Hardware interface of the XBee.
- Return type:
See also
- classmethod create_xbee_device(comm_port_data)
Creates and returns an
XBeeDevicefrom data of the port to which is connected.- Parameters:
comm_port_data (Dictionary) – Dictionary with all comm port data needed.
are (The dictionary keys) –
“baudRate” –> Baud rate.”port” –> Port number.”bitSize” –> Bit size.”stopBits” –> Stop bits.”parity” –> Parity.”flowControl” –> Flow control.”timeout” for –> Timeout for synchronous operations (in seconds).
- Returns:
XBee object created.
- Return type:
- Raises:
SerialException – If the port to open does not exist or is already opened.
See also
- del_bluetooth_data_received_callback(callback)
Deletes a callback for the callback list of
BluetoothDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_data_received_callback(callback)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- del_expl_data_received_callback(callback)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- del_fs_frame_received_callback(callback)
Deletes a callback for the callback list of
FileSystemFrameReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_io_sample_received_callback(callback)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- del_ip_data_received_callback(callback)
Deletes a callback for the callback list of
IPDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_micropython_data_received_callback(callback)
Deletes a callback for the callback list of
MicroPythonDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_modem_status_received_callback(callback)
Deletes a callback for the callback list of
ModemStatusReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_packet_received_callback(callback)
Deletes a callback for the callback list of
PacketReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_route_received_callback(callback)
Deletes a callback for the callback list of
RouteReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_sms_callback(callback)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- del_socket_data_received_callback(callback)
Deletes a callback for the callback list of
SocketDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_socket_data_received_from_callback(callback)
Deletes a callback for the callback list of
SocketDataReceivedFromevent.- Parameters:
callback (Function) – The callback to delete.
- del_socket_state_received_callback(callback)
Deletes a callback for the callback list of
SocketStateReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_user_data_relay_received_callback(callback)
Deletes a callback for the callback list of
RelayDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- determine_protocol(hardware_version, firmware_version)
Determines the XBee protocol based on the given hardware and firmware versions.
- Parameters:
hardware_version (Integer) – Hardware version to get its protocol.
firmware_version (Bytearray) – Firmware version to get its protocol.
- Returns:
- XBee protocol corresponding to the given
hardware and firmware versions.
- Return type:
- disable_bluetooth()
Disables the Bluetooth interface of this XBee.
Note that your device must include Bluetooth Low Energy support.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- enable_apply_changes(value)
Sets apply changes flag.
- Parameters:
value (Boolean) – True to enable apply changes flag, False to disable it.
- enable_bluetooth()
Enables the Bluetooth interface of this XBee.
To work with this interface, you must also configure the Bluetooth password if not done previously. Use method
AbstractXBeeDevice.update_bluetooth_password().Note that your XBee must include Bluetooth Low Energy support.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- execute_command(parameter, value=None, apply=None)
Executes the provided command.
- Parameters:
or (parameter (String) – class: .ATStringCommand): AT command to execute.
value (bytearray, optional, default=`None`) – Command value (if any).
apply (Boolean, optional, default=`None`) – True to apply changes in XBee configuration, False not to apply them, None to use is_apply_changes_enabled() returned value.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- flush_queues()
Flushes the packets queue.
- get_16bit_addr()
Deprecated.
This protocol does not have an associated 16-bit address.
- get_64bit_addr()
Deprecated.
Cellular protocol does not have an associated 64-bit address.
- get_adc_value(io_line)
Returns the analog value of the provided IO line.
The provided IO line must be previously configured as ADC. To do so, use
AbstractXBeeDevice.set_io_configuration()andIOMode.ADC.- Parameters:
io_line (
IOLine) – IO line to get its ADC value.- Returns:
Analog value corresponding to the provided IO line.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If response does not contain the value for the given IO line.
See also
- get_api_output_mode()
Deprecated since version 1.3: Use
get_api_output_mode_value()Returns the API output mode of the XBee.
The API output mode determines the format of the data through the serial interface of the XBee.
- Returns:
API output mode of the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_api_output_mode_value()
Returns the API output mode of the XBee.
The API output mode determines the format that the received data is output through the serial interface of the XBee.
- Returns:
the parameter value.
- Return type:
Bytearray
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
- get_bluetooth_mac_addr()
Reads and returns the EUI-48 Bluetooth MAC address of this XBee following the format 00112233AABB.
Note that your device must include Bluetooth Low Energy support.
- Returns:
The Bluetooth MAC address.
- Return type:
String
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- get_cellular_ai_status()
Returns the current association status of this Cellular device.
It indicates occurrences of errors during the modem initialization and connection.
- Returns:
- The association
indication status of the Cellular device.
- Return type:
- Raises:
TimeoutException – If there is a timeout getting the association indication status.
XBeeException – If there is any other XBee related exception.
- get_current_frame_id()
Returns the last used frame ID.
- Returns:
Last used frame ID.
- Return type:
Integer
- get_dest_address()
Deprecated.
Operation not supported in this protocol. Use
IPDevice.get_dest_ip_addr()instead. This method raises anAttributeError.
- get_dest_ip_addr()
Returns the destination IP address.
- Returns:
Configured destination IP address.
- Return type:
ipaddress.IPv4Address- Raises:
TimeoutException – If there is a timeout getting the destination IP address.
XBeeException – If there is any other XBee related exception.
See also
ipaddress.IPv4Address
- get_dio_value(io_line)
Returns the digital value of the provided IO line.
The provided IO line must be previously configured as digital I/O. To do so, use
AbstractXBeeDevice.set_io_configuration().- Parameters:
io_line (
IOLine) – the DIO line to gets its digital value.- Returns:
current value of the provided IO line.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If response does not contain the value for the given IO line.
See also
- get_file_manager()
Returns the file system manager for the XBee.
- Returns:
The file system manager.
- Return type:
- Raises:
FileSystemNotSupportedException – If the XBee does not support filesystem.
- get_firmware_version()
Returns the firmware version of the XBee.
- Returns:
Firmware version of the XBee.
- Return type:
Bytearray
- get_hardware_version()
Returns the hardware version of the XBee.
- Returns:
Hardware version of the XBee.
- Return type:
See also
- get_imei_addr()
Returns the IMEI address of this Cellular device.
To refresh this value use the method
CellularDevice.read_device_info().- Returns:
The IMEI address of this Cellular device.
- Return type:
- get_io_configuration(io_line)
Returns the configuration of the provided IO line.
- Parameters:
io_line (
IOLine) – IO line to get its configuration.- Returns:
IO mode of the IO line provided.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_io_sampling_rate()
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- get_ip_addr()
Returns the IP address of this IP XBee.
To refresh this value use the method
IPDevice.read_device_info().- Returns:
The IP address of this IP device.
- Return type:
ipaddress.IPv4Address
See also
ipaddress.IPv4Address
- get_network()
Deprecated.
This protocol does not support the network functionality.
- get_next_frame_id()
Returns the next frame ID of the XBee.
- Returns:
The next frame ID of the XBee.
- Return type:
Integer
- get_node_id()
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- get_pan_id()
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- get_parameter(parameter, parameter_value=None, apply=None)
Override.
See also
- get_power_level()
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- get_pwm_duty_cycle(io_line)
Returns the PWM duty cycle in % corresponding to the provided IO line.
- Parameters:
io_line (
IOLine) – IO line to get its PWM duty cycle.- Returns:
PWM duty cycle of the given IO line.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If io_line has no PWM capability.
See also
- get_route_to_node(remote, timeout=10, force=True)
Gets the route from this XBee to the given remote node.
- For Zigbee:
‘AR’ parameter of the local node must be configured with a value different from ‘FF’.
Set force to True to force the Zigbee remote node to return its route independently of the local node configuration as high or low RAM concentrator (‘DO’ of the local value)
- Parameters:
remote (
RemoteXBeeDevice) – The remote node.timeout (Float, optional, default=10) – Maximum number of seconds to wait for the route.
force (Boolean) – True to force asking for the route, False otherwise. Only for Zigbee.
- Returns:
- Tuple containing route data:
status (
TransmitStatus): The transmit status.Tuple with route data (None if the route was not read in the provided timeout):
source (
RemoteXBeeDevice): The source node of the route.destination (
RemoteXBeeDevice): The destination node of the route.hops (List): List of intermediate nodes (
RemoteXBeeDevice) ordered from closest to source to closest to destination node (source and destination not included).
- Return type:
Tuple
- get_socket_info(socket_id)
Returns the information of the socket with the given socket ID.
- Parameters:
socket_id (Integer) – ID of the socket.
- Returns:
- The socket information, or None if the
socket with that ID does not exist.
- Return type:
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
TimeoutException – If the response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
See also
- get_sockets_list()
Returns a list with the IDs of all active (open) sockets.
- Returns:
- list with the IDs of all active (open) sockets, or empty list
if there is not any active socket.
- Return type:
List
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
TimeoutException – If the response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
- get_sync_ops_timeout()
Returns the serial port read timeout.
- Returns:
Serial port read timeout in seconds.
- Return type:
Integer
- get_xbee_device_callbacks()
Returns this XBee internal callbacks for process received packets.
This method is called by the PacketListener associated with this XBee to get its callbacks. These callbacks are executed before user callbacks.
- Returns:
- has_explicit_packets()
Returns if there are pending explicit packets to read. This does not include non-explicit packets.
- Returns:
True if there are pending packets, False otherwise.
- Return type:
Boolean
See also
- has_packets()
Returns if there are pending packets to read. This does not include explicit packets.
- Returns:
True if there are pending packets, False otherwise.
- Return type:
Boolean
See also
- is_apply_changes_enabled()
Returns whether apply changes flag is enabled.
- Returns:
True if apply changes flag is enabled, False otherwise.
- Return type:
Boolean
- is_connected()
Returns whether the device is connected to the Internet.
- Returns:
True if connected to the Internet, False otherwise.
- Return type:
Boolean
- Raises:
TimeoutException – If there is a timeout getting the association indication status.
XBeeException – If there is any other XBee related exception.
- is_device_info_complete()
Override.
- is_open()
Returns whether this XBee is open.
- Returns:
Boolean. True if this XBee is open, False otherwise.
- is_remote()
Override method.
See also
- property log
Returns the XBee logger.
- Returns:
The XBee device logger.
- Return type:
Logger
- property operating_mode
Returns the operating mode of this XBee.
- Returns:
OperatingMode. This XBee operating mode.
- property reachable
Returns whether the XBee is reachable.
- Returns:
True if the device is reachable, False otherwise.
- Return type:
Boolean
- read_data(timeout=None)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- read_data_from(remote_xbee, timeout=None)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- read_device_info(init=True, fire_event=True)
Updates all instance parameters reading them from the XBee.
- Parameters:
init (Boolean, optional, default=`True`) – If False only not initialized parameters are read, all if True.
fire_event (Boolean, optional, default=`True`) – True to throw and update event if any parameter changed, False otherwise.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- read_expl_data(timeout=None)
Override.
Operation not supported in this protocol. This method raises an
AttributeError.
- read_expl_data_from(remote_xbee, timeout=None)
Override.
Operation not supported in this protocol. This method raises an
AttributeError.
- read_io_sample()
Returns an IO sample from the XBee containing the value of all enabled digital IO and analog input channels.
- Returns:
IO sample read from the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- read_ip_data(timeout=3)
Reads new IP data received by this XBee during the provided timeout.
This method blocks until new IP data is received or the provided timeout expires.
For non-blocking operations, register a callback and use the method
IPDevice.add_ip_data_received_callback().Before reading IP data you need to start listening for incoming IP data at a specific port. Use the method
IPDevice.start_listening()for that purpose. When finished, you can use the methodIPDevice.stop_listening()to stop listening for incoming IP data.- Parameters:
timeout (Integer, optional) – The time to wait for new IP data in seconds.
- Returns:
IP message, None if this device did not receive new data.
- Return type:
- Raises:
ValueError – If timeout is less than 0.
- read_ip_data_from(ip_addr, timeout=3)
Reads new IP data received from the given IP address during the provided timeout.
This method blocks until new IP data from the provided IP address is received or the given timeout expires.
For non-blocking operations, register a callback and use the method
IPDevice.add_ip_data_received_callback().Before reading IP data you need to start listening for incoming IP data at a specific port. Use the method
IPDevice.start_listening()for that purpose. When finished, you can use the methodIPDevice.stop_listening()to stop listening for incoming IP data.- Parameters:
ip_addr (
ipaddress.IPv4Address) – The IP address to read data from.timeout (Integer, optional) – The time to wait for new IP data in seconds.
- Returns:
- IP message, None if this device did not
receive new data from the provided IP address.
- Return type:
- Raises:
ValueError – If timeout is less than 0.
- reset()
Override method.
See also
- property scan_counter
Returns the scan counter for this node.
- Returns:
The scan counter for this node.
- Return type:
Integer
- send_bluetooth_data(data)
Sends the given data to the Bluetooth interface using a User Data Relay frame.
- Parameters:
data (Bytearray) – Data to send.
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If there is any problem sending the data.
- send_data(remote_xbee, data, transmit_options=0)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- send_data_async(remote_xbee, data, transmit_options=0)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- send_data_broadcast(data, transmit_options=0)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- send_expl_data(remote_xbee, data, src_endpoint, dest_endpoint, cluster_id, profile_id, transmit_options=0)
Override.
Operation not supported in this protocol. This method raises an
AttributeError.
- send_expl_data_async(remote_xbee, data, src_endpoint, dest_endpoint, cluster_id, profile_id, transmit_options=0)
Override.
Operation not supported in this protocol. This method raises an
AttributeError.
- send_expl_data_broadcast(data, src_endpoint, dest_endpoint, cluster_id, profile_id, transmit_options=0)
Override.
Operation not supported in this protocol. This method raises an
AttributeError.
- send_ip_data(ip_addr, dest_port, protocol, data, close_socket=False)
Sends the provided IP data to the given IP address and port using the specified IP protocol.
This method blocks until a success or error response arrives or the configured receive timeout expires.
- Parameters:
ip_addr (
ipaddress.IPv4Address) – The IP address to send IP data to.dest_port (Integer) – The destination port of the transmission.
protocol (
IPProtocol) – The IP protocol used for the transmission.data (String or Bytearray) – The IP data to be sent.
close_socket (Boolean, optional) – Must be False.
- Raises:
ValueError – If protocol is not UDP.
- send_ip_data_async(ip_addr, dest_port, protocol, data, close_socket=False)
Sends the provided IP data to the given IP address and port asynchronously using the specified IP protocol.
Asynchronous transmissions do not wait for answer from the remote device or for transmit status packet.
- Parameters:
ip_addr (
ipaddress.IPv4Address) – The IP address to send IP data to.dest_port (Integer) – The destination port of the transmission.
protocol (
IPProtocol) – The IP protocol used for the transmission.data (String or Bytearray) – The IP data to be sent.
close_socket (Boolean, optional) – Must be False.
- Raises:
ValueError – If protocol is not UDP.
- send_ip_data_broadcast(dest_port, data)
Sends the provided IP data to all clients.
This method blocks until a success or error transmit status arrives or the configured receive timeout expires.
- Parameters:
dest_port (Integer) – The destination port of the transmission.
data (String or Bytearray) – The IP data to be sent.
- Raises:
ValueError – If data is None or dest_port is less than 0 or greater than 65535.
TimeoutException – If there is a timeout sending the data.
XBeeException – If there is any other XBee related exception.
- send_micropython_data(data)
Sends the given data to the MicroPython interface using a User Data Relay frame.
- Parameters:
data (Bytearray) – Data to send.
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If there is any problem sending the data.
- send_packet(packet, sync=False)
Sends the packet and waits for the response. The packet to send is escaped depending on the current operating mode.
This method can be synchronous or asynchronous.
If synchronous, this method discards all response packets until it finds the one that has the appropriate frame ID, that is, the sent packet’s frame ID.
If asynchronous, this method does not wait for any response and returns None.
- Parameters:
packet (
XBeePacket) – The packet to send.sync (Boolean) – True to wait for the response of the sent packet and return it, False otherwise.
- Returns:
- Response packet if sync is True, None
otherwise.
- Return type:
- Raises:
TimeoutException – If sync is True and the response packet for the sent one cannot be read.
InvalidOperatingModeException – If the XBee operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the packet listener is not running or the XBee’s communication interface is closed.
See also
- send_packet_sync_and_get_response(packet_to_send, timeout=None)
Sends the packet and waits for its corresponding response.
- Parameters:
packet_to_send (
XBeePacket) – The packet to transmit.timeout (Integer, optional, default=`None`) – Number of seconds to wait. -1 to wait indefinitely.
- Returns:
Received response packet.
- Return type:
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
TimeoutException – If response is not received in the configured timeout.
XBeeException – If the XBee’s communication interface is closed.
See also
- send_sms(phone_number, data)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- send_sms_async(phone_number, data)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- send_user_data_relay(local_interface, data)
Sends the given data to the given XBee local interface.
- Parameters:
local_interface (
XBeeLocalInterface) – Destination XBee local interface.data (Bytearray) – Data to send.
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ValueError – If local_interface is None.
XBeeException – If there is any problem sending the User Data Relay.
See also
- property serial_port
Returns the serial port associated to the XBee, if any.
- Returns:
- Serial port of the XBee. None if the
local XBee does not use serial communication.
- Return type:
See also
- set_16bit_addr(value)
Sets the 16-bit address of the XBee.
- Parameters:
value (
XBee16BitAddress) – New 16-bit address of the XBee.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If the protocol is not 802.15.4.
- set_api_output_mode(api_output_mode)
Deprecated since version 1.3: Use
set_api_output_mode_value()Sets the API output mode of the XBee.
- Parameters:
api_output_mode (
APIOutputMode) – New API output mode.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
See also
- set_api_output_mode_value(api_output_mode)
Sets the API output mode of the XBee.
- Parameters:
api_output_mode (Integer) – New API output mode options. Calculate this value using the method
APIOutputModeBit.calculate_api_output_mode_value()with a set ofAPIOutputModeBit.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
See also
- set_dest_address(addr)
Deprecated.
Operation not supported in this protocol. Use
IPDevice.set_dest_ip_addr()instead. This method raises anAttributeError.
- set_dest_ip_addr(address)
Sets the destination IP address.
- Parameters:
address (
ipaddress.IPv4Address) – Destination IP address.- Raises:
ValueError – If address is None.
TimeoutException – If there is a timeout setting the destination IP address.
XBeeException – If there is any other XBee related exception.
See also
ipaddress.IPv4Address
- set_dio_change_detection(io_lines_set)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- set_dio_value(io_line, io_value)
Sets the digital value (high or low) to the provided IO line.
- Parameters:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- set_io_configuration(io_line, io_mode)
Sets the configuration of the provided IO line.
- Parameters:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_io_sampling_rate(rate)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- set_node_id(node_id)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- set_pan_id(value)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- set_parameter(parameter, value, apply=None)
Override.
- set_power_level(power_level)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- set_pwm_duty_cycle(io_line, cycle)
Sets the duty cycle in % of the provided IO line.
The provided IO line must be PWM-capable, previously configured as PWM output.
- Parameters:
io_line (
IOLine) – IO Line to be assigned.cycle (Integer) – Duty cycle in % to be assigned. Must be between 0 and 100.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If the given IO line does not have PWM capability or cycle is not between 0 and 100.
See also
- set_sync_ops_timeout(sync_ops_timeout)
Sets the serial port read timeout.
- Parameters:
sync_ops_timeout (Integer) – Read timeout in seconds.
- start_listening(src_port)
Starts listening for incoming IP transmissions in the provided port.
- Parameters:
src_port (Integer) – Port to listen for incoming transmissions.
- Raises:
ValueError – If source_port is less than 0 or greater than 65535.
TimeoutException – If there is a timeout setting the source port.
XBeeException – If there is any other XBee related exception.
- property stats
Gets the statistics for this XBee.
- Returns:
Statistics. XBee statistics.
- stop_listening()
Stops listening for incoming IP transmissions.
- Raises:
TimeoutException – If there is a timeout processing the operation.
XBeeException – If there is any other XBee related exception.
- update_bluetooth_password(new_password, apply=True, save=True)
Changes the Bluetooth password of this XBee with the new one provided.
Note that your device must include Bluetooth Low Energy support.
- Parameters:
new_password (String) – New Bluetooth password.
apply (Boolean, optional, default=`True`) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
save (Boolean, optional, default=`True`) – True to save changes, False otherwise.
- Raises:
ValueError – If new_password is invalid.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- update_bluetooth_salt_verifier(salt, verifier, apply=True, save=True)
Changes the Bluetooth password of this XBee with the new one provided.
Note that your device must include Bluetooth Low Energy support.
- Parameters:
salt (bytes) – New Bluetooth password.
verifier (bytes) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
apply (Boolean, optional, default=`True`) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
save (Boolean, optional, default=`True`) – True to save changes, False otherwise.
- Raises:
ValueError – If salt or verifier are invalid.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- update_device_data_from(device)
Updates the current node information with provided data. This is only for internal use.
- Parameters:
device (
AbstractXBeeDevice) – XBee to get the data from.- Returns:
True if the node data has been updated, False otherwise.
- Return type:
Boolean
- update_firmware(xml_firmware_file, xbee_firmware_file=None, bootloader_firmware_file=None, timeout=None, progress_callback=None)
Performs a firmware update operation of the XBee.
- Parameters:
xml_firmware_file (String) – Path of the XML file that describes the firmware to upload.
xbee_firmware_file (String, optional, default=`None`) – Location of the XBee binary firmware file.
bootloader_firmware_file (String, optional, default=`None`) – Location of the bootloader binary firmware file.
timeout (Integer, optional, default=`None`) – Maximum time to wait for target read operations during the update process (seconds).
progress_callback (Function, optional, default=`None`) –
Function to 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 XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
OperationNotSupportedException – If XBee does not support firmware update.
FirmwareUpdateException – If there is any error during the firmware update.
- write_changes()
Writes configurable parameter values to the non-volatile memory of the XBee so that parameter modifications persist through subsequent resets.
Parameters values remain in the device’s memory until overwritten by subsequent use of this method.
If changes are made without writing them, the XBee reverts back to previously saved parameters the next time the module is powered-on.
Writing the parameter modifications does not mean those values are immediately applied, this depends on the status of the ‘apply configuration changes’ option. Use method
is_apply_changes_enabled()to get its status andenable_apply_changes()to enable/disable the option. Methodapply_changes()can be used in order to manually apply the changes.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- class digi.xbee.devices.WiFiDevice(port=None, baud_rate=None, data_bits=serial.EIGHTBITS, stop_bits=serial.STOPBITS_ONE, parity=serial.PARITY_NONE, flow_control=FlowControl.NONE, _sync_ops_timeout=4, comm_iface=None)[source]
Bases:
IPDeviceThis class represents a local Wi-Fi XBee.
Class constructor. Instantiates a new
WiFiDevicewith the provided parameters.- Parameters:
port (String) – Serial port identifier. Depends on operating system. e.g. ‘/dev/ttyUSB0’ on ‘GNU/Linux’ or ‘COM3’ on Windows.
baud_rate (Integer) – Serial port baud rate.
(Integer (_sync_ops_timeout) –
serial.EIGHTBITS): Port bitsize.default –
serial.EIGHTBITS): Port bitsize.(Integer –
serial.STOPBITS_ONE): Port stop bits.default –
serial.STOPBITS_ONE): Port stop bits.(Character (parity) –
serial.PARITY_NONE): Port parity.default –
serial.PARITY_NONE): Port parity.(Integer –
FlowControl.NONE): Port flow control.default –
FlowControl.NONE): Port flow control.(Integer – 3): Read timeout (in seconds).
default – 3): Read timeout (in seconds).
comm_iface (
XBeeCommunicationInterface) – Communication interface.
:raises All exceptions raised by
XBeeDevice.__init__()constructor.:See also
v.__init__()- get_wifi_ai_status()[source]
Returns the current association status of the device.
- Returns:
- Current association
status of the device.
- Return type:
- Raises:
TimeoutException – If there is a timeout getting the association indication status.
XBeeException – If there is any other XBee related exception.
See also
- get_access_point(ssid)[source]
Finds and returns the access point that matches the supplied SSID.
- Parameters:
ssid (String) – SSID of the access point to get.
- Returns:
- Discovered access point with the provided
SID, or None if the timeout expires and the access point was not found.
- Return type:
- Raises:
TimeoutException – If there is a timeout getting the access point.
XBeeException – If there is an error sending the discovery command.
See also
- scan_access_points()[source]
Performs a scan to search for access points in the vicinity.
This method blocks until all the access points are discovered or the configured access point timeout expires.
The access point timeout is configured using the
WiFiDevice.set_access_point_timeout()method and can be consulted withWiFiDevice.get_access_point_timeout()method.- Returns:
List of
AccessPointobjects discovered.- Return type:
List
- Raises:
TimeoutException – If there is a timeout scanning the access points.
XBeeException – If there is any other XBee related exception.
See also
- connect_by_ap(access_point, password=None)[source]
Connects to the provided access point.
This method blocks until the connection with the access point is established or the configured access point timeout expires.
The access point timeout is configured using the
WiFiDevice.set_access_point_timeout()method and can be consulted withWiFiDevice.get_access_point_timeout()method.Once the module is connected to the access point, you can issue the
WiFiDevice.write_changes()method to save the connection settings. This way the module will try to connect to the access point every time it is powered on.- Parameters:
access_point (
AccessPoint) – The access point to connect to.password (String, optional) – The password for the access point, None if it does not have any encryption enabled.
- Returns:
- True if the module connected to the access point
successfully, False otherwise.
- Return type:
Boolean
- Raises:
ValueError – If access_point is None.
TimeoutException – If there is a timeout sending the connect commands.
XBeeException – If there is any other XBee related exception.
- connect_by_ssid(ssid, password=None)[source]
Connects to the access point with provided SSID.
This method blocks until the connection with the access point is established or the configured access point timeout expires.
The access point timeout is configured using the
WiFiDevice.set_access_point_timeout()method and can be consulted withWiFiDevice.get_access_point_timeout()method.Once the module is connected to the access point, you can issue the
WiFiDevice.write_changes()method to save the connection settings. This way the module will try to connect to the access point every time it is powered on.- Parameters:
ssid (String) – SSID of the access point to connect to.
password (String, optional) – The password for the access point, None if it does not have any encryption enabled.
- Returns:
- True if the module connected to the access point
successfully, False otherwise.
- Return type:
Boolean
- Raises:
ValueError – If ssid is None.
TimeoutException – If there is a timeout sending the connect commands.
XBeeException – If the access point with the provided SSID cannot be found.
XBeeException – If there is any other XBee related exception.
- disconnect()[source]
Disconnects from the access point that the device is connected to.
This method blocks until the device disconnects totally from the access point or the configured access point timeout expires.
The access point timeout is configured using the
WiFiDevice.set_access_point_timeout()method and can be consulted withWiFiDevice.get_access_point_timeout()method.- Returns:
- True if the module disconnected from the access point
successfully, False otherwise.
- Return type:
Boolean
- Raises:
TimeoutException – If there is a timeout sending the disconnect command.
XBeeException – If there is any other XBee related exception.
- is_connected()[source]
Returns whether the device is connected to an access point or not.
- Returns:
- True if the device is connected to an access point,
False otherwise.
- Return type:
Boolean
- Raises:
TimeoutException – If there is a timeout getting the association indication status.
- get_access_point_timeout()[source]
Returns the configured access point timeout for connecting, disconnecting and scanning access points.
- Returns:
The current access point timeout in milliseconds.
- Return type:
Integer
- set_access_point_timeout(ap_timeout)[source]
Configures the access point timeout in milliseconds for connecting, disconnecting and scanning access points.
- Parameters:
ap_timeout (Integer) – The new access point timeout in milliseconds.
- Raises:
ValueError – If ap_timeout is less than 0.
- get_ip_addressing_mode()[source]
Returns the IP addressing mode of the device.
- Returns:
The IP addressing mode.
- Return type:
- Raises:
TimeoutException – If there is a timeout reading the IP addressing mode.
- set_ip_addressing_mode(mode)[source]
Sets the IP addressing mode of the device.
- Parameters:
mode (
IPAddressingMode) – The new IP addressing mode to set.- Raises:
TimeoutException – If there is a timeout setting the IP addressing mode.
- set_ip_address(ip_address)[source]
Sets the IP address of the module.
This method can only be called if the module is configured in
IPAddressingMode.STATICmode. Otherwise an XBeeException will be thrown.- Parameters:
ip_address (
ipaddress.IPv4Address) – New IP address to set.- Raises:
TimeoutException – If there is a timeout setting the IP address.
See also
ipaddress.IPv4Address
- get_mask_address()[source]
Returns the subnet mask IP address.
- Returns:
The subnet mask IP address.
- Return type:
ipaddress.IPv4Address- Raises:
TimeoutException – If there is a timeout reading the subnet mask address.
See also
ipaddress.IPv4Address
- set_mask_address(mask_address)[source]
Sets the subnet mask IP address.
This method can only be called if the module is configured in
IPAddressingMode.STATICmode. Otherwise an XBeeException will be thrown.- Parameters:
mask_address (
ipaddress.IPv4Address) – New subnet mask address to set.- Raises:
TimeoutException – If there is a timeout setting the subnet mask address.
See also
ipaddress.IPv4Address
- get_gateway_address()[source]
Returns the IP address of the gateway.
- Returns:
The IP address of the gateway.
- Return type:
ipaddress.IPv4Address- Raises:
TimeoutException – If there is a timeout reading the gateway address.
See also
ipaddress.IPv4Address
- set_gateway_address(gateway_address)[source]
Sets the IP address of the gateway.
This method can only be called if the module is configured in
IPAddressingMode.STATICmode. Otherwise an XBeeException will be thrown.- Parameters:
gateway_address (
ipaddress.IPv4Address) – The new gateway address to set.- Raises:
TimeoutException – If there is a timeout setting the gateway address.
See also
ipaddress.IPv4Address
- get_dns_address()[source]
Returns the IP address of Domain Name Server (DNS).
- Returns:
The DNS address configured.
- Return type:
ipaddress.IPv4Address- Raises:
TimeoutException – If there is a timeout reading the DNS address.
See also
ipaddress.IPv4Address
- set_dns_address(dns_address)[source]
Sets the IP address of Domain Name Server (DNS).
- Parameters:
dns_address (
ipaddress.IPv4Address) – The new DNS address to set.- Raises:
TimeoutException – If there is a timeout setting the DNS address.
See also
ipaddress.IPv4Address
- TIMEOUT_READ_PACKET = 3
Timeout to read packets.
- add_bluetooth_data_received_callback(callback)
Adds a callback for the event
BluetoothDataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The Bluetooth data as a Bytearray.
- add_data_received_callback(callback)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- add_expl_data_received_callback(callback)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- add_fs_frame_received_callback(callback)
Adds a callback for the event
FileSystemFrameReceived.- Parameters:
callback (Function) –
The callback. Receives four arguments.
Source (
AbstractXBeeDevice): The node that sent the file system frame.Frame id (Integer): The received frame id.
Command (
FSCmd): The file system command.Receive options (Integer): Bitfield indicating receive options.
See also
- add_io_sample_received_callback(callback)
Adds a callback for the event
IOSampleReceived.- Parameters:
callback (Function) –
The callback. Receives three arguments.
The received IO sample as an
IOSample.The remote XBee which sent the packet as a
RemoteXBeeDevice.The time in which the packet was received as an Integer.
- add_ip_data_received_callback(callback)
Adds a callback for the event
IPDataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The data received as an
IPMessage
- add_micropython_data_received_callback(callback)
Adds a callback for the event
MicroPythonDataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The MicroPython data as a Bytearray.
- add_modem_status_received_callback(callback)
Adds a callback for the event
ModemStatusReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The modem status as a
ModemStatus.
- add_packet_received_callback(callback)
Adds a callback for the event
PacketReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The received packet as a
XBeeAPIPacket.
- add_route_received_callback(callback)
Adds a callback for the event
RouteReceived. This works for Zigbee and Digimesh devices.- Parameters:
callback (Function) –
The callback. Receives three arguments.
source (
XBeeDevice): The source node.destination (
RemoteXBeeDevice): The destination node.- hops (List): List of intermediate hops from closest to source
to closest to destination (
RemoteXBeeDevice).
- add_socket_data_received_callback(callback)
Adds a callback for the event
SocketDataReceived.- Parameters:
callback (Function) –
The callback. Receives two arguments.
The socket ID as an Integer.
The data received as Bytearray.
- add_socket_data_received_from_callback(callback)
Adds a callback for the event
SocketDataReceivedFrom.- Parameters:
callback (Function) –
The callback. Receives three arguments.
The socket ID as an Integer.
- Source address pair (host, port) where host is a string
representing an IPv4 address like ‘100.50.200.5’, and port is an integer.
The data received as Bytearray.
- add_socket_state_received_callback(callback)
Adds a callback for the event
SocketStateReceived.- Parameters:
callback (Function) –
The callback. Receives two arguments.
The socket ID as an Integer.
The state received as a
SocketState.
- add_user_data_relay_received_callback(callback)
Adds a callback for the event
RelayDataReceived.- Parameters:
callback (Function) –
The callback. Receives one argument.
The relay data as a
UserDataRelayMessage.
- apply_changes()
Applies changes via ‘AC’ command.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- apply_profile(profile_path, timeout=None, progress_callback=None)
Applies the given XBee profile to the XBee.
- Parameters:
profile_path (String) – Path of the XBee profile file to apply.
timeout (Integer, optional, default=`None`) – Maximum time to wait for target read operations during the apply profile (seconds).
progress_callback (Function, optional, default=`None`) –
Function 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 XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
UpdateProfileException – If there is any error applying the XBee profile.
- property br
Returns the BR value of the device.
- Returns:
The BR value of the device.
- Return type:
Integer
- close()
Closes the communication with the XBee.
This method guarantees that all threads running are stopped and the serial port is closed.
- property comm_iface
Returns the hardware interface associated to the XBee.
- Returns:
Hardware interface of the XBee.
- Return type:
See also
- classmethod create_xbee_device(comm_port_data)
Creates and returns an
XBeeDevicefrom data of the port to which is connected.- Parameters:
comm_port_data (Dictionary) – Dictionary with all comm port data needed.
are (The dictionary keys) –
“baudRate” –> Baud rate.”port” –> Port number.”bitSize” –> Bit size.”stopBits” –> Stop bits.”parity” –> Parity.”flowControl” –> Flow control.”timeout” for –> Timeout for synchronous operations (in seconds).
- Returns:
XBee object created.
- Return type:
- Raises:
SerialException – If the port to open does not exist or is already opened.
See also
- del_bluetooth_data_received_callback(callback)
Deletes a callback for the callback list of
BluetoothDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_data_received_callback(callback)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- del_expl_data_received_callback(callback)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- del_fs_frame_received_callback(callback)
Deletes a callback for the callback list of
FileSystemFrameReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_io_sample_received_callback(callback)
Deletes a callback for the callback list of
IOSampleReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_ip_data_received_callback(callback)
Deletes a callback for the callback list of
IPDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_micropython_data_received_callback(callback)
Deletes a callback for the callback list of
MicroPythonDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_modem_status_received_callback(callback)
Deletes a callback for the callback list of
ModemStatusReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_packet_received_callback(callback)
Deletes a callback for the callback list of
PacketReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_route_received_callback(callback)
Deletes a callback for the callback list of
RouteReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_socket_data_received_callback(callback)
Deletes a callback for the callback list of
SocketDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_socket_data_received_from_callback(callback)
Deletes a callback for the callback list of
SocketDataReceivedFromevent.- Parameters:
callback (Function) – The callback to delete.
- del_socket_state_received_callback(callback)
Deletes a callback for the callback list of
SocketStateReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- del_user_data_relay_received_callback(callback)
Deletes a callback for the callback list of
RelayDataReceivedevent.- Parameters:
callback (Function) – The callback to delete.
- determine_protocol(hardware_version, firmware_version)
Determines the XBee protocol based on the given hardware and firmware versions.
- Parameters:
hardware_version (Integer) – Hardware version to get its protocol.
firmware_version (Bytearray) – Firmware version to get its protocol.
- Returns:
- XBee protocol corresponding to the given
hardware and firmware versions.
- Return type:
- disable_bluetooth()
Disables the Bluetooth interface of this XBee.
Note that your device must include Bluetooth Low Energy support.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- enable_apply_changes(value)
Sets apply changes flag.
- Parameters:
value (Boolean) – True to enable apply changes flag, False to disable it.
- enable_bluetooth()
Enables the Bluetooth interface of this XBee.
To work with this interface, you must also configure the Bluetooth password if not done previously. Use method
AbstractXBeeDevice.update_bluetooth_password().Note that your XBee must include Bluetooth Low Energy support.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- execute_command(parameter, value=None, apply=None)
Executes the provided command.
- Parameters:
or (parameter (String) – class: .ATStringCommand): AT command to execute.
value (bytearray, optional, default=`None`) – Command value (if any).
apply (Boolean, optional, default=`None`) – True to apply changes in XBee configuration, False not to apply them, None to use is_apply_changes_enabled() returned value.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- flush_queues()
Flushes the packets queue.
- get_16bit_addr()
Deprecated.
This protocol does not have an associated 16-bit address.
- get_64bit_addr()
Returns the 64-bit address of the XBee.
- Returns:
64-bit address of the XBee.
- Return type:
See also
- get_adc_value(io_line)
Returns the analog value of the provided IO line.
The provided IO line must be previously configured as ADC. To do so, use
AbstractXBeeDevice.set_io_configuration()andIOMode.ADC.- Parameters:
io_line (
IOLine) – IO line to get its ADC value.- Returns:
Analog value corresponding to the provided IO line.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If response does not contain the value for the given IO line.
See also
- get_api_output_mode()
Deprecated since version 1.3: Use
get_api_output_mode_value()Returns the API output mode of the XBee.
The API output mode determines the format of the data through the serial interface of the XBee.
- Returns:
API output mode of the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_api_output_mode_value()
Returns the API output mode of the XBee.
The API output mode determines the format that the received data is output through the serial interface of the XBee.
- Returns:
the parameter value.
- Return type:
Bytearray
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
- get_bluetooth_mac_addr()
Reads and returns the EUI-48 Bluetooth MAC address of this XBee following the format 00112233AABB.
Note that your device must include Bluetooth Low Energy support.
- Returns:
The Bluetooth MAC address.
- Return type:
String
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- get_current_frame_id()
Returns the last used frame ID.
- Returns:
Last used frame ID.
- Return type:
Integer
- get_dest_address()
Deprecated.
Operation not supported in this protocol. Use
IPDevice.get_dest_ip_addr()instead. This method raises anAttributeError.
- get_dest_ip_addr()
Returns the destination IP address.
- Returns:
Configured destination IP address.
- Return type:
ipaddress.IPv4Address- Raises:
TimeoutException – If there is a timeout getting the destination IP address.
XBeeException – If there is any other XBee related exception.
See also
ipaddress.IPv4Address
- get_dio_value(io_line)
Returns the digital value of the provided IO line.
The provided IO line must be previously configured as digital I/O. To do so, use
AbstractXBeeDevice.set_io_configuration().- Parameters:
io_line (
IOLine) – the DIO line to gets its digital value.- Returns:
current value of the provided IO line.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If response does not contain the value for the given IO line.
See also
- get_file_manager()
Returns the file system manager for the XBee.
- Returns:
The file system manager.
- Return type:
- Raises:
FileSystemNotSupportedException – If the XBee does not support filesystem.
- get_firmware_version()
Returns the firmware version of the XBee.
- Returns:
Firmware version of the XBee.
- Return type:
Bytearray
- get_hardware_version()
Returns the hardware version of the XBee.
- Returns:
Hardware version of the XBee.
- Return type:
See also
- get_io_configuration(io_line)
Returns the configuration of the provided IO line.
- Parameters:
io_line (
IOLine) – IO line to get its configuration.- Returns:
IO mode of the IO line provided.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_io_sampling_rate()
Returns the IO sampling rate of the XBee.
- Returns:
IO sampling rate of XBee.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_ip_addr()
Returns the IP address of this IP XBee.
To refresh this value use the method
IPDevice.read_device_info().- Returns:
The IP address of this IP device.
- Return type:
ipaddress.IPv4Address
See also
ipaddress.IPv4Address
- get_network()
Deprecated.
This protocol does not support the network functionality.
- get_next_frame_id()
Returns the next frame ID of the XBee.
- Returns:
The next frame ID of the XBee.
- Return type:
Integer
- get_node_id()
Returns the node identifier (‘NI’) value of the XBee.
- Returns:
Node identifier (‘NI’) of the XBee.
- Return type:
String
- get_pan_id()
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- get_parameter(parameter, parameter_value=None, apply=None)
Override.
See also
- get_power_level()
Returns the power level of the XBee.
- Returns:
Power level of the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_pwm_duty_cycle(io_line)
Returns the PWM duty cycle in % corresponding to the provided IO line.
- Parameters:
io_line (
IOLine) – IO line to get its PWM duty cycle.- Returns:
PWM duty cycle of the given IO line.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If io_line has no PWM capability.
See also
- get_route_to_node(remote, timeout=10, force=True)
Gets the route from this XBee to the given remote node.
- For Zigbee:
‘AR’ parameter of the local node must be configured with a value different from ‘FF’.
Set force to True to force the Zigbee remote node to return its route independently of the local node configuration as high or low RAM concentrator (‘DO’ of the local value)
- Parameters:
remote (
RemoteXBeeDevice) – The remote node.timeout (Float, optional, default=10) – Maximum number of seconds to wait for the route.
force (Boolean) – True to force asking for the route, False otherwise. Only for Zigbee.
- Returns:
- Tuple containing route data:
status (
TransmitStatus): The transmit status.Tuple with route data (None if the route was not read in the provided timeout):
source (
RemoteXBeeDevice): The source node of the route.destination (
RemoteXBeeDevice): The destination node of the route.hops (List): List of intermediate nodes (
RemoteXBeeDevice) ordered from closest to source to closest to destination node (source and destination not included).
- Return type:
Tuple
- get_sync_ops_timeout()
Returns the serial port read timeout.
- Returns:
Serial port read timeout in seconds.
- Return type:
Integer
- get_xbee_device_callbacks()
Returns this XBee internal callbacks for process received packets.
This method is called by the PacketListener associated with this XBee to get its callbacks. These callbacks are executed before user callbacks.
- Returns:
- has_explicit_packets()
Returns if there are pending explicit packets to read. This does not include non-explicit packets.
- Returns:
True if there are pending packets, False otherwise.
- Return type:
Boolean
See also
- has_packets()
Returns if there are pending packets to read. This does not include explicit packets.
- Returns:
True if there are pending packets, False otherwise.
- Return type:
Boolean
See also
- is_apply_changes_enabled()
Returns whether apply changes flag is enabled.
- Returns:
True if apply changes flag is enabled, False otherwise.
- Return type:
Boolean
- is_device_info_complete()
Override.
- is_open()
Returns whether this XBee is open.
- Returns:
Boolean. True if this XBee is open, False otherwise.
- is_remote()
Override method.
See also
- property log
Returns the XBee logger.
- Returns:
The XBee device logger.
- Return type:
Logger
- property operating_mode
Returns the operating mode of this XBee.
- Returns:
OperatingMode. This XBee operating mode.
- property reachable
Returns whether the XBee is reachable.
- Returns:
True if the device is reachable, False otherwise.
- Return type:
Boolean
- read_data(timeout=None)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- read_data_from(remote_xbee, timeout=None)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- read_device_info(init=True, fire_event=True)
Updates all instance parameters reading them from the XBee.
- Parameters:
init (Boolean, optional, default=`True`) – If False only not initialized parameters are read, all if True.
fire_event (Boolean, optional, default=`True`) – True to throw and update event if any parameter changed, False otherwise.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- read_expl_data(timeout=None)
Override.
Operation not supported in this protocol. This method raises an
AttributeError.
- read_expl_data_from(remote_xbee, timeout=None)
Override.
Operation not supported in this protocol. This method raises an
AttributeError.
- read_io_sample()
Returns an IO sample from the XBee containing the value of all enabled digital IO and analog input channels.
- Returns:
IO sample read from the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- read_ip_data(timeout=3)
Reads new IP data received by this XBee during the provided timeout.
This method blocks until new IP data is received or the provided timeout expires.
For non-blocking operations, register a callback and use the method
IPDevice.add_ip_data_received_callback().Before reading IP data you need to start listening for incoming IP data at a specific port. Use the method
IPDevice.start_listening()for that purpose. When finished, you can use the methodIPDevice.stop_listening()to stop listening for incoming IP data.- Parameters:
timeout (Integer, optional) – The time to wait for new IP data in seconds.
- Returns:
IP message, None if this device did not receive new data.
- Return type:
- Raises:
ValueError – If timeout is less than 0.
- read_ip_data_from(ip_addr, timeout=3)
Reads new IP data received from the given IP address during the provided timeout.
This method blocks until new IP data from the provided IP address is received or the given timeout expires.
For non-blocking operations, register a callback and use the method
IPDevice.add_ip_data_received_callback().Before reading IP data you need to start listening for incoming IP data at a specific port. Use the method
IPDevice.start_listening()for that purpose. When finished, you can use the methodIPDevice.stop_listening()to stop listening for incoming IP data.- Parameters:
ip_addr (
ipaddress.IPv4Address) – The IP address to read data from.timeout (Integer, optional) – The time to wait for new IP data in seconds.
- Returns:
- IP message, None if this device did not
receive new data from the provided IP address.
- Return type:
- Raises:
ValueError – If timeout is less than 0.
- reset()
Override method.
See also
- property scan_counter
Returns the scan counter for this node.
- Returns:
The scan counter for this node.
- Return type:
Integer
- send_bluetooth_data(data)
Sends the given data to the Bluetooth interface using a User Data Relay frame.
- Parameters:
data (Bytearray) – Data to send.
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If there is any problem sending the data.
- send_data(remote_xbee, data, transmit_options=0)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- send_data_async(remote_xbee, data, transmit_options=0)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- send_data_broadcast(data, transmit_options=0)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- send_expl_data(remote_xbee, data, src_endpoint, dest_endpoint, cluster_id, profile_id, transmit_options=0)
Override.
Operation not supported in this protocol. This method raises an
AttributeError.
- send_expl_data_async(remote_xbee, data, src_endpoint, dest_endpoint, cluster_id, profile_id, transmit_options=0)
Override.
Operation not supported in this protocol. This method raises an
AttributeError.
- send_expl_data_broadcast(data, src_endpoint, dest_endpoint, cluster_id, profile_id, transmit_options=0)
Override.
Operation not supported in this protocol. This method raises an
AttributeError.
- send_ip_data(ip_addr, dest_port, protocol, data, close_socket=False)
Sends the provided IP data to the given IP address and port using the specified IP protocol. For TCP and TCP SSL protocols, you can also indicate if the socket should be closed when data is sent.
This method blocks until a success or error response arrives or the configured receive timeout expires.
- Parameters:
ip_addr (
ipaddress.IPv4Address) – The IP address to send IP data to.dest_port (Integer) – The destination port of the transmission.
protocol (
IPProtocol) – The IP protocol used for the transmission.data (String or Bytearray) – The IP data to be sent.
close_socket (Boolean, optional, default=`False`) – True to close the socket just after the transmission. False to keep it open.
- Raises:
ValueError – If ip_addr or protocol or data is None or dest_port is less than 0 or greater than 65535.
OperationNotSupportedException – If the XBee is remote.
TimeoutException – If there is a timeout sending the data.
XBeeException – If there is any other XBee related exception.
- send_ip_data_async(ip_addr, dest_port, protocol, data, close_socket=False)
Sends the provided IP data to the given IP address and port asynchronously using the specified IP protocol. For TCP and TCP SSL protocols, you can also indicate if the socket should be closed when data is sent.
Asynchronous transmissions do not wait for answer from the remote device or for transmit status packet.
- Parameters:
ip_addr (
ipaddress.IPv4Address) – The IP address to send IP data to.dest_port (Integer) – The destination port of the transmission.
protocol (
IPProtocol) – The IP protocol used for the transmission.data (String or Bytearray) – The IP data to be sent.
close_socket (Boolean, optional, default=`False`) – True to close the socket just after the transmission. False to keep it open.
- Raises:
ValueError – If ip_addr or protocol or data is None or dest_port is less than 0 or greater than 65535.
OperationNotSupportedException – If the XBee is remote.
XBeeException – If there is any other XBee related exception.
- send_ip_data_broadcast(dest_port, data)
Sends the provided IP data to all clients.
This method blocks until a success or error transmit status arrives or the configured receive timeout expires.
- Parameters:
dest_port (Integer) – The destination port of the transmission.
data (String or Bytearray) – The IP data to be sent.
- Raises:
ValueError – If data is None or dest_port is less than 0 or greater than 65535.
TimeoutException – If there is a timeout sending the data.
XBeeException – If there is any other XBee related exception.
- send_micropython_data(data)
Sends the given data to the MicroPython interface using a User Data Relay frame.
- Parameters:
data (Bytearray) – Data to send.
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If there is any problem sending the data.
- send_packet(packet, sync=False)
Sends the packet and waits for the response. The packet to send is escaped depending on the current operating mode.
This method can be synchronous or asynchronous.
If synchronous, this method discards all response packets until it finds the one that has the appropriate frame ID, that is, the sent packet’s frame ID.
If asynchronous, this method does not wait for any response and returns None.
- Parameters:
packet (
XBeePacket) – The packet to send.sync (Boolean) – True to wait for the response of the sent packet and return it, False otherwise.
- Returns:
- Response packet if sync is True, None
otherwise.
- Return type:
- Raises:
TimeoutException – If sync is True and the response packet for the sent one cannot be read.
InvalidOperatingModeException – If the XBee operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
XBeeException – If the packet listener is not running or the XBee’s communication interface is closed.
See also
- send_packet_sync_and_get_response(packet_to_send, timeout=None)
Sends the packet and waits for its corresponding response.
- Parameters:
packet_to_send (
XBeePacket) – The packet to transmit.timeout (Integer, optional, default=`None`) – Number of seconds to wait. -1 to wait indefinitely.
- Returns:
Received response packet.
- Return type:
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
TimeoutException – If response is not received in the configured timeout.
XBeeException – If the XBee’s communication interface is closed.
See also
- send_user_data_relay(local_interface, data)
Sends the given data to the given XBee local interface.
- Parameters:
local_interface (
XBeeLocalInterface) – Destination XBee local interface.data (Bytearray) – Data to send.
- Raises:
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ValueError – If local_interface is None.
XBeeException – If there is any problem sending the User Data Relay.
See also
- property serial_port
Returns the serial port associated to the XBee, if any.
- Returns:
- Serial port of the XBee. None if the
local XBee does not use serial communication.
- Return type:
See also
- set_16bit_addr(value)
Sets the 16-bit address of the XBee.
- Parameters:
value (
XBee16BitAddress) – New 16-bit address of the XBee.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If the protocol is not 802.15.4.
- set_api_output_mode(api_output_mode)
Deprecated since version 1.3: Use
set_api_output_mode_value()Sets the API output mode of the XBee.
- Parameters:
api_output_mode (
APIOutputMode) – New API output mode.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
See also
- set_api_output_mode_value(api_output_mode)
Sets the API output mode of the XBee.
- Parameters:
api_output_mode (Integer) – New API output mode options. Calculate this value using the method
APIOutputModeBit.calculate_api_output_mode_value()with a set ofAPIOutputModeBit.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
See also
- set_dest_address(addr)
Deprecated.
Operation not supported in this protocol. Use
IPDevice.set_dest_ip_addr()instead. This method raises anAttributeError.
- set_dest_ip_addr(address)
Sets the destination IP address.
- Parameters:
address (
ipaddress.IPv4Address) – Destination IP address.- Raises:
ValueError – If address is None.
TimeoutException – If there is a timeout setting the destination IP address.
XBeeException – If there is any other XBee related exception.
See also
ipaddress.IPv4Address
- set_dio_change_detection(io_lines_set)
Sets the digital IO lines to be monitored and sampled whenever their status changes. A None set of lines disables this feature.
- Parameters:
io_lines_set – Set of
IOLine.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_dio_value(io_line, io_value)
Sets the digital value (high or low) to the provided IO line.
- Parameters:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- set_io_configuration(io_line, io_mode)
Sets the configuration of the provided IO line.
- Parameters:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_io_sampling_rate(rate)
Sets the IO sampling rate of the XBee in seconds. A sample rate of 0 means the IO sampling feature is disabled.
- Parameters:
rate (Integer) – New IO sampling rate of the XBee in seconds.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_node_id(node_id)
Sets the node identifier (‘NI`) value of the XBee.
- Parameters:
node_id (String) – New node identifier (‘NI’) of the XBee.
- Raises:
ValueError – If node_id is None or its length is greater than 20.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- set_pan_id(value)
Deprecated.
Operation not supported in this protocol. This method raises an
AttributeError.
- set_parameter(parameter, value, apply=None)
Override.
- set_power_level(power_level)
Sets the power level of the XBee.
- Parameters:
power_level (
PowerLevel) – New power level of the XBee.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_pwm_duty_cycle(io_line, cycle)
Sets the duty cycle in % of the provided IO line.
The provided IO line must be PWM-capable, previously configured as PWM output.
- Parameters:
io_line (
IOLine) – IO Line to be assigned.cycle (Integer) – Duty cycle in % to be assigned. Must be between 0 and 100.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If the given IO line does not have PWM capability or cycle is not between 0 and 100.
See also
- set_sync_ops_timeout(sync_ops_timeout)
Sets the serial port read timeout.
- Parameters:
sync_ops_timeout (Integer) – Read timeout in seconds.
- start_listening(src_port)
Starts listening for incoming IP transmissions in the provided port.
- Parameters:
src_port (Integer) – Port to listen for incoming transmissions.
- Raises:
ValueError – If source_port is less than 0 or greater than 65535.
TimeoutException – If there is a timeout setting the source port.
XBeeException – If there is any other XBee related exception.
- property stats
Gets the statistics for this XBee.
- Returns:
Statistics. XBee statistics.
- stop_listening()
Stops listening for incoming IP transmissions.
- Raises:
TimeoutException – If there is a timeout processing the operation.
XBeeException – If there is any other XBee related exception.
- update_bluetooth_password(new_password, apply=True, save=True)
Changes the Bluetooth password of this XBee with the new one provided.
Note that your device must include Bluetooth Low Energy support.
- Parameters:
new_password (String) – New Bluetooth password.
apply (Boolean, optional, default=`True`) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
save (Boolean, optional, default=`True`) – True to save changes, False otherwise.
- Raises:
ValueError – If new_password is invalid.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- update_bluetooth_salt_verifier(salt, verifier, apply=True, save=True)
Changes the Bluetooth password of this XBee with the new one provided.
Note that your device must include Bluetooth Low Energy support.
- Parameters:
salt (bytes) – New Bluetooth password.
verifier (bytes) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
apply (Boolean, optional, default=`True`) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
save (Boolean, optional, default=`True`) – True to save changes, False otherwise.
- Raises:
ValueError – If salt or verifier are invalid.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- update_device_data_from(device)
Updates the current node information with provided data. This is only for internal use.
- Parameters:
device (
AbstractXBeeDevice) – XBee to get the data from.- Returns:
True if the node data has been updated, False otherwise.
- Return type:
Boolean
- update_firmware(xml_firmware_file, xbee_firmware_file=None, bootloader_firmware_file=None, timeout=None, progress_callback=None)
Performs a firmware update operation of the XBee.
- Parameters:
xml_firmware_file (String) – Path of the XML file that describes the firmware to upload.
xbee_firmware_file (String, optional, default=`None`) – Location of the XBee binary firmware file.
bootloader_firmware_file (String, optional, default=`None`) – Location of the bootloader binary firmware file.
timeout (Integer, optional, default=`None`) – Maximum time to wait for target read operations during the update process (seconds).
progress_callback (Function, optional, default=`None`) –
Function to 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 XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
OperationNotSupportedException – If XBee does not support firmware update.
FirmwareUpdateException – If there is any error during the firmware update.
- write_changes()
Writes configurable parameter values to the non-volatile memory of the XBee so that parameter modifications persist through subsequent resets.
Parameters values remain in the device’s memory until overwritten by subsequent use of this method.
If changes are made without writing them, the XBee reverts back to previously saved parameters the next time the module is powered-on.
Writing the parameter modifications does not mean those values are immediately applied, this depends on the status of the ‘apply configuration changes’ option. Use method
is_apply_changes_enabled()to get its status andenable_apply_changes()to enable/disable the option. Methodapply_changes()can be used in order to manually apply the changes.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- class digi.xbee.devices.RemoteXBeeDevice(local_xbee, x64bit_addr=<digi.xbee.models.address.XBee64BitAddress object>, x16bit_addr=<digi.xbee.models.address.XBee16BitAddress object>, node_id=None)[source]
Bases:
AbstractXBeeDeviceThis class represents a remote XBee.
Class constructor. Instantiates a new
RemoteXBeeDevicewith the provided parameters.- Parameters:
local_xbee (
XBeeDevice) – Local XBee associated with the remote one.x64bit_addr (
XBee64BitAddress) – 64-bit address of the remote XBee.x16bit_addr (
XBee16BitAddress) – 16-bit address of the remote XBee.node_id (String, optional) – Node identifier of the remote XBee.
See also
- get_local_xbee_device()[source]
Returns the local XBee associated to the remote one.
- Returns:
Local XBee.
- Return type:
- set_local_xbee_device(local_xbee_device)[source]
This methods associates a
XBeeDeviceto the remote XBee.- Parameters:
local_xbee_device (
XBeeDevice) – New local XBee associated to the remote one.
See also
- get_serial_port()[source]
Returns the serial port of the local XBee associated to the remote one.
- Returns:
- Serial port of the local XBee associated
to the remote one.
- Return type:
XBeeSerialPort
See also
XBeeSerialPort
- get_comm_iface()[source]
Returns the communication interface of the local XBee associated to the remote one.
- Returns:
- Communication interface of the
local XBee associated to the remote one.
- Return type:
XBeeCommunicationInterface
See also
XBeeCommunicationInterface
- get_ota_max_block_size()[source]
Returns the maximum number of bytes to send for ota updates.
- Returns:
Maximum ota block size to send.
- Return type:
Integer
- set_ota_max_block_size(size)[source]
Sets the maximum number of bytes to send for ota updates.
- Parameters:
size (Integer) – Maximum ota block size to send.
- Raises:
ValueError – If size is not between 0 and 255.
- update_filesystem_image(ota_filesystem_file, timeout=None, progress_callback=None)[source]
Performs a filesystem image update operation of the device.
- Parameters:
ota_filesystem_file (String) – Location of the OTA filesystem image file.
timeout (Integer, optional) – Maximum time to wait for target read operations during the update process.
progress_callback (Function, optional) –
Function 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 device is not open.
InvalidOperatingModeException – If the device operating mode is invalid.
FileSystemNotSupportedException – If the filesystem update is not supported in the XBee.
FileSystemException – If there is any error performing the filesystem update.
- apply_changes()
Applies changes via ‘AC’ command.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- apply_profile(profile_path, timeout=None, progress_callback=None)
Applies the given XBee profile to the XBee.
- Parameters:
profile_path (String) – Path of the XBee profile file to apply.
timeout (Integer, optional, default=`None`) – Maximum time to wait for target read operations during the apply profile (seconds).
progress_callback (Function, optional, default=`None`) –
Function 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 XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
UpdateProfileException – If there is any error applying the XBee profile.
- property br
Returns the BR value of the device.
- Returns:
The BR value of the device.
- Return type:
Integer
- determine_protocol(hardware_version, firmware_version)
Determines the XBee protocol based on the given hardware and firmware versions.
- Parameters:
hardware_version (Integer) – Hardware version to get its protocol.
firmware_version (Bytearray) – Firmware version to get its protocol.
- Returns:
- XBee protocol corresponding to the given
hardware and firmware versions.
- Return type:
- disable_bluetooth()
Disables the Bluetooth interface of this XBee.
Note that your device must include Bluetooth Low Energy support.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- enable_apply_changes(value)
Sets apply changes flag.
- Parameters:
value (Boolean) – True to enable apply changes flag, False to disable it.
- enable_bluetooth()
Enables the Bluetooth interface of this XBee.
To work with this interface, you must also configure the Bluetooth password if not done previously. Use method
AbstractXBeeDevice.update_bluetooth_password().Note that your XBee must include Bluetooth Low Energy support.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- execute_command(parameter, value=None, apply=None)
Executes the provided command.
- Parameters:
or (parameter (String) – class: .ATStringCommand): AT command to execute.
value (bytearray, optional, default=`None`) – Command value (if any).
apply (Boolean, optional, default=`None`) – True to apply changes in XBee configuration, False not to apply them, None to use is_apply_changes_enabled() returned value.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- get_16bit_addr()
Returns the 16-bit address of the XBee.
- Returns:
16-bit address of the XBee.
- Return type:
See also
- get_64bit_addr()
Returns the 64-bit address of the XBee.
- Returns:
64-bit address of the XBee.
- Return type:
See also
- get_adc_value(io_line)
Returns the analog value of the provided IO line.
The provided IO line must be previously configured as ADC. To do so, use
AbstractXBeeDevice.set_io_configuration()andIOMode.ADC.- Parameters:
io_line (
IOLine) – IO line to get its ADC value.- Returns:
Analog value corresponding to the provided IO line.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If response does not contain the value for the given IO line.
See also
- get_api_output_mode()
Deprecated since version 1.3: Use
get_api_output_mode_value()Returns the API output mode of the XBee.
The API output mode determines the format of the data through the serial interface of the XBee.
- Returns:
API output mode of the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_api_output_mode_value()
Returns the API output mode of the XBee.
The API output mode determines the format that the received data is output through the serial interface of the XBee.
- Returns:
the parameter value.
- Return type:
Bytearray
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
- get_bluetooth_mac_addr()
Reads and returns the EUI-48 Bluetooth MAC address of this XBee following the format 00112233AABB.
Note that your device must include Bluetooth Low Energy support.
- Returns:
The Bluetooth MAC address.
- Return type:
String
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- get_current_frame_id()
Returns the last used frame ID.
- Returns:
Last used frame ID.
- Return type:
Integer
- get_dest_address()
Returns the 64-bit address of the XBee that is data destination.
- Returns:
64-bit address of destination XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_dio_value(io_line)
Returns the digital value of the provided IO line.
The provided IO line must be previously configured as digital I/O. To do so, use
AbstractXBeeDevice.set_io_configuration().- Parameters:
io_line (
IOLine) – the DIO line to gets its digital value.- Returns:
current value of the provided IO line.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If response does not contain the value for the given IO line.
See also
- get_file_manager()
Returns the file system manager for the XBee.
- Returns:
The file system manager.
- Return type:
- Raises:
FileSystemNotSupportedException – If the XBee does not support filesystem.
- get_firmware_version()
Returns the firmware version of the XBee.
- Returns:
Firmware version of the XBee.
- Return type:
Bytearray
- get_hardware_version()
Returns the hardware version of the XBee.
- Returns:
Hardware version of the XBee.
- Return type:
See also
- get_io_configuration(io_line)
Returns the configuration of the provided IO line.
- Parameters:
io_line (
IOLine) – IO line to get its configuration.- Returns:
IO mode of the IO line provided.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_io_sampling_rate()
Returns the IO sampling rate of the XBee.
- Returns:
IO sampling rate of XBee.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_node_id()
Returns the node identifier (‘NI’) value of the XBee.
- Returns:
Node identifier (‘NI’) of the XBee.
- Return type:
String
- get_pan_id()
Returns the operating PAN ID of the XBee.
- Returns:
Operating PAN ID of the XBee.
- Return type:
Bytearray
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_power_level()
Returns the power level of the XBee.
- Returns:
Power level of the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_protocol()
Returns the current protocol of the XBee.
- Returns:
Current protocol of the XBee.
- Return type:
See also
- get_pwm_duty_cycle(io_line)
Returns the PWM duty cycle in % corresponding to the provided IO line.
- Parameters:
io_line (
IOLine) – IO line to get its PWM duty cycle.- Returns:
PWM duty cycle of the given IO line.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If io_line has no PWM capability.
See also
- get_sync_ops_timeout()
Returns the serial port read timeout.
- Returns:
Serial port read timeout in seconds.
- Return type:
Integer
- is_apply_changes_enabled()
Returns whether apply changes flag is enabled.
- Returns:
True if apply changes flag is enabled, False otherwise.
- Return type:
Boolean
- is_device_info_complete()
Returns whether XBee node information is complete.
- Returns:
True if node information is complete, False otherwise.
- Return type:
Boolean
- property log
Returns the XBee logger.
- Returns:
The XBee device logger.
- Return type:
Logger
- property reachable
Returns whether the XBee is reachable.
- Returns:
True if the device is reachable, False otherwise.
- Return type:
Boolean
- read_device_info(init=True, fire_event=True)
Updates all instance parameters reading them from the XBee.
- Parameters:
init (Boolean, optional, default=`True`) – If False only not initialized parameters are read, all if True.
fire_event (Boolean, optional, default=`True`) – True to throw and update event if any parameter changed, False otherwise.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- read_io_sample()
Returns an IO sample from the XBee containing the value of all enabled digital IO and analog input channels.
- Returns:
IO sample read from the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- property scan_counter
Returns the scan counter for this node.
- Returns:
The scan counter for this node.
- Return type:
Integer
- set_16bit_addr(value)
Sets the 16-bit address of the XBee.
- Parameters:
value (
XBee16BitAddress) – New 16-bit address of the XBee.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If the protocol is not 802.15.4.
- set_api_output_mode(api_output_mode)
Deprecated since version 1.3: Use
set_api_output_mode_value()Sets the API output mode of the XBee.
- Parameters:
api_output_mode (
APIOutputMode) – New API output mode.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
See also
- set_api_output_mode_value(api_output_mode)
Sets the API output mode of the XBee.
- Parameters:
api_output_mode (Integer) – New API output mode options. Calculate this value using the method
APIOutputModeBit.calculate_api_output_mode_value()with a set ofAPIOutputModeBit.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
See also
- set_dest_address(addr)
Sets the 64-bit address of the XBee that is data destination.
- Parameters:
addr (
XBee64BitAddressorRemoteXBeeDevice) – Address itself or remote XBee to be data destination.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If addr is None.
See also
- set_dio_change_detection(io_lines_set)
Sets the digital IO lines to be monitored and sampled whenever their status changes. A None set of lines disables this feature.
- Parameters:
io_lines_set – Set of
IOLine.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_dio_value(io_line, io_value)
Sets the digital value (high or low) to the provided IO line.
- Parameters:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- set_io_configuration(io_line, io_mode)
Sets the configuration of the provided IO line.
- Parameters:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_io_sampling_rate(rate)
Sets the IO sampling rate of the XBee in seconds. A sample rate of 0 means the IO sampling feature is disabled.
- Parameters:
rate (Integer) – New IO sampling rate of the XBee in seconds.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_node_id(node_id)
Sets the node identifier (‘NI`) value of the XBee.
- Parameters:
node_id (String) – New node identifier (‘NI’) of the XBee.
- Raises:
ValueError – If node_id is None or its length is greater than 20.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- set_pan_id(value)
Sets the operating PAN ID of the XBee.
- Parameters:
value (Bytearray) – New operating PAN ID of the XBee. Must have only 1 or 2 bytes.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_power_level(power_level)
Sets the power level of the XBee.
- Parameters:
power_level (
PowerLevel) – New power level of the XBee.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_pwm_duty_cycle(io_line, cycle)
Sets the duty cycle in % of the provided IO line.
The provided IO line must be PWM-capable, previously configured as PWM output.
- Parameters:
io_line (
IOLine) – IO Line to be assigned.cycle (Integer) – Duty cycle in % to be assigned. Must be between 0 and 100.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If the given IO line does not have PWM capability or cycle is not between 0 and 100.
See also
- set_sync_ops_timeout(sync_ops_timeout)
Sets the serial port read timeout.
- Parameters:
sync_ops_timeout (Integer) – Read timeout in seconds.
- update_bluetooth_password(new_password, apply=True, save=True)
Changes the Bluetooth password of this XBee with the new one provided.
Note that your device must include Bluetooth Low Energy support.
- Parameters:
new_password (String) – New Bluetooth password.
apply (Boolean, optional, default=`True`) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
save (Boolean, optional, default=`True`) – True to save changes, False otherwise.
- Raises:
ValueError – If new_password is invalid.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- update_bluetooth_salt_verifier(salt, verifier, apply=True, save=True)
Changes the Bluetooth password of this XBee with the new one provided.
Note that your device must include Bluetooth Low Energy support.
- Parameters:
salt (bytes) – New Bluetooth password.
verifier (bytes) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
apply (Boolean, optional, default=`True`) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
save (Boolean, optional, default=`True`) – True to save changes, False otherwise.
- Raises:
ValueError – If salt or verifier are invalid.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- update_device_data_from(device)
Updates the current node information with provided data. This is only for internal use.
- Parameters:
device (
AbstractXBeeDevice) – XBee to get the data from.- Returns:
True if the node data has been updated, False otherwise.
- Return type:
Boolean
- update_firmware(xml_firmware_file, xbee_firmware_file=None, bootloader_firmware_file=None, timeout=None, progress_callback=None)
Performs a firmware update operation of the XBee.
- Parameters:
xml_firmware_file (String) – Path of the XML file that describes the firmware to upload.
xbee_firmware_file (String, optional, default=`None`) – Location of the XBee binary firmware file.
bootloader_firmware_file (String, optional, default=`None`) – Location of the bootloader binary firmware file.
timeout (Integer, optional, default=`None`) – Maximum time to wait for target read operations during the update process (seconds).
progress_callback (Function, optional, default=`None`) –
Function to 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 XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
OperationNotSupportedException – If XBee does not support firmware update.
FirmwareUpdateException – If there is any error during the firmware update.
- write_changes()
Writes configurable parameter values to the non-volatile memory of the XBee so that parameter modifications persist through subsequent resets.
Parameters values remain in the device’s memory until overwritten by subsequent use of this method.
If changes are made without writing them, the XBee reverts back to previously saved parameters the next time the module is powered-on.
Writing the parameter modifications does not mean those values are immediately applied, this depends on the status of the ‘apply configuration changes’ option. Use method
is_apply_changes_enabled()to get its status andenable_apply_changes()to enable/disable the option. Methodapply_changes()can be used in order to manually apply the changes.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- class digi.xbee.devices.RemoteRaw802Device(local_xbee, x64bit_addr=None, x16bit_addr=None, node_id=None)[source]
Bases:
RemoteXBeeDeviceThis class represents a remote 802.15.4 XBee.
Class constructor. Instantiates a new
RemoteXBeeDevicewith the provided parameters.- Parameters:
local_xbee (
XBeeDevice) – Local XBee associated with the remote one.x64bit_addr (
XBee64BitAddress) – 64-bit address of the remote XBee.x16bit_addr (
XBee16BitAddress) – 16-bit address of the remote XBee.node_id (String, optional) – Node identifier of the remote XBee.
- Raises:
XBeeException – If the protocol of local_xbee is invalid.
See also
- set_64bit_addr(address)[source]
Sets the 64-bit address of this remote 802.15.4 device.
- Parameters:
address (
XBee64BitAddress) – The 64-bit address to set.- Raises:
ValueError – If address is None.
- get_ai_status()[source]
Returns the current association status of this XBee. It indicates occurrences of errors during the modem initialization and connection.
- Returns:
- The XBee association
indication status.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- apply_changes()
Applies changes via ‘AC’ command.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- apply_profile(profile_path, timeout=None, progress_callback=None)
Applies the given XBee profile to the XBee.
- Parameters:
profile_path (String) – Path of the XBee profile file to apply.
timeout (Integer, optional, default=`None`) – Maximum time to wait for target read operations during the apply profile (seconds).
progress_callback (Function, optional, default=`None`) –
Function 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 XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
UpdateProfileException – If there is any error applying the XBee profile.
- property br
Returns the BR value of the device.
- Returns:
The BR value of the device.
- Return type:
Integer
- determine_protocol(hardware_version, firmware_version)
Determines the XBee protocol based on the given hardware and firmware versions.
- Parameters:
hardware_version (Integer) – Hardware version to get its protocol.
firmware_version (Bytearray) – Firmware version to get its protocol.
- Returns:
- XBee protocol corresponding to the given
hardware and firmware versions.
- Return type:
- disable_bluetooth()
Disables the Bluetooth interface of this XBee.
Note that your device must include Bluetooth Low Energy support.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- enable_apply_changes(value)
Sets apply changes flag.
- Parameters:
value (Boolean) – True to enable apply changes flag, False to disable it.
- enable_bluetooth()
Enables the Bluetooth interface of this XBee.
To work with this interface, you must also configure the Bluetooth password if not done previously. Use method
AbstractXBeeDevice.update_bluetooth_password().Note that your XBee must include Bluetooth Low Energy support.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- execute_command(parameter, value=None, apply=None)
Executes the provided command.
- Parameters:
or (parameter (String) – class: .ATStringCommand): AT command to execute.
value (bytearray, optional, default=`None`) – Command value (if any).
apply (Boolean, optional, default=`None`) – True to apply changes in XBee configuration, False not to apply them, None to use is_apply_changes_enabled() returned value.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- get_16bit_addr()
Returns the 16-bit address of the XBee.
- Returns:
16-bit address of the XBee.
- Return type:
See also
- get_64bit_addr()
Returns the 64-bit address of the XBee.
- Returns:
64-bit address of the XBee.
- Return type:
See also
- get_adc_value(io_line)
Returns the analog value of the provided IO line.
The provided IO line must be previously configured as ADC. To do so, use
AbstractXBeeDevice.set_io_configuration()andIOMode.ADC.- Parameters:
io_line (
IOLine) – IO line to get its ADC value.- Returns:
Analog value corresponding to the provided IO line.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If response does not contain the value for the given IO line.
See also
- get_api_output_mode()
Deprecated since version 1.3: Use
get_api_output_mode_value()Returns the API output mode of the XBee.
The API output mode determines the format of the data through the serial interface of the XBee.
- Returns:
API output mode of the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_api_output_mode_value()
Returns the API output mode of the XBee.
The API output mode determines the format that the received data is output through the serial interface of the XBee.
- Returns:
the parameter value.
- Return type:
Bytearray
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
- get_bluetooth_mac_addr()
Reads and returns the EUI-48 Bluetooth MAC address of this XBee following the format 00112233AABB.
Note that your device must include Bluetooth Low Energy support.
- Returns:
The Bluetooth MAC address.
- Return type:
String
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- get_comm_iface()
Returns the communication interface of the local XBee associated to the remote one.
- Returns:
- Communication interface of the
local XBee associated to the remote one.
- Return type:
XBeeCommunicationInterface
See also
XBeeCommunicationInterface
- get_current_frame_id()
Returns the last used frame ID.
- Returns:
Last used frame ID.
- Return type:
Integer
- get_dest_address()
Returns the 64-bit address of the XBee that is data destination.
- Returns:
64-bit address of destination XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_dio_value(io_line)
Returns the digital value of the provided IO line.
The provided IO line must be previously configured as digital I/O. To do so, use
AbstractXBeeDevice.set_io_configuration().- Parameters:
io_line (
IOLine) – the DIO line to gets its digital value.- Returns:
current value of the provided IO line.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If response does not contain the value for the given IO line.
See also
- get_file_manager()
Returns the file system manager for the XBee.
- Returns:
The file system manager.
- Return type:
- Raises:
FileSystemNotSupportedException – If the XBee does not support filesystem.
- get_firmware_version()
Returns the firmware version of the XBee.
- Returns:
Firmware version of the XBee.
- Return type:
Bytearray
- get_hardware_version()
Returns the hardware version of the XBee.
- Returns:
Hardware version of the XBee.
- Return type:
See also
- get_io_configuration(io_line)
Returns the configuration of the provided IO line.
- Parameters:
io_line (
IOLine) – IO line to get its configuration.- Returns:
IO mode of the IO line provided.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_io_sampling_rate()
Returns the IO sampling rate of the XBee.
- Returns:
IO sampling rate of XBee.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_local_xbee_device()
Returns the local XBee associated to the remote one.
- Returns:
Local XBee.
- Return type:
- get_node_id()
Returns the node identifier (‘NI’) value of the XBee.
- Returns:
Node identifier (‘NI’) of the XBee.
- Return type:
String
- get_ota_max_block_size()
Returns the maximum number of bytes to send for ota updates.
- Returns:
Maximum ota block size to send.
- Return type:
Integer
- get_pan_id()
Returns the operating PAN ID of the XBee.
- Returns:
Operating PAN ID of the XBee.
- Return type:
Bytearray
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_parameter(parameter, parameter_value=None, apply=None)
Override.
See also
- get_power_level()
Returns the power level of the XBee.
- Returns:
Power level of the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_pwm_duty_cycle(io_line)
Returns the PWM duty cycle in % corresponding to the provided IO line.
- Parameters:
io_line (
IOLine) – IO line to get its PWM duty cycle.- Returns:
PWM duty cycle of the given IO line.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If io_line has no PWM capability.
See also
- get_serial_port()
Returns the serial port of the local XBee associated to the remote one.
- Returns:
- Serial port of the local XBee associated
to the remote one.
- Return type:
XBeeSerialPort
See also
XBeeSerialPort
- get_sync_ops_timeout()
Returns the serial port read timeout.
- Returns:
Serial port read timeout in seconds.
- Return type:
Integer
- is_apply_changes_enabled()
Returns whether apply changes flag is enabled.
- Returns:
True if apply changes flag is enabled, False otherwise.
- Return type:
Boolean
- is_device_info_complete()
Returns whether XBee node information is complete.
- Returns:
True if node information is complete, False otherwise.
- Return type:
Boolean
- is_remote()
Override method.
See also
- property log
Returns the XBee logger.
- Returns:
The XBee device logger.
- Return type:
Logger
- property reachable
Returns whether the XBee is reachable.
- Returns:
True if the device is reachable, False otherwise.
- Return type:
Boolean
- read_device_info(init=True, fire_event=True)
Updates all instance parameters reading them from the XBee.
- Parameters:
init (Boolean, optional, default=`True`) – If False only not initialized parameters are read, all if True.
fire_event (Boolean, optional, default=`True`) – True to throw and update event if any parameter changed, False otherwise.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- read_io_sample()
Returns an IO sample from the XBee containing the value of all enabled digital IO and analog input channels.
- Returns:
IO sample read from the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- reset()
Override method.
See also
- property scan_counter
Returns the scan counter for this node.
- Returns:
The scan counter for this node.
- Return type:
Integer
- set_16bit_addr(value)
Sets the 16-bit address of the XBee.
- Parameters:
value (
XBee16BitAddress) – New 16-bit address of the XBee.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If the protocol is not 802.15.4.
- set_api_output_mode(api_output_mode)
Deprecated since version 1.3: Use
set_api_output_mode_value()Sets the API output mode of the XBee.
- Parameters:
api_output_mode (
APIOutputMode) – New API output mode.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
See also
- set_api_output_mode_value(api_output_mode)
Sets the API output mode of the XBee.
- Parameters:
api_output_mode (Integer) – New API output mode options. Calculate this value using the method
APIOutputModeBit.calculate_api_output_mode_value()with a set ofAPIOutputModeBit.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
See also
- set_dest_address(addr)
Sets the 64-bit address of the XBee that is data destination.
- Parameters:
addr (
XBee64BitAddressorRemoteXBeeDevice) – Address itself or remote XBee to be data destination.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If addr is None.
See also
- set_dio_change_detection(io_lines_set)
Sets the digital IO lines to be monitored and sampled whenever their status changes. A None set of lines disables this feature.
- Parameters:
io_lines_set – Set of
IOLine.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_dio_value(io_line, io_value)
Sets the digital value (high or low) to the provided IO line.
- Parameters:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- set_io_configuration(io_line, io_mode)
Sets the configuration of the provided IO line.
- Parameters:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_io_sampling_rate(rate)
Sets the IO sampling rate of the XBee in seconds. A sample rate of 0 means the IO sampling feature is disabled.
- Parameters:
rate (Integer) – New IO sampling rate of the XBee in seconds.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_local_xbee_device(local_xbee_device)
This methods associates a
XBeeDeviceto the remote XBee.- Parameters:
local_xbee_device (
XBeeDevice) – New local XBee associated to the remote one.
See also
- set_node_id(node_id)
Sets the node identifier (‘NI`) value of the XBee.
- Parameters:
node_id (String) – New node identifier (‘NI’) of the XBee.
- Raises:
ValueError – If node_id is None or its length is greater than 20.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- set_ota_max_block_size(size)
Sets the maximum number of bytes to send for ota updates.
- Parameters:
size (Integer) – Maximum ota block size to send.
- Raises:
ValueError – If size is not between 0 and 255.
- set_pan_id(value)
Sets the operating PAN ID of the XBee.
- Parameters:
value (Bytearray) – New operating PAN ID of the XBee. Must have only 1 or 2 bytes.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_parameter(parameter, value, apply=None)
Override.
See also
- set_power_level(power_level)
Sets the power level of the XBee.
- Parameters:
power_level (
PowerLevel) – New power level of the XBee.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_pwm_duty_cycle(io_line, cycle)
Sets the duty cycle in % of the provided IO line.
The provided IO line must be PWM-capable, previously configured as PWM output.
- Parameters:
io_line (
IOLine) – IO Line to be assigned.cycle (Integer) – Duty cycle in % to be assigned. Must be between 0 and 100.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If the given IO line does not have PWM capability or cycle is not between 0 and 100.
See also
- set_sync_ops_timeout(sync_ops_timeout)
Sets the serial port read timeout.
- Parameters:
sync_ops_timeout (Integer) – Read timeout in seconds.
- update_bluetooth_password(new_password, apply=True, save=True)
Changes the Bluetooth password of this XBee with the new one provided.
Note that your device must include Bluetooth Low Energy support.
- Parameters:
new_password (String) – New Bluetooth password.
apply (Boolean, optional, default=`True`) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
save (Boolean, optional, default=`True`) – True to save changes, False otherwise.
- Raises:
ValueError – If new_password is invalid.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- update_bluetooth_salt_verifier(salt, verifier, apply=True, save=True)
Changes the Bluetooth password of this XBee with the new one provided.
Note that your device must include Bluetooth Low Energy support.
- Parameters:
salt (bytes) – New Bluetooth password.
verifier (bytes) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
apply (Boolean, optional, default=`True`) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
save (Boolean, optional, default=`True`) – True to save changes, False otherwise.
- Raises:
ValueError – If salt or verifier are invalid.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- update_device_data_from(device)
Updates the current node information with provided data. This is only for internal use.
- Parameters:
device (
AbstractXBeeDevice) – XBee to get the data from.- Returns:
True if the node data has been updated, False otherwise.
- Return type:
Boolean
- update_filesystem_image(ota_filesystem_file, timeout=None, progress_callback=None)
Performs a filesystem image update operation of the device.
- Parameters:
ota_filesystem_file (String) – Location of the OTA filesystem image file.
timeout (Integer, optional) – Maximum time to wait for target read operations during the update process.
progress_callback (Function, optional) –
Function 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 device is not open.
InvalidOperatingModeException – If the device operating mode is invalid.
FileSystemNotSupportedException – If the filesystem update is not supported in the XBee.
FileSystemException – If there is any error performing the filesystem update.
- update_firmware(xml_firmware_file, xbee_firmware_file=None, bootloader_firmware_file=None, timeout=None, progress_callback=None)
Performs a firmware update operation of the XBee.
- Parameters:
xml_firmware_file (String) – Path of the XML file that describes the firmware to upload.
xbee_firmware_file (String, optional, default=`None`) – Location of the XBee binary firmware file.
bootloader_firmware_file (String, optional, default=`None`) – Location of the bootloader binary firmware file.
timeout (Integer, optional, default=`None`) – Maximum time to wait for target read operations during the update process (seconds).
progress_callback (Function, optional, default=`None`) –
Function to 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 XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
OperationNotSupportedException – If XBee does not support firmware update.
FirmwareUpdateException – If there is any error during the firmware update.
- write_changes()
Writes configurable parameter values to the non-volatile memory of the XBee so that parameter modifications persist through subsequent resets.
Parameters values remain in the device’s memory until overwritten by subsequent use of this method.
If changes are made without writing them, the XBee reverts back to previously saved parameters the next time the module is powered-on.
Writing the parameter modifications does not mean those values are immediately applied, this depends on the status of the ‘apply configuration changes’ option. Use method
is_apply_changes_enabled()to get its status andenable_apply_changes()to enable/disable the option. Methodapply_changes()can be used in order to manually apply the changes.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- class digi.xbee.devices.RemoteDigiMeshDevice(local_xbee, x64bit_addr=None, node_id=None)[source]
Bases:
RemoteXBeeDeviceThis class represents a remote DigiMesh XBee device.
Class constructor. Instantiates a new
RemoteDigiMeshDevicewith the provided parameters.- Parameters:
local_xbee (
XBeeDevice) – Local XBee associated with the remote one.x64bit_addr (
XBee64BitAddress) – 64-bit address of the remote XBee.node_id (String, optional) – Node identifier of the remote XBee.
- Raises:
XBeeException – If the protocol of local_xbee is invalid.
See also
- get_neighbors(neighbor_cb=None, finished_cb=None, timeout=None)[source]
Returns the neighbors of this XBee. If neighbor_cb is not defined, the process blocks during the specified timeout.
- Parameters:
neighbor_cb (Function, optional, default=`None`) –
Method called when a new neighbor is received. Receives two arguments:
The XBee that owns this new neighbor.
The new neighbor.
finished_cb (Function, optional, default=`None`) –
Method to execute when the process finishes. Receives three arguments:
The XBee that is searching for its neighbors.
A list with the discovered neighbors.
An error message if something went wrong.
timeout (Float, optional, default=`NeighborFinder.DEFAULT_TIMEOUT`) – The timeout in seconds.
- Returns:
- List of
Neighborwhen neighbor_cb is not defined, None otherwise (in this case neighbors are received in the callback).
- List of
- Return type:
List
- Raises:
OperationNotSupportedException – If XBee protocol is not DigiMesh.
See also
com.digi.models.zdo.Neighbor
- apply_changes()
Applies changes via ‘AC’ command.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- apply_profile(profile_path, timeout=None, progress_callback=None)
Applies the given XBee profile to the XBee.
- Parameters:
profile_path (String) – Path of the XBee profile file to apply.
timeout (Integer, optional, default=`None`) – Maximum time to wait for target read operations during the apply profile (seconds).
progress_callback (Function, optional, default=`None`) –
Function 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 XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
UpdateProfileException – If there is any error applying the XBee profile.
- property br
Returns the BR value of the device.
- Returns:
The BR value of the device.
- Return type:
Integer
- determine_protocol(hardware_version, firmware_version)
Determines the XBee protocol based on the given hardware and firmware versions.
- Parameters:
hardware_version (Integer) – Hardware version to get its protocol.
firmware_version (Bytearray) – Firmware version to get its protocol.
- Returns:
- XBee protocol corresponding to the given
hardware and firmware versions.
- Return type:
- disable_bluetooth()
Disables the Bluetooth interface of this XBee.
Note that your device must include Bluetooth Low Energy support.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- enable_apply_changes(value)
Sets apply changes flag.
- Parameters:
value (Boolean) – True to enable apply changes flag, False to disable it.
- enable_bluetooth()
Enables the Bluetooth interface of this XBee.
To work with this interface, you must also configure the Bluetooth password if not done previously. Use method
AbstractXBeeDevice.update_bluetooth_password().Note that your XBee must include Bluetooth Low Energy support.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- execute_command(parameter, value=None, apply=None)
Executes the provided command.
- Parameters:
or (parameter (String) – class: .ATStringCommand): AT command to execute.
value (bytearray, optional, default=`None`) – Command value (if any).
apply (Boolean, optional, default=`None`) – True to apply changes in XBee configuration, False not to apply them, None to use is_apply_changes_enabled() returned value.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- get_16bit_addr()
Returns the 16-bit address of the XBee.
- Returns:
16-bit address of the XBee.
- Return type:
See also
- get_64bit_addr()
Returns the 64-bit address of the XBee.
- Returns:
64-bit address of the XBee.
- Return type:
See also
- get_adc_value(io_line)
Returns the analog value of the provided IO line.
The provided IO line must be previously configured as ADC. To do so, use
AbstractXBeeDevice.set_io_configuration()andIOMode.ADC.- Parameters:
io_line (
IOLine) – IO line to get its ADC value.- Returns:
Analog value corresponding to the provided IO line.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If response does not contain the value for the given IO line.
See also
- get_api_output_mode()
Deprecated since version 1.3: Use
get_api_output_mode_value()Returns the API output mode of the XBee.
The API output mode determines the format of the data through the serial interface of the XBee.
- Returns:
API output mode of the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_api_output_mode_value()
Returns the API output mode of the XBee.
The API output mode determines the format that the received data is output through the serial interface of the XBee.
- Returns:
the parameter value.
- Return type:
Bytearray
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
- get_bluetooth_mac_addr()
Reads and returns the EUI-48 Bluetooth MAC address of this XBee following the format 00112233AABB.
Note that your device must include Bluetooth Low Energy support.
- Returns:
The Bluetooth MAC address.
- Return type:
String
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- get_comm_iface()
Returns the communication interface of the local XBee associated to the remote one.
- Returns:
- Communication interface of the
local XBee associated to the remote one.
- Return type:
XBeeCommunicationInterface
See also
XBeeCommunicationInterface
- get_current_frame_id()
Returns the last used frame ID.
- Returns:
Last used frame ID.
- Return type:
Integer
- get_dest_address()
Returns the 64-bit address of the XBee that is data destination.
- Returns:
64-bit address of destination XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_dio_value(io_line)
Returns the digital value of the provided IO line.
The provided IO line must be previously configured as digital I/O. To do so, use
AbstractXBeeDevice.set_io_configuration().- Parameters:
io_line (
IOLine) – the DIO line to gets its digital value.- Returns:
current value of the provided IO line.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If response does not contain the value for the given IO line.
See also
- get_file_manager()
Returns the file system manager for the XBee.
- Returns:
The file system manager.
- Return type:
- Raises:
FileSystemNotSupportedException – If the XBee does not support filesystem.
- get_firmware_version()
Returns the firmware version of the XBee.
- Returns:
Firmware version of the XBee.
- Return type:
Bytearray
- get_hardware_version()
Returns the hardware version of the XBee.
- Returns:
Hardware version of the XBee.
- Return type:
See also
- get_io_configuration(io_line)
Returns the configuration of the provided IO line.
- Parameters:
io_line (
IOLine) – IO line to get its configuration.- Returns:
IO mode of the IO line provided.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_io_sampling_rate()
Returns the IO sampling rate of the XBee.
- Returns:
IO sampling rate of XBee.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_local_xbee_device()
Returns the local XBee associated to the remote one.
- Returns:
Local XBee.
- Return type:
- get_node_id()
Returns the node identifier (‘NI’) value of the XBee.
- Returns:
Node identifier (‘NI’) of the XBee.
- Return type:
String
- get_ota_max_block_size()
Returns the maximum number of bytes to send for ota updates.
- Returns:
Maximum ota block size to send.
- Return type:
Integer
- get_pan_id()
Returns the operating PAN ID of the XBee.
- Returns:
Operating PAN ID of the XBee.
- Return type:
Bytearray
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_parameter(parameter, parameter_value=None, apply=None)
Override.
See also
- get_power_level()
Returns the power level of the XBee.
- Returns:
Power level of the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_pwm_duty_cycle(io_line)
Returns the PWM duty cycle in % corresponding to the provided IO line.
- Parameters:
io_line (
IOLine) – IO line to get its PWM duty cycle.- Returns:
PWM duty cycle of the given IO line.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If io_line has no PWM capability.
See also
- get_serial_port()
Returns the serial port of the local XBee associated to the remote one.
- Returns:
- Serial port of the local XBee associated
to the remote one.
- Return type:
XBeeSerialPort
See also
XBeeSerialPort
- get_sync_ops_timeout()
Returns the serial port read timeout.
- Returns:
Serial port read timeout in seconds.
- Return type:
Integer
- is_apply_changes_enabled()
Returns whether apply changes flag is enabled.
- Returns:
True if apply changes flag is enabled, False otherwise.
- Return type:
Boolean
- is_device_info_complete()
Returns whether XBee node information is complete.
- Returns:
True if node information is complete, False otherwise.
- Return type:
Boolean
- is_remote()
Override method.
See also
- property log
Returns the XBee logger.
- Returns:
The XBee device logger.
- Return type:
Logger
- property reachable
Returns whether the XBee is reachable.
- Returns:
True if the device is reachable, False otherwise.
- Return type:
Boolean
- read_device_info(init=True, fire_event=True)
Updates all instance parameters reading them from the XBee.
- Parameters:
init (Boolean, optional, default=`True`) – If False only not initialized parameters are read, all if True.
fire_event (Boolean, optional, default=`True`) – True to throw and update event if any parameter changed, False otherwise.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- read_io_sample()
Returns an IO sample from the XBee containing the value of all enabled digital IO and analog input channels.
- Returns:
IO sample read from the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- reset()
Override method.
See also
- property scan_counter
Returns the scan counter for this node.
- Returns:
The scan counter for this node.
- Return type:
Integer
- set_16bit_addr(value)
Sets the 16-bit address of the XBee.
- Parameters:
value (
XBee16BitAddress) – New 16-bit address of the XBee.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If the protocol is not 802.15.4.
- set_api_output_mode(api_output_mode)
Deprecated since version 1.3: Use
set_api_output_mode_value()Sets the API output mode of the XBee.
- Parameters:
api_output_mode (
APIOutputMode) – New API output mode.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
See also
- set_api_output_mode_value(api_output_mode)
Sets the API output mode of the XBee.
- Parameters:
api_output_mode (Integer) – New API output mode options. Calculate this value using the method
APIOutputModeBit.calculate_api_output_mode_value()with a set ofAPIOutputModeBit.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
See also
- set_dest_address(addr)
Sets the 64-bit address of the XBee that is data destination.
- Parameters:
addr (
XBee64BitAddressorRemoteXBeeDevice) – Address itself or remote XBee to be data destination.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If addr is None.
See also
- set_dio_change_detection(io_lines_set)
Sets the digital IO lines to be monitored and sampled whenever their status changes. A None set of lines disables this feature.
- Parameters:
io_lines_set – Set of
IOLine.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_dio_value(io_line, io_value)
Sets the digital value (high or low) to the provided IO line.
- Parameters:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- set_io_configuration(io_line, io_mode)
Sets the configuration of the provided IO line.
- Parameters:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_io_sampling_rate(rate)
Sets the IO sampling rate of the XBee in seconds. A sample rate of 0 means the IO sampling feature is disabled.
- Parameters:
rate (Integer) – New IO sampling rate of the XBee in seconds.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_local_xbee_device(local_xbee_device)
This methods associates a
XBeeDeviceto the remote XBee.- Parameters:
local_xbee_device (
XBeeDevice) – New local XBee associated to the remote one.
See also
- set_node_id(node_id)
Sets the node identifier (‘NI`) value of the XBee.
- Parameters:
node_id (String) – New node identifier (‘NI’) of the XBee.
- Raises:
ValueError – If node_id is None or its length is greater than 20.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- set_ota_max_block_size(size)
Sets the maximum number of bytes to send for ota updates.
- Parameters:
size (Integer) – Maximum ota block size to send.
- Raises:
ValueError – If size is not between 0 and 255.
- set_pan_id(value)
Sets the operating PAN ID of the XBee.
- Parameters:
value (Bytearray) – New operating PAN ID of the XBee. Must have only 1 or 2 bytes.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_parameter(parameter, value, apply=None)
Override.
See also
- set_power_level(power_level)
Sets the power level of the XBee.
- Parameters:
power_level (
PowerLevel) – New power level of the XBee.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_pwm_duty_cycle(io_line, cycle)
Sets the duty cycle in % of the provided IO line.
The provided IO line must be PWM-capable, previously configured as PWM output.
- Parameters:
io_line (
IOLine) – IO Line to be assigned.cycle (Integer) – Duty cycle in % to be assigned. Must be between 0 and 100.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If the given IO line does not have PWM capability or cycle is not between 0 and 100.
See also
- set_sync_ops_timeout(sync_ops_timeout)
Sets the serial port read timeout.
- Parameters:
sync_ops_timeout (Integer) – Read timeout in seconds.
- update_bluetooth_password(new_password, apply=True, save=True)
Changes the Bluetooth password of this XBee with the new one provided.
Note that your device must include Bluetooth Low Energy support.
- Parameters:
new_password (String) – New Bluetooth password.
apply (Boolean, optional, default=`True`) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
save (Boolean, optional, default=`True`) – True to save changes, False otherwise.
- Raises:
ValueError – If new_password is invalid.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- update_bluetooth_salt_verifier(salt, verifier, apply=True, save=True)
Changes the Bluetooth password of this XBee with the new one provided.
Note that your device must include Bluetooth Low Energy support.
- Parameters:
salt (bytes) – New Bluetooth password.
verifier (bytes) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
apply (Boolean, optional, default=`True`) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
save (Boolean, optional, default=`True`) – True to save changes, False otherwise.
- Raises:
ValueError – If salt or verifier are invalid.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- update_device_data_from(device)
Updates the current node information with provided data. This is only for internal use.
- Parameters:
device (
AbstractXBeeDevice) – XBee to get the data from.- Returns:
True if the node data has been updated, False otherwise.
- Return type:
Boolean
- update_filesystem_image(ota_filesystem_file, timeout=None, progress_callback=None)
Performs a filesystem image update operation of the device.
- Parameters:
ota_filesystem_file (String) – Location of the OTA filesystem image file.
timeout (Integer, optional) – Maximum time to wait for target read operations during the update process.
progress_callback (Function, optional) –
Function 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 device is not open.
InvalidOperatingModeException – If the device operating mode is invalid.
FileSystemNotSupportedException – If the filesystem update is not supported in the XBee.
FileSystemException – If there is any error performing the filesystem update.
- update_firmware(xml_firmware_file, xbee_firmware_file=None, bootloader_firmware_file=None, timeout=None, progress_callback=None)
Performs a firmware update operation of the XBee.
- Parameters:
xml_firmware_file (String) – Path of the XML file that describes the firmware to upload.
xbee_firmware_file (String, optional, default=`None`) – Location of the XBee binary firmware file.
bootloader_firmware_file (String, optional, default=`None`) – Location of the bootloader binary firmware file.
timeout (Integer, optional, default=`None`) – Maximum time to wait for target read operations during the update process (seconds).
progress_callback (Function, optional, default=`None`) –
Function to 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 XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
OperationNotSupportedException – If XBee does not support firmware update.
FirmwareUpdateException – If there is any error during the firmware update.
- write_changes()
Writes configurable parameter values to the non-volatile memory of the XBee so that parameter modifications persist through subsequent resets.
Parameters values remain in the device’s memory until overwritten by subsequent use of this method.
If changes are made without writing them, the XBee reverts back to previously saved parameters the next time the module is powered-on.
Writing the parameter modifications does not mean those values are immediately applied, this depends on the status of the ‘apply configuration changes’ option. Use method
is_apply_changes_enabled()to get its status andenable_apply_changes()to enable/disable the option. Methodapply_changes()can be used in order to manually apply the changes.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- class digi.xbee.devices.RemoteDigiPointDevice(local_xbee, x64bit_addr=None, node_id=None)[source]
Bases:
RemoteXBeeDeviceThis class represents a remote DigiPoint XBee.
Class constructor. Instantiates a new
RemoteDigiMeshDevicewith the provided parameters.- Parameters:
local_xbee (
XBeeDevice) – Local XBee associated with the remote one.x64bit_addr (
XBee64BitAddress) – 64-bit address of the remote XBee.node_id (String, optional) – Node identifier of the remote XBee.
- Raises:
XBeeException – If the protocol of local_xbee is invalid.
See also
- apply_changes()
Applies changes via ‘AC’ command.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- apply_profile(profile_path, timeout=None, progress_callback=None)
Applies the given XBee profile to the XBee.
- Parameters:
profile_path (String) – Path of the XBee profile file to apply.
timeout (Integer, optional, default=`None`) – Maximum time to wait for target read operations during the apply profile (seconds).
progress_callback (Function, optional, default=`None`) –
Function 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 XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
UpdateProfileException – If there is any error applying the XBee profile.
- property br
Returns the BR value of the device.
- Returns:
The BR value of the device.
- Return type:
Integer
- determine_protocol(hardware_version, firmware_version)
Determines the XBee protocol based on the given hardware and firmware versions.
- Parameters:
hardware_version (Integer) – Hardware version to get its protocol.
firmware_version (Bytearray) – Firmware version to get its protocol.
- Returns:
- XBee protocol corresponding to the given
hardware and firmware versions.
- Return type:
- disable_bluetooth()
Disables the Bluetooth interface of this XBee.
Note that your device must include Bluetooth Low Energy support.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- enable_apply_changes(value)
Sets apply changes flag.
- Parameters:
value (Boolean) – True to enable apply changes flag, False to disable it.
- enable_bluetooth()
Enables the Bluetooth interface of this XBee.
To work with this interface, you must also configure the Bluetooth password if not done previously. Use method
AbstractXBeeDevice.update_bluetooth_password().Note that your XBee must include Bluetooth Low Energy support.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- execute_command(parameter, value=None, apply=None)
Executes the provided command.
- Parameters:
or (parameter (String) – class: .ATStringCommand): AT command to execute.
value (bytearray, optional, default=`None`) – Command value (if any).
apply (Boolean, optional, default=`None`) – True to apply changes in XBee configuration, False not to apply them, None to use is_apply_changes_enabled() returned value.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- get_16bit_addr()
Returns the 16-bit address of the XBee.
- Returns:
16-bit address of the XBee.
- Return type:
See also
- get_64bit_addr()
Returns the 64-bit address of the XBee.
- Returns:
64-bit address of the XBee.
- Return type:
See also
- get_adc_value(io_line)
Returns the analog value of the provided IO line.
The provided IO line must be previously configured as ADC. To do so, use
AbstractXBeeDevice.set_io_configuration()andIOMode.ADC.- Parameters:
io_line (
IOLine) – IO line to get its ADC value.- Returns:
Analog value corresponding to the provided IO line.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If response does not contain the value for the given IO line.
See also
- get_api_output_mode()
Deprecated since version 1.3: Use
get_api_output_mode_value()Returns the API output mode of the XBee.
The API output mode determines the format of the data through the serial interface of the XBee.
- Returns:
API output mode of the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_api_output_mode_value()
Returns the API output mode of the XBee.
The API output mode determines the format that the received data is output through the serial interface of the XBee.
- Returns:
the parameter value.
- Return type:
Bytearray
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
- get_bluetooth_mac_addr()
Reads and returns the EUI-48 Bluetooth MAC address of this XBee following the format 00112233AABB.
Note that your device must include Bluetooth Low Energy support.
- Returns:
The Bluetooth MAC address.
- Return type:
String
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- get_comm_iface()
Returns the communication interface of the local XBee associated to the remote one.
- Returns:
- Communication interface of the
local XBee associated to the remote one.
- Return type:
XBeeCommunicationInterface
See also
XBeeCommunicationInterface
- get_current_frame_id()
Returns the last used frame ID.
- Returns:
Last used frame ID.
- Return type:
Integer
- get_dest_address()
Returns the 64-bit address of the XBee that is data destination.
- Returns:
64-bit address of destination XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_dio_value(io_line)
Returns the digital value of the provided IO line.
The provided IO line must be previously configured as digital I/O. To do so, use
AbstractXBeeDevice.set_io_configuration().- Parameters:
io_line (
IOLine) – the DIO line to gets its digital value.- Returns:
current value of the provided IO line.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If response does not contain the value for the given IO line.
See also
- get_file_manager()
Returns the file system manager for the XBee.
- Returns:
The file system manager.
- Return type:
- Raises:
FileSystemNotSupportedException – If the XBee does not support filesystem.
- get_firmware_version()
Returns the firmware version of the XBee.
- Returns:
Firmware version of the XBee.
- Return type:
Bytearray
- get_hardware_version()
Returns the hardware version of the XBee.
- Returns:
Hardware version of the XBee.
- Return type:
See also
- get_io_configuration(io_line)
Returns the configuration of the provided IO line.
- Parameters:
io_line (
IOLine) – IO line to get its configuration.- Returns:
IO mode of the IO line provided.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_io_sampling_rate()
Returns the IO sampling rate of the XBee.
- Returns:
IO sampling rate of XBee.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_local_xbee_device()
Returns the local XBee associated to the remote one.
- Returns:
Local XBee.
- Return type:
- get_node_id()
Returns the node identifier (‘NI’) value of the XBee.
- Returns:
Node identifier (‘NI’) of the XBee.
- Return type:
String
- get_ota_max_block_size()
Returns the maximum number of bytes to send for ota updates.
- Returns:
Maximum ota block size to send.
- Return type:
Integer
- get_pan_id()
Returns the operating PAN ID of the XBee.
- Returns:
Operating PAN ID of the XBee.
- Return type:
Bytearray
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_parameter(parameter, parameter_value=None, apply=None)
Override.
See also
- get_power_level()
Returns the power level of the XBee.
- Returns:
Power level of the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_pwm_duty_cycle(io_line)
Returns the PWM duty cycle in % corresponding to the provided IO line.
- Parameters:
io_line (
IOLine) – IO line to get its PWM duty cycle.- Returns:
PWM duty cycle of the given IO line.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If io_line has no PWM capability.
See also
- get_serial_port()
Returns the serial port of the local XBee associated to the remote one.
- Returns:
- Serial port of the local XBee associated
to the remote one.
- Return type:
XBeeSerialPort
See also
XBeeSerialPort
- get_sync_ops_timeout()
Returns the serial port read timeout.
- Returns:
Serial port read timeout in seconds.
- Return type:
Integer
- is_apply_changes_enabled()
Returns whether apply changes flag is enabled.
- Returns:
True if apply changes flag is enabled, False otherwise.
- Return type:
Boolean
- is_device_info_complete()
Returns whether XBee node information is complete.
- Returns:
True if node information is complete, False otherwise.
- Return type:
Boolean
- is_remote()
Override method.
See also
- property log
Returns the XBee logger.
- Returns:
The XBee device logger.
- Return type:
Logger
- property reachable
Returns whether the XBee is reachable.
- Returns:
True if the device is reachable, False otherwise.
- Return type:
Boolean
- read_device_info(init=True, fire_event=True)
Updates all instance parameters reading them from the XBee.
- Parameters:
init (Boolean, optional, default=`True`) – If False only not initialized parameters are read, all if True.
fire_event (Boolean, optional, default=`True`) – True to throw and update event if any parameter changed, False otherwise.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- read_io_sample()
Returns an IO sample from the XBee containing the value of all enabled digital IO and analog input channels.
- Returns:
IO sample read from the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- reset()
Override method.
See also
- property scan_counter
Returns the scan counter for this node.
- Returns:
The scan counter for this node.
- Return type:
Integer
- set_16bit_addr(value)
Sets the 16-bit address of the XBee.
- Parameters:
value (
XBee16BitAddress) – New 16-bit address of the XBee.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If the protocol is not 802.15.4.
- set_api_output_mode(api_output_mode)
Deprecated since version 1.3: Use
set_api_output_mode_value()Sets the API output mode of the XBee.
- Parameters:
api_output_mode (
APIOutputMode) – New API output mode.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
See also
- set_api_output_mode_value(api_output_mode)
Sets the API output mode of the XBee.
- Parameters:
api_output_mode (Integer) – New API output mode options. Calculate this value using the method
APIOutputModeBit.calculate_api_output_mode_value()with a set ofAPIOutputModeBit.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
See also
- set_dest_address(addr)
Sets the 64-bit address of the XBee that is data destination.
- Parameters:
addr (
XBee64BitAddressorRemoteXBeeDevice) – Address itself or remote XBee to be data destination.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If addr is None.
See also
- set_dio_change_detection(io_lines_set)
Sets the digital IO lines to be monitored and sampled whenever their status changes. A None set of lines disables this feature.
- Parameters:
io_lines_set – Set of
IOLine.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_dio_value(io_line, io_value)
Sets the digital value (high or low) to the provided IO line.
- Parameters:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- set_io_configuration(io_line, io_mode)
Sets the configuration of the provided IO line.
- Parameters:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_io_sampling_rate(rate)
Sets the IO sampling rate of the XBee in seconds. A sample rate of 0 means the IO sampling feature is disabled.
- Parameters:
rate (Integer) – New IO sampling rate of the XBee in seconds.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_local_xbee_device(local_xbee_device)
This methods associates a
XBeeDeviceto the remote XBee.- Parameters:
local_xbee_device (
XBeeDevice) – New local XBee associated to the remote one.
See also
- set_node_id(node_id)
Sets the node identifier (‘NI`) value of the XBee.
- Parameters:
node_id (String) – New node identifier (‘NI’) of the XBee.
- Raises:
ValueError – If node_id is None or its length is greater than 20.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- set_ota_max_block_size(size)
Sets the maximum number of bytes to send for ota updates.
- Parameters:
size (Integer) – Maximum ota block size to send.
- Raises:
ValueError – If size is not between 0 and 255.
- set_pan_id(value)
Sets the operating PAN ID of the XBee.
- Parameters:
value (Bytearray) – New operating PAN ID of the XBee. Must have only 1 or 2 bytes.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_parameter(parameter, value, apply=None)
Override.
See also
- set_power_level(power_level)
Sets the power level of the XBee.
- Parameters:
power_level (
PowerLevel) – New power level of the XBee.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_pwm_duty_cycle(io_line, cycle)
Sets the duty cycle in % of the provided IO line.
The provided IO line must be PWM-capable, previously configured as PWM output.
- Parameters:
io_line (
IOLine) – IO Line to be assigned.cycle (Integer) – Duty cycle in % to be assigned. Must be between 0 and 100.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If the given IO line does not have PWM capability or cycle is not between 0 and 100.
See also
- set_sync_ops_timeout(sync_ops_timeout)
Sets the serial port read timeout.
- Parameters:
sync_ops_timeout (Integer) – Read timeout in seconds.
- update_bluetooth_password(new_password, apply=True, save=True)
Changes the Bluetooth password of this XBee with the new one provided.
Note that your device must include Bluetooth Low Energy support.
- Parameters:
new_password (String) – New Bluetooth password.
apply (Boolean, optional, default=`True`) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
save (Boolean, optional, default=`True`) – True to save changes, False otherwise.
- Raises:
ValueError – If new_password is invalid.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- update_bluetooth_salt_verifier(salt, verifier, apply=True, save=True)
Changes the Bluetooth password of this XBee with the new one provided.
Note that your device must include Bluetooth Low Energy support.
- Parameters:
salt (bytes) – New Bluetooth password.
verifier (bytes) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
apply (Boolean, optional, default=`True`) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
save (Boolean, optional, default=`True`) – True to save changes, False otherwise.
- Raises:
ValueError – If salt or verifier are invalid.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- update_device_data_from(device)
Updates the current node information with provided data. This is only for internal use.
- Parameters:
device (
AbstractXBeeDevice) – XBee to get the data from.- Returns:
True if the node data has been updated, False otherwise.
- Return type:
Boolean
- update_filesystem_image(ota_filesystem_file, timeout=None, progress_callback=None)
Performs a filesystem image update operation of the device.
- Parameters:
ota_filesystem_file (String) – Location of the OTA filesystem image file.
timeout (Integer, optional) – Maximum time to wait for target read operations during the update process.
progress_callback (Function, optional) –
Function 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 device is not open.
InvalidOperatingModeException – If the device operating mode is invalid.
FileSystemNotSupportedException – If the filesystem update is not supported in the XBee.
FileSystemException – If there is any error performing the filesystem update.
- update_firmware(xml_firmware_file, xbee_firmware_file=None, bootloader_firmware_file=None, timeout=None, progress_callback=None)
Performs a firmware update operation of the XBee.
- Parameters:
xml_firmware_file (String) – Path of the XML file that describes the firmware to upload.
xbee_firmware_file (String, optional, default=`None`) – Location of the XBee binary firmware file.
bootloader_firmware_file (String, optional, default=`None`) – Location of the bootloader binary firmware file.
timeout (Integer, optional, default=`None`) – Maximum time to wait for target read operations during the update process (seconds).
progress_callback (Function, optional, default=`None`) –
Function to 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 XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
OperationNotSupportedException – If XBee does not support firmware update.
FirmwareUpdateException – If there is any error during the firmware update.
- write_changes()
Writes configurable parameter values to the non-volatile memory of the XBee so that parameter modifications persist through subsequent resets.
Parameters values remain in the device’s memory until overwritten by subsequent use of this method.
If changes are made without writing them, the XBee reverts back to previously saved parameters the next time the module is powered-on.
Writing the parameter modifications does not mean those values are immediately applied, this depends on the status of the ‘apply configuration changes’ option. Use method
is_apply_changes_enabled()to get its status andenable_apply_changes()to enable/disable the option. Methodapply_changes()can be used in order to manually apply the changes.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- class digi.xbee.devices.RemoteZigBeeDevice(local_xbee, x64bit_addr=None, x16bit_addr=None, node_id=None)[source]
Bases:
RemoteXBeeDeviceThis class represents a remote Zigbee XBee.
Class constructor. Instantiates a new
RemoteDigiMeshDevicewith the provided parameters.- Parameters:
local_xbee (
XBeeDevice) – Local XBee associated with the remote one.x64bit_addr (
XBee64BitAddress) – 64-bit address of the remote XBee.x16bit_addr (
XBee16BitAddress) – 16-bit address of the remote XBee.node_id (String, optional) – Node identifier of the remote XBee.
- Raises:
XBeeException – If the protocol of local_xbee is invalid.
See also
- property parent
Returns the parent of the XBee if it is an end device.
- Returns:
- The parent of the node for end
devices, None if unknown or if it is not an end device.
- Return type:
- get_ai_status()[source]
Returns the current association status of this XBee. It indicates occurrences of errors during the modem initialization and connection.
- Returns:
- The XBee association
indication status.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- force_disassociate()[source]
Forces this XBee to immediately disassociate from the network and re-attempt to associate.
Only valid for End Devices.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- get_routes(route_cb=None, finished_cb=None, timeout=None)[source]
Returns the routes of this XBee. If route_cb is not defined, the process blocks until the complete routing table is read.
- Parameters:
route_cb (Function, optional, default=`None`) –
Method called when a new route is received. Receives two arguments:
The XBee that owns this new route.
The new route.
finished_cb (Function, optional, default=`None`) –
Method to execute when the process finishes. Receives three arguments:
The XBee that executed the ZDO command.
A list with the discovered routes.
An error message if something went wrong.
timeout (Float, optional, default=`RouteTableReader.DEFAULT_TIMEOUT`) – The ZDO command timeout in seconds.
- Returns:
- List of
Routewhen route_cb is not defined, None otherwise (in this case routes are received in the callback).
- List of
- Return type:
List
- Raises:
OperationNotSupportedException – If XBee protocol is not Zigbee or Smart Energy.
See also
com.digi.models.zdo.Route
- get_neighbors(neighbor_cb=None, finished_cb=None, timeout=None)[source]
Returns the neighbors of this XBee. If neighbor_cb is not defined, the process blocks until the complete neighbor table is read.
- Parameters:
neighbor_cb (Function, optional, default=`None`) –
Method called when a new neighbor is received. Receives two arguments:
The XBee that owns this new neighbor.
The new neighbor.
finished_cb (Function, optional, default=`None`) –
Method to execute when the process finishes. Receives three arguments:
The XBee that executed the ZDO command.
A list with the discovered neighbors.
An error message if something went wrong.
timeout (Float, optional, default=`NeighborTableReader.DEFAULT_TIMEOUT`) – The ZDO command timeout in seconds.
- Returns:
- List of
Neighborwhen neighbor_cb is not defined, None otherwise (in this case neighbors are received in the callback).
- List of
- Return type:
List
- Raises:
OperationNotSupportedException – If XBee protocol is not Zigbee or Smart Energy.
See also
com.digi.models.zdo.Neighbor
- apply_changes()
Applies changes via ‘AC’ command.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- apply_profile(profile_path, timeout=None, progress_callback=None)
Applies the given XBee profile to the XBee.
- Parameters:
profile_path (String) – Path of the XBee profile file to apply.
timeout (Integer, optional, default=`None`) – Maximum time to wait for target read operations during the apply profile (seconds).
progress_callback (Function, optional, default=`None`) –
Function 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 XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
UpdateProfileException – If there is any error applying the XBee profile.
- property br
Returns the BR value of the device.
- Returns:
The BR value of the device.
- Return type:
Integer
- determine_protocol(hardware_version, firmware_version)
Determines the XBee protocol based on the given hardware and firmware versions.
- Parameters:
hardware_version (Integer) – Hardware version to get its protocol.
firmware_version (Bytearray) – Firmware version to get its protocol.
- Returns:
- XBee protocol corresponding to the given
hardware and firmware versions.
- Return type:
- disable_bluetooth()
Disables the Bluetooth interface of this XBee.
Note that your device must include Bluetooth Low Energy support.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- enable_apply_changes(value)
Sets apply changes flag.
- Parameters:
value (Boolean) – True to enable apply changes flag, False to disable it.
- enable_bluetooth()
Enables the Bluetooth interface of this XBee.
To work with this interface, you must also configure the Bluetooth password if not done previously. Use method
AbstractXBeeDevice.update_bluetooth_password().Note that your XBee must include Bluetooth Low Energy support.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- execute_command(parameter, value=None, apply=None)
Executes the provided command.
- Parameters:
or (parameter (String) – class: .ATStringCommand): AT command to execute.
value (bytearray, optional, default=`None`) – Command value (if any).
apply (Boolean, optional, default=`None`) – True to apply changes in XBee configuration, False not to apply them, None to use is_apply_changes_enabled() returned value.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- get_16bit_addr()
Returns the 16-bit address of the XBee.
- Returns:
16-bit address of the XBee.
- Return type:
See also
- get_64bit_addr()
Returns the 64-bit address of the XBee.
- Returns:
64-bit address of the XBee.
- Return type:
See also
- get_adc_value(io_line)
Returns the analog value of the provided IO line.
The provided IO line must be previously configured as ADC. To do so, use
AbstractXBeeDevice.set_io_configuration()andIOMode.ADC.- Parameters:
io_line (
IOLine) – IO line to get its ADC value.- Returns:
Analog value corresponding to the provided IO line.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If response does not contain the value for the given IO line.
See also
- get_api_output_mode()
Deprecated since version 1.3: Use
get_api_output_mode_value()Returns the API output mode of the XBee.
The API output mode determines the format of the data through the serial interface of the XBee.
- Returns:
API output mode of the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_api_output_mode_value()
Returns the API output mode of the XBee.
The API output mode determines the format that the received data is output through the serial interface of the XBee.
- Returns:
the parameter value.
- Return type:
Bytearray
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
- get_bluetooth_mac_addr()
Reads and returns the EUI-48 Bluetooth MAC address of this XBee following the format 00112233AABB.
Note that your device must include Bluetooth Low Energy support.
- Returns:
The Bluetooth MAC address.
- Return type:
String
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- get_comm_iface()
Returns the communication interface of the local XBee associated to the remote one.
- Returns:
- Communication interface of the
local XBee associated to the remote one.
- Return type:
XBeeCommunicationInterface
See also
XBeeCommunicationInterface
- get_current_frame_id()
Returns the last used frame ID.
- Returns:
Last used frame ID.
- Return type:
Integer
- get_dest_address()
Returns the 64-bit address of the XBee that is data destination.
- Returns:
64-bit address of destination XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_dio_value(io_line)
Returns the digital value of the provided IO line.
The provided IO line must be previously configured as digital I/O. To do so, use
AbstractXBeeDevice.set_io_configuration().- Parameters:
io_line (
IOLine) – the DIO line to gets its digital value.- Returns:
current value of the provided IO line.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If response does not contain the value for the given IO line.
See also
- get_file_manager()
Returns the file system manager for the XBee.
- Returns:
The file system manager.
- Return type:
- Raises:
FileSystemNotSupportedException – If the XBee does not support filesystem.
- get_firmware_version()
Returns the firmware version of the XBee.
- Returns:
Firmware version of the XBee.
- Return type:
Bytearray
- get_hardware_version()
Returns the hardware version of the XBee.
- Returns:
Hardware version of the XBee.
- Return type:
See also
- get_io_configuration(io_line)
Returns the configuration of the provided IO line.
- Parameters:
io_line (
IOLine) – IO line to get its configuration.- Returns:
IO mode of the IO line provided.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_io_sampling_rate()
Returns the IO sampling rate of the XBee.
- Returns:
IO sampling rate of XBee.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_local_xbee_device()
Returns the local XBee associated to the remote one.
- Returns:
Local XBee.
- Return type:
- get_node_id()
Returns the node identifier (‘NI’) value of the XBee.
- Returns:
Node identifier (‘NI’) of the XBee.
- Return type:
String
- get_ota_max_block_size()
Returns the maximum number of bytes to send for ota updates.
- Returns:
Maximum ota block size to send.
- Return type:
Integer
- get_pan_id()
Returns the operating PAN ID of the XBee.
- Returns:
Operating PAN ID of the XBee.
- Return type:
Bytearray
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_parameter(parameter, parameter_value=None, apply=None)
Override.
See also
- get_power_level()
Returns the power level of the XBee.
- Returns:
Power level of the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_pwm_duty_cycle(io_line)
Returns the PWM duty cycle in % corresponding to the provided IO line.
- Parameters:
io_line (
IOLine) – IO line to get its PWM duty cycle.- Returns:
PWM duty cycle of the given IO line.
- Return type:
Integer
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If io_line has no PWM capability.
See also
- get_serial_port()
Returns the serial port of the local XBee associated to the remote one.
- Returns:
- Serial port of the local XBee associated
to the remote one.
- Return type:
XBeeSerialPort
See also
XBeeSerialPort
- get_sync_ops_timeout()
Returns the serial port read timeout.
- Returns:
Serial port read timeout in seconds.
- Return type:
Integer
- is_apply_changes_enabled()
Returns whether apply changes flag is enabled.
- Returns:
True if apply changes flag is enabled, False otherwise.
- Return type:
Boolean
- is_remote()
Override method.
See also
- property log
Returns the XBee logger.
- Returns:
The XBee device logger.
- Return type:
Logger
- property reachable
Returns whether the XBee is reachable.
- Returns:
True if the device is reachable, False otherwise.
- Return type:
Boolean
- read_device_info(init=True, fire_event=True)
Updates all instance parameters reading them from the XBee.
- Parameters:
init (Boolean, optional, default=`True`) – If False only not initialized parameters are read, all if True.
fire_event (Boolean, optional, default=`True`) – True to throw and update event if any parameter changed, False otherwise.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- read_io_sample()
Returns an IO sample from the XBee containing the value of all enabled digital IO and analog input channels.
- Returns:
IO sample read from the XBee.
- Return type:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- reset()
Override method.
See also
- property scan_counter
Returns the scan counter for this node.
- Returns:
The scan counter for this node.
- Return type:
Integer
- set_16bit_addr(value)
Sets the 16-bit address of the XBee.
- Parameters:
value (
XBee16BitAddress) – New 16-bit address of the XBee.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If the protocol is not 802.15.4.
- set_api_output_mode(api_output_mode)
Deprecated since version 1.3: Use
set_api_output_mode_value()Sets the API output mode of the XBee.
- Parameters:
api_output_mode (
APIOutputMode) – New API output mode.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
See also
- set_api_output_mode_value(api_output_mode)
Sets the API output mode of the XBee.
- Parameters:
api_output_mode (Integer) – New API output mode options. Calculate this value using the method
APIOutputModeBit.calculate_api_output_mode_value()with a set ofAPIOutputModeBit.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
OperationNotSupportedException – If it is not supported by the current protocol.
See also
- set_dest_address(addr)
Sets the 64-bit address of the XBee that is data destination.
- Parameters:
addr (
XBee64BitAddressorRemoteXBeeDevice) – Address itself or remote XBee to be data destination.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If addr is None.
See also
- set_dio_change_detection(io_lines_set)
Sets the digital IO lines to be monitored and sampled whenever their status changes. A None set of lines disables this feature.
- Parameters:
io_lines_set – Set of
IOLine.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_dio_value(io_line, io_value)
Sets the digital value (high or low) to the provided IO line.
- Parameters:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- set_io_configuration(io_line, io_mode)
Sets the configuration of the provided IO line.
- Parameters:
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_io_sampling_rate(rate)
Sets the IO sampling rate of the XBee in seconds. A sample rate of 0 means the IO sampling feature is disabled.
- Parameters:
rate (Integer) – New IO sampling rate of the XBee in seconds.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_local_xbee_device(local_xbee_device)
This methods associates a
XBeeDeviceto the remote XBee.- Parameters:
local_xbee_device (
XBeeDevice) – New local XBee associated to the remote one.
See also
- set_node_id(node_id)
Sets the node identifier (‘NI`) value of the XBee.
- Parameters:
node_id (String) – New node identifier (‘NI’) of the XBee.
- Raises:
ValueError – If node_id is None or its length is greater than 20.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- set_ota_max_block_size(size)
Sets the maximum number of bytes to send for ota updates.
- Parameters:
size (Integer) – Maximum ota block size to send.
- Raises:
ValueError – If size is not between 0 and 255.
- set_pan_id(value)
Sets the operating PAN ID of the XBee.
- Parameters:
value (Bytearray) – New operating PAN ID of the XBee. Must have only 1 or 2 bytes.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_parameter(parameter, value, apply=None)
Override.
See also
- set_power_level(power_level)
Sets the power level of the XBee.
- Parameters:
power_level (
PowerLevel) – New power level of the XBee.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_pwm_duty_cycle(io_line, cycle)
Sets the duty cycle in % of the provided IO line.
The provided IO line must be PWM-capable, previously configured as PWM output.
- Parameters:
io_line (
IOLine) – IO Line to be assigned.cycle (Integer) – Duty cycle in % to be assigned. Must be between 0 and 100.
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
ValueError – If the given IO line does not have PWM capability or cycle is not between 0 and 100.
See also
- set_sync_ops_timeout(sync_ops_timeout)
Sets the serial port read timeout.
- Parameters:
sync_ops_timeout (Integer) – Read timeout in seconds.
- update_bluetooth_password(new_password, apply=True, save=True)
Changes the Bluetooth password of this XBee with the new one provided.
Note that your device must include Bluetooth Low Energy support.
- Parameters:
new_password (String) – New Bluetooth password.
apply (Boolean, optional, default=`True`) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
save (Boolean, optional, default=`True`) – True to save changes, False otherwise.
- Raises:
ValueError – If new_password is invalid.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- update_bluetooth_salt_verifier(salt, verifier, apply=True, save=True)
Changes the Bluetooth password of this XBee with the new one provided.
Note that your device must include Bluetooth Low Energy support.
- Parameters:
salt (bytes) – New Bluetooth password.
verifier (bytes) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
apply (Boolean, optional, default=`True`) – True to apply changes, False otherwise, None to use is_apply_changes_enabled() returned value.
save (Boolean, optional, default=`True`) – True to save changes, False otherwise.
- Raises:
ValueError – If salt or verifier are invalid.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- update_device_data_from(device)
Updates the current node information with provided data. This is only for internal use.
- Parameters:
device (
AbstractXBeeDevice) – XBee to get the data from.- Returns:
True if the node data has been updated, False otherwise.
- Return type:
Boolean
- update_filesystem_image(ota_filesystem_file, timeout=None, progress_callback=None)
Performs a filesystem image update operation of the device.
- Parameters:
ota_filesystem_file (String) – Location of the OTA filesystem image file.
timeout (Integer, optional) – Maximum time to wait for target read operations during the update process.
progress_callback (Function, optional) –
Function 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 device is not open.
InvalidOperatingModeException – If the device operating mode is invalid.
FileSystemNotSupportedException – If the filesystem update is not supported in the XBee.
FileSystemException – If there is any error performing the filesystem update.
- update_firmware(xml_firmware_file, xbee_firmware_file=None, bootloader_firmware_file=None, timeout=None, progress_callback=None)
Performs a firmware update operation of the XBee.
- Parameters:
xml_firmware_file (String) – Path of the XML file that describes the firmware to upload.
xbee_firmware_file (String, optional, default=`None`) – Location of the XBee binary firmware file.
bootloader_firmware_file (String, optional, default=`None`) – Location of the bootloader binary firmware file.
timeout (Integer, optional, default=`None`) – Maximum time to wait for target read operations during the update process (seconds).
progress_callback (Function, optional, default=`None`) –
Function to 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 XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
OperationNotSupportedException – If XBee does not support firmware update.
FirmwareUpdateException – If there is any error during the firmware update.
- write_changes()
Writes configurable parameter values to the non-volatile memory of the XBee so that parameter modifications persist through subsequent resets.
Parameters values remain in the device’s memory until overwritten by subsequent use of this method.
If changes are made without writing them, the XBee reverts back to previously saved parameters the next time the module is powered-on.
Writing the parameter modifications does not mean those values are immediately applied, this depends on the status of the ‘apply configuration changes’ option. Use method
is_apply_changes_enabled()to get its status andenable_apply_changes()to enable/disable the option. Methodapply_changes()can be used in order to manually apply the changes.- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- class digi.xbee.devices.XBeeNetwork(xbee_device)[source]
Bases:
objectThis class represents an XBee Network.
The network allows the discovery of remote devices in the same network as the local one and stores them.
Class constructor. Instantiates a new XBeeNetwork.
- Parameters:
xbee_device (
XBeeDevice) – Local XBee to get the network from.- Raises:
ValueError – If xbee_device is None.
- ND_PACKET_FINISH = 1
Flag that indicates a “discovery process finish” packet.
- ND_PACKET_REMOTE = 2
Flag that indicates a discovery process packet with info about a remote XBee.
- DEFAULT_TIME_BETWEEN_SCANS = 10
Default time (in seconds) to wait before starting a new scan.
- MIN_TIME_BETWEEN_SCANS = 0
Low limit for the time (in seconds) to wait before starting a new scan.
- MAX_TIME_BETWEEN_SCANS = 259200
High limit for the time (in seconds) to wait before starting a new scan.
- DEFAULT_TIME_BETWEEN_REQUESTS = 5
Default time (in seconds) to wait between node neighbors requests.
- MIN_TIME_BETWEEN_REQUESTS = 0
Low limit for the time (in seconds) to wait between node neighbors requests.
- MAX_TIME_BETWEEN_REQUESTS = 600
High limit for the time (in seconds) to wait between node neighbors requests.
- SCAN_TIL_CANCEL = 0
The neighbor discovery process continues until is manually stopped.
- property scan_counter
Returns the scan counter.
- Returns:
The scan counter.
- Return type:
Integer
- start_discovery_process(deep=False, n_deep_scans=1)[source]
Starts the discovery process. This method is not blocking.
This process can discover node neighbors and connections, or only nodes:
Deep discovery: Network nodes and connections between them (including quality) are discovered.
The discovery process will be running the number of scans configured in n_deep_scans. A scan is considered the process of discovering the full network. If there are more than one number of scans configured, after finishing one another is started, until n_deep_scans is satisfied.
See
set_deep_discovery_options()to establish the way the network discovery process is performed.No deep discovery: Only network nodes are discovered.
The discovery process will be running until the configured timeout expires or, in case of 802.15.4, until the ‘end’ packet is read.
It may occur that, after timeout expiration, there are nodes that continue sending discovery responses to the local XBee. In this case, these nodes will not be added to the network.
In 802.15.4, both (deep and no deep discovery) are the same and none discover the node connections or their quality. The difference is the possibility of running more than one scan using a deep discovery.
- Parameters:
deep (Boolean, optional, default=`False`) – True for a deep network scan, looking for neighbors and their connections, False otherwise.
n_deep_scans (Integer, optional, default=1) – Number of scans to perform before automatically stopping the discovery process.
SCAN_TIL_CANCELmeans the process will not be automatically stopped. Only applicable if deep=True.
See also
- stop_discovery_process()[source]
Stops the discovery process if it is running.
Note that some DigiMesh/DigiPoint devices are blocked until the discovery time configured (‘NT’ parameter) has elapsed, so, when trying to get/set any parameter during the discovery process, a TimeoutException is raised.
- discover_device(node_id)[source]
Blocking method. Discovers and reports the first remote XBee that matches the supplied identifier.
- Parameters:
node_id (String) – Node identifier of the node to discover.
- Returns:
- Discovered remote XBee, None if the
timeout expires and the node was not found.
- Return type:
- discover_devices(device_id_list)[source]
Blocking method. Attempts to discover a list of nodes and add them to the current network.
This method does not guarantee that all nodes of device_id_list will be found, even if they exist physically. This depends on the node discovery operation and timeout.
- Parameters:
device_id_list (List) – List of device IDs to discover.
- Returns:
- List with the discovered nodes. It may not contain all nodes
specified in device_id_list.
- Return type:
List
- is_discovery_running()[source]
Returns whether the discovery process is running.
- Returns:
True if the discovery process is running, False otherwise.
- Return type:
Boolean
- get_devices()[source]
Returns a copy of the XBee devices list of the network.
If a new XBee node is added to the list after the execution of this method, this new XBee is not added to the list returned by this method.
- Returns:
A copy of the XBee devices list of the network.
- Return type:
List
- has_devices()[source]
Returns whether there is any device in the network.
- Returns:
- True if there is at least one node in the network,
False otherwise.
- Return type:
Boolean
- get_number_devices()[source]
Returns the number of nodes in the network.
- Returns:
Number of nodes in the network.
- Return type:
Integer
- export(dir_path=None, name=None, desc=None)[source]
Exports this network to the given file path.
If the provided path already exists the file is removed.
- Parameters:
dir_path (String, optional, default=`None`) – Absolute path of the directory to export the network. It should not include the file name. If not defined home directory is used.
name (String, optional, default=`None`) – Network human readable name.
desc (String, optional, default=`None`) – Network description.
- Returns:
- Tuple with result (0: success, 1: failure)
and string (exported file path if success, error string otherwise).
- Return type:
Tuple (Integer, String)
- update_nodes(task_list)[source]
Performs the provided update tasks. It blocks until all tasks finish.
- Parameters:
task_list (List or tuple) – List of update tasks (
FwUpdateTaskorProfileUpdateTask)- Returns:
- Uses the 64-bit address of the XBee as key and, as
value, a Tuple with the XBee (
AbstractXBeeDevice) and anXBeeExceptionif the process failed for that node (None if it successes)
- Return type:
Dictionary
- add_network_modified_callback(callback)[source]
Adds a callback for the event
NetworkModified.- Parameters:
callback (Function) –
The callback. Receives three arguments.
The event type as a
NetworkEventType.The reason of the event as a
NetworkEventReason.The node added, updated or removed from the network as a
XBeeDeviceorRemoteXBeeDevice.
- add_device_discovered_callback(callback)[source]
Adds a callback for the event
DeviceDiscovered.- Parameters:
callback (Function) –
The callback. Receives one argument.
The discovered remote XBee as a
RemoteXBeeDevice.
- add_init_discovery_scan_callback(callback)[source]
Adds a callback for the event
InitDiscoveryScan.- Parameters:
callback (Function) –
The callback. Receives two arguments.
Number of scan to start (starting with 1).
Total number of scans.
- add_end_discovery_scan_callback(callback)[source]
Adds a callback for the event
EndDiscoveryScan.- Parameters:
callback (Function) –
The callback. Receives two arguments.
Number of scan that has finished (starting with 1).
Total number of scans.
- add_discovery_process_finished_callback(callback)[source]
Adds a callback for the event
DiscoveryProcessFinished.- Parameters:
callback (Function) –
The callback. Receives two arguments.
The event code as an
NetworkDiscoveryStatus.(Optional) A description of the discovery process as a string.
- add_packet_received_from_callback(node, callback)[source]
Adds a callback to listen to any received packet from the provided node.
- Parameters:
node (
RemoteXBeeDevice) – The node to listen for frames.callback (Function) –
The callback. Receives two arguments.
The received packet as a
XBeeAPIPacket.The remote XBee who sent the packet as a
RemoteXBeeDevice.
- add_update_progress_callback(callback)[source]
Adds a callback for the event
NetworkUpdateProgress.- Parameters:
callback (Function) – The callback. Receives three arguments. * The XBee being updated. * An
UpdateProgressStatuswith the current status.
- del_network_modified_callback(callback)[source]
Deletes a callback for the callback list of
NetworkModified.- Parameters:
callback (Function) – The callback to delete.
- del_device_discovered_callback(callback)[source]
Deletes a callback for the callback list of
DeviceDiscoveredevent.- Parameters:
callback (Function) – The callback to delete.
- del_init_discovery_scan_callback(callback)[source]
Deletes a callback for the callback list of
InitDiscoveryScan.- Parameters:
callback (Function) – The callback to delete.
- del_end_discovery_scan_callback(callback)[source]
Deletes a callback for the callback list of
EndDiscoveryScan.- Parameters:
callback (Function) – The callback to delete.
- del_discovery_process_finished_callback(callback)[source]
Deletes a callback for the callback list of
DiscoveryProcessFinishedevent.- Parameters:
callback (Function) – The callback to delete.
- del_packet_received_from_callback(node, callb=None)[source]
Deletes a received packet callback from the provided node.
- Parameters:
node (
RemoteXBeeDevice) – The node to listen for frames.callb (Function, optional, default=`None`) – The callback to delete, None to delete all.
- del_update_progress_callback(callback)[source]
Deletes a callback for the callback list of
NetworkUpdateProgress.- Parameters:
callback (Function) – The callback to delete.
- get_update_progress_callbacks()[source]
Returns the list of registered callbacks for update progress. This is only for internal use.
- Returns:
List of
NetworkUpdateProgressevents.- Return type:
List
- get_discovery_options()[source]
Returns the network discovery process options.
- Returns:
Discovery options value.
- Return type:
Bytearray
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- set_discovery_options(options)[source]
Configures the discovery options (NO parameter) with the given value.
- Parameters:
options (Set of
DiscoveryOptions) – New discovery options, empty set to clear the options.- Raises:
ValueError – If options is None.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- get_deep_discovery_options()[source]
Returns the deep discovery process options.
- Returns:
- (
NeighborDiscoveryMode, Boolean): Tuple containing: - mode (
NeighborDiscoveryMode): Neighbor discovery mode, the way to perform the network discovery process.
- mode (
- remove_nodes (Boolean): True to remove nodes from the
network if they were not discovered in the last scan, False otherwise.
- (
- Return type:
Tuple
- set_deep_discovery_options(deep_mode=NeighborDiscoveryMode.CASCADE, del_not_discovered_nodes_in_last_scan=False)[source]
Configures the deep discovery options with the given values. These options are only applicable for “deep” discovery (see
start_discovery_process())- Parameters:
deep_mode (
NeighborDiscoveryMode, optional, default=`NeighborDiscoveryMode.CASCADE`) – Neighbor discovery mode, the way to perform the network discovery process.del_not_discovered_nodes_in_last_scan (Boolean, optional, default=`False`) – True to remove nodes from the network if they were not discovered in the last scan.
- get_discovery_timeout()[source]
Returns the network discovery timeout.
- Returns:
Network discovery timeout.
- Return type:
Float
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- set_discovery_timeout(discovery_timeout)[source]
Sets the discovery network timeout.
- Parameters:
discovery_timeout (Float) – Timeout in seconds.
- Raises:
ValueError – If discovery_timeout is not between the allowed minimum and maximum values.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- get_deep_discovery_timeouts()[source]
Gets deep discovery network timeouts. These timeouts are only applicable for “deep” discovery (see
start_discovery_process())- Returns:
- Tuple containing:
- node_timeout (Float): Maximum duration in seconds of the
discovery process per node. This is used to find neighbors of a node. This timeout is highly dependent on the nature of the network:
It should be greater than the highest ‘NT’ (Node Discovery Timeout) of your network.
And include enough time to let the message propagate depending on the sleep cycle of your network nodes.
- time_bw_nodes (Float): Time to wait between node neighbors
requests. Use this setting not to saturate your network:
For ‘Cascade’, the number of seconds to wait after completion of the neighbor discovery process of the previous node.
For ‘Flood’, the minimum time to wait between each node’s neighbor requests.
- time_bw_scans (Float): Time to wait before starting a new
network scan.
- Return type:
Tuple (Float, Float, Float)
- set_deep_discovery_timeouts(node_timeout=None, time_bw_requests=None, time_bw_scans=None)[source]
Sets deep discovery network timeouts. These timeouts are only applicable for “deep” discovery (see
start_discovery_process())- node_timeout (Float, optional, default=`None`):
Maximum duration in seconds of the discovery process used to find neighbors of a node. If None already configured timeouts are used.
- time_bw_requests (Float, optional, default=`DEFAULT_TIME_BETWEEN_REQUESTS`): Time to wait
between node neighbors requests. It must be between
MIN_TIME_BETWEEN_REQUESTSandMAX_TIME_BETWEEN_REQUESTSseconds inclusive. Use this setting not to saturate your network:For ‘Cascade’, the number of seconds to wait after completion of the neighbor discovery process of the previous node.
For ‘Flood’, the minimum time to wait between each node’s neighbor requests.
- time_bw_scans (Float, optional, default=`DEFAULT_TIME_BETWEEN_SCANS`): Time to wait
before starting a new network scan. It must be between
MIN_TIME_BETWEEN_SCANSandMAX_TIME_BETWEEN_SCANSseconds inclusive.
- Raises:
ValueError – if node_timeout, time_bw_requests or time_bw_scans are not between their corresponding limits.
- classmethod get_nt_limits(protocol)[source]
Returns a tuple with the minimum and maximum values for the ‘NT’ value depending on the protocol.
- Returns:
- Minimum value in seconds, maximum value in
seconds.
- Return type:
Tuple (Float, Float)
- is_node_in_network(node)[source]
Checks if the provided node is in the network or if it is the local XBee.
- Parameters:
node (
AbstractXBeeDevice) – The node to check.- Returns:
True if the node is in the network, False otherwise.
- Return type:
Boolean
- Raises:
ValueError – If node is None.
- get_device_by_64(x64bit_addr)[source]
Returns the XBee in the network whose 64-bit address matches the given one.
- Parameters:
x64bit_addr (
XBee64BitAddress) – 64-bit address of the node to retrieve.- Returns:
XBee in the network or None if not found.
- Return type:
- Raises:
ValueError – If x64bit_addr is None or unknown.
- get_device_by_16(x16bit_addr)[source]
Returns the XBee in the network whose 16-bit address matches the given one.
- Parameters:
x16bit_addr (
XBee16BitAddress) – 16-bit address of the node to retrieve.- Returns:
XBee in the network or Non if not found.
- Return type:
- Raises:
ValueError – If x16bit_addr is None or unknown.
- get_device_by_node_id(node_id)[source]
Returns the XBee in the network whose node identifier matches the given one.
- Parameters:
node_id (String) – Node identifier of the node to retrieve.
- Returns:
XBee in the network or None if not found.
- Return type:
- Raises:
ValueError – If node_id is None.
- add_if_not_exist(x64bit_addr=None, x16bit_addr=None, node_id=None)[source]
Adds an XBee with the provided information if it does not exist in the current network.
If the XBee already exists, its data is updated with the provided information.
If no valid address is provided (x64bit_addr, x16bit_addr), None is returned.
- Parameters:
x64bit_addr (
XBee64BitAddress, optional, default=`None`) – 64-bit address.x16bit_addr (
XBee16BitAddress, optional, default=`None`) – 16-bit address.node_id (String, optional, default=`None`) – Node identifier.
- Returns:
- the remote XBee with the updated
information. If the XBee was not in the list yet, this method returns the given XBee without changes.
- Return type:
- add_remote(remote_xbee)[source]
Adds the provided remote XBee to the network if it is not in yet.
If the XBee is already in the network, its data is updated with the information of the provided XBee that are not None.
- Parameters:
remote_xbee (
RemoteXBeeDevice) – Remote XBee to add.- Returns:
- Provided XBee with updated data. If
the XBee was not in the list, it returns it without changes.
- Return type:
- add_remotes(remote_xbees)[source]
Adds a list of remote XBee nodes to the network.
If any node in the list is already in the network, its data is updated with the information of the corresponding XBee in the list.
- Parameters:
remote_xbees (List) – List of
RemoteXBeeDeviceto add.
- remove_device(remote_xbee)[source]
Removes the provided remote XBee from the network.
- Parameters:
remote_xbee (
RemoteXBeeDevice) – Remote XBee to remove.- Raises:
ValueError – If the provided remote_xbee is not in the network.
- get_discovery_callbacks()[source]
Returns the API callbacks that are used in the device discovery process.
This callbacks notify the user callbacks for each XBee discovered.
- Returns:
- Callback for generic devices discovery
process, callback for discovery specific XBee ops.
- Return type:
Tuple (Function, Function)
- get_connections()[source]
Returns a copy of the XBee network connections.
A deep discover must be performed to get the connections between network nodes.
If a new connection is added to the list after the execution of this method, this new connection is not added to the list returned by this method.
- Returns:
A copy of the list of
Connectionfor the network.- Return type:
List
- get_node_connections(node)[source]
Returns the network connections with one of their ends node.
A deep discover must be performed to get the connections between network nodes.
If a new connection is added to the list after the execution of this method, this new connection is not added to the list returned by this method.
- Parameters:
node (
AbstractXBeeDevice) – The node to get its connections.- Returns:
List of
Connectionwith node end.- Return type:
List
- class digi.xbee.devices.ZigBeeNetwork(device)[source]
Bases:
XBeeNetworkThis class represents a Zigbee network.
The network allows the discovery of remote nodes in the same network as the local one and stores them.
Class constructor. Instantiates a new ZigBeeNetwork.
- Parameters:
device (
ZigBeeDevice) – Local Zigbee node to get the network from.- Raises:
ValueError – If device is None.
- DEFAULT_TIME_BETWEEN_REQUESTS = 5
Default time (in seconds) to wait between node neighbors requests.
- DEFAULT_TIME_BETWEEN_SCANS = 10
Default time (in seconds) to wait before starting a new scan.
- MAX_TIME_BETWEEN_REQUESTS = 600
High limit for the time (in seconds) to wait between node neighbors requests.
- MAX_TIME_BETWEEN_SCANS = 259200
High limit for the time (in seconds) to wait before starting a new scan.
- MIN_TIME_BETWEEN_REQUESTS = 0
Low limit for the time (in seconds) to wait between node neighbors requests.
- MIN_TIME_BETWEEN_SCANS = 0
Low limit for the time (in seconds) to wait before starting a new scan.
- ND_PACKET_FINISH = 1
Flag that indicates a “discovery process finish” packet.
- ND_PACKET_REMOTE = 2
Flag that indicates a discovery process packet with info about a remote XBee.
- SCAN_TIL_CANCEL = 0
The neighbor discovery process continues until is manually stopped.
- add_device_discovered_callback(callback)
Adds a callback for the event
DeviceDiscovered.- Parameters:
callback (Function) –
The callback. Receives one argument.
The discovered remote XBee as a
RemoteXBeeDevice.
- add_discovery_process_finished_callback(callback)
Adds a callback for the event
DiscoveryProcessFinished.- Parameters:
callback (Function) –
The callback. Receives two arguments.
The event code as an
NetworkDiscoveryStatus.(Optional) A description of the discovery process as a string.
- add_end_discovery_scan_callback(callback)
Adds a callback for the event
EndDiscoveryScan.- Parameters:
callback (Function) –
The callback. Receives two arguments.
Number of scan that has finished (starting with 1).
Total number of scans.
- add_if_not_exist(x64bit_addr=None, x16bit_addr=None, node_id=None)
Adds an XBee with the provided information if it does not exist in the current network.
If the XBee already exists, its data is updated with the provided information.
If no valid address is provided (x64bit_addr, x16bit_addr), None is returned.
- Parameters:
x64bit_addr (
XBee64BitAddress, optional, default=`None`) – 64-bit address.x16bit_addr (
XBee16BitAddress, optional, default=`None`) – 16-bit address.node_id (String, optional, default=`None`) – Node identifier.
- Returns:
- the remote XBee with the updated
information. If the XBee was not in the list yet, this method returns the given XBee without changes.
- Return type:
- add_init_discovery_scan_callback(callback)
Adds a callback for the event
InitDiscoveryScan.- Parameters:
callback (Function) –
The callback. Receives two arguments.
Number of scan to start (starting with 1).
Total number of scans.
- add_network_modified_callback(callback)
Adds a callback for the event
NetworkModified.- Parameters:
callback (Function) –
The callback. Receives three arguments.
The event type as a
NetworkEventType.The reason of the event as a
NetworkEventReason.The node added, updated or removed from the network as a
XBeeDeviceorRemoteXBeeDevice.
- add_packet_received_from_callback(node, callback)
Adds a callback to listen to any received packet from the provided node.
- Parameters:
node (
RemoteXBeeDevice) – The node to listen for frames.callback (Function) –
The callback. Receives two arguments.
The received packet as a
XBeeAPIPacket.The remote XBee who sent the packet as a
RemoteXBeeDevice.
- add_remote(remote_xbee)
Adds the provided remote XBee to the network if it is not in yet.
If the XBee is already in the network, its data is updated with the information of the provided XBee that are not None.
- Parameters:
remote_xbee (
RemoteXBeeDevice) – Remote XBee to add.- Returns:
- Provided XBee with updated data. If
the XBee was not in the list, it returns it without changes.
- Return type:
- add_remotes(remote_xbees)
Adds a list of remote XBee nodes to the network.
If any node in the list is already in the network, its data is updated with the information of the corresponding XBee in the list.
- Parameters:
remote_xbees (List) – List of
RemoteXBeeDeviceto add.
- add_update_progress_callback(callback)
Adds a callback for the event
NetworkUpdateProgress.- Parameters:
callback (Function) – The callback. Receives three arguments. * The XBee being updated. * An
UpdateProgressStatuswith the current status.
- clear()
Removes all remote XBee nodes from the network.
- del_device_discovered_callback(callback)
Deletes a callback for the callback list of
DeviceDiscoveredevent.- Parameters:
callback (Function) – The callback to delete.
- del_discovery_process_finished_callback(callback)
Deletes a callback for the callback list of
DiscoveryProcessFinishedevent.- Parameters:
callback (Function) – The callback to delete.
- del_end_discovery_scan_callback(callback)
Deletes a callback for the callback list of
EndDiscoveryScan.- Parameters:
callback (Function) – The callback to delete.
- del_init_discovery_scan_callback(callback)
Deletes a callback for the callback list of
InitDiscoveryScan.- Parameters:
callback (Function) – The callback to delete.
- del_network_modified_callback(callback)
Deletes a callback for the callback list of
NetworkModified.- Parameters:
callback (Function) – The callback to delete.
- del_packet_received_from_callback(node, callb=None)
Deletes a received packet callback from the provided node.
- Parameters:
node (
RemoteXBeeDevice) – The node to listen for frames.callb (Function, optional, default=`None`) – The callback to delete, None to delete all.
- del_update_progress_callback(callback)
Deletes a callback for the callback list of
NetworkUpdateProgress.- Parameters:
callback (Function) – The callback to delete.
- discover_device(node_id)
Blocking method. Discovers and reports the first remote XBee that matches the supplied identifier.
- Parameters:
node_id (String) – Node identifier of the node to discover.
- Returns:
- Discovered remote XBee, None if the
timeout expires and the node was not found.
- Return type:
- discover_devices(device_id_list)
Blocking method. Attempts to discover a list of nodes and add them to the current network.
This method does not guarantee that all nodes of device_id_list will be found, even if they exist physically. This depends on the node discovery operation and timeout.
- Parameters:
device_id_list (List) – List of device IDs to discover.
- Returns:
- List with the discovered nodes. It may not contain all nodes
specified in device_id_list.
- Return type:
List
- export(dir_path=None, name=None, desc=None)
Exports this network to the given file path.
If the provided path already exists the file is removed.
- Parameters:
dir_path (String, optional, default=`None`) – Absolute path of the directory to export the network. It should not include the file name. If not defined home directory is used.
name (String, optional, default=`None`) – Network human readable name.
desc (String, optional, default=`None`) – Network description.
- Returns:
- Tuple with result (0: success, 1: failure)
and string (exported file path if success, error string otherwise).
- Return type:
Tuple (Integer, String)
- get_connections()
Returns a copy of the XBee network connections.
A deep discover must be performed to get the connections between network nodes.
If a new connection is added to the list after the execution of this method, this new connection is not added to the list returned by this method.
- Returns:
A copy of the list of
Connectionfor the network.- Return type:
List
- get_deep_discovery_options()
Returns the deep discovery process options.
- Returns:
- (
NeighborDiscoveryMode, Boolean): Tuple containing: - mode (
NeighborDiscoveryMode): Neighbor discovery mode, the way to perform the network discovery process.
- mode (
- remove_nodes (Boolean): True to remove nodes from the
network if they were not discovered in the last scan, False otherwise.
- (
- Return type:
Tuple
- get_deep_discovery_timeouts()
Gets deep discovery network timeouts. These timeouts are only applicable for “deep” discovery (see
start_discovery_process())- Returns:
- Tuple containing:
- node_timeout (Float): Maximum duration in seconds of the
discovery process per node. This is used to find neighbors of a node. This timeout is highly dependent on the nature of the network:
It should be greater than the highest ‘NT’ (Node Discovery Timeout) of your network.
And include enough time to let the message propagate depending on the sleep cycle of your network nodes.
- time_bw_nodes (Float): Time to wait between node neighbors
requests. Use this setting not to saturate your network:
For ‘Cascade’, the number of seconds to wait after completion of the neighbor discovery process of the previous node.
For ‘Flood’, the minimum time to wait between each node’s neighbor requests.
- time_bw_scans (Float): Time to wait before starting a new
network scan.
- Return type:
Tuple (Float, Float, Float)
- get_device_by_16(x16bit_addr)
Returns the XBee in the network whose 16-bit address matches the given one.
- Parameters:
x16bit_addr (
XBee16BitAddress) – 16-bit address of the node to retrieve.- Returns:
XBee in the network or Non if not found.
- Return type:
- Raises:
ValueError – If x16bit_addr is None or unknown.
- get_device_by_64(x64bit_addr)
Returns the XBee in the network whose 64-bit address matches the given one.
- Parameters:
x64bit_addr (
XBee64BitAddress) – 64-bit address of the node to retrieve.- Returns:
XBee in the network or None if not found.
- Return type:
- Raises:
ValueError – If x64bit_addr is None or unknown.
- get_device_by_node_id(node_id)
Returns the XBee in the network whose node identifier matches the given one.
- Parameters:
node_id (String) – Node identifier of the node to retrieve.
- Returns:
XBee in the network or None if not found.
- Return type:
- Raises:
ValueError – If node_id is None.
- get_devices()
Returns a copy of the XBee devices list of the network.
If a new XBee node is added to the list after the execution of this method, this new XBee is not added to the list returned by this method.
- Returns:
A copy of the XBee devices list of the network.
- Return type:
List
- get_discovery_callbacks()
Returns the API callbacks that are used in the device discovery process.
This callbacks notify the user callbacks for each XBee discovered.
- Returns:
- Callback for generic devices discovery
process, callback for discovery specific XBee ops.
- Return type:
Tuple (Function, Function)
- get_discovery_options()
Returns the network discovery process options.
- Returns:
Discovery options value.
- Return type:
Bytearray
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- get_discovery_timeout()
Returns the network discovery timeout.
- Returns:
Network discovery timeout.
- Return type:
Float
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- get_node_connections(node)
Returns the network connections with one of their ends node.
A deep discover must be performed to get the connections between network nodes.
If a new connection is added to the list after the execution of this method, this new connection is not added to the list returned by this method.
- Parameters:
node (
AbstractXBeeDevice) – The node to get its connections.- Returns:
List of
Connectionwith node end.- Return type:
List
- classmethod get_nt_limits(protocol)
Returns a tuple with the minimum and maximum values for the ‘NT’ value depending on the protocol.
- Returns:
- Minimum value in seconds, maximum value in
seconds.
- Return type:
Tuple (Float, Float)
- get_number_devices()
Returns the number of nodes in the network.
- Returns:
Number of nodes in the network.
- Return type:
Integer
- get_update_progress_callbacks()
Returns the list of registered callbacks for update progress. This is only for internal use.
- Returns:
List of
NetworkUpdateProgressevents.- Return type:
List
- has_devices()
Returns whether there is any device in the network.
- Returns:
- True if there is at least one node in the network,
False otherwise.
- Return type:
Boolean
- is_discovery_running()
Returns whether the discovery process is running.
- Returns:
True if the discovery process is running, False otherwise.
- Return type:
Boolean
- is_node_in_network(node)
Checks if the provided node is in the network or if it is the local XBee.
- Parameters:
node (
AbstractXBeeDevice) – The node to check.- Returns:
True if the node is in the network, False otherwise.
- Return type:
Boolean
- Raises:
ValueError – If node is None.
- remove_device(remote_xbee)
Removes the provided remote XBee from the network.
- Parameters:
remote_xbee (
RemoteXBeeDevice) – Remote XBee to remove.- Raises:
ValueError – If the provided remote_xbee is not in the network.
- property scan_counter
Returns the scan counter.
- Returns:
The scan counter.
- Return type:
Integer
- set_deep_discovery_options(deep_mode=NeighborDiscoveryMode.CASCADE, del_not_discovered_nodes_in_last_scan=False)
Configures the deep discovery options with the given values. These options are only applicable for “deep” discovery (see
start_discovery_process())- Parameters:
deep_mode (
NeighborDiscoveryMode, optional, default=`NeighborDiscoveryMode.CASCADE`) – Neighbor discovery mode, the way to perform the network discovery process.del_not_discovered_nodes_in_last_scan (Boolean, optional, default=`False`) – True to remove nodes from the network if they were not discovered in the last scan.
- set_deep_discovery_timeouts(node_timeout=None, time_bw_requests=None, time_bw_scans=None)
Sets deep discovery network timeouts. These timeouts are only applicable for “deep” discovery (see
start_discovery_process())- node_timeout (Float, optional, default=`None`):
Maximum duration in seconds of the discovery process used to find neighbors of a node. If None already configured timeouts are used.
- time_bw_requests (Float, optional, default=`DEFAULT_TIME_BETWEEN_REQUESTS`): Time to wait
between node neighbors requests. It must be between
MIN_TIME_BETWEEN_REQUESTSandMAX_TIME_BETWEEN_REQUESTSseconds inclusive. Use this setting not to saturate your network:For ‘Cascade’, the number of seconds to wait after completion of the neighbor discovery process of the previous node.
For ‘Flood’, the minimum time to wait between each node’s neighbor requests.
- time_bw_scans (Float, optional, default=`DEFAULT_TIME_BETWEEN_SCANS`): Time to wait
before starting a new network scan. It must be between
MIN_TIME_BETWEEN_SCANSandMAX_TIME_BETWEEN_SCANSseconds inclusive.
- Raises:
ValueError – if node_timeout, time_bw_requests or time_bw_scans are not between their corresponding limits.
- set_discovery_options(options)
Configures the discovery options (NO parameter) with the given value.
- Parameters:
options (Set of
DiscoveryOptions) – New discovery options, empty set to clear the options.- Raises:
ValueError – If options is None.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_discovery_timeout(discovery_timeout)
Sets the discovery network timeout.
- Parameters:
discovery_timeout (Float) – Timeout in seconds.
- Raises:
ValueError – If discovery_timeout is not between the allowed minimum and maximum values.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- start_discovery_process(deep=False, n_deep_scans=1)
Starts the discovery process. This method is not blocking.
This process can discover node neighbors and connections, or only nodes:
Deep discovery: Network nodes and connections between them (including quality) are discovered.
The discovery process will be running the number of scans configured in n_deep_scans. A scan is considered the process of discovering the full network. If there are more than one number of scans configured, after finishing one another is started, until n_deep_scans is satisfied.
See
set_deep_discovery_options()to establish the way the network discovery process is performed.No deep discovery: Only network nodes are discovered.
The discovery process will be running until the configured timeout expires or, in case of 802.15.4, until the ‘end’ packet is read.
It may occur that, after timeout expiration, there are nodes that continue sending discovery responses to the local XBee. In this case, these nodes will not be added to the network.
In 802.15.4, both (deep and no deep discovery) are the same and none discover the node connections or their quality. The difference is the possibility of running more than one scan using a deep discovery.
- Parameters:
deep (Boolean, optional, default=`False`) – True for a deep network scan, looking for neighbors and their connections, False otherwise.
n_deep_scans (Integer, optional, default=1) – Number of scans to perform before automatically stopping the discovery process.
SCAN_TIL_CANCELmeans the process will not be automatically stopped. Only applicable if deep=True.
See also
- stop_discovery_process()
Stops the discovery process if it is running.
Note that some DigiMesh/DigiPoint devices are blocked until the discovery time configured (‘NT’ parameter) has elapsed, so, when trying to get/set any parameter during the discovery process, a TimeoutException is raised.
- update_nodes(task_list)
Performs the provided update tasks. It blocks until all tasks finish.
- Parameters:
task_list (List or tuple) – List of update tasks (
FwUpdateTaskorProfileUpdateTask)- Returns:
- Uses the 64-bit address of the XBee as key and, as
value, a Tuple with the XBee (
AbstractXBeeDevice) and anXBeeExceptionif the process failed for that node (None if it successes)
- Return type:
Dictionary
- class digi.xbee.devices.Raw802Network(xbee_device)[source]
Bases:
XBeeNetworkThis class represents an 802.15.4 network.
The network allows the discovery of remote nodes in the same network as the local one and stores them.
Class constructor. Instantiates a new XBeeNetwork.
- Parameters:
xbee_device (
XBeeDevice) – Local XBee to get the network from.- Raises:
ValueError – If xbee_device is None.
- DEFAULT_TIME_BETWEEN_REQUESTS = 5
Default time (in seconds) to wait between node neighbors requests.
- DEFAULT_TIME_BETWEEN_SCANS = 10
Default time (in seconds) to wait before starting a new scan.
- MAX_TIME_BETWEEN_REQUESTS = 600
High limit for the time (in seconds) to wait between node neighbors requests.
- MAX_TIME_BETWEEN_SCANS = 259200
High limit for the time (in seconds) to wait before starting a new scan.
- MIN_TIME_BETWEEN_REQUESTS = 0
Low limit for the time (in seconds) to wait between node neighbors requests.
- MIN_TIME_BETWEEN_SCANS = 0
Low limit for the time (in seconds) to wait before starting a new scan.
- ND_PACKET_FINISH = 1
Flag that indicates a “discovery process finish” packet.
- ND_PACKET_REMOTE = 2
Flag that indicates a discovery process packet with info about a remote XBee.
- SCAN_TIL_CANCEL = 0
The neighbor discovery process continues until is manually stopped.
- add_device_discovered_callback(callback)
Adds a callback for the event
DeviceDiscovered.- Parameters:
callback (Function) –
The callback. Receives one argument.
The discovered remote XBee as a
RemoteXBeeDevice.
- add_discovery_process_finished_callback(callback)
Adds a callback for the event
DiscoveryProcessFinished.- Parameters:
callback (Function) –
The callback. Receives two arguments.
The event code as an
NetworkDiscoveryStatus.(Optional) A description of the discovery process as a string.
- add_end_discovery_scan_callback(callback)
Adds a callback for the event
EndDiscoveryScan.- Parameters:
callback (Function) –
The callback. Receives two arguments.
Number of scan that has finished (starting with 1).
Total number of scans.
- add_if_not_exist(x64bit_addr=None, x16bit_addr=None, node_id=None)
Adds an XBee with the provided information if it does not exist in the current network.
If the XBee already exists, its data is updated with the provided information.
If no valid address is provided (x64bit_addr, x16bit_addr), None is returned.
- Parameters:
x64bit_addr (
XBee64BitAddress, optional, default=`None`) – 64-bit address.x16bit_addr (
XBee16BitAddress, optional, default=`None`) – 16-bit address.node_id (String, optional, default=`None`) – Node identifier.
- Returns:
- the remote XBee with the updated
information. If the XBee was not in the list yet, this method returns the given XBee without changes.
- Return type:
- add_init_discovery_scan_callback(callback)
Adds a callback for the event
InitDiscoveryScan.- Parameters:
callback (Function) –
The callback. Receives two arguments.
Number of scan to start (starting with 1).
Total number of scans.
- add_network_modified_callback(callback)
Adds a callback for the event
NetworkModified.- Parameters:
callback (Function) –
The callback. Receives three arguments.
The event type as a
NetworkEventType.The reason of the event as a
NetworkEventReason.The node added, updated or removed from the network as a
XBeeDeviceorRemoteXBeeDevice.
- add_packet_received_from_callback(node, callback)
Adds a callback to listen to any received packet from the provided node.
- Parameters:
node (
RemoteXBeeDevice) – The node to listen for frames.callback (Function) –
The callback. Receives two arguments.
The received packet as a
XBeeAPIPacket.The remote XBee who sent the packet as a
RemoteXBeeDevice.
- add_remote(remote_xbee)
Adds the provided remote XBee to the network if it is not in yet.
If the XBee is already in the network, its data is updated with the information of the provided XBee that are not None.
- Parameters:
remote_xbee (
RemoteXBeeDevice) – Remote XBee to add.- Returns:
- Provided XBee with updated data. If
the XBee was not in the list, it returns it without changes.
- Return type:
- add_remotes(remote_xbees)
Adds a list of remote XBee nodes to the network.
If any node in the list is already in the network, its data is updated with the information of the corresponding XBee in the list.
- Parameters:
remote_xbees (List) – List of
RemoteXBeeDeviceto add.
- add_update_progress_callback(callback)
Adds a callback for the event
NetworkUpdateProgress.- Parameters:
callback (Function) – The callback. Receives three arguments. * The XBee being updated. * An
UpdateProgressStatuswith the current status.
- clear()
Removes all remote XBee nodes from the network.
- del_device_discovered_callback(callback)
Deletes a callback for the callback list of
DeviceDiscoveredevent.- Parameters:
callback (Function) – The callback to delete.
- del_discovery_process_finished_callback(callback)
Deletes a callback for the callback list of
DiscoveryProcessFinishedevent.- Parameters:
callback (Function) – The callback to delete.
- del_end_discovery_scan_callback(callback)
Deletes a callback for the callback list of
EndDiscoveryScan.- Parameters:
callback (Function) – The callback to delete.
- del_init_discovery_scan_callback(callback)
Deletes a callback for the callback list of
InitDiscoveryScan.- Parameters:
callback (Function) – The callback to delete.
- del_network_modified_callback(callback)
Deletes a callback for the callback list of
NetworkModified.- Parameters:
callback (Function) – The callback to delete.
- del_packet_received_from_callback(node, callb=None)
Deletes a received packet callback from the provided node.
- Parameters:
node (
RemoteXBeeDevice) – The node to listen for frames.callb (Function, optional, default=`None`) – The callback to delete, None to delete all.
- del_update_progress_callback(callback)
Deletes a callback for the callback list of
NetworkUpdateProgress.- Parameters:
callback (Function) – The callback to delete.
- discover_device(node_id)
Blocking method. Discovers and reports the first remote XBee that matches the supplied identifier.
- Parameters:
node_id (String) – Node identifier of the node to discover.
- Returns:
- Discovered remote XBee, None if the
timeout expires and the node was not found.
- Return type:
- discover_devices(device_id_list)
Blocking method. Attempts to discover a list of nodes and add them to the current network.
This method does not guarantee that all nodes of device_id_list will be found, even if they exist physically. This depends on the node discovery operation and timeout.
- Parameters:
device_id_list (List) – List of device IDs to discover.
- Returns:
- List with the discovered nodes. It may not contain all nodes
specified in device_id_list.
- Return type:
List
- export(dir_path=None, name=None, desc=None)
Exports this network to the given file path.
If the provided path already exists the file is removed.
- Parameters:
dir_path (String, optional, default=`None`) – Absolute path of the directory to export the network. It should not include the file name. If not defined home directory is used.
name (String, optional, default=`None`) – Network human readable name.
desc (String, optional, default=`None`) – Network description.
- Returns:
- Tuple with result (0: success, 1: failure)
and string (exported file path if success, error string otherwise).
- Return type:
Tuple (Integer, String)
- get_connections()
Returns a copy of the XBee network connections.
A deep discover must be performed to get the connections between network nodes.
If a new connection is added to the list after the execution of this method, this new connection is not added to the list returned by this method.
- Returns:
A copy of the list of
Connectionfor the network.- Return type:
List
- get_deep_discovery_options()
Returns the deep discovery process options.
- Returns:
- (
NeighborDiscoveryMode, Boolean): Tuple containing: - mode (
NeighborDiscoveryMode): Neighbor discovery mode, the way to perform the network discovery process.
- mode (
- remove_nodes (Boolean): True to remove nodes from the
network if they were not discovered in the last scan, False otherwise.
- (
- Return type:
Tuple
- get_deep_discovery_timeouts()
Gets deep discovery network timeouts. These timeouts are only applicable for “deep” discovery (see
start_discovery_process())- Returns:
- Tuple containing:
- node_timeout (Float): Maximum duration in seconds of the
discovery process per node. This is used to find neighbors of a node. This timeout is highly dependent on the nature of the network:
It should be greater than the highest ‘NT’ (Node Discovery Timeout) of your network.
And include enough time to let the message propagate depending on the sleep cycle of your network nodes.
- time_bw_nodes (Float): Time to wait between node neighbors
requests. Use this setting not to saturate your network:
For ‘Cascade’, the number of seconds to wait after completion of the neighbor discovery process of the previous node.
For ‘Flood’, the minimum time to wait between each node’s neighbor requests.
- time_bw_scans (Float): Time to wait before starting a new
network scan.
- Return type:
Tuple (Float, Float, Float)
- get_device_by_16(x16bit_addr)
Returns the XBee in the network whose 16-bit address matches the given one.
- Parameters:
x16bit_addr (
XBee16BitAddress) – 16-bit address of the node to retrieve.- Returns:
XBee in the network or Non if not found.
- Return type:
- Raises:
ValueError – If x16bit_addr is None or unknown.
- get_device_by_64(x64bit_addr)
Returns the XBee in the network whose 64-bit address matches the given one.
- Parameters:
x64bit_addr (
XBee64BitAddress) – 64-bit address of the node to retrieve.- Returns:
XBee in the network or None if not found.
- Return type:
- Raises:
ValueError – If x64bit_addr is None or unknown.
- get_device_by_node_id(node_id)
Returns the XBee in the network whose node identifier matches the given one.
- Parameters:
node_id (String) – Node identifier of the node to retrieve.
- Returns:
XBee in the network or None if not found.
- Return type:
- Raises:
ValueError – If node_id is None.
- get_devices()
Returns a copy of the XBee devices list of the network.
If a new XBee node is added to the list after the execution of this method, this new XBee is not added to the list returned by this method.
- Returns:
A copy of the XBee devices list of the network.
- Return type:
List
- get_discovery_callbacks()
Returns the API callbacks that are used in the device discovery process.
This callbacks notify the user callbacks for each XBee discovered.
- Returns:
- Callback for generic devices discovery
process, callback for discovery specific XBee ops.
- Return type:
Tuple (Function, Function)
- get_discovery_options()
Returns the network discovery process options.
- Returns:
Discovery options value.
- Return type:
Bytearray
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- get_discovery_timeout()
Returns the network discovery timeout.
- Returns:
Network discovery timeout.
- Return type:
Float
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- get_node_connections(node)
Returns the network connections with one of their ends node.
A deep discover must be performed to get the connections between network nodes.
If a new connection is added to the list after the execution of this method, this new connection is not added to the list returned by this method.
- Parameters:
node (
AbstractXBeeDevice) – The node to get its connections.- Returns:
List of
Connectionwith node end.- Return type:
List
- classmethod get_nt_limits(protocol)
Returns a tuple with the minimum and maximum values for the ‘NT’ value depending on the protocol.
- Returns:
- Minimum value in seconds, maximum value in
seconds.
- Return type:
Tuple (Float, Float)
- get_number_devices()
Returns the number of nodes in the network.
- Returns:
Number of nodes in the network.
- Return type:
Integer
- get_update_progress_callbacks()
Returns the list of registered callbacks for update progress. This is only for internal use.
- Returns:
List of
NetworkUpdateProgressevents.- Return type:
List
- has_devices()
Returns whether there is any device in the network.
- Returns:
- True if there is at least one node in the network,
False otherwise.
- Return type:
Boolean
- is_discovery_running()
Returns whether the discovery process is running.
- Returns:
True if the discovery process is running, False otherwise.
- Return type:
Boolean
- is_node_in_network(node)
Checks if the provided node is in the network or if it is the local XBee.
- Parameters:
node (
AbstractXBeeDevice) – The node to check.- Returns:
True if the node is in the network, False otherwise.
- Return type:
Boolean
- Raises:
ValueError – If node is None.
- remove_device(remote_xbee)
Removes the provided remote XBee from the network.
- Parameters:
remote_xbee (
RemoteXBeeDevice) – Remote XBee to remove.- Raises:
ValueError – If the provided remote_xbee is not in the network.
- property scan_counter
Returns the scan counter.
- Returns:
The scan counter.
- Return type:
Integer
- set_deep_discovery_options(deep_mode=NeighborDiscoveryMode.CASCADE, del_not_discovered_nodes_in_last_scan=False)
Configures the deep discovery options with the given values. These options are only applicable for “deep” discovery (see
start_discovery_process())- Parameters:
deep_mode (
NeighborDiscoveryMode, optional, default=`NeighborDiscoveryMode.CASCADE`) – Neighbor discovery mode, the way to perform the network discovery process.del_not_discovered_nodes_in_last_scan (Boolean, optional, default=`False`) – True to remove nodes from the network if they were not discovered in the last scan.
- set_deep_discovery_timeouts(node_timeout=None, time_bw_requests=None, time_bw_scans=None)
Sets deep discovery network timeouts. These timeouts are only applicable for “deep” discovery (see
start_discovery_process())- node_timeout (Float, optional, default=`None`):
Maximum duration in seconds of the discovery process used to find neighbors of a node. If None already configured timeouts are used.
- time_bw_requests (Float, optional, default=`DEFAULT_TIME_BETWEEN_REQUESTS`): Time to wait
between node neighbors requests. It must be between
MIN_TIME_BETWEEN_REQUESTSandMAX_TIME_BETWEEN_REQUESTSseconds inclusive. Use this setting not to saturate your network:For ‘Cascade’, the number of seconds to wait after completion of the neighbor discovery process of the previous node.
For ‘Flood’, the minimum time to wait between each node’s neighbor requests.
- time_bw_scans (Float, optional, default=`DEFAULT_TIME_BETWEEN_SCANS`): Time to wait
before starting a new network scan. It must be between
MIN_TIME_BETWEEN_SCANSandMAX_TIME_BETWEEN_SCANSseconds inclusive.
- Raises:
ValueError – if node_timeout, time_bw_requests or time_bw_scans are not between their corresponding limits.
- set_discovery_options(options)
Configures the discovery options (NO parameter) with the given value.
- Parameters:
options (Set of
DiscoveryOptions) – New discovery options, empty set to clear the options.- Raises:
ValueError – If options is None.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_discovery_timeout(discovery_timeout)
Sets the discovery network timeout.
- Parameters:
discovery_timeout (Float) – Timeout in seconds.
- Raises:
ValueError – If discovery_timeout is not between the allowed minimum and maximum values.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- start_discovery_process(deep=False, n_deep_scans=1)
Starts the discovery process. This method is not blocking.
This process can discover node neighbors and connections, or only nodes:
Deep discovery: Network nodes and connections between them (including quality) are discovered.
The discovery process will be running the number of scans configured in n_deep_scans. A scan is considered the process of discovering the full network. If there are more than one number of scans configured, after finishing one another is started, until n_deep_scans is satisfied.
See
set_deep_discovery_options()to establish the way the network discovery process is performed.No deep discovery: Only network nodes are discovered.
The discovery process will be running until the configured timeout expires or, in case of 802.15.4, until the ‘end’ packet is read.
It may occur that, after timeout expiration, there are nodes that continue sending discovery responses to the local XBee. In this case, these nodes will not be added to the network.
In 802.15.4, both (deep and no deep discovery) are the same and none discover the node connections or their quality. The difference is the possibility of running more than one scan using a deep discovery.
- Parameters:
deep (Boolean, optional, default=`False`) – True for a deep network scan, looking for neighbors and their connections, False otherwise.
n_deep_scans (Integer, optional, default=1) – Number of scans to perform before automatically stopping the discovery process.
SCAN_TIL_CANCELmeans the process will not be automatically stopped. Only applicable if deep=True.
See also
- stop_discovery_process()
Stops the discovery process if it is running.
Note that some DigiMesh/DigiPoint devices are blocked until the discovery time configured (‘NT’ parameter) has elapsed, so, when trying to get/set any parameter during the discovery process, a TimeoutException is raised.
- update_nodes(task_list)
Performs the provided update tasks. It blocks until all tasks finish.
- Parameters:
task_list (List or tuple) – List of update tasks (
FwUpdateTaskorProfileUpdateTask)- Returns:
- Uses the 64-bit address of the XBee as key and, as
value, a Tuple with the XBee (
AbstractXBeeDevice) and anXBeeExceptionif the process failed for that node (None if it successes)
- Return type:
Dictionary
- class digi.xbee.devices.DigiMeshNetwork(device)[source]
Bases:
XBeeNetworkThis class represents a DigiMesh network.
The network allows the discovery of remote nodes in the same network as the local one and stores them.
Class constructor. Instantiates a new DigiMeshNetwork.
- Parameters:
device (
DigiMeshDevice) – Local DigiMesh node to get the network from.- Raises:
ValueError – If device is None.
- DEFAULT_TIME_BETWEEN_REQUESTS = 5
Default time (in seconds) to wait between node neighbors requests.
- DEFAULT_TIME_BETWEEN_SCANS = 10
Default time (in seconds) to wait before starting a new scan.
- MAX_TIME_BETWEEN_REQUESTS = 600
High limit for the time (in seconds) to wait between node neighbors requests.
- MAX_TIME_BETWEEN_SCANS = 259200
High limit for the time (in seconds) to wait before starting a new scan.
- MIN_TIME_BETWEEN_REQUESTS = 0
Low limit for the time (in seconds) to wait between node neighbors requests.
- MIN_TIME_BETWEEN_SCANS = 0
Low limit for the time (in seconds) to wait before starting a new scan.
- ND_PACKET_FINISH = 1
Flag that indicates a “discovery process finish” packet.
- ND_PACKET_REMOTE = 2
Flag that indicates a discovery process packet with info about a remote XBee.
- SCAN_TIL_CANCEL = 0
The neighbor discovery process continues until is manually stopped.
- add_device_discovered_callback(callback)
Adds a callback for the event
DeviceDiscovered.- Parameters:
callback (Function) –
The callback. Receives one argument.
The discovered remote XBee as a
RemoteXBeeDevice.
- add_discovery_process_finished_callback(callback)
Adds a callback for the event
DiscoveryProcessFinished.- Parameters:
callback (Function) –
The callback. Receives two arguments.
The event code as an
NetworkDiscoveryStatus.(Optional) A description of the discovery process as a string.
- add_end_discovery_scan_callback(callback)
Adds a callback for the event
EndDiscoveryScan.- Parameters:
callback (Function) –
The callback. Receives two arguments.
Number of scan that has finished (starting with 1).
Total number of scans.
- add_if_not_exist(x64bit_addr=None, x16bit_addr=None, node_id=None)
Adds an XBee with the provided information if it does not exist in the current network.
If the XBee already exists, its data is updated with the provided information.
If no valid address is provided (x64bit_addr, x16bit_addr), None is returned.
- Parameters:
x64bit_addr (
XBee64BitAddress, optional, default=`None`) – 64-bit address.x16bit_addr (
XBee16BitAddress, optional, default=`None`) – 16-bit address.node_id (String, optional, default=`None`) – Node identifier.
- Returns:
- the remote XBee with the updated
information. If the XBee was not in the list yet, this method returns the given XBee without changes.
- Return type:
- add_init_discovery_scan_callback(callback)
Adds a callback for the event
InitDiscoveryScan.- Parameters:
callback (Function) –
The callback. Receives two arguments.
Number of scan to start (starting with 1).
Total number of scans.
- add_network_modified_callback(callback)
Adds a callback for the event
NetworkModified.- Parameters:
callback (Function) –
The callback. Receives three arguments.
The event type as a
NetworkEventType.The reason of the event as a
NetworkEventReason.The node added, updated or removed from the network as a
XBeeDeviceorRemoteXBeeDevice.
- add_packet_received_from_callback(node, callback)
Adds a callback to listen to any received packet from the provided node.
- Parameters:
node (
RemoteXBeeDevice) – The node to listen for frames.callback (Function) –
The callback. Receives two arguments.
The received packet as a
XBeeAPIPacket.The remote XBee who sent the packet as a
RemoteXBeeDevice.
- add_remote(remote_xbee)
Adds the provided remote XBee to the network if it is not in yet.
If the XBee is already in the network, its data is updated with the information of the provided XBee that are not None.
- Parameters:
remote_xbee (
RemoteXBeeDevice) – Remote XBee to add.- Returns:
- Provided XBee with updated data. If
the XBee was not in the list, it returns it without changes.
- Return type:
- add_remotes(remote_xbees)
Adds a list of remote XBee nodes to the network.
If any node in the list is already in the network, its data is updated with the information of the corresponding XBee in the list.
- Parameters:
remote_xbees (List) – List of
RemoteXBeeDeviceto add.
- add_update_progress_callback(callback)
Adds a callback for the event
NetworkUpdateProgress.- Parameters:
callback (Function) – The callback. Receives three arguments. * The XBee being updated. * An
UpdateProgressStatuswith the current status.
- clear()
Removes all remote XBee nodes from the network.
- del_device_discovered_callback(callback)
Deletes a callback for the callback list of
DeviceDiscoveredevent.- Parameters:
callback (Function) – The callback to delete.
- del_discovery_process_finished_callback(callback)
Deletes a callback for the callback list of
DiscoveryProcessFinishedevent.- Parameters:
callback (Function) – The callback to delete.
- del_end_discovery_scan_callback(callback)
Deletes a callback for the callback list of
EndDiscoveryScan.- Parameters:
callback (Function) – The callback to delete.
- del_init_discovery_scan_callback(callback)
Deletes a callback for the callback list of
InitDiscoveryScan.- Parameters:
callback (Function) – The callback to delete.
- del_network_modified_callback(callback)
Deletes a callback for the callback list of
NetworkModified.- Parameters:
callback (Function) – The callback to delete.
- del_packet_received_from_callback(node, callb=None)
Deletes a received packet callback from the provided node.
- Parameters:
node (
RemoteXBeeDevice) – The node to listen for frames.callb (Function, optional, default=`None`) – The callback to delete, None to delete all.
- del_update_progress_callback(callback)
Deletes a callback for the callback list of
NetworkUpdateProgress.- Parameters:
callback (Function) – The callback to delete.
- discover_device(node_id)
Blocking method. Discovers and reports the first remote XBee that matches the supplied identifier.
- Parameters:
node_id (String) – Node identifier of the node to discover.
- Returns:
- Discovered remote XBee, None if the
timeout expires and the node was not found.
- Return type:
- discover_devices(device_id_list)
Blocking method. Attempts to discover a list of nodes and add them to the current network.
This method does not guarantee that all nodes of device_id_list will be found, even if they exist physically. This depends on the node discovery operation and timeout.
- Parameters:
device_id_list (List) – List of device IDs to discover.
- Returns:
- List with the discovered nodes. It may not contain all nodes
specified in device_id_list.
- Return type:
List
- export(dir_path=None, name=None, desc=None)
Exports this network to the given file path.
If the provided path already exists the file is removed.
- Parameters:
dir_path (String, optional, default=`None`) – Absolute path of the directory to export the network. It should not include the file name. If not defined home directory is used.
name (String, optional, default=`None`) – Network human readable name.
desc (String, optional, default=`None`) – Network description.
- Returns:
- Tuple with result (0: success, 1: failure)
and string (exported file path if success, error string otherwise).
- Return type:
Tuple (Integer, String)
- get_connections()
Returns a copy of the XBee network connections.
A deep discover must be performed to get the connections between network nodes.
If a new connection is added to the list after the execution of this method, this new connection is not added to the list returned by this method.
- Returns:
A copy of the list of
Connectionfor the network.- Return type:
List
- get_deep_discovery_options()
Returns the deep discovery process options.
- Returns:
- (
NeighborDiscoveryMode, Boolean): Tuple containing: - mode (
NeighborDiscoveryMode): Neighbor discovery mode, the way to perform the network discovery process.
- mode (
- remove_nodes (Boolean): True to remove nodes from the
network if they were not discovered in the last scan, False otherwise.
- (
- Return type:
Tuple
- get_deep_discovery_timeouts()
Gets deep discovery network timeouts. These timeouts are only applicable for “deep” discovery (see
start_discovery_process())- Returns:
- Tuple containing:
- node_timeout (Float): Maximum duration in seconds of the
discovery process per node. This is used to find neighbors of a node. This timeout is highly dependent on the nature of the network:
It should be greater than the highest ‘NT’ (Node Discovery Timeout) of your network.
And include enough time to let the message propagate depending on the sleep cycle of your network nodes.
- time_bw_nodes (Float): Time to wait between node neighbors
requests. Use this setting not to saturate your network:
For ‘Cascade’, the number of seconds to wait after completion of the neighbor discovery process of the previous node.
For ‘Flood’, the minimum time to wait between each node’s neighbor requests.
- time_bw_scans (Float): Time to wait before starting a new
network scan.
- Return type:
Tuple (Float, Float, Float)
- get_device_by_16(x16bit_addr)
Returns the XBee in the network whose 16-bit address matches the given one.
- Parameters:
x16bit_addr (
XBee16BitAddress) – 16-bit address of the node to retrieve.- Returns:
XBee in the network or Non if not found.
- Return type:
- Raises:
ValueError – If x16bit_addr is None or unknown.
- get_device_by_64(x64bit_addr)
Returns the XBee in the network whose 64-bit address matches the given one.
- Parameters:
x64bit_addr (
XBee64BitAddress) – 64-bit address of the node to retrieve.- Returns:
XBee in the network or None if not found.
- Return type:
- Raises:
ValueError – If x64bit_addr is None or unknown.
- get_device_by_node_id(node_id)
Returns the XBee in the network whose node identifier matches the given one.
- Parameters:
node_id (String) – Node identifier of the node to retrieve.
- Returns:
XBee in the network or None if not found.
- Return type:
- Raises:
ValueError – If node_id is None.
- get_devices()
Returns a copy of the XBee devices list of the network.
If a new XBee node is added to the list after the execution of this method, this new XBee is not added to the list returned by this method.
- Returns:
A copy of the XBee devices list of the network.
- Return type:
List
- get_discovery_callbacks()
Returns the API callbacks that are used in the device discovery process.
This callbacks notify the user callbacks for each XBee discovered.
- Returns:
- Callback for generic devices discovery
process, callback for discovery specific XBee ops.
- Return type:
Tuple (Function, Function)
- get_discovery_options()
Returns the network discovery process options.
- Returns:
Discovery options value.
- Return type:
Bytearray
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- get_discovery_timeout()
Returns the network discovery timeout.
- Returns:
Network discovery timeout.
- Return type:
Float
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- get_node_connections(node)
Returns the network connections with one of their ends node.
A deep discover must be performed to get the connections between network nodes.
If a new connection is added to the list after the execution of this method, this new connection is not added to the list returned by this method.
- Parameters:
node (
AbstractXBeeDevice) – The node to get its connections.- Returns:
List of
Connectionwith node end.- Return type:
List
- classmethod get_nt_limits(protocol)
Returns a tuple with the minimum and maximum values for the ‘NT’ value depending on the protocol.
- Returns:
- Minimum value in seconds, maximum value in
seconds.
- Return type:
Tuple (Float, Float)
- get_number_devices()
Returns the number of nodes in the network.
- Returns:
Number of nodes in the network.
- Return type:
Integer
- get_update_progress_callbacks()
Returns the list of registered callbacks for update progress. This is only for internal use.
- Returns:
List of
NetworkUpdateProgressevents.- Return type:
List
- has_devices()
Returns whether there is any device in the network.
- Returns:
- True if there is at least one node in the network,
False otherwise.
- Return type:
Boolean
- is_discovery_running()
Returns whether the discovery process is running.
- Returns:
True if the discovery process is running, False otherwise.
- Return type:
Boolean
- is_node_in_network(node)
Checks if the provided node is in the network or if it is the local XBee.
- Parameters:
node (
AbstractXBeeDevice) – The node to check.- Returns:
True if the node is in the network, False otherwise.
- Return type:
Boolean
- Raises:
ValueError – If node is None.
- remove_device(remote_xbee)
Removes the provided remote XBee from the network.
- Parameters:
remote_xbee (
RemoteXBeeDevice) – Remote XBee to remove.- Raises:
ValueError – If the provided remote_xbee is not in the network.
- property scan_counter
Returns the scan counter.
- Returns:
The scan counter.
- Return type:
Integer
- set_deep_discovery_options(deep_mode=NeighborDiscoveryMode.CASCADE, del_not_discovered_nodes_in_last_scan=False)
Configures the deep discovery options with the given values. These options are only applicable for “deep” discovery (see
start_discovery_process())- Parameters:
deep_mode (
NeighborDiscoveryMode, optional, default=`NeighborDiscoveryMode.CASCADE`) – Neighbor discovery mode, the way to perform the network discovery process.del_not_discovered_nodes_in_last_scan (Boolean, optional, default=`False`) – True to remove nodes from the network if they were not discovered in the last scan.
- set_deep_discovery_timeouts(node_timeout=None, time_bw_requests=None, time_bw_scans=None)
Sets deep discovery network timeouts. These timeouts are only applicable for “deep” discovery (see
start_discovery_process())- node_timeout (Float, optional, default=`None`):
Maximum duration in seconds of the discovery process used to find neighbors of a node. If None already configured timeouts are used.
- time_bw_requests (Float, optional, default=`DEFAULT_TIME_BETWEEN_REQUESTS`): Time to wait
between node neighbors requests. It must be between
MIN_TIME_BETWEEN_REQUESTSandMAX_TIME_BETWEEN_REQUESTSseconds inclusive. Use this setting not to saturate your network:For ‘Cascade’, the number of seconds to wait after completion of the neighbor discovery process of the previous node.
For ‘Flood’, the minimum time to wait between each node’s neighbor requests.
- time_bw_scans (Float, optional, default=`DEFAULT_TIME_BETWEEN_SCANS`): Time to wait
before starting a new network scan. It must be between
MIN_TIME_BETWEEN_SCANSandMAX_TIME_BETWEEN_SCANSseconds inclusive.
- Raises:
ValueError – if node_timeout, time_bw_requests or time_bw_scans are not between their corresponding limits.
- set_discovery_options(options)
Configures the discovery options (NO parameter) with the given value.
- Parameters:
options (Set of
DiscoveryOptions) – New discovery options, empty set to clear the options.- Raises:
ValueError – If options is None.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_discovery_timeout(discovery_timeout)
Sets the discovery network timeout.
- Parameters:
discovery_timeout (Float) – Timeout in seconds.
- Raises:
ValueError – If discovery_timeout is not between the allowed minimum and maximum values.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- start_discovery_process(deep=False, n_deep_scans=1)
Starts the discovery process. This method is not blocking.
This process can discover node neighbors and connections, or only nodes:
Deep discovery: Network nodes and connections between them (including quality) are discovered.
The discovery process will be running the number of scans configured in n_deep_scans. A scan is considered the process of discovering the full network. If there are more than one number of scans configured, after finishing one another is started, until n_deep_scans is satisfied.
See
set_deep_discovery_options()to establish the way the network discovery process is performed.No deep discovery: Only network nodes are discovered.
The discovery process will be running until the configured timeout expires or, in case of 802.15.4, until the ‘end’ packet is read.
It may occur that, after timeout expiration, there are nodes that continue sending discovery responses to the local XBee. In this case, these nodes will not be added to the network.
In 802.15.4, both (deep and no deep discovery) are the same and none discover the node connections or their quality. The difference is the possibility of running more than one scan using a deep discovery.
- Parameters:
deep (Boolean, optional, default=`False`) – True for a deep network scan, looking for neighbors and their connections, False otherwise.
n_deep_scans (Integer, optional, default=1) – Number of scans to perform before automatically stopping the discovery process.
SCAN_TIL_CANCELmeans the process will not be automatically stopped. Only applicable if deep=True.
See also
- stop_discovery_process()
Stops the discovery process if it is running.
Note that some DigiMesh/DigiPoint devices are blocked until the discovery time configured (‘NT’ parameter) has elapsed, so, when trying to get/set any parameter during the discovery process, a TimeoutException is raised.
- update_nodes(task_list)
Performs the provided update tasks. It blocks until all tasks finish.
- Parameters:
task_list (List or tuple) – List of update tasks (
FwUpdateTaskorProfileUpdateTask)- Returns:
- Uses the 64-bit address of the XBee as key and, as
value, a Tuple with the XBee (
AbstractXBeeDevice) and anXBeeExceptionif the process failed for that node (None if it successes)
- Return type:
Dictionary
- class digi.xbee.devices.DigiPointNetwork(xbee_device)[source]
Bases:
XBeeNetworkThis class represents a DigiPoint network.
The network allows the discovery of remote nodes in the same network as the local one and stores them.
Class constructor. Instantiates a new XBeeNetwork.
- Parameters:
xbee_device (
XBeeDevice) – Local XBee to get the network from.- Raises:
ValueError – If xbee_device is None.
- DEFAULT_TIME_BETWEEN_REQUESTS = 5
Default time (in seconds) to wait between node neighbors requests.
- DEFAULT_TIME_BETWEEN_SCANS = 10
Default time (in seconds) to wait before starting a new scan.
- MAX_TIME_BETWEEN_REQUESTS = 600
High limit for the time (in seconds) to wait between node neighbors requests.
- MAX_TIME_BETWEEN_SCANS = 259200
High limit for the time (in seconds) to wait before starting a new scan.
- MIN_TIME_BETWEEN_REQUESTS = 0
Low limit for the time (in seconds) to wait between node neighbors requests.
- MIN_TIME_BETWEEN_SCANS = 0
Low limit for the time (in seconds) to wait before starting a new scan.
- ND_PACKET_FINISH = 1
Flag that indicates a “discovery process finish” packet.
- ND_PACKET_REMOTE = 2
Flag that indicates a discovery process packet with info about a remote XBee.
- SCAN_TIL_CANCEL = 0
The neighbor discovery process continues until is manually stopped.
- add_device_discovered_callback(callback)
Adds a callback for the event
DeviceDiscovered.- Parameters:
callback (Function) –
The callback. Receives one argument.
The discovered remote XBee as a
RemoteXBeeDevice.
- add_discovery_process_finished_callback(callback)
Adds a callback for the event
DiscoveryProcessFinished.- Parameters:
callback (Function) –
The callback. Receives two arguments.
The event code as an
NetworkDiscoveryStatus.(Optional) A description of the discovery process as a string.
- add_end_discovery_scan_callback(callback)
Adds a callback for the event
EndDiscoveryScan.- Parameters:
callback (Function) –
The callback. Receives two arguments.
Number of scan that has finished (starting with 1).
Total number of scans.
- add_if_not_exist(x64bit_addr=None, x16bit_addr=None, node_id=None)
Adds an XBee with the provided information if it does not exist in the current network.
If the XBee already exists, its data is updated with the provided information.
If no valid address is provided (x64bit_addr, x16bit_addr), None is returned.
- Parameters:
x64bit_addr (
XBee64BitAddress, optional, default=`None`) – 64-bit address.x16bit_addr (
XBee16BitAddress, optional, default=`None`) – 16-bit address.node_id (String, optional, default=`None`) – Node identifier.
- Returns:
- the remote XBee with the updated
information. If the XBee was not in the list yet, this method returns the given XBee without changes.
- Return type:
- add_init_discovery_scan_callback(callback)
Adds a callback for the event
InitDiscoveryScan.- Parameters:
callback (Function) –
The callback. Receives two arguments.
Number of scan to start (starting with 1).
Total number of scans.
- add_network_modified_callback(callback)
Adds a callback for the event
NetworkModified.- Parameters:
callback (Function) –
The callback. Receives three arguments.
The event type as a
NetworkEventType.The reason of the event as a
NetworkEventReason.The node added, updated or removed from the network as a
XBeeDeviceorRemoteXBeeDevice.
- add_packet_received_from_callback(node, callback)
Adds a callback to listen to any received packet from the provided node.
- Parameters:
node (
RemoteXBeeDevice) – The node to listen for frames.callback (Function) –
The callback. Receives two arguments.
The received packet as a
XBeeAPIPacket.The remote XBee who sent the packet as a
RemoteXBeeDevice.
- add_remote(remote_xbee)
Adds the provided remote XBee to the network if it is not in yet.
If the XBee is already in the network, its data is updated with the information of the provided XBee that are not None.
- Parameters:
remote_xbee (
RemoteXBeeDevice) – Remote XBee to add.- Returns:
- Provided XBee with updated data. If
the XBee was not in the list, it returns it without changes.
- Return type:
- add_remotes(remote_xbees)
Adds a list of remote XBee nodes to the network.
If any node in the list is already in the network, its data is updated with the information of the corresponding XBee in the list.
- Parameters:
remote_xbees (List) – List of
RemoteXBeeDeviceto add.
- add_update_progress_callback(callback)
Adds a callback for the event
NetworkUpdateProgress.- Parameters:
callback (Function) – The callback. Receives three arguments. * The XBee being updated. * An
UpdateProgressStatuswith the current status.
- clear()
Removes all remote XBee nodes from the network.
- del_device_discovered_callback(callback)
Deletes a callback for the callback list of
DeviceDiscoveredevent.- Parameters:
callback (Function) – The callback to delete.
- del_discovery_process_finished_callback(callback)
Deletes a callback for the callback list of
DiscoveryProcessFinishedevent.- Parameters:
callback (Function) – The callback to delete.
- del_end_discovery_scan_callback(callback)
Deletes a callback for the callback list of
EndDiscoveryScan.- Parameters:
callback (Function) – The callback to delete.
- del_init_discovery_scan_callback(callback)
Deletes a callback for the callback list of
InitDiscoveryScan.- Parameters:
callback (Function) – The callback to delete.
- del_network_modified_callback(callback)
Deletes a callback for the callback list of
NetworkModified.- Parameters:
callback (Function) – The callback to delete.
- del_packet_received_from_callback(node, callb=None)
Deletes a received packet callback from the provided node.
- Parameters:
node (
RemoteXBeeDevice) – The node to listen for frames.callb (Function, optional, default=`None`) – The callback to delete, None to delete all.
- del_update_progress_callback(callback)
Deletes a callback for the callback list of
NetworkUpdateProgress.- Parameters:
callback (Function) – The callback to delete.
- discover_device(node_id)
Blocking method. Discovers and reports the first remote XBee that matches the supplied identifier.
- Parameters:
node_id (String) – Node identifier of the node to discover.
- Returns:
- Discovered remote XBee, None if the
timeout expires and the node was not found.
- Return type:
- discover_devices(device_id_list)
Blocking method. Attempts to discover a list of nodes and add them to the current network.
This method does not guarantee that all nodes of device_id_list will be found, even if they exist physically. This depends on the node discovery operation and timeout.
- Parameters:
device_id_list (List) – List of device IDs to discover.
- Returns:
- List with the discovered nodes. It may not contain all nodes
specified in device_id_list.
- Return type:
List
- export(dir_path=None, name=None, desc=None)
Exports this network to the given file path.
If the provided path already exists the file is removed.
- Parameters:
dir_path (String, optional, default=`None`) – Absolute path of the directory to export the network. It should not include the file name. If not defined home directory is used.
name (String, optional, default=`None`) – Network human readable name.
desc (String, optional, default=`None`) – Network description.
- Returns:
- Tuple with result (0: success, 1: failure)
and string (exported file path if success, error string otherwise).
- Return type:
Tuple (Integer, String)
- get_connections()
Returns a copy of the XBee network connections.
A deep discover must be performed to get the connections between network nodes.
If a new connection is added to the list after the execution of this method, this new connection is not added to the list returned by this method.
- Returns:
A copy of the list of
Connectionfor the network.- Return type:
List
- get_deep_discovery_options()
Returns the deep discovery process options.
- Returns:
- (
NeighborDiscoveryMode, Boolean): Tuple containing: - mode (
NeighborDiscoveryMode): Neighbor discovery mode, the way to perform the network discovery process.
- mode (
- remove_nodes (Boolean): True to remove nodes from the
network if they were not discovered in the last scan, False otherwise.
- (
- Return type:
Tuple
- get_deep_discovery_timeouts()
Gets deep discovery network timeouts. These timeouts are only applicable for “deep” discovery (see
start_discovery_process())- Returns:
- Tuple containing:
- node_timeout (Float): Maximum duration in seconds of the
discovery process per node. This is used to find neighbors of a node. This timeout is highly dependent on the nature of the network:
It should be greater than the highest ‘NT’ (Node Discovery Timeout) of your network.
And include enough time to let the message propagate depending on the sleep cycle of your network nodes.
- time_bw_nodes (Float): Time to wait between node neighbors
requests. Use this setting not to saturate your network:
For ‘Cascade’, the number of seconds to wait after completion of the neighbor discovery process of the previous node.
For ‘Flood’, the minimum time to wait between each node’s neighbor requests.
- time_bw_scans (Float): Time to wait before starting a new
network scan.
- Return type:
Tuple (Float, Float, Float)
- get_device_by_16(x16bit_addr)
Returns the XBee in the network whose 16-bit address matches the given one.
- Parameters:
x16bit_addr (
XBee16BitAddress) – 16-bit address of the node to retrieve.- Returns:
XBee in the network or Non if not found.
- Return type:
- Raises:
ValueError – If x16bit_addr is None or unknown.
- get_device_by_64(x64bit_addr)
Returns the XBee in the network whose 64-bit address matches the given one.
- Parameters:
x64bit_addr (
XBee64BitAddress) – 64-bit address of the node to retrieve.- Returns:
XBee in the network or None if not found.
- Return type:
- Raises:
ValueError – If x64bit_addr is None or unknown.
- get_device_by_node_id(node_id)
Returns the XBee in the network whose node identifier matches the given one.
- Parameters:
node_id (String) – Node identifier of the node to retrieve.
- Returns:
XBee in the network or None if not found.
- Return type:
- Raises:
ValueError – If node_id is None.
- get_devices()
Returns a copy of the XBee devices list of the network.
If a new XBee node is added to the list after the execution of this method, this new XBee is not added to the list returned by this method.
- Returns:
A copy of the XBee devices list of the network.
- Return type:
List
- get_discovery_callbacks()
Returns the API callbacks that are used in the device discovery process.
This callbacks notify the user callbacks for each XBee discovered.
- Returns:
- Callback for generic devices discovery
process, callback for discovery specific XBee ops.
- Return type:
Tuple (Function, Function)
- get_discovery_options()
Returns the network discovery process options.
- Returns:
Discovery options value.
- Return type:
Bytearray
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- get_discovery_timeout()
Returns the network discovery timeout.
- Returns:
Network discovery timeout.
- Return type:
Float
- Raises:
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- get_node_connections(node)
Returns the network connections with one of their ends node.
A deep discover must be performed to get the connections between network nodes.
If a new connection is added to the list after the execution of this method, this new connection is not added to the list returned by this method.
- Parameters:
node (
AbstractXBeeDevice) – The node to get its connections.- Returns:
List of
Connectionwith node end.- Return type:
List
- classmethod get_nt_limits(protocol)
Returns a tuple with the minimum and maximum values for the ‘NT’ value depending on the protocol.
- Returns:
- Minimum value in seconds, maximum value in
seconds.
- Return type:
Tuple (Float, Float)
- get_number_devices()
Returns the number of nodes in the network.
- Returns:
Number of nodes in the network.
- Return type:
Integer
- get_update_progress_callbacks()
Returns the list of registered callbacks for update progress. This is only for internal use.
- Returns:
List of
NetworkUpdateProgressevents.- Return type:
List
- has_devices()
Returns whether there is any device in the network.
- Returns:
- True if there is at least one node in the network,
False otherwise.
- Return type:
Boolean
- is_discovery_running()
Returns whether the discovery process is running.
- Returns:
True if the discovery process is running, False otherwise.
- Return type:
Boolean
- is_node_in_network(node)
Checks if the provided node is in the network or if it is the local XBee.
- Parameters:
node (
AbstractXBeeDevice) – The node to check.- Returns:
True if the node is in the network, False otherwise.
- Return type:
Boolean
- Raises:
ValueError – If node is None.
- remove_device(remote_xbee)
Removes the provided remote XBee from the network.
- Parameters:
remote_xbee (
RemoteXBeeDevice) – Remote XBee to remove.- Raises:
ValueError – If the provided remote_xbee is not in the network.
- property scan_counter
Returns the scan counter.
- Returns:
The scan counter.
- Return type:
Integer
- set_deep_discovery_options(deep_mode=NeighborDiscoveryMode.CASCADE, del_not_discovered_nodes_in_last_scan=False)
Configures the deep discovery options with the given values. These options are only applicable for “deep” discovery (see
start_discovery_process())- Parameters:
deep_mode (
NeighborDiscoveryMode, optional, default=`NeighborDiscoveryMode.CASCADE`) – Neighbor discovery mode, the way to perform the network discovery process.del_not_discovered_nodes_in_last_scan (Boolean, optional, default=`False`) – True to remove nodes from the network if they were not discovered in the last scan.
- set_deep_discovery_timeouts(node_timeout=None, time_bw_requests=None, time_bw_scans=None)
Sets deep discovery network timeouts. These timeouts are only applicable for “deep” discovery (see
start_discovery_process())- node_timeout (Float, optional, default=`None`):
Maximum duration in seconds of the discovery process used to find neighbors of a node. If None already configured timeouts are used.
- time_bw_requests (Float, optional, default=`DEFAULT_TIME_BETWEEN_REQUESTS`): Time to wait
between node neighbors requests. It must be between
MIN_TIME_BETWEEN_REQUESTSandMAX_TIME_BETWEEN_REQUESTSseconds inclusive. Use this setting not to saturate your network:For ‘Cascade’, the number of seconds to wait after completion of the neighbor discovery process of the previous node.
For ‘Flood’, the minimum time to wait between each node’s neighbor requests.
- time_bw_scans (Float, optional, default=`DEFAULT_TIME_BETWEEN_SCANS`): Time to wait
before starting a new network scan. It must be between
MIN_TIME_BETWEEN_SCANSandMAX_TIME_BETWEEN_SCANSseconds inclusive.
- Raises:
ValueError – if node_timeout, time_bw_requests or time_bw_scans are not between their corresponding limits.
- set_discovery_options(options)
Configures the discovery options (NO parameter) with the given value.
- Parameters:
options (Set of
DiscoveryOptions) – New discovery options, empty set to clear the options.- Raises:
ValueError – If options is None.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
See also
- set_discovery_timeout(discovery_timeout)
Sets the discovery network timeout.
- Parameters:
discovery_timeout (Float) – Timeout in seconds.
- Raises:
ValueError – If discovery_timeout is not between the allowed minimum and maximum values.
TimeoutException – If response is not received before the read timeout expires.
XBeeException – If the XBee’s communication interface is closed.
InvalidOperatingModeException – If the XBee’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
ATCommandException – If response is not as expected.
- start_discovery_process(deep=False, n_deep_scans=1)
Starts the discovery process. This method is not blocking.
This process can discover node neighbors and connections, or only nodes:
Deep discovery: Network nodes and connections between them (including quality) are discovered.
The discovery process will be running the number of scans configured in n_deep_scans. A scan is considered the process of discovering the full network. If there are more than one number of scans configured, after finishing one another is started, until n_deep_scans is satisfied.
See
set_deep_discovery_options()to establish the way the network discovery process is performed.No deep discovery: Only network nodes are discovered.
The discovery process will be running until the configured timeout expires or, in case of 802.15.4, until the ‘end’ packet is read.
It may occur that, after timeout expiration, there are nodes that continue sending discovery responses to the local XBee. In this case, these nodes will not be added to the network.
In 802.15.4, both (deep and no deep discovery) are the same and none discover the node connections or their quality. The difference is the possibility of running more than one scan using a deep discovery.
- Parameters:
deep (Boolean, optional, default=`False`) – True for a deep network scan, looking for neighbors and their connections, False otherwise.
n_deep_scans (Integer, optional, default=1) – Number of scans to perform before automatically stopping the discovery process.
SCAN_TIL_CANCELmeans the process will not be automatically stopped. Only applicable if deep=True.
See also
- stop_discovery_process()
Stops the discovery process if it is running.
Note that some DigiMesh/DigiPoint devices are blocked until the discovery time configured (‘NT’ parameter) has elapsed, so, when trying to get/set any parameter during the discovery process, a TimeoutException is raised.
- update_nodes(task_list)
Performs the provided update tasks. It blocks until all tasks finish.
- Parameters:
task_list (List or tuple) – List of update tasks (
FwUpdateTaskorProfileUpdateTask)- Returns:
- Uses the 64-bit address of the XBee as key and, as
value, a Tuple with the XBee (
AbstractXBeeDevice) and anXBeeExceptionif the process failed for that node (None if it successes)
- Return type:
Dictionary
- class digi.xbee.devices.NetworkEventType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]
Bases:
EnumEnumerates the different network event types.
Values:XBee added to the network (0) = (0, ‘XBee added to the network’)XBee removed from the network (1) = (1, ‘XBee removed from the network’)XBee in the network updated (2) = (2, ‘XBee in the network updated’)Network cleared (3) = (3, ‘Network cleared’)- property code
Returns the code of the NetworkEventType element.
- Returns
Integer: Code of the NetworkEventType element.
- property description
Returns the description of the NetworkEventType element.
- Returns:
Description of the NetworkEventType element.
- Return type:
String
- class digi.xbee.devices.NetworkEventReason(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]
Bases:
EnumEnumerates the different network event reasons.
Values:Discovered XBee (0) = (0, ‘Discovered XBee’)Discovered as XBee neighbor (1) = (1, ‘Discovered as XBee neighbor’)Received message from XBee (2) = (2, ‘Received message from XBee’)Manual modification (3) = (3, ‘Manual modification’)Hop of a network route (4) = (4, ‘Hop of a network route’)Read XBee information (5) = (5, ‘Read XBee information’)The firmware of the device was updated (6) = (6, ‘The firmware of the device was updated’)New profile applied to the device (7) = (7, ‘New profile applied to the device’)- property code
Returns the code of the NetworkEventReason element.
- Returns:
Code of the NetworkEventReason element.
- Return type:
Integer
- property description
Returns the description of the NetworkEventReason element.
- Returns:
Description of the NetworkEventReason element.
- Return type:
String
- class digi.xbee.devices.LinkQuality(lq=None, is_rssi=False)[source]
Bases:
objectThis class represents the link quality of a connection. It can be a LQI (Link Quality Index) for Zigbee devices, or RSSI (Received Signal Strength Indicator) for the rest.
Class constructor. Instantiates a new LinkQuality.
- Parameters:
lq (Integer, optional, default=`UNKNOWN`) – Link quality.
is_rssi (Boolean, optional, default=`False`) – True to specify the value is a RSSI, False for LQI.
- UNKNOWN = <digi.xbee.devices.LinkQuality object>
Unknown link quality.
- UNKNOWN_VALUE = -9999
Unknown link quality value.
- property lq
Returns the link quality value.
- Returns:
The link quality value.
- Return type:
Integer
- property is_rssi
Returns whether this is a RSSI value.
- Returns:
True if this is an RSSI value, False for LQI.
- Return type:
Boolean
- class digi.xbee.devices.Connection(node_a, node_b, lq_a2b=None, lq_b2a=None, status_a2b=None, status_b2a=None)[source]
Bases:
objectThis class represents a generic connection between two nodes in a XBee network. It contains the source and destination nodes, the link quality of the connection between them and its status.
Class constructor. Instantiates a new Connection.
- Parameters:
node_a (
AbstractXBeeDevice) – One of the connection ends.node_b (
AbstractXBeeDevice) – The other connection end.lq_a2b (
LinkQualityor Integer, optional, default=`None`) – Link quality for the connection node_a -> node_b. If not specified LinkQuality.UNKNOWN is used.lq_b2a (
LinkQualityor Integer, optional, default=`None`) – Link quality for the connection node_b -> node_a. If not specified LinkQuality.UNKNOWN is used.status_a2b (
digi.xbee.models.zdo.RouteStatus, optional, default=`None`) – The status for the connection node_a -> node_b. If not specified RouteStatus.UNKNOWN is used.status_b2a (
digi.xbee.models.zdo.RouteStatus, optional, default=`None`) – The status for the connection node_b -> node_a. If not specified RouteStatus.UNKNOWN is used.
- Raises:
ValueError – If node_a or node_b is None.
- property node_a
Returns the node A of this connection.
- Returns:
The node A.
- Return type:
See also
- property node_b
Returns the node B of this connection.
- Returns:
The node B.
- Return type:
See also
- property lq_a2b
Returns the link quality of the connection from node A to node B.
- Returns:
Link quality for the connection A -> B.
- Return type:
See also
- property lq_b2a
Returns the link quality of the connection from node B to node A.
- Returns:
Link quality for the connection B -> A.
- Return type:
See also
- property status_a2b
Returns the status of this connection from node A to node B.
- Returns:
The status for A -> B connection.
- Return type:
See also
- property status_b2a
Returns the status of this connection from node B to node A.
- Returns:
The status for B -> A connection.
- Return type:
See also
- property scan_counter_a2b
Returns the scan counter for this connection, discovered by its A node.
- Returns:
The scan counter for this connection, discovered by its A node.
- Return type:
Integer
- property scan_counter_b2a
Returns the scan counter for this connection, discovered by its B node.
- Returns:
The scan counter for this connection, discovered by its B node.
- Return type:
Integer