Synchronize Bluetooth documentation between development-publish and publish branch #233
Conversation
| * `id` Only one Bluetooth peripheral available so must always be 0. | ||
| * `mode` currently the only supported mode is `Bluetooth.BLE`. | ||
| * `antenna` selects between the internal and the external antenna. Can be either `Bluetooth.INT_ANT`, `Bluetooth.EXT_ANT`. | ||
| * `modem_sleep` Enables or Disables BLE modem sleep, Disable modem sleep as a workaround when having Crashes due to flash cache being disabled, as this prevents BLE task saving data in external RAM while accesing external flash for R/W. |
There was a problem hiding this comment.
1st: Enables or Disables BLE modem sleep. Disable modem sleep is a workaround when experiencing crashes due to the flash cache being disabled. It prevents the BLE task saving data in the external RAM while accessing the external flash for R/W.
| * `mode` currently the only supported mode is `Bluetooth.BLE`. | ||
| * `antenna` selects between the internal and the external antenna. Can be either `Bluetooth.INT_ANT`, `Bluetooth.EXT_ANT`. | ||
| * `modem_sleep` Enables or Disables BLE modem sleep, Disable modem sleep as a workaround when having Crashes due to flash cache being disabled, as this prevents BLE task saving data in external RAM while accesing external flash for R/W. | ||
| * `pin` a one to six digit number (`0`-`9`) to connect to the GATT Sever. Setting any valid pin, GATT Server security features are activated. |
There was a problem hiding this comment.
2nd: By setting a valid pin, the GATT Server security features are activated.
| * `antenna` selects between the internal and the external antenna. Can be either `Bluetooth.INT_ANT`, `Bluetooth.EXT_ANT`. | ||
| * `modem_sleep` Enables or Disables BLE modem sleep, Disable modem sleep as a workaround when having Crashes due to flash cache being disabled, as this prevents BLE task saving data in external RAM while accesing external flash for R/W. | ||
| * `pin` a one to six digit number (`0`-`9`) to connect to the GATT Sever. Setting any valid pin, GATT Server security features are activated. | ||
| * `privacy` Enables or Disables local privacy settings so address will be random or public. |
There was a problem hiding this comment.
3rd: Enables or disables the local privacy settings so the address will be random or public.
| * `mtu` Maximum Transmission Unit (MTU) is the maximum length of an ATT packet. Value must be between `23` and `200`. | ||
| | ||
| With our development boards it defaults to using the internal antenna, but in the case of an OEM module, the antenna pin (`P12`) is not used, so it's free to be used for other things. | ||
| With our development boards it defaults to using the internal antenna, but in the case of an OEM module, the antenna pin (`P12`) is not used, so it's free to be used for other things. |
There was a problem hiding this comment.
4th: Our development boards' default is to use the internal antenna. However, with the OEM module, the antenna pin (P12) is not used so it's free to be used for other things.
| ### bluetooth.start\_scan(timeout) | ||
| #### bluetooth.start\_scan(timeout) | ||
| | ||
| Starts performing a scan listening for BLE devices sending advertisements. This function always returns immediately, the scanning will be performed on the background. The return value is `None`. After starting the scan the function `get_adv()` can be used to retrieve the advertisements messages from the FIFO. The internal FIFO has space to cache 16 advertisements. |
There was a problem hiding this comment.
5th: Starts performing a scan, listening for BLE devices sending advertisements. This function always returns immediately and the scanning will be performed in the background. The return value is None.
After starting the scan, the function get_adv() can be used to retrieve the advertisement's messages from the FIFO. The internal FIFO has space to cache 16 advertisements.
| ### bluetooth.set\_advertisement(\* , name=None, manufacturer\_data=None, service\_data=None, service\_uuid=None) | ||
| #### bluetooth.set\_advertisement(\* , name=None, manufacturer\_data=None, service\_data=None, service\_uuid=None) | ||
| | ||
| Configure the data to be sent while advertising. If left with the default of `None` the data won't be part of the advertisement message. |
There was a problem hiding this comment.
13th: Configures the data to be sent whilst advertising. If left with the default of None, the data won't be part of the advertisement message.
| * `adv_int_min` is the minimum advertising interval for undirected and low duty cycle directed advertising. | ||
| * `adv_int_max` is the maximum advertising interval for undirected and low duty cycle directed advertising. | ||
| * `adv_type` is the advertising type. | ||
| * `own_addr_type` is the owner bluetooth device address type. |
There was a problem hiding this comment.
14th: is the owner's bluetooth device address type.
| ### bluetooth.tx\_power(type, level) | ||
| | ||
| Gets or sets the TX Power level. | ||
| If called with only `type` parameter it returns with the current value belonging to the given type. |
There was a problem hiding this comment.
15th: If called with only type parameter, it returns with the current value belonging to the given type.
| #### characteristic.events() | ||
| | ||
| Returns a value with bit flags identifying the events that have occurred since the last call. Calling this function clears the events. | ||
| We recommend getting both the `event` and new `value` of the characteristic via this tuple, and not via `characteristic.event()` and `characteristic.value()` calls in the context of the `handler` to make sure no event and value is lost. |
There was a problem hiding this comment.
16th: We recommend getting both the event and new value of the characteristic via this tuple, and not via characteristic.event() and characteristic.value() calls in the context of the handler. This is to make sure that no event and value is lost.
| | ||
| * `uuid` is the UUID of the service. Can take an integer or a 16 byte long string or bytes object. | ||
| * `permissions` configures the permissions of the characteristic. Takes an integer with a combination of the flags. | ||
| * `permissions` configures the permissions of the characteristic. Takes an integer with a combination of the flags. When bluetooth object is initialized with PIN, read and write permissions are set to encrypted. Setting PIN later with set_pin() call does not affect the permissions of the already existing characteristics, thus they will remain not secured. |
There was a problem hiding this comment.
17th: When the bluetooth object is initialized with the PIN, read and write permissions are set to encrypted. Setting the PIN later with the set_pin() call does not affect the permissions of the already existing characteristics, thus they will remain unsecured.
| @lilycey : let me not modify these things as this is just a synchronization commit between the documentation of the development release and stable release. These corrections should be made in both documentation. |
3 participants
To be merged when the 2 features from the beginning of the list below are released in a stable release.
In this PR the currently latest version of Bluetooth documentation from "development-publish" is synchronized with "publish" branch as there were lots of not documented, but already released, changes: