1# BTstack Port for the Espressif ESP32 Platform 2 3Status: Basic port incl. all examples. BTstack runs on dedicated FreeRTOS thread. Multi threading not supported. 4 5## Setup 6 7- Follow [Espressif IoT Development Framework (IDF) setup](https://github.com/espressif/esp-idf) to install xtensa toolchain. 8- Checkout our [esp-idf fork](https://github.com/mringwal/esp-idf) make IDF_PATH point to it. 9- In port/esp32, configure serial port for firmware upload as described before 10 11## Usage 12 13In port/esp32, run 14 15 ./create_examples.py 16 17Now, it creates project folders for all examples. Inside an example, e.g. in port/esp32/spp_and_le_counter, run 18 19 make 20 21to compile the example 22 23Run 24 25 make flash 26 27to upload it to your device. 28 29Run 30 31 make monitor 32 33to get the debug output. You can quit the monitor with CTRL-] 34 35## Limitations 36 37### Broken Host Controller to Host Flow Control 38There's currently no way to let the virtual HCI (VHCI) of the ESP32 know when data cannot be processed fast enough. For most applications, this won't be an issue, but please keep it in mind. See https://github.com/espressif/esp-idf/issues/480 39 40### Multi-threading 41 42BTstack is not thread-safe, but you're using a multi-threading OS. To call the BTstack API from other threads, there are currently two options: 43 44- *btstack_run_loop_freertos_single_threaded_execute_code_on_main_thread* allows to schedule a function callback from the BTstack thread. This function can call any BTstack function. Also, any function that is called from BTstack e.g. packet handler can directly call into BTstack without issues. 45- Setup a BTstack Data Source (btstack_data_source_t) and enable the polling callback (DATA_SOURCE_CALLBACK_POLL). The process function set in the data source will be called in every iteration of the BTstack Run Loop. To trigger a run loop iteration from a different thread, you can call *btstack_run_loop_freertos_trigger* 46 47With both options, the called function should check if there are any pending BTstack calls and execute them. The '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. 48We're considering different options to make BTstack thread-safe, but for now, please use one of the suggested options. 49 50### Acknowledgments 51 52First HCI Reset was sent to Bluetooth chipset by [@mattkelly](https://github.com/mattkelly) 53