diff --git a/docs/conf.py b/docs/conf.py index dc54792b..e7d471ee 100644 --- a/docs/conf.py +++ b/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. diff --git a/docs/delegate.rst b/docs/delegate.rst new file mode 100644 index 00000000..7fb0ee0c --- /dev/null +++ b/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. diff --git a/docs/index.rst b/docs/index.rst index 94df3c3d..3e43becf 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -18,6 +18,9 @@ Contents: :maxdepth: 2 peripheral + scanner + scanentry + delegate uuid service characteristic diff --git a/docs/peripheral.rst b/docs/peripheral.rst index 031c3bce..625ae3ae 100644 --- a/docs/peripheral.rst +++ b/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,13 +89,18 @@ 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 @@ -92,6 +108,22 @@ Instance Methods ``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. diff --git a/docs/scanentry.rst b/docs/scanentry.rst new file mode 100644 index 00000000..f311c756 --- /dev/null +++ b/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). + + \ No newline at end of file diff --git a/docs/scanner.rst b/docs/scanner.rst new file mode 100644 index 00000000..14a86eb3 --- /dev/null +++ b/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() + +