docs/library: Update ubluetooth for new events and discover by uuid.
This commit is contained in:
Jim Mussared
Damien George
parent
9902ce12eb
commit
9708fe8788
|
|
@ -65,15 +65,12 @@ Configuration
|
|||
Event Handling
|
||||
--------------
|
||||
|
||||
.. method:: BLE.irq(handler, trigger=0xffff)
|
||||
.. method:: BLE.irq(handler)
|
||||
|
||||
Registers a callback for events from the BLE stack. The *handler* takes two
|
||||
arguments, ``event`` (which will be one of the codes below) and ``data``
|
||||
(which is an event-specific tuple of values).
|
||||
|
||||
The optional *trigger* parameter allows you to set a mask of events that
|
||||
your program is interested in. The default is all events.
|
||||
|
||||
Note: the ``addr``, ``adv_data``, ``char_data``, ``notify_data``, and
|
||||
``uuid`` entries in the tuples are
|
||||
references to data managed by the :mod:`ubluetooth` module (i.e. the same
|
||||
|
|
@ -101,7 +98,7 @@ Event Handling
|
|||
elif event == _IRQ_SCAN_RESULT:
|
||||
# A single scan result.
|
||||
addr_type, addr, adv_type, rssi, adv_data = data
|
||||
elif event == _IRQ_SCAN_COMPLETE:
|
||||
elif event == _IRQ_SCAN_DONE:
|
||||
# Scan duration finished or manually stopped.
|
||||
pass
|
||||
elif event == _IRQ_PERIPHERAL_CONNECT:
|
||||
|
|
@ -113,17 +110,31 @@ Event Handling
|
|||
elif event == _IRQ_GATTC_SERVICE_RESULT:
|
||||
# Called for each service found by gattc_discover_services().
|
||||
conn_handle, start_handle, end_handle, uuid = data
|
||||
elif event == _IRQ_GATTC_SERVICE_DONE:
|
||||
# Called once service discovery is complete.
|
||||
conn_handle, status = data
|
||||
elif event == _IRQ_GATTC_CHARACTERISTIC_RESULT:
|
||||
# Called for each characteristic found by gattc_discover_services().
|
||||
conn_handle, def_handle, value_handle, properties, uuid = data
|
||||
elif event == _IRQ_GATTC_CHARACTERISTIC_DONE:
|
||||
# Called once service discovery is complete.
|
||||
conn_handle, status = data
|
||||
elif event == _IRQ_GATTC_DESCRIPTOR_RESULT:
|
||||
# Called for each descriptor found by gattc_discover_descriptors().
|
||||
conn_handle, dsc_handle, uuid = data
|
||||
elif event == _IRQ_GATTC_DESCRIPTOR_DONE:
|
||||
# Called once service discovery is complete.
|
||||
conn_handle, status = data
|
||||
elif event == _IRQ_GATTC_READ_RESULT:
|
||||
# A gattc_read() has completed.
|
||||
conn_handle, value_handle, char_data = data
|
||||
elif event == _IRQ_GATTC_WRITE_STATUS:
|
||||
elif event == _IRQ_GATTC_READ_DONE:
|
||||
# A gattc_read() has completed.
|
||||
# Note: The value_handle will be zero on btstack (but present on NimBLE).
|
||||
conn_handle, value_handle, status = data
|
||||
elif event == _IRQ_GATTC_WRITE_DONE:
|
||||
# A gattc_write() has completed.
|
||||
# Note: The value_handle will be zero on btstack (but present on NimBLE).
|
||||
conn_handle, value_handle, status = data
|
||||
elif event == _IRQ_GATTC_NOTIFY:
|
||||
# A peripheral has sent a notify request.
|
||||
|
|
@ -135,21 +146,25 @@ Event Handling
|
|||
The event codes are::
|
||||
|
||||
from micropython import const
|
||||
_IRQ_CENTRAL_CONNECT = const(1 << 0)
|
||||
_IRQ_CENTRAL_DISCONNECT = const(1 << 1)
|
||||
_IRQ_GATTS_WRITE = const(1 << 2)
|
||||
_IRQ_GATTS_READ_REQUEST = const(1 << 3)
|
||||
_IRQ_SCAN_RESULT = const(1 << 4)
|
||||
_IRQ_SCAN_COMPLETE = const(1 << 5)
|
||||
_IRQ_PERIPHERAL_CONNECT = const(1 << 6)
|
||||
_IRQ_PERIPHERAL_DISCONNECT = const(1 << 7)
|
||||
_IRQ_GATTC_SERVICE_RESULT = const(1 << 8)
|
||||
_IRQ_GATTC_CHARACTERISTIC_RESULT = const(1 << 9)
|
||||
_IRQ_GATTC_DESCRIPTOR_RESULT = const(1 << 10)
|
||||
_IRQ_GATTC_READ_RESULT = const(1 << 11)
|
||||
_IRQ_GATTC_WRITE_STATUS = const(1 << 12)
|
||||
_IRQ_GATTC_NOTIFY = const(1 << 13)
|
||||
_IRQ_GATTC_INDICATE = const(1 << 14)
|
||||
_IRQ_CENTRAL_CONNECT = const(1)
|
||||
_IRQ_CENTRAL_DISCONNECT = const(2)
|
||||
_IRQ_GATTS_WRITE = const(3)
|
||||
_IRQ_GATTS_READ_REQUEST = const(4)
|
||||
_IRQ_SCAN_RESULT = const(5)
|
||||
_IRQ_SCAN_DONE = const(6)
|
||||
_IRQ_PERIPHERAL_CONNECT = const(7)
|
||||
_IRQ_PERIPHERAL_DISCONNECT = const(8)
|
||||
_IRQ_GATTC_SERVICE_RESULT = const(9)
|
||||
_IRQ_GATTC_SERVICE_DONE = const(10)
|
||||
_IRQ_GATTC_CHARACTERISTIC_RESULT = const(11)
|
||||
_IRQ_GATTC_CHARACTERISTIC_DONE = const(12)
|
||||
_IRQ_GATTC_DESCRIPTOR_RESULT = const(13)
|
||||
_IRQ_GATTC_DESCRIPTOR_DONE = const(14)
|
||||
_IRQ_GATTC_READ_RESULT = const(15)
|
||||
_IRQ_GATTC_READ_DONE = const(16)
|
||||
_IRQ_GATTC_WRITE_DONE = const(17)
|
||||
_IRQ_GATTC_NOTIFY = const(18)
|
||||
_IRQ_GATTC_INDICATE = const(19)
|
||||
|
||||
In order to save space in the firmware, these constants are not included on the
|
||||
:mod:`ubluetooth` module. Add the ones that you need from the list above to your
|
||||
|
|
@ -203,7 +218,7 @@ Observer Role (Scanner)
|
|||
* 0x04 - SCAN_RSP - scan response
|
||||
|
||||
When scanning is stopped (either due to the duration finishing or when
|
||||
explicitly stopped), the ``_IRQ_SCAN_COMPLETE`` event will be raised.
|
||||
explicitly stopped), the ``_IRQ_SCAN_DONE`` event will be raised.
|
||||
|
||||
|
||||
Peripheral Role (GATT Server)
|
||||
|
|
@ -313,33 +328,42 @@ Central Role (GATT Client)
|
|||
Returns ``False`` if the connection handle wasn't connected, and ``True``
|
||||
otherwise.
|
||||
|
||||
.. method:: BLE.gattc_discover_services(conn_handle)
|
||||
.. method:: BLE.gattc_discover_services(conn_handle, [uuid])
|
||||
|
||||
Query a connected peripheral for its services.
|
||||
|
||||
For each service discovered, the ``_IRQ_GATTC_SERVICE_RESULT`` event will be
|
||||
raised.
|
||||
Optionally specify a service *uuid* to query for that service only.
|
||||
|
||||
.. method:: BLE.gattc_discover_characteristics(conn_handle, start_handle, end_handle)
|
||||
For each service discovered, the ``_IRQ_GATTC_SERVICE_RESULT`` event will
|
||||
be raised, followed by ``_IRQ_GATTC_SERVICE_DONE`` on completion.
|
||||
|
||||
.. method:: BLE.gattc_discover_characteristics(conn_handle, start_handle, end_handle, [uuid])
|
||||
|
||||
Query a connected peripheral for characteristics in the specified range.
|
||||
|
||||
Optionally specify a characteristic *uuid* to query for that
|
||||
characteristic only.
|
||||
|
||||
You can use ``start_handle=1``, ``end_handle=0xffff`` to search for a
|
||||
characteristic in any service.
|
||||
|
||||
For each characteristic discovered, the ``_IRQ_GATTC_CHARACTERISTIC_RESULT``
|
||||
event will be raised.
|
||||
event will be raised, followed by ``_IRQ_GATTC_CHARACTERISTIC_DONE`` on completion.
|
||||
|
||||
.. method:: BLE.gattc_discover_descriptors(conn_handle, start_handle, end_handle)
|
||||
|
||||
Query a connected peripheral for descriptors in the specified range.
|
||||
|
||||
For each descriptor discovered, the ``_IRQ_GATTC_DESCRIPTOR_RESULT`` event
|
||||
will be raised.
|
||||
will be raised, followed by ``_IRQ_GATTC_DESCRIPTOR_DONE`` on completion.
|
||||
|
||||
.. method:: BLE.gattc_read(conn_handle, value_handle)
|
||||
|
||||
Issue a remote read to a connected peripheral for the specified
|
||||
characteristic or descriptor handle.
|
||||
|
||||
On success, the ``_IRQ_GATTC_READ_RESULT`` event will be raised.
|
||||
When a value is available, the ``_IRQ_GATTC_READ_RESULT`` event will be
|
||||
raised. Additionally, the ``_IRQ_GATTC_READ_DONE`` will be raised.
|
||||
|
||||
.. method:: BLE.gattc_write(conn_handle, value_handle, data, mode=0, /)
|
||||
|
||||
|
|
@ -357,7 +381,7 @@ Central Role (GATT Client)
|
|||
data.
|
||||
|
||||
If a response is received from the remote peripheral the
|
||||
``_IRQ_GATTC_WRITE_STATUS`` event will be raised.
|
||||
``_IRQ_GATTC_WRITE_DONE`` event will be raised.
|
||||
|
||||
|
||||
class UUID
|
||||
|
|
|
|||
Loading…
Reference in New Issue