Source code for digi.xbee.packets.zigbee

# Copyright 2019-2021, Digi International Inc.
#
# This Source Code Form is subject to the terms of the Mozilla Public
# License, v. 2.0. If a copy of the MPL was not distributed with this
# file, You can obtain one at http://mozilla.org/MPL/2.0/.
#
# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF

from digi.xbee.exception import InvalidOperatingModeException, InvalidPacketException
from digi.xbee.models.address import XBee64BitAddress, XBee16BitAddress
from digi.xbee.models.mode import OperatingMode
from digi.xbee.models.options import RegisterKeyOptions
from digi.xbee.models.status import ZigbeeRegisterStatus, EmberBootloaderMessageType
from digi.xbee.packets.aft import ApiFrameType
from digi.xbee.packets.base import XBeeAPIPacket, DictKeys
from digi.xbee.util import utils


[docs]class RegisterJoiningDevicePacket(XBeeAPIPacket): """ This class represents a Register Joining Device packet. Packet is built using the parameters of the constructor or providing a valid API payload. Use this frame to securely register 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). If registering a device with a centralized trust center (EO = 2), then the key entry will only persist for KT seconds before expiring. Registering devices in a distributed trust center (EO = 0) is persistent and the key entry will never expire unless explicitly removed. To remove a key entry on a distributed trust center, this frame should be issued with a null (None) key. In a centralized trust center you cannot use this method to explicitly remove the key entries. .. seealso:: | :class:`.XBeeAPIPacket` """ __MIN_PACKET_LENGTH = 17 def __init__(self, frame_id, registrant_address, options, key, op_mode=OperatingMode.API_MODE): """ Class constructor. Instantiates a new :class:`.RegisterJoiningDevicePacket` object with the provided parameters. Args: frame_id (integer): the frame ID of the packet. registrant_address (:class:`.XBee64BitAddress`): the 64-bit address of the destination device. options (:class:`.RegisterKeyOptions`): the register options indicating the key source. key (Bytearray): key of the device to register. Up to 16 bytes if entering a Link Key or up to 18 bytes (16-byte code + 2 byte CRC) if entering an Install Code. op_mode (:class:`.OperatingMode`, optional, default=`OperatingMode.API_MODE`): The mode in which the frame was captured. Raises: ValueError: if `frame_id` is less than 0 or greater than 255. .. seealso:: | :class:`.XBee64BitAddress` | :class:`.XBeeAPIPacket` | :class:`.RegisterKeyOptions` """ if frame_id < 0 or frame_id > 255: raise ValueError("Frame id must be between 0 and 255.") super().__init__(ApiFrameType.REGISTER_JOINING_DEVICE, op_mode=op_mode) self._frame_id = frame_id self.__registrant_addr = registrant_address self.__opts = options self.__key = key
[docs] @staticmethod def create_packet(raw, operating_mode): """ Override method. Returns: :class:`.RegisterJoiningDevicePacket`. Raises: InvalidPacketException: if the bytearray length is less than 17. (start delim. + length (2 bytes) + frame type + frame id + 64-bit registrant addr. (8 bytes) + 16-bit registrant addr. (2 bytes) + options + checksum = 17 bytes). InvalidPacketException: if the length field of 'raw' is different from its real length. (length field: bytes 2 and 3) InvalidPacketException: if the first byte of 'raw' is not the header byte. See :class:`.SpecialByte`. InvalidPacketException: if the calculated checksum is different from the checksum field value (last byte). InvalidPacketException: if the frame type is not :attr:`.ApiFrameType.REGISTER_JOINING_DEVICE`. InvalidOperatingModeException: if `operating_mode` is not supported. .. seealso:: | :meth:`.XBeePacket.create_packet` | :meth:`.XBeeAPIPacket._check_api_packet` """ if operating_mode not in (OperatingMode.ESCAPED_API_MODE, OperatingMode.API_MODE): raise InvalidOperatingModeException( operating_mode.name + " is not supported.") XBeeAPIPacket._check_api_packet( raw, min_length=RegisterJoiningDevicePacket.__MIN_PACKET_LENGTH) if raw[3] != ApiFrameType.REGISTER_JOINING_DEVICE.code: raise InvalidPacketException( "This packet is not a Register Joining Device packet.") return RegisterJoiningDevicePacket(raw[4], XBee64BitAddress(raw[5:13]), RegisterKeyOptions.get(raw[15]), raw[16:-1], op_mode=operating_mode)
[docs] def needs_id(self): """ Override method. .. seealso:: | :meth:`.XBeeAPIPacket.needs_id` """ return True
def _get_api_packet_spec_data(self): """ Override method. .. seealso:: | :meth:`.XBeeAPIPacket._get_api_packet_spec_data` """ ret = self.__registrant_addr.address ret += XBee16BitAddress.UNKNOWN_ADDRESS.address ret.append(self.__opts.code) if self.__key is not None: ret += self.__key return ret def _get_api_packet_spec_data_dict(self): """ Override method. .. seealso:: | :meth:`.XBeeAPIPacket._get_api_packet_spec_data_dict` """ return {DictKeys.X64BIT_ADDR: "%s (%s)" % (self.__registrant_addr.packed, self.__registrant_addr.exploded), DictKeys.RESERVED: XBee16BitAddress.UNKNOWN_ADDRESS.address, DictKeys.OPTIONS: "%s (%s)" % (self.__opts.code, self.__opts.description), DictKeys.KEY: list(self.__key) if self.__key is not None else None} @property def registrant_address(self): """ Returns the 64-bit registrant address. Returns: :class:`.XBee64BitAddress`: the 64-bit registrant address. .. seealso:: | :class:`.XBee64BitAddress` """ return self.__registrant_addr @registrant_address.setter def registrant_address(self, registrant_address): """ Sets the 64-bit registrant address. Args: registrant_address (:class:`.XBee64BitAddress`): The new 64-bit registrant address. .. seealso:: | :class:`.XBee64BitAddress` """ if registrant_address is not None: self.__registrant_addr = registrant_address @property def options(self): """ Returns the register options value. Returns: :class:`.RegisterKeyOptions`: the register options indicating the key source. .. seealso:: | :class:`.RegisterKeyOptions` """ return self.__opts @options.setter def options(self, options): """ Sets the register options value. Args: options (:class:`.RegisterKeyOptions`): the new register options. .. seealso:: | :class:`.RegisterKeyOptions` """ self.__opts = options @property def key(self): """ Returns the register key. Returns: Bytearray: the register key. """ if self.__key is None: return None return self.__key.copy() @key.setter def key(self, key): """ Sets the register key. Args: key (Bytearray): the new register key. """ if key is None: self.__key = None else: self.__key = key.copy()
[docs]class RegisterDeviceStatusPacket(XBeeAPIPacket): """ This class represents a Register Device Status packet. Packet is built using the parameters of the constructor or providing a valid API payload. This frame is sent out of the UART of the trust center as a response to a 0x24 Register Device frame, indicating whether the registration was successful or not. .. seealso:: | :class:`.RegisterJoiningDevicePacket` | :class:`.XBeeAPIPacket` """ __MIN_PACKET_LENGTH = 7 def __init__(self, frame_id, status, op_mode=OperatingMode.API_MODE): """ Class constructor. Instantiates a new :class:`.RegisterDeviceStatusPacket` object with the provided parameters. Args: frame_id (integer): the frame ID of the packet. status (:class:`.ZigbeeRegisterStatus`): status of the register device operation. op_mode (:class:`.OperatingMode`, optional, default=`OperatingMode.API_MODE`): The mode in which the frame was captured. Raises: ValueError: if `frame_id` is less than 0 or greater than 255. .. seealso:: | :class:`.XBeeAPIPacket` | :class:`.ZigbeeRegisterStatus` """ if frame_id < 0 or frame_id > 255: raise ValueError("Frame id must be between 0 and 255.") super().__init__(ApiFrameType.REGISTER_JOINING_DEVICE_STATUS, op_mode=op_mode) self._frame_id = frame_id self.__status = status
[docs] @staticmethod def create_packet(raw, operating_mode): """ Override method. Returns: :class:`.RegisterDeviceStatusPacket`. Raises: InvalidPacketException: if the bytearray length is less than 17. (start delim. + length (2 bytes) + frame type + frame id + status + checksum = 7 bytes). InvalidPacketException: if the length field of 'raw' is different from its real length. (length field: bytes 1 and 3) InvalidPacketException: if the first byte of 'raw' is not the header byte. See :class:`.SpecialByte`. InvalidPacketException: if the calculated checksum is different from the checksum field value (last byte). InvalidPacketException: if the frame type is not :attr:`.ApiFrameType.REGISTER_JOINING_DEVICE_STATUS`. InvalidOperatingModeException: if `operating_mode` is not supported. .. seealso:: | :meth:`.XBeePacket.create_packet` | :meth:`.XBeeAPIPacket._check_api_packet` """ if operating_mode not in (OperatingMode.ESCAPED_API_MODE, OperatingMode.API_MODE): raise InvalidOperatingModeException( operating_mode.name + " is not supported.") XBeeAPIPacket._check_api_packet( raw, min_length=RegisterDeviceStatusPacket.__MIN_PACKET_LENGTH) if raw[3] != ApiFrameType.REGISTER_JOINING_DEVICE_STATUS.code: raise InvalidPacketException( "This packet is not a Register Device Status packet.") return RegisterDeviceStatusPacket( raw[4], ZigbeeRegisterStatus.get(raw[5]), op_mode=operating_mode)
[docs] def needs_id(self): """ Override method. .. seealso:: | :meth:`.XBeeAPIPacket.needs_id` """ return True
def _get_api_packet_spec_data(self): """ Override method. .. seealso:: | :meth:`.XBeeAPIPacket._get_api_packet_spec_data` """ return bytearray([self.__status.code]) def _get_api_packet_spec_data_dict(self): """ Override method. .. seealso:: | :meth:`.XBeeAPIPacket._get_api_packet_spec_data_dict` """ return {DictKeys.STATUS: "%s (%s)" % (self.__status.code, self.__status.description)} @property def status(self): """ Returns the register device status. Returns: :class:`.ZigbeeRegisterStatus`: the register device status. .. seealso:: | :class:`.ZigbeeRegisterStatus` """ return self.__status @status.setter def status(self, status): """ Sets the register device status. Args: status (:class:`.ZigbeeRegisterStatus`): the new register device status. .. seealso:: | :class:`.ZigbeeRegisterStatus` """ self.__status = status
[docs]class RouteRecordIndicatorPacket(XBeeAPIPacket): """ This class represents a Zigbee Route Record Indicator packet. Packet is built using the parameters of the constructor or providing a valid API payload. The route record indicator is received whenever a device sends a Zigbee route record command. This is used with many-to-one routing to create source routes for devices in a network. Among received data, some options can also be received indicating transmission parameters. .. seealso:: | :class:`.ReceiveOptions` | :class:`.XBeeAPIPacket` """ __MIN_PACKET_LENGTH = 17 def __init__(self, x64bit_addr, x16bit_addr, rx_opts, hops=None, op_mode=OperatingMode.API_MODE): """ Class constructor. Instantiates a new :class:`.RouteRecordIndicatorPacket` object with the provided parameters. Args: x64bit_addr (:class:`.XBee64BitAddress`): The 64-bit source address. x16bit_addr (:class:`.XBee16BitAddress`): The 16-bit source address. rx_opts (Integer): Bitfield indicating the receive options. hops (List, optional, default=`None`): List of 16-bit address of intermediate hops in the source route (excluding source and destination). op_mode (:class:`.OperatingMode`, optional, default=`OperatingMode.API_MODE`): The mode in which the frame was captured. .. seealso:: | :class:`.ReceiveOptions` | :class:`.XBee16BitAddress` | :class:`.XBee64BitAddress` | :class:`.XBeeAPIPacket` """ super().__init__(ApiFrameType.ROUTE_RECORD_INDICATOR, op_mode=op_mode) self.__x64_addr = x64bit_addr self.__x16_addr = x16bit_addr self.__rx_opts = rx_opts self.__hops = hops if hops else []
[docs] @staticmethod def create_packet(raw, operating_mode): """ Override method. Returns: :class:`.RouteRecordIndicatorPacket`. Raises: InvalidPacketException: If the bytearray length is less than 17. (start delim. + length (2 bytes) + frame type + 64bit addr. + 16bit addr. + Receive options + num of addrs + checksum = 17 bytes). InvalidPacketException: If the length field of `raw` is different from its real length. (length field: bytes 1 and 3) InvalidPacketException: If the first byte of 'raw' is not the header byte. See :class:`.SpecialByte`. InvalidPacketException: If the calculated checksum is different from the checksum field value (last byte). InvalidPacketException: If the frame type is not :attr:`.ApiFrameType.ROUTE_RECORD_INDICATOR`. InvalidPacketException: If the number of hops does not match with the number of 16-bit addresses. InvalidOperatingModeException: If `operating_mode` is not supported. .. seealso:: | :meth:`.XBeePacket.create_packet` | :meth:`.XBeeAPIPacket._check_api_packet` """ if operating_mode not in (OperatingMode.ESCAPED_API_MODE, OperatingMode.API_MODE): raise InvalidOperatingModeException( operating_mode.name + " is not supported.") XBeeAPIPacket._check_api_packet( raw, min_length=RouteRecordIndicatorPacket.__MIN_PACKET_LENGTH) if raw[3] != ApiFrameType.ROUTE_RECORD_INDICATOR.code: raise InvalidPacketException( "This packet is not a Route Record Indicator packet.") hops = [XBee16BitAddress(raw[i:i+2]) for i in range(16, len(raw) - 1, 2)] if raw[15] != len(hops): raise InvalidPacketException("Specified number of hops does not" "match with the length of addresses.") return RouteRecordIndicatorPacket( XBee64BitAddress(raw[4:12]), XBee16BitAddress(raw[12:14]), raw[14], hops, op_mode=operating_mode)
[docs] def needs_id(self): """ Override method. .. seealso:: | :meth:`.XBeeAPIPacket.needs_id` """ return False
[docs] def is_broadcast(self): """ Override method. .. seealso:: | :meth:`XBeeAPIPacket.is_broadcast` """ return utils.is_bit_enabled(self.__rx_opts, 1)
def _get_api_packet_spec_data(self): """ Override method. .. seealso:: | :meth:`.XBeeAPIPacket._get_api_packet_spec_data` """ ret = self.__x64_addr.address ret += self.__x16_addr.address ret.append(self.__rx_opts) ret.append(len(self.__hops)) for hop in self.__hops: ret += hop.address return ret def _get_api_packet_spec_data_dict(self): """ Override method. .. seealso:: | :meth:`.XBeeAPIPacket._get_api_packet_spec_data_dict` """ hops_array = [hop.address for hop in self.__hops] return {DictKeys.X64BIT_ADDR: self.__x64_addr.address, DictKeys.X16BIT_ADDR: self.__x16_addr.address, DictKeys.RECEIVE_OPTIONS: self.__rx_opts, DictKeys.NUM_OF_HOPS: len(hops_array), DictKeys.HOPS: hops_array} @property def x64bit_source_addr(self): """ Returns the 64-bit source address. Returns: :class:`.XBee64BitAddress`: The 64-bit source address. .. seealso:: | :class:`.XBee64BitAddress` """ return self.__x64_addr @x64bit_source_addr.setter def x64bit_source_addr(self, x64bit_addr): """ Sets the 64-bit source address. Args: x64bit_addr (:class:`.XBee64BitAddress`): The new 64-bit source address. .. seealso:: | :class:`.XBee64BitAddress` """ self.__x64_addr = x64bit_addr @property def x16bit_source_addr(self): """ Returns the 16-bit source address. Returns: :class:`.XBee16BitAddress`: The 16-bit source address. .. seealso:: | :class:`.XBee16BitAddress` """ return self.__x16_addr @x16bit_source_addr.setter def x16bit_source_addr(self, x16bit_addr): """ Sets the 16-bit source address. Args: x16bit_addr (:class:`.XBee16BitAddress`): The new 16-bit source address. .. seealso:: | :class:`.XBee16BitAddress` """ self.__x16_addr = x16bit_addr @property def receive_options(self): """ Returns the receive options bitfield. Returns: Integer: The receive options bitfield. .. seealso:: | :class:`.ReceiveOptions` """ return self.__rx_opts @receive_options.setter def receive_options(self, receive_options): """ Sets the receive options bitfield. Args: receive_options (Integer): The new receive options bitfield. .. seealso:: | :class:`.ReceiveOptions` """ self.__rx_opts = receive_options @property def number_of_hops(self): """ Returns the number of intermediate hops in the source route (excluding source and destination). Returns: Integer: The number of addresses. """ return len(self.__hops) @property def hops(self): """ Returns the list of intermediate hops starting from the closest to destination hop and finishing with the closest to the source (excluding source and destination). Returns: List: The list of 16-bit addresses of intermediate hops. .. seealso:: | :class:`.XBee16BitAddress` """ return self.__hops @hops.setter def hops(self, hops): """ Sets the hops of the route (excluding source and destination). Args: hops (List): List of `XBee16BitAddress`. .. seealso:: | :class:`.XBee16BitAddress` """ self.__hops = hops if hops else []
[docs]class CreateSourceRoutePacket(XBeeAPIPacket): """ This class represents a Zigbee Create Source Route packet. This packet is built using the parameters of the constructor or providing a valid API payload. This frame creates a source route in the node. A source route specifies the complete route a packet should travese to get from source to destination. Source routing should be used with many-to-one routing for best results. Note: Both, 64-bit and 16-bit destination addresses are required when creating a source route. These are obtained when a Route Record Indicator (0xA1) frame is received. .. seealso:: | :class:`.RouteRecordIndicatorPacket` | :class:`.XBeeAPIPacket` """ __MIN_PACKET_LENGTH = 18 def __init__(self, frame_id, x64bit_addr, x16bit_addr, route_options=0, hops=None, op_mode=OperatingMode.API_MODE): """ Class constructor. Instantiates a new :class:`.CreateSourceRoutePacket` object with the provided parameters. Args: frame_id (integer): the frame ID of the packet. x64bit_addr (:class:`.XBee64BitAddress`): The 64-bit destination address. x16bit_addr (:class:`.XBee16BitAddress`): The 16-bit destination address. route_options (Integer): Route command options. hops (List, optional, default=`None`): List of 16-bit addresses of intermediate hops in the source route (excluding source and destination). op_mode (:class:`.OperatingMode`, optional, default=`OperatingMode.API_MODE`): The mode in which the frame was captured. .. seealso:: | :class:`.XBee16BitAddress` | :class:`.XBee64BitAddress` | :class:`.XBeeAPIPacket` """ if frame_id < 0 or frame_id > 255: raise ValueError("Frame id must be between 0 and 255.") super().__init__(ApiFrameType.CREATE_SOURCE_ROUTE, op_mode=op_mode) self._frame_id = frame_id self.__x64_addr = x64bit_addr self.__x16_addr = x16bit_addr self.__route_opts = route_options self.__hops = hops if hops else []
[docs] @staticmethod def create_packet(raw, operating_mode): """ Override method. Returns: :class:`.CreateSourceRoutePacket`. Raises: InvalidPacketException: If the bytearray length is less than 18. (start delim. + length (2 bytes) + frame type + frame id + 64-bit addr. + 16-bit addr. + Route command options + num of addrs + hops 16-bit addrs + checksum = 18 bytes). InvalidPacketException: If the length field of `raw` is different from its real length. (length field: bytes 1 and 3) InvalidPacketException: If the first byte of 'raw' is not the header byte. See :class:`.SpecialByte`. InvalidPacketException: If the calculated checksum is different from the checksum field value (last byte). InvalidPacketException: If the frame type is not :attr:`.ApiFrameType.CREATE_SOURCE_ROUTE`. InvalidPacketException: If the number of hops does not match with the number of 16-bit addresses. InvalidOperatingModeException: If `operating_mode` is not supported. .. seealso:: | :meth:`.XBeePacket.create_packet` | :meth:`.XBeeAPIPacket._check_api_packet` """ if operating_mode not in (OperatingMode.ESCAPED_API_MODE, OperatingMode.API_MODE): raise InvalidOperatingModeException( operating_mode.name + " is not supported.") XBeeAPIPacket._check_api_packet( raw, min_length=CreateSourceRoutePacket.__MIN_PACKET_LENGTH) if raw[3] != ApiFrameType.CREATE_SOURCE_ROUTE.code: raise InvalidPacketException( "This packet is not a Create Source Route packet.") hops = [XBee16BitAddress(raw[i:i+2]) for i in range(17, len(raw) - 1, 2)] if raw[16] != len(hops): raise InvalidPacketException("Specified number of hops does not" "match with the length of addresses.") return CreateSourceRoutePacket( raw[4], XBee64BitAddress(raw[5:13]), XBee16BitAddress(raw[13:15]), raw[15], hops, op_mode=operating_mode)
[docs] def needs_id(self): """ Override method. .. seealso:: | :meth:`.XBeeAPIPacket.needs_id` """ return True
def _get_api_packet_spec_data(self): """ Override method. .. seealso:: | :meth:`.XBeeAPIPacket._get_api_packet_spec_data` """ ret = self.__x64_addr.address ret += self.__x16_addr.address ret.append(self.__route_opts) ret.append(len(self.__hops)) for hop in self.__hops: ret += hop.address return ret def _get_api_packet_spec_data_dict(self): """ Override method. .. seealso:: | :meth:`.XBeeAPIPacket._get_api_packet_spec_data_dict` """ hops_array = [hop.address for hop in self.__hops] return {DictKeys.X64BIT_ADDR: self.__x64_addr.address, DictKeys.X16BIT_ADDR: self.__x16_addr.address, DictKeys.ROUTE_CMD_OPTIONS: self.__route_opts, DictKeys.NUM_OF_HOPS: len(hops_array), DictKeys.HOPS: hops_array} @property def x64bit_dest_addr(self): """ Returns the 64-bit destination address. Returns: :class:`.XBee64BitAddress`: The 64-bit destination address. .. seealso:: | :class:`.XBee64BitAddress` """ return self.__x64_addr @x64bit_dest_addr.setter def x64bit_dest_addr(self, x64bit_addr): """ Sets the 64-bit destination address. Args: x64bit_addr (:class:`.XBee64BitAddress`): The new 64-bit destination address. .. seealso:: | :class:`.XBee64BitAddress` """ self.__x64_addr = x64bit_addr @property def x16bit_dest_addr(self): """ Returns the 16-bit destination address. Returns: :class:`.XBee16BitAddress`: The 16-bit destination address. .. seealso:: | :class:`.XBee16BitAddress` """ return self.__x16_addr @x16bit_dest_addr.setter def x16bit_dest_addr(self, x16bit_addr): """ Sets the 16-bit destination address. Args: x16bit_addr (:class:`.XBee16BitAddress`): The new 16-bit destination address. .. seealso:: | :class:`.XBee16BitAddress` """ self.__x16_addr = x16bit_addr @property def route_cmd_options(self): """ Returns the route command options bitfield. Returns: Integer: The route command options bitfield. """ return self.__route_opts @route_cmd_options.setter def route_cmd_options(self, route_options): """ Sets the route command options bitfield. Args: route_options (Integer): The new route command options bitfield. """ self.__route_opts = route_options @property def number_of_hops(self): """ Returns the number of intermediate hops in the source route (excluding source and destination). Returns: Integer: The number of intermediate hops. """ return len(self.__hops) @property def hops(self): """ Returns the list of intermediate hops starting from the closest to destination hop and finishing with the closest to the source (excluding source and destination). Returns: List: The list of 16-bit addresses of intermediate hops. .. seealso:: | :class:`.XBee16BitAddress` """ return self.__hops @hops.setter def hops(self, hops): """ Sets the hops of the route (excluding source and destination). Args: hops (List): List of `XBee16BitAddress`. .. seealso:: | :class:`.XBee16BitAddress` """ self.__hops = hops if hops else []
[docs]class OTAFirmwareUpdateStatusPacket(XBeeAPIPacket): """ This class represents a an Over The Air Firmware Update Status packet. Packet is built using the parameters of the constructor or providing a valid API payload. This frame provides a status indication of a firmware update transmission. If a query request returns a 0x15 (NACK) status, the target is likely waiting for a firmware update image. If no messages are sent to it for about 75 seconds, the target will timeout and accept new query messages. If a query status returns a 0x51 (QUERY) status, then the target's bootloader is not active and will not respond to query messages. .. seealso:: | :class:`.EmberBootloaderMessageType` | :class:`.XBeeAPIPacket` """ __MIN_PACKET_LENGTH = 26 def __init__(self, src_address_64, updater_address_16, rx_options, msg_type, block_number, target_address_64, op_mode=OperatingMode.API_MODE): """ Class constructor. Instantiates a new :class:`.OTAFirmwareUpdateStatusPacket` object with the provided parameters. Args: src_address_64 (:class:`.XBee64BitAddress`): the 64-bit address of the device returning this answer. updater_address_16 (:class:`.XBee16BitAddress`): the 16-bit address of the updater device. rx_options (Integer): bitfield indicating the receive options. msg_type (:class:`.EmberBootloaderMessageType`): Ember bootloader message type block_number (Integer): block number used in the update request. target_address_64 (:class:`.XBee64BitAddress`): the 64-bit address of the device that is being updated. op_mode (:class:`.OperatingMode`, optional, default=`OperatingMode.API_MODE`): The mode in which the frame was captured. .. seealso:: | :class:`.XBeeAPIPacket` | :class:`.XBee16BitAddress` | :class:`.XBee64BitAddress` | :class:`.ReceiveOptions` | :class:`.EmberBootloaderMessageType` """ super().__init__(ApiFrameType.OTA_FIRMWARE_UPDATE_STATUS, op_mode=op_mode) self.__src_x64bit_addr = src_address_64 self.__updater_x16bit_addr = updater_address_16 self.__rx_opts = rx_options self.__msg_type = msg_type self.__block_number = block_number self.__target_x64bit_addr = target_address_64
[docs] @staticmethod def create_packet(raw, operating_mode): """ Override method. Returns: :class:`.OTAFirmwareUpdateStatusPacket`. Raises: InvalidPacketException: if the bytearray length is less than 17. (start delim. + length (2 bytes) + frame type + source 64bit addr. (8 bytes) + updater 16bit addr. (2 bytes) + receive options + bootloader message type + block number + source 64bit addr. (8 bytes) + checksum = 27 bytes). InvalidPacketException: if the length field of 'raw' is different from its real length. (length field: bytes 1 and 3) InvalidPacketException: if the first byte of 'raw' is not the header byte. See :class:`.SpecialByte`. InvalidPacketException: if the calculated checksum is different from the checksum field value (last byte). InvalidPacketException: if the frame type is not :attr:`.ApiFrameType.OTA_FIRMWARE_UPDATE_STATUS`. InvalidOperatingModeException: if `operating_mode` is not supported. .. seealso:: | :meth:`.XBeePacket.create_packet` | :meth:`.XBeeAPIPacket._check_api_packet` """ if operating_mode not in (OperatingMode.ESCAPED_API_MODE, OperatingMode.API_MODE): raise InvalidOperatingModeException( operating_mode.name + " is not supported.") XBeeAPIPacket._check_api_packet( raw, min_length=OTAFirmwareUpdateStatusPacket.__MIN_PACKET_LENGTH) if raw[3] != ApiFrameType.OTA_FIRMWARE_UPDATE_STATUS.code: raise InvalidPacketException( "This packet is not an OTA Firmware Update Status packet.") return OTAFirmwareUpdateStatusPacket( XBee64BitAddress(raw[4:12]), XBee16BitAddress(raw[12:14]), raw[14], EmberBootloaderMessageType.get(raw[15]), raw[16], XBee64BitAddress(raw[17:25]), op_mode=operating_mode)
[docs] def needs_id(self): """ Override method. .. seealso:: | :meth:`.XBeeAPIPacket.needs_id` """ return False
def _get_api_packet_spec_data(self): """ Override method. .. seealso:: | :meth:`.XBeeAPIPacket._get_api_packet_spec_data` """ raw = self.__src_x64bit_addr.address raw += self.__updater_x16bit_addr.address raw.append(self.__rx_opts & 0xFF) raw.append(self.__msg_type.code & 0xFF) raw.append(self.__block_number & 0xFF) raw += self.__target_x64bit_addr.address return raw def _get_api_packet_spec_data_dict(self): """ Override method. .. seealso:: | :meth:`.XBeeAPIPacket._get_api_packet_spec_data_dict` """ return {DictKeys.SRC_64BIT_ADDR: self.__src_x64bit_addr.address, DictKeys.UPDATER_16BIT_ADDR: self.__updater_x16bit_addr.address, DictKeys.RECEIVE_OPTIONS: self.__rx_opts, DictKeys.BOOTLOADER_MSG_TYPE: self.__msg_type, DictKeys.BLOCK_NUMBER: self.__block_number, DictKeys.TARGET_64BIT_ADDR: self.__target_x64bit_addr.address} @property def x64bit_source_addr(self): """ Returns the 64-bit source address. Returns: :class:`.XBee64BitAddress`: the 64-bit source address. .. seealso:: | :class:`.XBee64BitAddress` """ return self.__src_x64bit_addr @x64bit_source_addr.setter def x64bit_source_addr(self, x64bit_source_addr): """ Sets the 64-bit source address. Args: x64bit_source_addr (:class:`.XBee64BitAddress`): the new 64-bit source address. .. seealso:: | :class:`.XBee64BitAddress` """ self.__src_x64bit_addr = x64bit_source_addr @property def x16bit_updater_addr(self): """ Returns the 16-bit updater address. Returns: :class:`.XBee16BitAddress`: the 16-bit updater address. .. seealso:: | :class:`.XBee16BitAddress` """ return self.__updater_x16bit_addr @x16bit_updater_addr.setter def x16bit_updater_addr(self, x16bit_updater_addr): """ Sets the 16-bit updater address. Args: x16bit_updater_addr (:class:`.XBee16BitAddress`): the new 16-bit updater address. .. seealso:: | :class:`.XBee16BitAddress` """ self.__updater_x16bit_addr = x16bit_updater_addr @property def receive_options(self): """ Returns the receive options bitfield. Returns: Integer: the receive options bitfield. .. seealso:: | :class:`.ReceiveOptions` """ return self.__rx_opts @receive_options.setter def receive_options(self, receive_options): """ Sets the receive options bitfield. Args: receive_options (Integer): the new receive options bitfield. .. seealso:: | :class:`.ReceiveOptions` """ self.__rx_opts = receive_options @property def bootloader_msg_type(self): """ Returns the bootloader message type. Returns: :class:`.EmberBootloaderMessageType`: the bootloader message type. .. seealso:: | :class:`.EmberBootloaderMessageType` """ return self.__msg_type @bootloader_msg_type.setter def bootloader_msg_type(self, bootloader_message_type): """ Sets the receive options bitfield. Args: bootloader_message_type (:class:`.EmberBootloaderMessageType`): the new bootloader message type. .. seealso:: | :class:`.EmberBootloaderMessageType` """ self.__msg_type = bootloader_message_type @property def block_number(self): """ Returns the block number of the request. Returns: Integer: the block number of the request. """ return self.__block_number @block_number.setter def block_number(self, block_number): """ Sets the block number. Args: block_number (Integer): the new block number. """ self.__block_number = block_number @property def x64bit_target_addr(self): """ Returns the 64-bit target address. Returns: :class:`.XBee64BitAddress`: the 64-bit target address. .. seealso:: | :class:`.XBee64BitAddress` """ return self.__target_x64bit_addr @x64bit_target_addr.setter def x64bit_target_addr(self, x64bit_target_addr): """ Sets the 64-bit source address. Args: x64bit_target_addr (:class:`.XBee64BitAddress`): the new 64-bit target address. .. seealso:: | :class:`.XBee64BitAddress` """ self.__target_x64bit_addr = x64bit_target_addr