Merge branch 'docs/btdm_ble_ibeacon_example' into 'master'

docs: refactor BLE iBeacon demo readme

See merge request idf/esp-idf!2905

examples/bluetooth/ble_ibeacon/README.md

@@ -1,9 +1,113 @@
-ESP-IDF iBeacon demo
+# ESP-IDF iBeacon demo
-========================
+
-This example demonstrates iBeacon-compatible BLE advertising, and scanning of iBeacons.
+From welcoming people as they arrive at a sporting event to providing information about a nearby museum exhibit, iBeacon opens a new world of possibilities for location awareness, and countless opportunities for interactivity between iOS devices and iBeacon hardware.
-- IBEACON_SENDER: demo to send iBeacon-compatible advertising data.
+
-- IBEACON_RECEIVER: demo to receive and resolve iBeacon advertising data.
+## Using Example 
 
 iBeacon is a trademark of Apple Inc.
 
 Before building devices which use iBeacon technology, visit https://developer.apple.com/ibeacon/ to obtain a license.
+
+### iBeacon Mode
+
+This example demonstrates iBeacon-compatible BLE advertising, and scanning of iBeacons:
+
+- **IBEACON_SENDER**: demo to send iBeacon-compatible advertising data.
+ 
+- **IBEACON_RECEIVER**: demo to receive and resolve iBeacon advertising data.
+
+Which demo will be run depends on the menuconfig, developers can set it in `iBeacon Example Configuration`. 
+
+The default mode is iBeacon Sender.
+
+### Menuconfig
+Before compiling the demo，developers also need to configure the menuconfig:
+
+```c
+make menuconfig
+```
+And then enter `Component config->Bluetooth->Bluedroid Enable`
+
+Because the number of peripherals may be very large, developers can enable the **BLE Scan Duplicate Options**, the maximum number of devices in scan duplicate filter depends on the free heap size, when the cache is full, it is cleared.
+
+### Event Processing
+In the iBeacon receiver demo, the scan result will be posted to `ESP_GAP_SEARCH_INQ_RES_EVT` event:
+
+```c
+switch (scan_result->scan_rst.search_evt) {
+    case ESP_GAP_SEARCH_INQ_RES_EVT:
+    /* Search for BLE iBeacon Packet */
+    ......
+    break;
+    default:
+    break;
+}
+
+```
+### Build and Flash
+
+Build each project and flash it to the board, then run monitor tool to view serial output:
+
+```
+make -j4 flash monitor
+```
+
+(To exit the serial monitor, type ``Ctrl-]``.)
+
+See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
+
+## Example Output
+
+The iBeacon sender will broadcast iBeacon packet after initializing the Bluetooth protocol stack, and the iBeacon receiver will scan the iBeacon packet.
+
+### iBeacon Sender
+
+```
+I (384) boot: Loaded app from partition at offset 0x10000
+I (384) boot: Disabling RNG early entropy source...
+I (386) cpu_start: Pro cpu up.
+I (389) cpu_start: Starting app cpu, entry point is 0x40081010
+I (0) cpu_start: App cpu up.
+I (400) heap_init: Initializing. RAM available for dynamic allocation:
+I (406) heap_init: At 3FFAFF10 len 000000F0 (0 KiB): DRAM
+I (413) heap_init: At 3FFCCCA8 len 00013358 (76 KiB): DRAM
+I (419) heap_init: At 3FFE0440 len 00003BC0 (14 KiB): D/IRAM
+I (425) heap_init: At 3FFE4350 len 0001BCB0 (111 KiB): D/IRAM
+I (431) heap_init: At 40090E58 len 0000F1A8 (60 KiB): IRAM
+I (438) cpu_start: Pro cpu start user code
+I (120) cpu_start: Starting scheduler on PRO CPU
+I (0) cpu_start: Starting scheduler on APP CPU
+I (244) BTDM_INIT: BT controller compile version [44d04c1]
+
+I (244) system_api: Base MAC address is not set, read default base MAC address from BLK0 of EFUSE
+I (624) phy: phy_version: 3910, c0c45a3, May 21 2018, 18:07:06, 0, 0
+I (654) IBEACON_DEMO: register callback
+```
+
+### iBeacon Receiver
+
+```
+I (384) boot: Loaded app from partition at offset 0x10000
+I (384) boot: Disabling RNG early entropy source...
+I (385) cpu_start: Pro cpu up.\0x1b[0m
+I (389) cpu_start: Starting app cpu, entry point is 0x40081010
+I (0) cpu_start: App cpu up.
+I (400) heap_init: Initializing. RAM available for dynamic allocation:
+I (406) heap_init: At 3FFAFF10 len 000000F0 (0 KiB): DRAM
+I (412) heap_init: At 3FFCCC88 len 00013378 (76 KiB): DRAM
+I (418) heap_init: At 3FFE0440 len 00003BC0 (14 KiB): D/IRAM
+I (425) heap_init: At 3FFE4350 len 0001BCB0 (111 KiB): D/IRAM
+I (431) heap_init: At 40090E58 len 0000F1A8 (60 KiB): IRAM
+I (437) cpu_start: Pro cpu start user code\0x1b[0m
+I (120) cpu_start: Starting scheduler on PRO CPU.
+I (0) cpu_start: Starting scheduler on APP CPU.
+I (243) BTDM_INIT: BT controller compile version [44d04c1]
+
+I (243) system_api: Base MAC address is not set, read default base MAC address from BLK0 of EFUSE
+I (633) phy: phy_version: 3910, c0c45a3, May 21 2018, 18:07:06, 0, 0
+I (663) IBEACON_DEMO: register callback
+I (329203) IBEACON_DEMO: ----------iBeacon Found----------
+I (329203) IBEACON_DEMO: Device address:: 30 ae a4 00 42 82
+I (329203) IBEACON_DEMO: Proximity UUID:: fd a5 06 93 a4 e2 4f b1 af cf c6 eb 07 64 78 25
+```
+ 

examples/bluetooth/ble_ibeacon/main/Kconfig.projbuild

@@ -0,0 +1,26 @@
+menu "iBeacon Example Configuration"
+
+choice IBEACON_MODE
+    bool "iBeacon Mode"
+    default IBEACON_SENDER
+    help
+        Select the iBeacon Mode.
+
+config IBEACON_SENDER
+    bool "iBeacon Sender Mode"
+    help
+        Select the iBeacon Sender Mode.
+
+config IBEACON_RECEIVER
+    bool "iBeacon Receiver Mode"
+    help
+        Select the iBeacon Receiver Mode.
+
+endchoice
+
+config IBEACON_MODE
+    int
+    default 0 if IBEACON_SENDER
+    default 1 if IBEACON_RECEIVER
+
+endmenu

examples/bluetooth/ble_ibeacon/main/esp_ibeacon_api.h

@@ -31,7 +31,7 @@
  * so iBeacon sender and receiver should not run simultaneously */
 #define IBEACON_SENDER      0
 #define IBEACON_RECEIVER    1
-#define IBEACON_MODE IBEACON_SENDER
+#define IBEACON_MODE CONFIG_IBEACON_MODE
 
 /* Major and Minor part are stored in big endian mode in iBeacon packet,
  * need to use this macro to transfer while creating or processing