ble: add several methods related to the Bluetooth interface

- enable_bluetooth()
- disable_bluetooth()
- get_bluetooth_mac_addr()
- update_bluetooth_password(String)

Added also a new chapter in the documentation explaining these new methods.

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

Author: rubenmoral

digi/xbee/devices.py

@@ -21,6 +21,8 @@
 import serial
 from serial.serialutil import SerialTimeoutException
 
+import srp
+
 from digi.xbee.packets.cellular import TXSMSPacket
 from digi.xbee.models.accesspoint import AccessPoint, WiFiEncryptionType
 from digi.xbee.models.atcomm import ATCommandResponse, ATCommand
@@ -61,6 +63,11 @@ class AbstractXBeeDevice(object):
     The default timeout for all synchronous operations, in seconds.
     """
 
+    _BLE_API_USERNAME = "apiservice"
+    """
+    The Bluetooth Low Energy API username.
+    """
+
     LOG_PATTERN = "{port:<6s}{event:<12s}{opmode:<20s}{content:<50s}"
     """
     Pattern used to log packet events.
@@ -1079,6 +1086,112 @@ def set_api_output_mode(self, api_output_mode):
         """
         self.set_parameter("AO", bytearray([api_output_mode.code]))
 
+    def enable_bluetooth(self):
+        """
+        Enables the Bluetooth interface of this XBee device.
+
+        To work with this interface, you must also configure the Bluetooth password if not done previously.
+        You can use the :meth:`.AbstractXBeeDevice.update_bluetooth_password` method for that purpose.
+
+        Note that your device must have Bluetooth Low Energy support to use this method.
+
+        Raises:
+            TimeoutException: if the response is not received before the read timeout expires.
+            XBeeException: if the XBee device's serial port is closed.
+            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.
+        """
+        self._enable_bluetooth(True)
+
+    def disable_bluetooth(self):
+        """
+        Disables the Bluetooth interface of this XBee device.
+
+        Note that your device must have Bluetooth Low Energy support to use this method.
+
+        Raises:
+            TimeoutException: if the response is not received before the read timeout expires.
+            XBeeException: if the XBee device's serial port is closed.
+            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.
+        """
+        self._enable_bluetooth(False)
+
+    def _enable_bluetooth(self, enable):
+        """
+        Enables or disables the Bluetooth interface of this XBee device.
+
+        Args:
+            enable (Boolean): ``True`` to enable the Bluetooth interface, ``False`` to disable it.
+
+        Raises:
+            TimeoutException: if the response is not received before the read timeout expires.
+            XBeeException: if the XBee device's serial port is closed.
+            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.
+        """
+        self.set_parameter("BT", b'\x01' if enable else b'\x00')
+        self.write_changes()
+        self.apply_changes()
+
+    def get_bluetooth_mac_addr(self):
+        """
+        Reads and returns the EUI-48 Bluetooth MAC address of this XBee device in a format such as ``00112233AABB``.
+
+        Note that your device must have Bluetooth Low Energy support to use this method.
+
+        Returns:
+            String: The Bluetooth MAC address.
+
+        Raises:
+            TimeoutException: if the response is not received before the read timeout expires.
+            XBeeException: if the XBee device's serial port is closed.
+            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.
+        """
+        return utils.hex_to_string(self.get_parameter("BL"), False)
+
+    def update_bluetooth_password(self, new_password):
+        """
+        Changes the password of this Bluetooth device with the new one provided.
+
+        Note that your device must have Bluetooth Low Energy support to use this method.
+
+        Args:
+            new_password (String): New Bluetooth password.
+
+        Raises:
+            TimeoutException: if the response is not received before the read timeout expires.
+            XBeeException: if the XBee device's serial port is closed.
+            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.
+        """
+        # Generate the salt and verifier using the SRP library.
+        salt, verifier = srp.create_salted_verification_key(self._BLE_API_USERNAME, new_password,
+                                                            hash_alg=srp.SHA256, ng_type=srp.NG_1024, salt_len=4)
+
+        # Ensure the verifier is 128 bytes.
+        verifier = (128 - len(verifier)) * b'\x00' + verifier
+
+        # Set the salt.
+        self.set_parameter("$S", salt)
+
+        # Set the verifier (split in 4 settings)
+        index = 0
+        at_length = int(len(verifier) / 4)
+
+        self.set_parameter("$V", verifier[index:(index + at_length)])
+        index += at_length
+        self.set_parameter("$W", verifier[index:(index + at_length)])
+        index += at_length
+        self.set_parameter("$X", verifier[index:(index + at_length)])
+        index += at_length
+        self.set_parameter("$Y", verifier[index:(index + at_length)])
+
+        # Write and apply changes.
+        self.write_changes()
+        self.apply_changes()
+
     def _get_ai_status(self):
         """
         Returns the current association status of this XBee device.

digi/xbee/util/utils.py

@@ -238,18 +238,21 @@ def int_to_length(number):
     return length
 
 
-def hex_to_string(byte_array):
+def hex_to_string(byte_array, pretty=True):
     """
     Returns the provided bytearray in a pretty string format. All bytes are separated by blank spaces and
     printed in hex format.
 
     Args:
         byte_array (Bytearray): the bytearray to print in pretty string.
+        pretty (Boolean, optional): ``True`` for pretty string format, ``False`` for plain string format.
+            Default to ``True``.
 
     Returns:
-        String: the bytearray formatted in a pretty string.
+        String: the bytearray formatted in a string format.
     """
-    return " ".join(["%02X" % i for i in byte_array])
+    separator = " " if pretty else ""
+    return separator.join(["%02X" % i for i in byte_array])
 
 
 def doc_enum(enum_class, descriptions=None):

doc/user_doc/configuring_the_xbee_device.rst

@@ -630,3 +630,152 @@ with the following methods:
 +-------------+---------------------------+
 | DNS address | **set_dns_address()**     |
 +-------------+---------------------------+
+
+
+.. _configBluetooth:
+
+Configure Bluetooth settings
+----------------------------
+
+Newer XBee3 devices have a Bluetooth® Low Energy (BLE) interface that enables
+you to connect your XBee device to another device such as a cellphone. The XBee
+device classes (local and remote) offer some methods that allow you to:
+
+* :ref:`_configBluetoothEnableDisable`
+* :ref:`_configBluetoothConfigurePassword`
+* :ref:`_configBluetoothReadMacAddress`
+
+
+.. _configBluetoothEnableDisable:
+
+Enable and disable Bluetooth
+````````````````````````````
+
+Before connecting to your XBee device over Bluetooth Low Energy, you first have
+to enable this interface. The XBee Python Library provides a couple of methods
+to enable or disable this interface:
+
++-------------------------+------------------------------------------------------------------+
+| Method                  | Description                                                      |
++=========================+==================================================================+
+| **enable_bluetooth()**  | Enables the Bluetooth Low Energy interface of your XBee device.  |
++-------------------------+------------------------------------------------------------------+
+| **disable_bluetooth()** | Disables the Bluetooth Low Energy interface of your XBee device. |
++-------------------------+------------------------------------------------------------------+
+
+**Enabling and disabling the Bluetooth interface**
+
+.. code:: python
+
+  [...]
+
+  # Instantiate an XBee device object.
+  local_xbee = XBeeDevice("COM1", 9600)
+  local_xbee.open()
+
+  # Enable the Bluetooth interface.
+  local_xbee.enable_bluetooth()
+
+  [...]
+
+  # Disable the Bluetooth interface.
+  local_xbee.disable_bluetooth()
+
+  [...]
+
+These methods may fail for the following reasons:
+
+* ACK of the command sent is not received in the configured timeout, throwing
+  a ``TimeoutException``.
+* Other errors caught as ``XBeeException``:
+    * The operating mode of the device is not ``API_MODE`` or
+      ``ESCAPED_API_MODE``, throwing an ``InvalidOperatingModeException``.
+    * The response of the command is not valid, throwing an
+      ``ATCommandException``.
+    * There is an error writing to the XBee interface, throwing a generic
+      ``XBeeException``.
+
+
+.. _configBluetoothConfigurePassword:
+
+Configure the Bluetooth password
+````````````````````````````````
+
+Once you have enabled the Bluetooth Low Energy, you must configure the password
+you will use to connect to the device over that interface (if not previously
+done). For this purpose, the API offers the following method:
+
++----------------------------------------+-----------------------------------------------------------+
+| Method                                 | Description                                               |
++========================================+===========================================================+
+| **update_bluetooth_password(String)**  | Specifies the new Bluetooth password of the XBee device.  |
++----------------------------------------+-----------------------------------------------------------+
+
+**Configuring or changing the Bluetooth password**
+
+.. code:: python
+
+  [...]
+
+  # Instantiate an XBee device object.
+  local_xbee = XBeeDevice("COM1", 9600)
+  local_xbee.open()
+
+  new_password = "myBluetoothPassword" # Do not hard-code it in the app!
+
+  # Configure the Bluetooth password.
+  local_xbee.update_bluetooth_password(new_password)
+
+  [...]
+
+The ``update_bluetooth_password`` method may fail for the following reasons:
+
+* ACK of the command sent is not received in the configured timeout, throwing
+  a ``TimeoutException``.
+* Other errors caught as ``XBeeException``:
+    * The operating mode of the device is not ``API_MODE`` or
+      ``ESCAPED_API_MODE``, throwing an ``InvalidOperatingModeException``.
+    * The response of the command is not valid, throwing an
+      ``ATCommandException``.
+    * There is an error writing to the XBee interface, throwing a generic
+      ``XBeeException``.
+
+.. warning::
+  Never hard-code the Bluetooth password in the code, a malicious person could
+  decompile the application and find it out.
+
+
+.. _configBluetoothReadMacAddress:
+
+Read the Bluetooth MAC address
+``````````````````````````````
+
+Another method that the XBee Java Library provides is
+``get_bluetooth_mac_addr()``, which returns the EUI-48 Bluetooth MAC address of
+your XBee device in a format such as "00112233AABB".
+
+**Reading the Bluetooth MAC address**
+
+.. code:: python
+
+  [...]
+
+  # Instantiate an XBee device object.
+  local_xbee = XBeeDevice("COM1", 9600)
+  local_xbee.open()
+
+  print("The Bluetooth MAC address is: %s" % local_xbee.get_bluetooth_mac_addr())
+
+  [...]
+
+The ``get_bluetooth_mac_addr`` method may fail for the following reasons:
+
+* ACK of the command sent is not received in the configured timeout, throwing
+  a ``TimeoutException``.
+* Other errors caught as ``XBeeException``:
+    * The operating mode of the device is not ``API_MODE`` or
+      ``ESCAPED_API_MODE``, throwing an ``InvalidOperatingModeException``.
+    * The response of the command is not valid, throwing an
+      ``ATCommandException``.
+    * There is an error writing to the XBee interface, throwing a generic
+      ``XBeeException``.

requirements.txt

@@ -1,2 +1,3 @@
 pyserial>=3
-sphinxcontrib.napoleon
+sphinxcontrib.napoleon
+srp