1| Supported Targets | ESP32 | 2| ----------------- | ----- | 3 4# BLE Peripheral Example 5 6(See the README.md file in the upper level 'examples' directory for more information about examples.) 7 8This example creates GATT server and then starts advertising, waiting to be connected to a GATT client. 9 10It uses ESP32's Bluetooth controller and NimBLE stack based BLE host. 11 12This example aims at understanding GATT database configuration, advertisement and SMP related NimBLE APIs. 13 14It also demonstrates security features of NimBLE stack. SMP parameters like I/O capabilities of device, Bonding flag, MITM protection flag and Secure Connection only mode etc., can be configured through menuconfig options. 15 16For RPA feature (currently Host based privacy feature is supported), use API `ble_hs_pvcy_rpa_config` to enable/disable host based privacy, `own_addr_type` needs to be set to `BLE_ADDR_RANDOM` to use this feature. Please include `ble_hs_pvcy.h` while using this API. As `ble_hs_pvcy_rpa_config` configures host privacy and sets address in controller, it is necessary to call this API after host-controller are synced (e.g. in `bleprph_on_sync` callback). 17 18To test this demo, any BLE scanner app can be used. 19 20A Python based utility `bleprph_test.py` is also provided (which will run as a BLE GATT Client) and can be used to test this example. 21 22Note : 23 24* Make sure to run `python -m pip install --user -r $IDF_PATH/requirements.txt -r $IDF_PATH/tools/ble/requirements.txt` to install the dependency packages needed. 25* Currently this Python utility is only supported on Linux (BLE communication is via BLuez + DBus). 26 27## How to Use Example 28 29Before project configuration and build, be sure to set the correct chip target using: 30 31```bash 32idf.py set-target <chip_name> 33``` 34 35### Configure the project 36 37Open the project configuration menu: 38 39```bash 40idf.py menuconfig 41``` 42 43In the `Example Configuration` menu: 44 45* Select I/O capabilities of device from `Example Configuration --> I/O Capability`, default is `Just_works`. 46* Enable/Disable other security related parameters `Bonding, MITM option, secure connection(SM SC)`. 47 48### Build and Flash 49 50Run `idf.py -p PORT flash monitor` to build, flash and monitor the project. 51 52(To exit the serial monitor, type ``Ctrl-]``.) 53 54See the [Getting Started Guide](https://idf.espressif.com/) for full steps to configure and use ESP-IDF to build projects. 55 56## Example Output 57 58There is this console output when bleprph is connected and characteristic is read: 59 60``` 61I (118) BTDM_INIT: BT controller compile version [fe7ced0] 62I (118) system_api: Base MAC address is not set, read default base MAC address from BLK0 of EFUSE 63W (128) phy_init: failed to load RF calibration data (0xffffffff), falling back to full calibration 64I (268) phy: phy_version: 4100, 6fa5e27, Jan 25 2019, 17:02:06, 0, 2 65I (508) NimBLE_BLE_PRPH: BLE Host Task Started 66I (508) uart: queue free spaces: 8 67GAP procedure initiated: stop advertising. 68Device Address: xx:xx:xx:xx:xx:xx 69GAP procedure initiated: advertise; disc_mode=2 adv_channel_map=0 own_addr_type=0 adv_filter_policy=0 adv_itvl_min=0 adv_itvl_max=0 70connection established; status=0 handle=0 our_ota_addr_type=0 our_ota_addr=xx:xx:xx:xx:xx:xx our_id_addr_type=0 our_id_addr=xx:xx:xx:xx:xx:xx peer_ota_addr_type=1 peer_ota_addr=xx:xx:xx:xx:xx:xx peer_id_addr_type=1 peer_id_addr=xx:xx:xx:xx:xx:xx conn_itvl=39 conn_latency=0 supervision_timeout=500 encrypted=0 authenticated=0 bonded=0 71 72connection updated; status=0 handle=0 our_ota_addr_type=0 our_ota_addr=xx:xx:xx:xx:xx:xx our_id_addr_type=0 our_id_addr=xx:xx:xx:xx:xx:xx peer_ota_addr_type=1 peer_ota_addr=xx:xx:xx:xx:xx:xx peer_id_addr_type=1 peer_id_addr=xx:xx:xx:xx:xx:xx conn_itvl=6 conn_latency=0 supervision_timeout=500 encrypted=0 authenticated=0 bonded=0 73 74I (50888) NimBLE_BLE_PRPH: PASSKEY_ACTION_EVENT started 75 76I (50888) NimBLE_BLE_PRPH: Passkey on device's display: xxxxxx 77I (50888) NimBLE_BLE_PRPH: Accept or reject the passkey through console in this format -> key Y or key N 78key Y 79I (50898) NimBLE_BLE_PRPH: ble_sm_inject_io result: 0 80 81encryption change event; status=0 handle=0 our_ota_addr_type=0 our_ota_addr=xx:xx:xx:xx:xx:xx our_id_addr_type=0 our_id_addr=xx:xx:xx:xx:xx:xx peer_ota_addr_type=1 peer_ota_addr=xx:xx:xx:xx:xx:xx peer_id_addr_type=1 82peer_id_addr=xx:xx:xx:xx:xx:xx conn_itvl=6 conn_latency=0 supervision_timeout=500 encrypted=1 authenticated=1 bonded=1 83 84connection updated; status=0 handle=0 our_ota_addr_type=0 our_ota_addr=xx:xx:xx:xx:xx:xx our_id_addr_type=0 our_id_addr=xx:xx:xx:xx:xx:xx 85peer_ota_addr_type=1 peer_ota_addr=xx:xx:xx:xx:xx:xx peer_id_addr_type=1 peer_id_addr=xx:xx:xx:xx:xx:xx conn_itvl=39 conn_latency=0 supervision_timeout=500 encrypted=1 authenticated=1 bonded=1 86``` 87 88## Running Python Utility 89 90```bash 91python bleprph_test.py 92``` 93 94## Python Utility Output 95 96This is this output seen on the python side on successful connection: 97 98``` 99discovering adapter... 100bluetooth adapter discovered 101powering on adapter... 102bluetooth adapter powered on 103 104Started Discovery 105 106Connecting to device... 107 108Connected to device 109 110Services 111 112[dbus.String(u'00001801-0000-1000-8000-00805f9b34fb', variant_level=1), dbus.String(u'59462f12-9543-9999-12c8-58b459a2712d', variant_level=1)] 113 114Characteristics retrieved 115 116 Characteristic: /org/bluez/hci0/dev_xx_xx_xx_xx_xx_xx/service000a/char000b 117 Characteristic UUID: 5c3a659e-897e-45e1-b016-007107c96df6 118 Value: dbus.Array([dbus.Byte(45), dbus.Byte(244), dbus.Byte(81), dbus.Byte(88)], signature=dbus.Signature('y')) 119 Properties: : dbus.Array([dbus.String(u'read')], signature=dbus.Signature('s'), variant_level=1) 120 121 Characteristic: /org/bluez/hci0/dev_xx_xx_xx_xx_xx_xx/service000a/char000d 122 Characteristic UUID: 5c3a659e-897e-45e1-b016-007107c96df7 123 Value: dbus.Array([dbus.Byte(0)], signature=dbus.Signature('y')) 124 Properties: : dbus.Array([dbus.String(u'read'), dbus.String(u'write')], signature=dbus.Signature('s'), variant_level=1) 125 126 Characteristic: /org/bluez/hci0/dev_xx_xx_xx_xx_xx_xx/service0006/char0007 127 Characteristic UUID: 00002a05-0000-1000-8000-00805f9b34fb 128 Value: None 129 Properties: : dbus.Array([dbus.String(u'indicate')], signature=dbus.Signature('s'), variant_level=1) 130 131Characteristics after write operation 132 133 Characteristic: /org/bluez/hci0/dev_xx_xx_xx_xx_xx_xx/service000a/char000b 134 Characteristic UUID: 5c3a659e-897e-45e1-b016-007107c96df6 135 Value: dbus.Array([dbus.Byte(45), dbus.Byte(244), dbus.Byte(81), dbus.Byte(88)], signature=dbus.Signature('y')) 136 Properties: : dbus.Array([dbus.String(u'read')], signature=dbus.Signature('s'), variant_level=1) 137 138 Characteristic: /org/bluez/hci0/dev_xx_xx_xx_xx_xx_xx/service000a/char000d 139 Characteristic UUID: 5c3a659e-897e-45e1-b016-007107c96df7 140 Value: dbus.Array([dbus.Byte(65)], signature=dbus.Signature('y')) 141 Properties: : dbus.Array([dbus.String(u'read'), dbus.String(u'write')], signature=dbus.Signature('s'), variant_level=1) 142 143 Characteristic: /org/bluez/hci0/dev_xx_xx_xx_xx_xx_xx/service0006/char0007 144 Characteristic UUID: 00002a05-0000-1000-8000-00805f9b34fb 145 Value: None 146 Properties: : dbus.Array([dbus.String(u'indicate')], signature=dbus.Signature('s'), variant_level=1) 147 148exiting from test... 149disconnecting device... 150device disconnected 151powering off adapter... 152bluetooth adapter powered off 153``` 154 155## Note 156* NVS support is not yet integrated to bonding. So, for now, bonding is not persistent across reboot. 157 158## Troubleshooting 159 160For any technical queries, please open an [issue](https://github.com/espressif/esp-idf/issues) on GitHub. We will get back to you soon. 161
