examples: add new example to receive a file from the Bluetooth interface

This example is used in conjunction with the 'XBee BLE Microcontroller'
example of the Mobile SDK.

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

Author: rubenmoral

examples/communication/bluetooth/ReceiveBluetoothFileSample/ReceiveBluetoothFileSample.py

@@ -0,0 +1,89 @@
+# Copyright 2019, Digi International Inc.
+#
+# Permission to use, copy, modify, and/or distribute this software for any
+# purpose with or without fee is hereby granted, provided that the above
+# copyright notice and this permission notice appear in all copies.
+#
+# 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
+# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+from digi.xbee.devices import XBeeDevice
+from datetime import datetime
+
+# TODO: Replace with the serial port where your local module is connected to.
+PORT = "COM1"
+# TODO: Replace with the baud rate of your local module.
+BAUD_RATE = 9600
+
+SEPARATOR = "@@@"
+
+MSG_START = "START" + SEPARATOR
+MSG_END = "END"
+MSG_ACK = "OK"
+
+
+def main():
+    print(" +---------------------------------------------------+")
+    print(" | XBee Python Library Receive Bluetooth File Sample |")
+    print(" +---------------------------------------------------+\n")
+
+    file = None
+
+    device = XBeeDevice(PORT, BAUD_RATE)
+
+    try:
+        device.open()
+
+        def bluetooth_data_callback(data):
+            global file
+
+            # Check if the data is 'START' or 'END'.
+            if data.startswith(bytearray(MSG_START, 'utf-8')):
+                # Get the file name.
+                file_name = data.decode('utf-8').split(SEPARATOR)[1]
+                # Open the file for writing.
+                file = open(file_name, "w+b")
+                print(">> START message received, saving data to file...")
+                send_ack(device)
+            elif data == bytearray(MSG_END, 'utf-8'):
+                file.close()
+                print(">> END message received, file '%s'\n" % file.name)
+                send_ack(device)
+            elif file is not None:
+                payload = data[:-1]
+                checksum = data[-1]
+                # Validate the checksum.
+                if 0xFF - (sum(payload) & 0xFF) == checksum:
+                    # Write block to file.
+                    file.write(payload)
+                    send_ack(device)
+
+        device.add_bluetooth_data_received_callback(bluetooth_data_callback)
+
+        print("Waiting for data from the Bluetooth interface...\n")
+        input()
+
+    finally:
+        if file is not None and file.closed:
+            file.close()
+        if device is not None and device.is_open():
+            device.close()
+
+
+def send_ack(device):
+    """
+    Sends the ACK message to the given XBee device.
+
+    Args:
+        device: XBee device to send the message to.
+    """
+    device.send_bluetooth_data(MSG_ACK.encode("utf-8"))
+
+
+if __name__ == '__main__':
+    main()

examples/communication/bluetooth/ReceiveBluetoothFileSample/readme.txt

@@ -0,0 +1,66 @@
+  Introduction
+  ------------
+  This sample Python application shows how to receive and process data coming
+  from the Bluetooth interface of the XBee device.
+
+  The application registers a callback to be notified when new data coming from
+  Bluetooth is received and and stores it in a file.
+
+  NOTE: This example uses the generic XBee device (XBeeDevice) class, but it
+        can be applied to any other local XBee device class.
+
+
+  Requirements
+  ------------
+  To run this example you will need:
+
+    * One XBee3 module in API mode and its corresponding carrier board (XBIB
+      or equivalent).
+    * The XCTU application (available at www.digi.com/xctu).
+    * An Android or iOS device with the 'XBee BLE Microcontroller' sample
+      installed.
+
+
+  Compatible protocols
+  --------------------
+    * 802.15.4
+    * Cellular
+    * DigiMesh
+    * Zigbee
+
+
+  Example setup
+  -------------
+    1) Plug the XBee radio into the XBee adapter and connect it to your
+       computer's USB or serial port.
+
+    2) Ensure that the module is in API mode.
+       For further information on how to perform this task, read the
+       'Configuring Your XBee Modules' topic of the Getting Started guide.
+
+    3) Enable the Bluetooth interface of the XBee device and configure the
+       Bluetooth authentication using XCTU.
+       For further information on how to perform this task, refer to the
+       XCTU user manual.
+
+    4) Set the port and baud rate of the XBee radio in the sample file.
+       If you configured the module in the previous step with XCTU, you will
+       see the port number and baud rate in the 'Port' label of the device
+       on the left view.
+
+
+  Running the example
+  -------------------
+  First, build and launch the application. Then, launch the 'XBee BLE
+  Microcontroller' sample of the Digi Mobile SDK and follow the instructions
+  explained in that sample's README file.
+
+  When you load and send a file in your mobile device, the sample prints out
+  the following messages in the console at the beginning and at the end of the
+  process:
+
+    >> START message received, saving data to file...
+    >> END message received, file 'received_file_20190627120254.txt'
+
+  Verify that the received file is created successfully and is the same as the
+  one you sent with the mobile application.