doc: add documentation about sending and receiving User Data Relay messages

Signed-off-by: Diego Escalona <diego.escalona@digi.com>

Author: diescalo

doc/api/digi.xbee.packets.relay.rst

@@ -0,0 +1,7 @@
+digi\.xbee\.packets\.relay module
+===================================
+
+.. automodule:: digi.xbee.packets.relay
+    :members:
+    :inherited-members:
+    :show-inheritance:

doc/examples.rst

@@ -276,6 +276,19 @@ You can find the example at the following path:
    :ref:`communicateSendIPData`.
 
 
+Send User Data Relay
+````````````````````
+
+This sample application shows how to send data to other XBee interface.
+
+You can find the example at the following path:
+**examples/communication/relay/SendUserDataRelaySample**
+
+.. note::
+   For more information about sending User Data Relay messages, see
+   :ref:`communicateSendRelayData`.
+
+
 Receive data
 ````````````
 
@@ -370,6 +383,19 @@ You can find the example at the following path:
    :ref:`communicateReceiveSMS`.
 
 
+Receive User Data Relay messages
+````````````````````````````````
+
+This sample application shows how to receive data from other XBee interface.
+
+You can find the example at the following path:
+**examples/communication/relay/ReceiveUserDataRelaySample**
+
+.. note::
+   For more information about receiving User Data Relay messages, see
+   :ref:`communicateReceiveRelayData`.
+
+
 Receive modem status
 ````````````````````
 

doc/index.rst

@@ -26,6 +26,8 @@ Python Library includes the following features:
 * Ability to transmit and receive data from any XBee device on the network.
 * Ability to manage the General Purpose Input and Output lines of all your XBee
   devices.
+* Ability to send and receive data from other XBee interfaces (Serial,
+  Bluetooth Low Energy and MicroPython).
 
 This portal provides the following documentation to help you with the different
 development stages of your Python applications using the XBee Python Library.

doc/user_doc/communicating_with_xbee_devices.rst

@@ -2,8 +2,9 @@ Communicate with XBee devices
 =============================
 
 The XBee Python Library provides the ability to communicate with remote nodes in
-the network. The communication between XBee devices in a network involves the
-transmission and reception of data.
+the network, IoT devices and other interfaces of the local device. The
+communication between XBee devices in a network involves the transmission and
+reception of data.
 
 .. warning::
   Communication features described in this topic and sub-topics are only
@@ -745,6 +746,66 @@ The ``send_sms_async`` method may fail for the following reasons:
       generic ``XBeeException``.
 
 
+.. _communicateSendRelayData:
+
+Send data to other interfaces
+-----------------------------
+
+XBee3 modules have the ability to send and receive data to/from other XBee
+interfaces through User Data Relay frames. The supported interfaces are: Serial
+port (SPI, or UART when in API mode), Bluetooth Low Energy and MicroPython.
+This can be useful if your application wants to transmit data to a MicroPython
+program running on the module or a cellphone connected to it over BLE.
+
+The ``XBeeDevice`` class and its subclasses provide the following method to
+send data to any XBee interface:
+
++-------------------------------------------------------------+-----------------------------------------------------------------+
+| Method                                                      | Description                                                     |
++=============================================================+=================================================================+
+| **send_user_data_relay(UserDataRelayInterface, Bytearray)** | Specifies the destination relay interface and the data to send. |
++-------------------------------------------------------------+-----------------------------------------------------------------+
+
+This method is asynchronous, which means that your application does not block during the transmit process.
+
+**Send user data relay message**
+
+.. code:: python
+
+  [...]
+
+  # Instantiate an XBee device object.
+  device = XBeeDevice("COM1", 9600)
+  device.open()
+
+  destInterface = UserDataRelayInterface.MICROPYTHON
+  message = "MicroPython, are you there?"
+
+  # Send the message to the MicroPython interface.
+  device.send_user_data_relay(destInterface, message.encode("utf8"))
+
+  [...]
+
+The ``send_user_data_relay`` method may fail for the following reasons:
+
+* If the relay interface or data is ``None``, the method throws a
+  ``ValueError``.
+* Errors register as ``XBeeException``:
+    * If the operating mode of the device is not ``API`` or
+      ``ESCAPED_API_MODE``, the method throws an
+      ``InvalidOperatingModeException``.
+    * If there is an error writing to the XBee interface, the method throws a
+      generic ``XBeeException``.
+
++------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Example: Send User Data Relay                                                                                                                                    |
++==================================================================================================================================================================+
+| The XBee Python Library includes a sample application that demonstrates how to send a User Data Relay message. You can locate the example in the following path: |
+|                                                                                                                                                                  |
+| **examples/communication/relay/SendUserDataRelaySample**                                                                                                                |
++------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+
+
 Receive data
 ------------
 
@@ -1504,6 +1565,73 @@ unsubscribe the already-registered listener.
 +------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 
 
+.. _communicateReceiveRelayData:
+
+Receive data from other interfaces
+----------------------------------
+
+You can be notified when a new User Data Relay message has been received if you
+are subscribed or registered to the User Data Relay reception service by using
+the ``add_user_data_relay_received_callback`` method.
+
+**User Data Relay reception registration**
+
+.. code:: python
+
+  [...]
+
+  # Instantiate an XBee device object.
+  device = XBeeDevice("COM1", 9600)
+  device.open()
+
+  # Define the callback.
+  def my_data_relay_callback(relay_message):
+      print("Relay data received from %s >> '%s'" %
+                  (relay_message.relay_interface.description,
+                   relay_message.data.decode("utf-8")))
+
+  # Add the callback.
+  device.add_user_data_relay_received_callback(my_data_relay_callback)
+
+  [...]
+
+When a new User Data Relay message is received, your callback is executed
+providing a ``UserDataRelayMessage`` object as parameter. This object contains
+the source interface that sent the data and the data itself.
+
+To stop listening to new User Data Relay messages, use the
+``del_user_data_relay_received_callback`` method to unsubscribe the
+already-registered listener.
+
+**Deregister User Data Relay reception**
+
+.. code:: python
+
+  [...]
+
+  device = [...]
+
+  def my_data_relay_callback(relay_message):
+      [...]
+
+  device.add_user_data_relay_received_callback(my_data_relay_callback)
+
+  [...]
+
+  # Delete the User Data Relay callback.
+  device.del_user_data_relay_received_callback(my_data_relay_callback)
+
+  [...]
+
++----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Example: Receive User Data Relay messages                                                                                                                                                                                                    |
++==============================================================================================================================================================================================================================================+
+| The XBee Python Library includes a sample application that demonstrates how to subscribe to the User Data Relay reception service in order to receive messages from other XBee interfaces. You can locate the example in the following path: |
+|                                                                                                                                                                                                                                              |
+| **examples/communication/relay/ReceiveUserDataRelaySample**                                                                                                                                                                                         |
++----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+
+
 .. _communicateReceiveModemStatus:
 
 Receive modem status events