relay_frames: add wrappers to send and receive data between XBee local

interfaces

- The new methods allow sending data and registering a listener to receive
  data from the Bluetooth and MicroPython interface.
- The UserDataRelayInterface class has been renamed to XBeeLocalInterface.
- Updated also the documentation.

Signed-off-by: Ruben Moral <ruben.moral@digi.com>

Author: rubenmoral

digi/xbee/devices.py

@@ -28,7 +28,7 @@
 from digi.xbee.models.mode import OperatingMode, APIOutputMode, IPAddressingMode
 from digi.xbee.models.address import XBee64BitAddress, XBee16BitAddress, XBeeIMEIAddress
 from digi.xbee.models.message import XBeeMessage, ExplicitXBeeMessage, IPMessage
-from digi.xbee.models.options import TransmitOptions, RemoteATCmdOptions, DiscoveryOptions
+from digi.xbee.models.options import TransmitOptions, RemoteATCmdOptions, DiscoveryOptions, XBeeLocalInterface
 from digi.xbee.models.protocol import XBeeProtocol, IPProtocol
 from digi.xbee.models.status import ATCommandStatus, TransmitStatus, PowerLevel, \
     ModemStatus, CellularAssociationIndicationStatus, WiFiAssociationIndicationStatus, AssociationIndicationStatus,\
@@ -1295,6 +1295,28 @@ def _add_user_data_relay_received_callback(self, callback):
         """
         self._packet_listener.add_user_data_relay_received_callback(callback)
 
+    def _add_bluetooth_data_received_callback(self, callback):
+        """
+        Adds a callback for the event :class:`.BluetoothDataReceived`.
+
+        Args:
+            callback (Function): the callback. Receives one argument.
+
+                * The Bluetooth data as a Bytearray
+        """
+        self._packet_listener.add_bluetooth_data_received_callback(callback)
+
+    def _add_micropython_data_received_callback(self, callback):
+        """
+        Adds a callback for the event :class:`.MicroPythonDataReceived`.
+
+        Args:
+            callback (Function): the callback. Receives one argument.
+
+                * The MicroPython data as a Bytearray
+        """
+        self._packet_listener.add_micropython_data_received_callback(callback)
+
     def _del_packet_received_callback(self, callback):
         """
         Deletes a callback for the callback list of :class:`.PacketReceived` event.
@@ -1367,6 +1389,30 @@ def _del_user_data_relay_received_callback(self, callback):
         """
         self._packet_listener.del_user_data_relay_received_callback(callback)
 
+    def _del_bluetooth_data_received_callback(self, callback):
+        """
+        Deletes a callback for the callback list of :class:`.BluetoothDataReceived` event.
+
+        Args:
+            callback (Function): the callback to delete.
+
+        Raises:
+            ValueError: if ``callback`` is not in the callback list of :class:`.BluetoothDataReceived` event.
+        """
+        self._packet_listener.del_bluetooth_data_received_callback(callback)
+
+    def _del_micropython_data_received_callback(self, callback):
+        """
+        Deletes a callback for the callback list of :class:`.MicroPythonDataReceived` event.
+
+        Args:
+            callback (Function): the callback to delete.
+
+        Raises:
+            ValueError: if ``callback`` is not in the callback list of :class:`.MicroPythonDataReceived` event.
+        """
+        self._packet_listener.del_micropython_data_received_callback(callback)
+
     def _send_packet_sync_and_get_response(self, packet_to_send):
         """
         Perform all operations needed for a synchronous operation when the packet
@@ -2161,25 +2207,65 @@ def send_data_broadcast(self, data, transmit_options=TransmitOptions.NONE.value)
         """
         return self._send_data_64(XBee64BitAddress.BROADCAST_ADDRESS, data, transmit_options)
 
-    def send_user_data_relay(self, relay_interface, data):
+    @AbstractXBeeDevice._before_send_method
+    def send_user_data_relay(self, local_interface, data):
         """
-        Sends the given data to the given relay interface.
+        Sends the given data to the given XBee local interface.
 
         Args:
-            relay_interface (:class:`.UserDataRelayInterface`): Destination relay interface.
+            local_interface (:class:`.XBeeLocalInterface`): Destination XBee local interface.
             data (Bytearray): Data to send.
 
         Raises:
-            ValueError: if ``relay_interface`` is ``None``.
+            InvalidOperatingModeException: if the XBee device'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.
 
         .. seealso::
-           | :class:`.UserDataRelayInterface`
+           | :class:`.XBeeLocalInterface`
         """
-        if relay_interface is None:
-            raise ValueError("Relay interface cannot be None")
+        if local_interface is None:
+            raise ValueError("Destination interface cannot be None")
 
         # Send the packet asynchronously since User Data Relay frames do not receive any transmit status.
-        self.send_packet(UserDataRelayPacket(self.get_next_frame_id(), relay_interface, data))
+        self.send_packet(UserDataRelayPacket(self.get_next_frame_id(), local_interface, data))
+
+    def send_bluetooth_data(self, data):
+        """
+        Sends the given data to the Bluetooth interface using a User Data Relay frame.
+
+        Args:
+            data (Bytearray): Data to send.
+
+        Raises:
+            InvalidOperatingModeException: if the XBee device'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.
+
+        .. seealso::
+           | :meth:`.XBeeDevice.send_micropython_data`
+           | :meth:`.XBeeDevice.send_user_data_relay`
+        """
+        self.send_user_data_relay(XBeeLocalInterface.BLUETOOTH, data)
+
+    def send_micropython_data(self, data):
+        """
+        Sends the given data to the MicroPython interface using a User Data Relay frame.
+
+        Args:
+            data (Bytearray): Data to send.
+
+        Raises:
+            InvalidOperatingModeException: if the XBee device'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.
+
+        .. seealso::
+           | :meth:`.XBeeDevice.send_bluetooth_data`
+           | :meth:`.XBeeDevice.send_user_data_relay`
+        """
+        self.send_user_data_relay(XBeeLocalInterface.MICROPYTHON, data)
 
     def read_data(self, timeout=None):
         """
@@ -2338,6 +2424,18 @@ def add_user_data_relay_received_callback(self, callback):
         """
         super()._add_user_data_relay_received_callback(callback)
 
+    def add_bluetooth_data_received_callback(self, callback):
+        """
+        Override.
+        """
+        super()._add_bluetooth_data_received_callback(callback)
+
+    def add_micropython_data_received_callback(self, callback):
+        """
+        Override.
+        """
+        super()._add_micropython_data_received_callback(callback)
+
     def del_packet_received_callback(self, callback):
         """
         Override.
@@ -2374,6 +2472,18 @@ def _del_user_data_relay_received_callback(self, callback):
         """
         super()._del_user_data_relay_received_callback(callback)
 
+    def _del_bluetooth_data_received_callback(self, callback):
+        """
+        Override.
+        """
+        super()._del_bluetooth_data_received_callback(callback)
+
+    def _del_micropython_data_received_callback(self, callback):
+        """
+        Override.
+        """
+        super()._del_micropython_data_received_callback(callback)
+
     def get_xbee_device_callbacks(self):
         """
         Returns this XBee internal callbacks for process received packets.

digi/xbee/models/message.py

@@ -401,38 +401,38 @@ class UserDataRelayMessage(object):
     interface and the content (data) of the message.
 
     .. seealso::
-       | :class:`.UserDataRelayInterface`
+       | :class:`.XBeeLocalInterface`
     """
 
-    def __init__(self, relay_interface, data):
+    def __init__(self, local_interface, data):
         """
         Class constructor. Instantiates a new :class:`.UserDataRelayMessage` object with
         the provided parameters.
 
         Args:
-            relay_interface (:class:`.UserDataRelayInterface`): The source relay interface.
+            local_interface (:class:`.XBeeLocalInterface`): The source XBee local interface.
             data (Bytearray): Byte array containing the data of the message.
 
         Raises:
             ValueError: if ``relay_interface`` is ``None``.
 
         .. seealso::
-            | :class:`.UserDataRelayInterface`
+            | :class:`.XBeeLocalInterface`
         """
-        if relay_interface is None:
-            raise ValueError("Relay interface cannot be None")
+        if local_interface is None:
+            raise ValueError("XBee local interface cannot be None")
 
-        self.__relay_interface = relay_interface
+        self.__local_interface = local_interface
         self.__data = data
 
-    def __get_relay_interface(self):
+    def __get_src_interface(self):
         """
         Returns the source interface that sent the message.
 
         Returns:
-            :class:`.UserDataRelayInterface`: The source interface that sent the message.
+            :class:`.XBeeLocalInterface`: The source interface that sent the message.
         """
-        return self.__relay_interface
+        return self.__local_interface
 
     def __get_data(self):
         """
@@ -447,11 +447,11 @@ def to_dict(self):
         """
         Returns the message information as a dictionary.
         """
-        return {"Relay interface: ": self.__relay_interface,
-                "Data: ":            self.__data}
+        return {"XBee local interface: ": self.__local_interface,
+                "Data: ":                 self.__data}
 
-    relay_interface = property(__get_relay_interface)
-    """:class:`.UserDataRelayInterface`. Source interface that sent the message."""
+    local_interface = property(__get_src_interface)
+    """:class:`.XBeeLocalInterface`. Source interface that sent the message."""
 
     data = property(__get_data)
     """Bytearray. The data of the message."""

digi/xbee/models/options.py

@@ -406,14 +406,14 @@ def calculate_discovery_value(protocol, options):
 
 
 @unique
-class UserDataRelayInterface(Enum):
+class XBeeLocalInterface(Enum):
     """
     Enumerates the different interfaces for the :class:`.UserDataRelayPacket`
     and :class:`.UserDataRelayOutputPacket`.
 
     | Inherited properties:
-    |     **name** (String): the name (id) of the relay interface.
-    |     **value** (String): the value of the relay interface.
+    |     **name** (String): the name (id) of the XBee local interface.
+    |     **value** (String): the value of the XBee local interface.
     """
     SERIAL = (0, "Serial port (UART when in API mode, or SPI interface)")
     BLUETOOTH = (1, "BLE API interface (on XBee devices which support BLE)")
@@ -426,45 +426,45 @@ def __init__(self, code, description):
 
     def __get_code(self):
         """
-        Returns the code of the UserDataRelayInterface element.
+        Returns the code of the ``XBeeLocalInterface`` element.
 
         Returns:
-            Integer: the code of the UserDataRelayInterface element.
+            Integer: the code of the ``XBeeLocalInterface`` element.
         """
         return self.__code
 
     def __get_description(self):
         """
-        Returns the description of the UserDataRelayInterface element.
+        Returns the description of the ``XBeeLocalInterface`` element.
 
         Returns:
-            String: the description of the UserDataRelayInterface element.
+            String: the description of the ``XBeeLocalInterface`` element.
         """
         return self.__description
 
     @classmethod
     def get(cls, code):
         """
-        Returns the User Data Relay interface option for the given code.
+        Returns the XBee local interface option for the given code.
 
         Args:
-            code (Integer): the code of the User Data Relay interface to get.
+            code (Integer): the code of the XBee local interface to get.
 
         Returns:
-            :class:`.UserDataRelayInterface`: the UserDataRelayInterface with the given code,
-                ``UNKNOWN`` if there is not any UserDataRelayInterface with the provided code.
+            :class:`.XBeeLocalInterface`: the ``XBeeLocalInterface`` with the given code,
+                ``UNKNOWN`` if there is not any ``XBeeLocalInterface`` with the provided code.
         """
         try:
             return cls.lookupTable[code]
         except KeyError:
-            return UserDataRelayInterface.UNKNOWN
+            return XBeeLocalInterface.UNKNOWN
 
     code = property(__get_code)
-    """Integer. The User Data Relay interface code."""
+    """Integer. The XBee local interface code."""
 
     description = property(__get_description)
-    """String. The User Data Relay interface description."""
+    """String. The XBee local interface description."""
 
 
-UserDataRelayInterface.lookupTable = {x.code: x for x in UserDataRelayInterface}
-UserDataRelayInterface.__doc__ += utils.doc_enum(UserDataRelayInterface)
+XBeeLocalInterface.lookupTable = {x.code: x for x in XBeeLocalInterface}
+XBeeLocalInterface.__doc__ += utils.doc_enum(XBeeLocalInterface)