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. This module provides an interface to a Bluetooth controller on a board.
Currently this supports Bluetooth Low Energy (BLE) in Central, Peripheral, 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 This API is intended to match the low-level Bluetooth protocol and provide
building-blocks for higher-level abstractions such as specific device types. building-blocks for higher-level abstractions such as specific device types.
@ -66,6 +67,7 @@ Event Handling
elif event == _IRQ_GATTS_READ_REQUEST: elif event == _IRQ_GATTS_READ_REQUEST:
# A central has issued a read. Note: this is a hard IRQ. # A central has issued a read. Note: this is a hard IRQ.
# Return None to deny the read. # Return None to deny the read.
# Note: This event is not supported on ESP32.
conn_handle, attr_handle = data conn_handle, attr_handle = data
elif event == _IRQ_SCAN_RESULT: elif event == _IRQ_SCAN_RESULT:
# A single scan result. # A single scan result.
@ -138,6 +140,11 @@ Broadcaster Role (Advertiser)
protocol (e.g. ``bytes``, ``bytearray``, ``str``). *adv_data* is included protocol (e.g. ``bytes``, ``bytearray``, ``str``). *adv_data* is included
in all broadcasts, and *resp_data* is send in reply to an active scan. 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) 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 characteristics, which each have a value. Characteristics can also contain
descriptors, which themselves have values. descriptors, which themselves have values.
These values are stored locally and can be read from or written to by a remote These values are stored locally, and are accessed by their "value handle" which
central device. Additionally, a peripheral can "notify" its value to a connected is generated during service registration. They can also be read from or written
central via its connection handle. 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) .. method:: BLE.gatts_register_services(services_definition)