Work in progress, docs fixes + additions for scanning

docs/conf.py

@@ -56,7 +56,7 @@
 # The short X.Y version.
 version = '0.9'
 # The full version, including alpha/beta/rc tags.
-release = '0.9.0'
+release = '0.9.10'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/delegate.rst

@@ -0,0 +1,40 @@
+.. _delegate:
+
+The ``DefaultDelegate`` class
+=============================
+
+``bluepy`` functions which receive Bluetooth messages asynchronously -
+such as notifications, indications, and advertising data - pass this information
+to the user by calling methods on a 'delegate' object.
+
+To be useful, the delegate object will be from a class created by the user.
+Bluepy's ``DefaultDelegate`` is a base class for this - you should override
+some or all of the methods here with your own application-specific code.
+
+Constructor
+-----------
+
+.. function:: DefaultDelegate()
+
+    Initialises the object instance. 
+
+
+Instance Methods
+----------------
+
+.. py:method:: handleNotification(cHandle, data)
+
+   Called when a notification or indication is received from a connected
+   ``Peripheral`` object. *cHandle* is the (integer) handle for the 
+   characteristic - this can be used to distinguish between notifications
+   from multiple sources on the same peripheral. *data* is the characteristic
+   data (a ``str`` type on Python 2.x, and ``bytes`` on 3.x).
+
+.. py:method:: handleScan(scanEntry, isNewDev, isNewData)
+
+   Called when advertising data is received from an LE device while a
+   ``Scanner`` object is active. *scanEntry* contains device information
+   and advertising data - see the ``ScanEntry`` class for details. *isNewDev* 
+   is ``True`` if the device (as identified by its MAC address) has not been
+   seen before by the scanner, and ``False`` otherwise. *isNewData* is ``True``
+   if new or updated advertising data is available.

docs/index.rst

@@ -18,6 +18,9 @@ Contents:
    :maxdepth: 2
 
    peripheral
+   scanner
+   scanentry
+   delegate
    uuid
    service
    characteristic

docs/peripheral.rst

@@ -8,27 +8,36 @@ Bluepy's ``Peripheral`` class encapsulates a connection to a Bluetooth LE periph
 Constructor
 -----------
 
-.. function:: Peripheral([deviceAddress=None, [addrType=ADDR_TYPE_PUBLIC]])
+.. function:: Peripheral([deviceAddress=None, [addrType=ADDR_TYPE_PUBLIC [, iface=None]]])
 
    If *deviceAddress* is not ``None``, creates a ``Peripheral`` object and makes a connection
    to the device indicated by *deviceAddress* (which should be a string comprising six hex
    bytes separated by colons, e.g. ``"11:22:33:ab:cd:ed"``).
 
    If *deviceAddress* is ``None``, creates an un-connected ``Peripheral`` object. You must call the ``connect()`` method on this object (passing it a device address) before it will be usable.
-
+   
    The *addrType* parameter can be used to select between fixed (``btle.ADDR_TYPE_PUBLIC``)
    and random (``btle.ADDR_TYPE_RANDOM``) address types, depending on what the target
    peripheral requires. See section 10.8 of the Bluetooth 4.0 specification for more
    details.
+
+   The *iface* parameter allows the Bluetooth interface on which to make the connection to be set.
+   On Linux, ``0`` means */dev/hci0*, ``1`` means */dev/hci1* and so on.
+
+   *deviceAddress* may also be a ``ScanEntry`` object. In this case the device address,
+   address type, and interface number are all taken from the ``ScanEntry`` values, and 
+   the *addrType* and *iface* parameters are ignored.
 
    The constructor will throw a ``BTLEException`` if connection to the device fails.
 
 Instance Methods
 ----------------
 
-.. function:: connect(deviceAddress)
+.. function:: connect(deviceAddress, [addrType=ADDR_TYPE_PUBLIC [, iface=None]])
 
-    Makes a connection to the device indicated by *deviceAddress*. You should only call
+    Makes a connection to the device indicated by *deviceAddress*, with address type
+    *addrType* and interface number *iface* (see the ``Peripheral`` constructor for details).
+    You should only call
     this method if the ``Peripheral`` is un-connected (i.e. you did not pass a *deviceAddress*
     to the constructor); a given peripheral object cannot be re-connected once connected.
 
@@ -45,7 +54,9 @@ Instance Methods
     This will perform Bluetooth service discovery if this has not already been done;
     otherwise it will return a cached list of services immediately.
 
-.. function:: getServiceByUUID(uuidVal):
+    On Python 3.x, this returns a *dictionary view* object, not a list.
+
+.. function:: getServiceByUUID( uuidVal )
 
     Returns an instance of a ``Service`` object which has the indicated UUID.
     ``uuidVal`` can be a ``UUID`` object, or any string or integer which can be
@@ -54,7 +65,7 @@ Instance Methods
     the peripheral otherwise. It raises a *BTLEEException* if the service is not
     found.
 
-.. function:: getCharacteristics(startHnd=1, endHnd=0xFFFF, uuid=None):
+.. function:: getCharacteristics(startHnd=1, endHnd=0xFFFF, uuid=None)
 
     Returns a list containing ``Characteristic`` objects for the peripheral. If no
     arguments are given, will return all characteristics. If *startHnd* and/or 
@@ -67,7 +78,7 @@ Instance Methods
 
     If no matching characteristics are found, returns an empty list.
 
-.. function:: getDescriptors(startHnd=1, endHnd=0xFFFF):
+.. function:: getDescriptors(startHnd=1, endHnd=0xFFFF)
 
     Returns a list containing ``Descriptor`` objects for the peripheral. If no
     arguments are given, will return all descriptors. If *startHnd* and/or 
@@ -78,20 +89,41 @@ Instance Methods
 
     If no matching descriptors are found, returns an empty list.
 
-.. function:: setDelegate(delegate):
+.. function:: withDelegate(delegate)
 
     This stores a reference to a "delegate" object, which is called when asynchronous
     events such as Bluetooth notifications occur. This should be a subclass of the
-    ``DefaultDelegate`` class. See :ref:`notifications` for more information.
+    ``DefaultDelegate`` class. See :ref:`notifications` for more information. This
+    method returns the ``Peripheral`` object.
+
+.. function:: setDelegate(delegate)
 
-.. function:: waitForNotifications(timeout):
+    *(deprecated since 0.9.10)* Same as *withDelegate()*.
+
+.. function:: waitForNotifications(timeout)
 
     Blocks until a notification is received from the peripheral, or until the 
     given *timeout* (in seconds) has elapsed. If a notification is received, the
     delegate object's ``handleNotification()`` method will be called, and
     ``waitForNotifications()`` will then return ``True``.
 
     If nothing is received before the timeout elapses, this will return ``False``.
+
+.. function:: writeCharacteristic(handle, val, withResponse=False)
+
+    Writes the data *val* (of type ``str`` on Python 2.x, ``byte`` on 3.x) to the
+    characteristic identified by handle *handle*, which should be an integer in the
+    range 1 to 65535. This is useful if you know a characteristic's GATT handle,
+    but do not have a ``Characteristic`` object. 
+
+    If *withResponse* is true, will await confirmation that the write was successful
+    from the device.
+
+.. function:: readCharacteristic(handle):
+
+    Reads the current value of the characteristic identified by *handle*. This is
+    useful if you know the handle for the characteristic but do not have a suitable
+    ``Characteristic`` object.
 
 
 

docs/scanentry.rst

@@ -0,0 +1,72 @@
+.. _scanentry:
+
+The ``ScanEntry`` class
+=======================
+
+A ``ScanEntry`` object contains information received from a Bluetooth LE
+device received during ``Scanner`` operation. This includes parameters
+needed to connect to the device (MAC address, address type), and 
+advertising data (such as its name or available services) supplied in
+the device's broadcasts.
+
+Constructor
+-----------
+
+``ScanEntry`` objects are created by the ``Scanner`` class, and should not
+be created by the user.
+
+Instance Methods
+----------------
+
+.. py:method:: getDescription(adtype)
+
+    Returns a human-readable description of the advertising data 'type'
+    code *adtype*. For instance, an *adtype* value of 9 would return the
+    string ``"Complete Local Name"``. See the Generic Access Profile 
+    assigned numbers at https://www.bluetooth.org/en-us/specification/assigned-numbers/generic-access-profile
+    for a complete list.
+
+.. py:method:: getValueText(adtype)
+
+    Returns a human-readable string representation of the advertising data
+    for code *adtype*. Values such as the 'local name' are returned as
+    strings directly; other values are converted to hex strings. If the
+    requested data is not available, ``None`` is returned.
+
+.. py:method:: getScanData()
+
+    Returns a list of tuples *(adtype, description, value)* containing the
+    AD type code, human-readable description and value (as reported by
+    ``getDescription()`` and ``getValueText()``) for all available advertising
+    data items.
+
+Properties
+----------
+
+All the properties listed below are read-only.
+
+.. py:attribute:: addr
+
+    Device MAC address (as a hex string separated by colons).
+
+.. py:attribute:: addrType
+
+    Device address type - one of *ADDR_TYPE_PUBLIC* or *ADDR_TYPE_RANDOM*.
+
+.. py:attribute:: rssi
+
+    Received Signal Strength Indication for the last received broadcast from the
+    device. This is an integer value measured in dB, where 0 dB is the maximum 
+    (theoretical) signal strength, and more negative numbers indicate a weaker signal.
+
+.. py:attribute:: connectable
+
+    Boolean value - ``True`` if the device supports connections, and ``False`` 
+    otherwise (typically used for advertising 'beacons').
+
+.. py:attribute:: updateCount
+
+    Integer count of the number of advertising packets received from the device
+    so far (since *clear()* was called on the ``Scanner`` object which found it).
+
+

docs/scanner.rst

@@ -0,0 +1,53 @@
+.. _scanner:
+
+The ``Scanner`` class
+=====================
+
+A ``Scanner`` object is used to scan for LE devices which are broadcasting
+advertising data. In most situations this will give a set of devices which
+are available for connection. (Note, however, that Bluetooth LE devices may
+accept connections without broadcasting advertising data, or may broadcast
+advertising data but may not accept connections).
+
+
+Constructor
+-----------
+
+.. function:: Scanner( [index=0] )
+
+    Creates and initialises a new scanner object. *index* identifies the
+    Bluetooth interface to use (where 0 is **/dev/hci0** etc). Scanning
+    does not start until the *start()* or *scan()* methods are called -
+    see below for details.
+
+Instance Methods
+----------------
+
+.. function:: withDelegate(delegate)
+
+    Stores a reference to a *delegate* object, which receives callbacks
+    when broadcasts from devices are received. See the documentation for
+    ``DefaultDelegate`` for details. 
+
+.. function:: scan( [timeout = 10] )
+
+    Scans for devices for the given *timeout* in seconds. During this 
+    period, callbacks to the *delegate* object will be called. When the
+    timeout ends, scanning will stop and the method will return a list
+    (or a *view* on Python 3.x) of ``ScanEntry`` objects for all devices
+    discovered during that time.
+
+    *scan()* is equivalent to calling the *clear()*, *start()*, 
+    *process()* and *stop()* methods.
+
+.. function:: clear()
+
+    Clears the current set of discovered devices. 
+
+.. function:: start()
+
+.. function:: process ( [timeout = 10] )
+
+.. function:: stop()
+
+