README.md
1| Supported Targets | ESP32 |
2| ----------------- | ----- |
3
4# ESP-IDF BT-SPP-INITATOR demo
5
6This is the demo for user to use ESP_APIs to create a **Serial Port Protocol** (**SPP**) initiator and we aggregate **Secure Simple Pair** (**SSP**) into this demo to show how to use SPP when creating your own APPs.
7
8## How to use example
9
10### Hardware Required
11
12This example is designed to run on commonly available ESP32 development board, e.g. ESP32-DevKitC. To operate it should be connected to an SPP Acceptor running on another device.
13
14### Configure the project
15
16```
17idf.py menuconfig
18```
19
20In `menuconfig` path: `Coponent config --> Bluetooth--> Bluedroid Options -->SPP` and `Coponent config --> Bluetooth--> Bluedroid Options -->Secure Simple Pair`.
21
22### Build and Flash
23
24Build the project and flash it to the board, then run monitor tool to view serial output:
25
26```
27idf.py -p PORT flash monitor
28```
29
30(Replace PORT with the name of the serial port to use.)
31
32(To exit the serial monitor, type ``Ctrl-]``.)
33
34See the [Getting Started Guide](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/index.html) for full steps to configure and use ESP-IDF to build projects.
35
36### Example Output
37
38When you run this example and the IO capability is `ESP_IO_CAP_IO` or `ESP_IO_CAP_IN` , the commands help table prints the following at the very beginning:
39
40```
41########################################################################
42Supported commands are as follows, arguments are embraced with < and >
43spp h; -- show command manual
44
45Use this cmmand table if the IO Capability of local device set as IO_CAP_IO.
46spp ok; -- manual Numeric Confirmation.
47
48Use this cmmand table if the IO Capability of local device set as IO_CAP_IN.
49spp key <auth key>; -- manual Passkey. (e.g. spp key 136245;)
50
51########################################################################
52```
53
54**Note:**
55
56- Only after SPP service is initialized and a service level connection exists between an Initiator and Acceptor device, could other commands be available.
57- This command help table will print out in monitor whenever you type `spp h;` or if you input a command that is not required by the command parse rule.
58
59- Commands should always start with `spp` and end with `;` or the example will not responds.
60
61- The command you typed will not echo in monitor.
62
63### Situation under `ESP_IO_CAP_IN`
64
65The log in terminal will indicate you to input the passkey to initiate the connection of SPP.
66
67```
68I (2244) SPP_INITIATOR_DEMO: ESP_BT_GAP_DISC_RES_EVT
69I (2244) SPP_INITIATOR_DEMO: ......
70I (2394) SPP_INITIATOR_DEMO: ESP_BT_GAP_DISC_RES_EVT
71I (2404) SPP_INITIATOR_DEMO: ......
72I (2404) SPP_INITIATOR_DEMO: ESP_SPP_ACCEPTOR
73I (2414) SPP_INITIATOR_DEMO: ESP_BT_GAP_DISC_STATE_CHANGED_EVT
74I (3274) SPP_INITIATOR_DEMO: ESP_SPP_DISCOVERY_COMP_EVT status=0 scn_num=1
75I (3284) SPP_INITIATOR_DEMO: ESP_SPP_CL_INIT_EVT
76I (3454) SPP_INITIATOR_DEMO: ESP_BT_GAP_KEY_REQ_EVT Please enter passkey!
77W (3454) SPP_INITIATOR_DEMO: To input the key, type `spp key xxxxxx;`
78```
79
80### Situation under `ESP_IO_CAP_IO`
81
82The log in terminal will indicate you to confirm the number to initiate the connection of SPP.
83
84```
85I (2342) SPP_INITIATOR_DEMO: ESP_BT_GAP_DISC_RES_EVT
86I (2342) SPP_INITIATOR_DEMO: 30 ae a4 80 18 32
87I (2342) SPP_INITIATOR_DEMO: ESP_SPP_ACCEPTOR
88I (2352) SPP_INITIATOR_DEMO: ESP_BT_GAP_DISC_STATE_CHANGED_EVT
89I (3212) SPP_INITIATOR_DEMO: ESP_SPP_DISCOVERY_COMP_EVT status=0 scn_num=1
90I (3222) SPP_INITIATOR_DEMO: ESP_SPP_CL_INIT_EVT
91I (3392) SPP_INITIATOR_DEMO: ESP_BT_GAP_CFM_REQ_EVT Please compare the numeric value: 864115
92W (3392) SPP_INITIATOR_DEMO: To confirm the value, type `spp ok;`
93```
94
95**Note:**
96
97Whether you should passkey or confirm the number also depends on the IO capability of the peer device. And whether the two device are already paired before.
98
99## Troubleshouting
100
101- Set `SPP_SHOW_MODE` as `SPP_SHOW_DATA` or `SPP_SHOW_SPEED` in code (should be same with bt_spp_acceptor).
102
103- After the program started, It will connect to bt_spp_acceptor and send data.
104
105- We haven't do the same update to `bt_acceptor_demo` for the sake of reducing the size of ESP_IDF, but transplanting of input module is supported.
106
107- We also show the Security Simple Pair in this SPP demo. Users can set the IO Capability and Security Mode for their device (security level is fixed level 4). The default security mode of this demo is `ESP_SPP_SEC_AUTHENTICATE` which support MITM (Man In The Middle) protection. For more information about Security Simple Pair on ESP32, please refer to [ESP32_SSP](../bt_spp_acceptor/ESP32_SSP.md).
108
109## Example Breakdown
110
111To clearly show how the SSP aggregate with the SPP , we use the Commands and Effects scheme to illustrate the process of secure paring and connection establishment.
112
113- The example will respond to user command through UART console. Please go to `console_uart.c` for the configuration details.
114
115- If you want to update the command table, please refer to `app_spp_msg_set.c`.
116
117- If you want to update the command parse rules, please refer to `app_spp_msg_prs.c`.
118
119- If you want to update the responses of HF Unit or want to update the log, please refer to `bt_app_spp.c`.
120
121- Task configuration part is in `example_spp_initiator_demo.c`.
122
