sascha_hemi/pycom-documentation
1
0
Fork 0
mirror of https://github.com/sascha-hemi/pycom-documentation.git synced 2026-03-21 08:06:34 +01:00
Code Issues Packages Projects Releases Wiki Activity

Synchronize Bluetooth documentation between development-publish and publish branch

Browse Source
This commit is contained in:
Geza Husi
2020-02-25 07:29:48 +01:00
parent bc05f1d688
commit 61bb260082
3 changed files with 86 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files

86
content/firmwareapi/pycom/network/bluetooth/_index.md
View File

@@ -1,6 +1,7 @@
---
title: "Bluetooth"
aliases:
- chapter/firmwareapi/pycom/network/bluetooth
---
This class provides a driver for the Bluetooth radio in the module. Currently, only basic BLE functionality is available.
@@ -60,14 +61,18 @@ bluetooth = Bluetooth()
## Methods
### bluetooth.init(id=0, mode=Bluetooth.BLE, antenna=None, secure=False)
#### bluetooth.init(id=0, mode=Bluetooth.BLE, antenna=None, modem\_sleep=True, pin=None, privacy=True, secure\_connections=True, mtu=200)
* `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`.
* `secure` enables or disables the GATT Server security features.
* `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.
* `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.
* `secure_connections` Enables or Disables Secure Connections and MITM Protection.
* `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.
Initialises and enables the Bluetooth radio in BLE mode.
@@ -84,7 +89,7 @@ Pin('P12', mode=Pin.OUT)(True)
Disables the Bluetooth radio.
### 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.
@@ -95,20 +100,19 @@ The arguments are:
Examples:
```python
bluetooth.start_scan(10) # starts scanning and stop after 10 seconds
bluetooth.start_scan(-1) # starts scanning indefinitely until bluetooth.stop_scan() is called
```
### bluetooth.stop\_scan()
#### bluetooth.stop\_scan()
Stops an ongoing scanning process. Returns `None`.
### bluetooth.isscanning()
#### bluetooth.isscanning()
Returns `True` if a Bluetooth scan is in progress. `False` otherwise.
### bluetooth.get\_adv()
#### bluetooth.get\_adv()
Gets an named tuple with the advertisement data received during the scanning. The tuple has the following structure: `(mac, addr_type, adv_type, rssi, data)`
@@ -121,7 +125,6 @@ Gets an named tuple with the advertisement data received during the scanning. Th
Example for getting `mac` address of an advertiser:
```python
import ubinascii
bluetooth = Bluetooth()
@@ -131,11 +134,11 @@ adv = bluetooth.get_adv() #
ubinascii.hexlify(adv.mac) # convert hexadecimal to ascii
```
### bluetooth.get\_advertisements()
#### bluetooth.get\_advertisements()
Same as the `get_adv()` method, but this one returns a list with all the advertisements received.
### bluetooth.resolve\_adv\_data(data, data\_type)
#### bluetooth.resolve\_adv\_data(data, data\_type)
Parses the advertisement data and returns the requested `data_type` if present. If the data type is not present, the function returns `None`.
@@ -147,7 +150,6 @@ Arguments:
Example:
```python
import ubinascii
from network import Bluetooth
bluetooth = Bluetooth()
@@ -166,18 +168,20 @@ while bluetooth.isscanning():
print(ubinascii.hexlify(mfg_data))
```
### bluetooth.connect(mac\_addr)
#### bluetooth.set\_pin()
Opens a BLE connection with the device specified by the `mac_addr` argument. This function blocks until the connection succeeds or fails. If the connections succeeds it returns a object of type `GATTCConnection`.
Configures a new PIN to be used by the device. The PIN is a 1-6 digit length decimal number, if less than 6 digits are given the missing leading digits are considered as 0. E.g. 1234 becomes 001234. When a new PIN is configured, the information of all previously bonded device is removed and the current connection is terminated. To restart advertisement the advertise() must be called after PIN is changed.
Connections are initiated by the central device. There is a maximum of 4 simultaneous connections.
#### bluetooth.connect(mac\_addr, timeout=None)
* `mac_addr` is the address of the remote device to connect
* `timeout` specifies the amount of time in milliseconds to wait for the connection process to finish. If not given then no timeout is applied The function blocks until the connection succeeds or fails (raises OSError) or the given `timeout` expires (raises `Bluetooth.timeout TimeoutError`). If the connections succeeds it returns a object of type `GATTCConnection`.
```python
bluetooth.connect('112233eeddff') # mac address is accepted as a string
```
### bluetooth.callback(trigger=None, handler=None, arg=None)
#### bluetooth.callback(trigger=None, handler=None, arg=None)
Creates a callback that will be executed when any of the triggers occurs. The arguments are:
@@ -187,14 +191,13 @@ Creates a callback that will be executed when any of the triggers occurs. The ar
An example of how this may be used can be seen in the [`bluetooth.events()`](./#bluetooth-events) method.
### bluetooth.events()
#### bluetooth.events()
Returns a value with bit flags identifying the events that have occurred since the last call. Calling this function clears the events.
Example of usage:
```python
from network import Bluetooth
bluetooth = Bluetooth()
@@ -212,7 +215,7 @@ bluetooth.callback(trigger=Bluetooth.CLIENT_CONNECTED | Bluetooth.CLIENT_DISCONN
bluetooth.advertise(True)
```
### 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.
@@ -226,15 +229,27 @@ The arguments are:
Example:
```python
bluetooth.set_advertisement(name="advert", manufacturer_data="lopy_v1")
```
### bluetooth.advertise(\[Enable\])
#### bluetooth.set\_advertisement\_params(\* , adv\_int\_min=0x20, adv\_int\_max=0x40, adv\_type=Bluetooth.ADV\_TYPE\_IND, own\_addr\_type=Bluetooth.BLE\_ADDR\_TYPE\_PUBLIC, channel\_map=Bluetooth.ADV\_CHNL\_ALL, adv\_filter\_policy=Bluetooth.ADV\_FILTER\_ALLOW\_SCAN\_ANY\_CON\_ANY)
Configure the parameters used when advertising.
The arguments are:
* `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.
* `channel_map` is the advertising channel map.
* `adv_filter_policy` is the advertising filter policy.
#### bluetooth.advertise(\[Enable\])
Start or stop sending advertisements. The `set_advertisement()` method must have been called prior to this one.
### bluetooth.service(uuid, \* , isprimary=True, nbr\_chars=1, start=True)
#### bluetooth.service(uuid, \* , isprimary=True, nbr\_chars=1, start=True)
Create a new service on the internal GATT server. Returns a object of type `BluetoothServerService`.
@@ -246,20 +261,35 @@ The arguments are:
* `start` if `True` the service is started immediately.
```python
bluetooth.service('abc123')
```
### bluetooth.disconnect\_client()
#### bluetooth.disconnect\_client()
Closes the BLE connection with the client.
### 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.
If both `type` and `level` parameters are given, it sets the TX Power.
Valid values for `type`: `Bluetooth.TX_PWR_CONN` -> for handling connection, `Bluetooth.TX_PWR_ADV` -> for advertising, `Bluetooth.TX_PWR_SCAN` -> for scan, `Bluetooth.TX_PWR_DEFAULT` -> default, if others not set
Valid values for `level`: Bluetooth.TX_PWR_N12` -> -12dbm, `Bluetooth.TX_PWR_N9` -> -9dbm, `Bluetooth.TX_PWR_N6` -> -6dbm, `Bluetooth.TX_PWR_N3` -> -3dbm, `Bluetooth.TX_PWR_0` -> 0dbm, `Bluetooth.TX_PWR_P3` -> 3dbm, `Bluetooth.TX_PWR_P6` -> 6dbm, `Bluetooth.TX_PWR_P9` -> 9dbm
## Constants
* Bluetooth mode: `Bluetooth.BLE`
* Advertisement type: `Bluetooth.CONN_ADV`, `Bluetooth.CONN_DIR_ADV`, `Bluetooth.DISC_ADV`, `Bluetooth.NON_CONN_ADV`, `Bluetooth.SCAN_RSP`
* Address type: `Bluetooth.PUBLIC_ADDR`, `Bluetooth.RANDOM_ADDR`, `Bluetooth.PUBLIC_RPA_ADDR`, `Bluetooth.RANDOM_RPA_ADDR`
* Advertisement data type: `Bluetooth.ADV_FLAG`, `Bluetooth.ADV_16SRV_PART`, `Bluetooth.ADV_T16SRV_CMPL`, `Bluetooth.ADV_32SRV_PART`, `Bluetooth.ADV_32SRV_CMPL`, `Bluetooth.ADV_128SRV_PART`, `Bluetooth.ADV_128SRV_CMPL`, `Bluetooth.ADV_NAME_SHORT`, `Bluetooth.ADV_NAME_CMPL`, `Bluetooth.ADV_TX_PWR`, `Bluetooth.ADV_DEV_CLASS`, `Bluetooth.ADV_SERVICE_DATA`, `Bluetooth.ADV_APPEARANCE`, `Bluetooth.ADV_ADV_INT`, `Bluetooth.ADV_32SERVICE_DATA`, `Bluetooth.ADV_128SERVICE_DATA`, `Bluetooth.ADV_MANUFACTURER_DATA`
* Advertisement parameters: `Bluetooth.ADV_TYPE_IND`, `Bluetooth.ADV_TYPE_DIRECT_IND_HIGH`, `Bluetooth.ADV_TYPE_SCAN_IND`, `Bluetooth.ADV_TYPE_NONCONN_IND`, `Bluetooth.ADV_TYPE_DIRECT_IND_LOW`, `Bluetooth.ADV_BLE_ADDR_TYPE_PUBLIC`, `Bluetooth.ADV_BLE_ADDR_TYPE_RANDOM`, `Bluetooth.ADV_BLE_ADDR_TYPE_RPA_PUBLIC`, `Bluetooth.ADV_BLE_ADDR_TYPE_RPA_RANDOM`, `Bluetooth.ADV_CHNL_37`, `Bluetooth.ADV_CHNL_38`, `Bluetooth.ADV_CHNL_39`, `Bluetooth.ADV_CHNL_ALL`, `Bluetooth.ADV_FILTER_ALLOW_SCAN_ANY_CON_ANY`, `Bluetooth.ADV_FILTER_ALLOW_SCAN_WLST_CON_ANY`, `Bluetooth.ADV_FILTER_ALLOW_SCAN_ANY_CON_WLST`, `Bluetooth.ADV_FILTER_ALLOW_SCAN_WLST_CON_WLST`
* Characteristic properties (bit values that can be combined): `Bluetooth.PROP_BROADCAST`, `Bluetooth.PROP_READ`, `Bluetooth.PROP_WRITE_NR`, `Bluetooth.PROP_WRITE`, `Bluetooth.PROP_NOTIFY`, `Bluetooth.PROP_INDICATE`, `Bluetooth.PROP_AUTH`, `Bluetooth.PROP_EXT_PROP`
* Characteristic callback events: `Bluetooth.CHAR_READ_EVENT`, `Bluetooth.CHAR_WRITE_EVENT`, `Bluetooth.NEW_ADV_EVENT`, `Bluetooth.CLIENT_CONNECTED`, `Bluetooth.CLIENT_DISCONNECTED`, `Bluetooth.CHAR_NOTIFY_EVENT`
* Antenna type: `Bluetooth.INT_ANT`, `Bluetooth.EXT_ANT`
* TX Power type: `Bluetooth.TX_PWR_CONN`, `Bluetooth.TX_PWR_ADV`, `Bluetooth.TX_PWR_SCAN`, `Bluetooth.TX_PWR_DEFAULT`
* TX Power level: `Bluetooth.TX_PWR_N12`, `Bluetooth.TX_PWR_N9`, `Bluetooth.TX_PWR_N6`, `Bluetooth.TX_PWR_N3`, `Bluetooth.TX_PWR_0`, `Bluetooth.TX_PWR_P3`, `Bluetooth.TX_PWR_P6`, `Bluetooth.TX_PWR_P9`
## Exceptions
* `Bluetooth.timeout`

61
content/firmwareapi/pycom/network/bluetooth/gattscharacteristic.md
View File

@@ -21,29 +21,29 @@ characteristic.value(123) # set characteristic value to an integer with the valu
characteristic.value() # get characteristic value
```
#### characteristic.events()
Returns a value with bit flags, identifying the events that have occurred since the last call. Calling this function clears the events.
#### characteristic.callback(trigger=None, handler=None, arg=None)
Creates a callback that will be executed when any of the triggers occurs. The arguments are:
Creates a callback that will be executed when any of the triggers occur. The arguments are:
* `trigger` can be either `Bluetooth.CHAR_READ_EVENT` or `Bluetooth.CHAR_WRITE_EVENT`.
* `handler` is the function that will be executed when the callback is triggered.
* `arg` is the argument that gets passed to the callback. If nothing is given, the characteristic object that owns the callback will be used.
An example of how this could be implemented can be seen in the [`characteristic.events()` ](gattscharacteristic.md#characteristic-events)section.
Beyond the `arg` a tuple (called `data`) is also passed to `handler`. The tuple consists of (event, value), where `event` is the triggering event and `value` is the value strictly belonging to the `event` in case of a WRITE event. If the `event` is not a WRITE event, the `value` has no meaning.
#### characteristic.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.
The reason behind this is that `characteristic.event()` and `characteristic.value()` return with the very last event received and with the current value of the characteristic, while the input parameters are always linked to the specific event triggering the `handler`. If the device is busy executing other operations, the `handler` of an incoming event may not be called before the next event occurs and is processed.
Returns a value with bit flags identifying the events that have occurred since the last call. Calling this function clears the events.
An example of advertising and creating services on the device:
An example of how this can be implemented is shown below, via an example of advertising and creating services on the device:
```python
from network import Bluetooth
bluetooth = Bluetooth()
bluetooth.set_advertisement(name='LoPy', service_uuid=b'1234567890123456')
def conn_cb (bt_o):
events = bt_o.events()
if events & Bluetooth.CLIENT_CONNECTED:
@@ -51,40 +51,33 @@ def conn_cb (bt_o):
elif events & Bluetooth.CLIENT_DISCONNECTED:
print("Client disconnected")
bluetooth.callback(trigger=Bluetooth.CLIENT_CONNECTED | Bluetooth.CLIENT_DISCONNECTED, handler=conn_cb)
def char1_cb_handler(chr, data):
# The data is a tuple containing the triggering event and the value if the event is a WRITE event.
# We recommend fetching the event and value from the input parameter, and not via characteristic.event() and characteristic.value()
events, value = data
if events & Bluetooth.CHAR_WRITE_EVENT:
print("Write request with value = {}".format(value))
else:
print('Read request on char 1')
def char2_cb_handler(chr, data):
# The value is not used in this callback as the WRITE events are not processed.
events, value = data
if events & Bluetooth.CHAR_READ_EVENT:
print('Read request on char 2')
bluetooth = Bluetooth()
bluetooth.set_advertisement(name='LoPy', service_uuid=b'1234567890123456')
bluetooth.callback(trigger=Bluetooth.CLIENT_CONNECTED | Bluetooth.CLIENT_DISCONNECTED, handler=conn_cb)
bluetooth.advertise(True)
srv1 = bluetooth.service(uuid=b'1234567890123456', isprimary=True)
chr1 = srv1.characteristic(uuid=b'ab34567890123456', value=5)
char1_read_counter = 0
def char1_cb_handler(chr):
global char1_read_counter
char1_read_counter += 1
events = chr.events()
if events & Bluetooth.CHAR_WRITE_EVENT:
print("Write request with value = {}".format(chr.value()))
else:
if char1_read_counter < 3:
print('Read request on char 1')
else:
return 'ABC DEF'
char1_cb = chr1.callback(trigger=Bluetooth.CHAR_WRITE_EVENT | Bluetooth.CHAR_READ_EVENT, handler=char1_cb_handler)
srv2 = bluetooth.service(uuid=1234, isprimary=True)
chr2 = srv2.characteristic(uuid=4567, value=0x1234)
char2_read_counter = 0xF0
def char2_cb_handler(chr):
global char2_read_counter
char2_read_counter += 1
if char2_read_counter > 0xF1:
return char2_read_counter
char2_cb = chr2.callback(trigger=Bluetooth.CHAR_READ_EVENT, handler=char2_cb_handler)
```

3
content/firmwareapi/pycom/network/bluetooth/gattsservice.md
View File

@@ -27,7 +27,7 @@ Stops the service if previously started.
Creates a new characteristic on the service. Returns an object of the class `GATTSCharacteristic`. The arguments are:
* `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.
* `properties` sets the properties. Takes an integer with an OR-ed combination of the flags.
* `value` sets the initial value. Can take an integer, a string or a bytes object.
@@ -35,4 +35,3 @@ Creates a new characteristic on the service. Returns an object of the class `GAT
service.characteristic('temp', value=25)
```