djsundog/circuitpython
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs/library/bluetooth.rst: Clarify gap_advertise adv_data behavior.

Browse Source 
Make it clear that the previous adv_data will be reused if it's not set.
And some minor other improvements.
This commit is contained in:
Jim Mussared 2019-10-14 15:45:31 +11:00 committed by Damien George
parent ba16a22991
commit 62e3a966fb
1 changed files with 12 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
docs/library/bluetooth.rst
View File

@ -6,7 +6,8 @@
This module provides an interface to a Bluetooth controller on a board.
Currently this supports Bluetooth Low Energy (BLE) in Central, Peripheral,
Broadcaster, and Observer roles.
Broadcaster, and Observer roles, and a device may operate in multiple
roles concurrently.
This API is intended to match the low-level Bluetooth protocol and provide
building-blocks for higher-level abstractions such as specific device types.
@ -66,6 +67,7 @@ Event Handling
elif event == _IRQ_GATTS_READ_REQUEST:
# A central has issued a read. Note: this is a hard IRQ.
# Return None to deny the read.
# Note: This event is not supported on ESP32.
conn_handle, attr_handle = data
elif event == _IRQ_SCAN_RESULT:
# A single scan result.
@ -138,6 +140,11 @@ Broadcaster Role (Advertiser)
protocol (e.g. ``bytes``, ``bytearray``, ``str``). *adv_data* is included
in all broadcasts, and *resp_data* is send in reply to an active scan.
Note: if *adv_data* (or *resp_data*) is ``None``, then the data passed
to the previous call to ``gap_advertise`` will be re-used. This allows a
broadcaster to resume advertising with just ``gap_advertise(interval_us)``.
To clear the advertising payload pass an empty ``bytes``, i.e. ``b''``.
Observer Role (Scanner)
-----------------------
@ -169,9 +176,10 @@ A BLE peripheral has a set of registered services. Each service may contain
characteristics, which each have a value. Characteristics can also contain
descriptors, which themselves have values.
These values are stored locally and can be read from or written to by a remote
central device. Additionally, a peripheral can "notify" its value to a connected
central via its connection handle.
These values are stored locally, and are accessed by their "value handle" which
is generated during service registration. They can also be read from or written
to by a remote central device. Additionally, a peripheral can "notify" a
characteristic to a connected central via a connection handle.
.. method:: BLE.gatts_register_services(services_definition)