1# BTstack Port for the Espressif ESP32 Platform 2 3Status: Basic port incl. all examples. BTstack runs on dedicated FreeRTOS thread. Multi threading (calling BTstack functions from a different thread) is not supported. 4 5## Setup 6 7- Follow [Espressif IoT Development Framework (ESP-IDF) setup](https://github.com/espressif/esp-idf) to install XTensa toolchain and the ESP-IDF. 8- Make sure your checkout is newer than 4654278b1bd6b7f7f55013f7edad76109f7ee944 from Aug 25th, 2017 9- In port/esp32/template, configure the serial port for firmware upload as described in the ESP-IDF setup guides. 10 11## Usage 12 13In port/esp32, run 14 15 ./integrate_btstack.sh 16 17The script will copy parts of the BTstack tree into the ESP-IDF as $IDF_PATH/components/btstack and then create project folders for all examples. Each example project folder, e.g. port/esp32/examples/spp_and_le_counter, contains a Makefile. Please run the command again after updating the BTstack tree to also update the copy in the ESP-IDF. 18 19To compile an example, run: 20 21 make 22 23 24To upload the binary to your device, run: 25 26 make flash 27 28 29To get the debug output, run: 30 31 make monitor 32 33You can quit the monitor with CTRL-]. 34 35## Old Make Versions 36 37Compilation fails with older versions of the make tool, e.g. make 3.8.1 (from 2006) providedby the current Xcode 9 on macOS. 38Interestingly, if you run make a second time, it completes the compilation. 39 40## Configuration 41 42The sdkconfig of the example template disables the original Bluedroid stack by disabling the CONFIG_BLUEDROID_ENABLED kconfig option. 43 44## Limitations 45 46### Bug in Host Controller to Host Flow Control implementation 47The Link Layer in the ESP32 does not reset the supervision timeout while the Host does not accept new packets (due to slow processing etc..), which will eventually triggger a disconnect based on Connection Timeout (reason 8). See https://github.com/espressif/esp-idf/issues/644#issuecomment-325251315 48 49For most applications, this won't be an issue, but please keep it in mind if you're LE data processing is very slow. 50 51### Multi-Threading 52 53BTstack is not thread-safe, but you're using a multi-threading OS. Any function that is called from BTstack, e.g. packet handlers, can directly call into BTstack without issues. For other situations, you need to provide some general 'do BTstack tasks' function and trigger BTstack to execute it on its own thread. 54To call a function from the BTstack thread, there are currently two options: 55 56- *btstack_run_loop_freertos_execute_code_on_main_thread* allows to directly schedule a function callback, i.e. 'do BTstack tasks' function, from the BTstack thread. 57- Setup a BTstack Data Source (btstack_data_source_t): 58 Set 'do BTstack tasks' function as its process function and enable its polling callback (DATA_SOURCE_CALLBACK_POLL). The process function will be called in every iteration of the BTstack Run Loop. To trigger a run loop iteration, you can call *btstack_run_loop_freertos_trigger*. 59 60With both options, the called function should check if there are any pending BTstack tasks and execute them. 61 62The 'run on main thread' method is only provided by a few ports and requires a queue to store the calls. This should be used with care, since calling it multiple times could cause the queue to overflow. 63 64We're considering different options to make BTstack thread-safe, but for now, please use one of the suggested options. 65 66### Acknowledgments 67 68First HCI Reset was sent to Bluetooth chipset by [@mattkelly](https://github.com/mattkelly) 69