Synchronize Bluetooth documentation between development-publish and publish branch

content/firmwareapi/pycom/network/bluetooth/_index.md

@@ -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)
 
-```python
+* `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`

content/firmwareapi/pycom/network/bluetooth/gattscharacteristic.md

@@ -21,70 +21,63 @@ 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()
-
-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.
+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.
 
-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:
  print("Client connected")
  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)
 ```
 

content/firmwareapi/pycom/network/bluetooth/gattsservice.md

@@ -27,12 +27,11 @@ 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.
 
 ```python
 
 service.characteristic('temp', value=25)
 ```
-