Documentation commit.

Updated documentation about scanning filters.
Added scanning filters to .NET discover method.
Updated CHANGLOG.

Author: hbldh

CHANGELOG.rst

@@ -18,6 +18,7 @@ Added
 * Two devices example file to use for e.g. debugging.
 * Detection/discovery callbacks in Core Bluetooth backend ```Scanner`` implemented.
 * Characteristic handle printout in ``service_explorer.py``.
+* Added scanning filters to .NET backend's ``discover`` method.
 
 Changed
 ~~~~~~~
@@ -36,15 +37,10 @@ Changed
 * Renamed ``HISTORY.rst`` to ``CHANGELOG.rst`` and adopted
   the `Keep a Changelog <https://keepachangelog.com/en/1.0.0/>`_ format.
 * Python 3.5 support from macOS is officially removed since pyobjc>6 requires 3.6+
-* Pin pyobjc to version 6.2. (PR #194)
-* Pin pyobjc-framework-corebluetooth to version 6.2.
+* Pin ``pyobjc`` dependencies to use at least version 6.2. (PR #194)
 * Pin development requirement on `bump2version` to version 1.0.0
 * Added ``.pyup.yml`` for Pyup
 * Using CBManagerState constants from pyobj instead of integers.
-* Improved handling of the txdbus connection to avoid hanging of disconnection
-  clients in BlueZ backend. Fixes #216, #219 & #221.
-* #150 hints at the device path not being possible to create as is done in the `get_device_object_path` method.
-  Now, we try to get it from BlueZ first. Otherwise, use the old fallback.
 
 Removed
 ~~~~~~~
@@ -54,13 +50,17 @@ Removed
 * Removed the ``bleak.backends.bluez.utils.get_gatt_service_path`` method. It is not used by
   bleak and possibly generates errors.
 
-
 Fixed
 ~~~~~
 
+* Improved handling of the txdbus connection to avoid hanging of disconnection
+  clients in BlueZ backend. Fixes #216, #219 & #221.
+* #150 hints at the device path not being possible to create as is done in the `get_device_object_path` method.
+  Now, we try to get it from BlueZ first. Otherwise, use the old fallback.
 * Minor documentation errors corrected.
 * ``CBManagerStatePoweredOn`` is now properly handled in Core Bluetooth.
 * Device enumeration in ``discover``and ``Scanner`` corrected. Fixes #211
+* Updated documentation about scanning filters.
 
 `0.6.4`_ (2020-05-20)
 ---------------------

LICENSE

@@ -1,7 +1,7 @@
 
 MIT License
 
-Copyright (c) 2019, Henrik Blidh
+Copyright (c) 2020, Henrik Blidh
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

bleak/__version__.py

@@ -1,3 +1,3 @@
 # -*- coding: utf-8 -*-
 
-__version__ = "0.6.5a8"
+__version__ = "0.6.5a9"

bleak/backends/dotnet/discovery.py

@@ -36,13 +36,22 @@ async def discover(
         loop (Event Loop): The event loop to use.
 
     Keyword Args:
+        SignalStrengthFilter (Windows.Devices.Bluetooth.BluetoothSignalStrengthFilter): A
+          BluetoothSignalStrengthFilter object used for configuration of Bluetooth
+          LE advertisement filtering that uses signal strength-based filtering.
+        AdvertisementFilter (Windows.Devices.Bluetooth.Advertisement.BluetoothLEAdvertisementFilter): A
+          BluetoothLEAdvertisementFilter object used for configuration of Bluetooth LE
+          advertisement filtering that uses payload section-based filtering.
         string_output (bool): If set to false, ``discover`` returns .NET
             device objects instead.
 
     Returns:
         List of strings or objects found.
 
     """
+    signal_strength_filter = kwargs.get("SignalStrengthFilter", None)
+    advertisement_filter = kwargs.get("AdvertisementFilter", None)
+
     loop = loop if loop else asyncio.get_event_loop()
 
     watcher = BluetoothLEAdvertisementWatcher()
@@ -85,6 +94,11 @@ def AdvertisementWatcher_Stopped(sender, e):
 
     watcher.ScanningMode = BluetoothLEScanningMode.Active
 
+    if signal_strength_filter is not None:
+        watcher.SignalStrengthFilter = signal_strength_filter
+    if advertisement_filter is not None:
+        watcher.AdvertisementFilter = advertisement_filter
+
     # Watcher works outside of the Python process.
     watcher.Start()
     await asyncio.sleep(timeout, loop=loop)

bleak/backends/scanner.py

@@ -7,7 +7,7 @@
 
 
 class BaseBleakScanner(abc.ABC):
-    """Interface for Bleak Bluetooth LE Scanners
+    """Interface for Bleak Bluetooth LE Scanners.
 
     Args:
         loop (Event Loop): The event loop to use.

docs/api.rst

@@ -8,9 +8,9 @@ Connection Client Interface
     :members:
 
 Scanning Client Interface
----------------------------
+-------------------------
 
-.. automodule:: bleak.backends.scanning
+.. automodule:: bleak.backends.scanner
     :members:
 
 Interface for BLE devices

docs/backends/windows.rst

@@ -9,13 +9,13 @@ The Windows backend implements a ``BleakClient`` in the module ``bleak.backends.
 method in the ``bleak.backends.dotnet.discovery`` module. There are also backend-specific implementations of the
 ``BleakGATTService``, ``BleakGATTCharacteristic`` and ``BleakGATTDescriptor`` classes.
 
-FInally, some .NET/``asyncio``-connectivity methods are available in the ``bleak.backends.dotnet.utils`` module.
+Finally, some .NET/``asyncio``-connectivity methods are available in the ``bleak.backends.dotnet.utils`` module.
 
 Specific features for the Windows backend
 -----------------------------------------
 
 Client
 ~~~~~~
  - The constructor keyword ``address_type`` which can have the values ``"public"`` or ``"random"``. This value
-   makes sure that the connect
+   makes sure that the connection is made in a fashion that suits the peripheral.
 

docs/history.rst

@@ -1 +1 @@
-.. include:: ../HISTORY.rst
+.. include:: ../CHANGELOG.rst

docs/scanning.rst

@@ -31,6 +31,7 @@ and ``rssi`` attributes, as well as a ``metadata`` attribute, a dict with keys `
 which potentially contains a list of all service UUIDs on the device and a binary string of data from
 the manufacturer of the device respectively.
 
+
 BleakScanner
 ------------
 
@@ -95,3 +96,19 @@ or separately, calling ``start`` and ``stop`` methods on the scanner manually:
 In the manual mode, it is possible to add an own callback that you want to call upon each
 scanner detection, as can be seen above. There is also possibilities of adding scanning filters,
 but these differ so widely between implementations, so these details are recorded there instead.
+
+Scanning Filters
+----------------
+
+There are some scanning filters that can be applied, that will reduce your scanning
+results prior to them getting to bleak. These are pretty quite backend specific, but
+they are generally used like this:
+
+- On the `discover` method, send in keyword arguments according to what is
+  described in the docstring of the method.
+- On the backend's `BleakScanner` implementation, either send in keyword arguments
+  according to what is described in the docstring of the class or use the
+  ``set_scanning_filter`` method to set them after the instance has been created.
+
+Scanning filters are currently implemented in Windows and BlueZ backends, but not yet
+in the macOS backend.

docs/usage.rst

@@ -2,6 +2,14 @@
 Usage
 =====
 
+.. note::
+
+    A Bluetooth peripheral may have several characteristics with the same UUID, so
+    the means of specifying characteristics by UUID or string representation of it
+    might not always work in bleak version > 0.7.0. One can now also use the characteristic's
+    handle or even the ``BleakGATTCharacteristic`` object itself in
+    ``read_gatt_char``, ``write_gatt_char``, ``start_notify``, and ``stop_notify``.
+
 
 One can use the ``BleakClient`` to connect to a Bluetooth device and read its model number
 via the asyncronous context manager like this:
@@ -46,7 +54,7 @@ or one can do it without the context manager like this:
     loop = asyncio.get_event_loop()
     loop.run_until_complete(run(address, loop))
 
-Try to make sure you always get to call the disconnect method for a client before discarding it;
+Make sure you always get to call the disconnect method for a client before discarding it;
 the Bluetooth stack on the OS might need to be cleared of residual data which is cached in the
 ``BleakClient``.
 

examples/sensortag.py

@@ -104,7 +104,7 @@ async def run(address, loop, debug=False):
         # h.setLevel(logging.DEBUG)
         # l.addHandler(h)
 
-    async with BleakClient(address, loop=loop) as client:
+    async with BleakClient(address, timeout=1.0, loop=loop) as client:
         x = await client.is_connected()
         logger.info("Connected: {0}".format(x))