backends:bgapi: initial documentation.

Adds a feature to the changelog and some initial notes on the specifics
of this backend.

Signed-off-by: Karl Palsson <karlp@etactica.com>

Author: karlp

CHANGELOG.rst

@@ -18,6 +18,7 @@ Added
 * Added ``BleakScanner.find_device_by_name()`` class method.
 * Added optional command line argument to use debug log level to all applicable examples.
 * Make sure the disconnect monitor task is properly cancelled on the BlueZ client.
+* Added new backend, for Silicon Labs NCP devices implementing BGAPI
 
 Changed
 -------

docs/backends/bgapi.rst

@@ -0,0 +1,62 @@
+.. _bgapi-backend:
+
+Silicon Labs BGAPI backend
+=============
+
+The BGAPI backend of Bleak communicates with any device that implements Silicon Labs "BGAPI"
+Protocol.  Classically, this is a Silicon Labs microcontroller, attached via a serial port,
+which has been programmed with some variant of "NCP" (Network Co-Processor) firmware.
+
+This does `not` apply to devices using "RCP" (Radio Co-Processor) firmware, as those only
+expose the much lower level HCI interface.
+
+References:
+ * `AN1259: Using the v3.x Silicon Labs Bluetooth Stack in Network Co-Processor Mode <https://www.silabs.com/documents/public/application-notes/an1259-bt-ncp-mode-sdk-v3x.pdf>`_
+ * https://docs.silabs.com/bluetooth/5.0/index
+
+Requirements
+------
+This backend uses `pyBGAPI <https://pypi.org/project/pybgapi/>`_ to handle the protocol layers.
+
+
+Usage
+-----
+This backend cannot be automatically selected based on system type, so must be manually
+selected, using code such as:
+
+.. code-block:: python
+
+    async with bleak.BleakClient(
+            "11:aa:bb:cc:22:33",
+            backend=bleak.backends.bgapi.client.BleakClientBGAPI,
+            bgapi="/home/karlp/SimplicityStudio/SDKs/gecko-4.2.0/protocol/bluetooth/api/sl_bt.xapi",
+            adapter="/dev/ttyACM1",
+            ) as client:
+        logging.info("Connected to %s", client)
+
+Pay attention that the ``bgapi`` file must be provided, corresponding to the firmware used on your device.
+These files can be found in the `Silicon Labs Gecko SDK <https://github.com/SiliconLabs/gecko_sdk/>`_ in
+the ``protocol/bluetooth/api`` directory.
+
+Likewise, the ``adapter`` kwarg should be used to specify where the device is attached.
+
+At the time of writing, support for sockets or the Silicon Labs CPC daemon is not tested.
+
+
+
+API
+---
+
+Scanner
+~~~~~~~
+
+.. automodule:: bleak.backends.bluezdbus.scanner
+    :members:
+
+Client
+~~~~~~
+
+.. automodule:: bleak.backends.bluezdbus.client
+    :members:
+
+.. _`asyncio event loop`: https://docs.python.org/3/library/asyncio-eventloop.html

docs/index.rst

@@ -39,6 +39,7 @@ Features
 * Supports Windows 10, version 16299 (Fall Creators Update) or greater
 * Supports Linux distributions with BlueZ >= 5.43 (See :ref:`linux-backend` for more details)
 * OS X/macOS support via Core Bluetooth API, from at least OS X version 10.11
+* Supports any os via Silicon Labs NCP devices. (See :ref:`bgapi-backend` for more details)
 
 Bleak supports reading, writing and getting notifications from
 GATT servers, as well as a function for discovering BLE devices.