1edbc01eeSMatthias Ringwald# BTstack Port for the Espressif ESP32 Platform 2edbc01eeSMatthias Ringwald 3*2d4acfc3SMatthias RingwaldStatus: Basic port incl. all examples. BTstack runs on dedicated FreeRTOS thread. Multi threading not supported. 4edbc01eeSMatthias Ringwald 5edbc01eeSMatthias Ringwald## Setup 6edbc01eeSMatthias Ringwald 7f69d0bf9SMatthias Ringwald- Follow [Espressif IoT Development Framework (IDF) setup](https://github.com/espressif/esp-idf) to install xtensa toolchain. 8d238d4bbSMatthias Ringwald- Checkout our [esp-idf fork](https://github.com/mringwal/esp-idf) make IDF_PATH point to it. 9edbc01eeSMatthias Ringwald- In port/esp32, configure serial port for firmware upload as described before 10edbc01eeSMatthias Ringwald 11edbc01eeSMatthias Ringwald## Usage 12edbc01eeSMatthias Ringwald 13a681a241SMatthias RingwaldIn port/esp32, run 14a681a241SMatthias Ringwald 15*2d4acfc3SMatthias Ringwald ./create_examples.py 16a681a241SMatthias Ringwald 17*2d4acfc3SMatthias RingwaldNow, it creates project folders for all examples. Inside an example, e.g. in port/esp32/spp_and_le_counter, run 18edbc01eeSMatthias Ringwald 19edbc01eeSMatthias Ringwald make 20edbc01eeSMatthias Ringwald 21a681a241SMatthias Ringwaldto compile the example 22edbc01eeSMatthias Ringwald 23edbc01eeSMatthias RingwaldRun 24edbc01eeSMatthias Ringwald 25edbc01eeSMatthias Ringwald make flash 26edbc01eeSMatthias Ringwald 27edbc01eeSMatthias Ringwaldto upload it to your device. 28edbc01eeSMatthias Ringwald 29*2d4acfc3SMatthias RingwaldRun 30*2d4acfc3SMatthias Ringwald 31*2d4acfc3SMatthias Ringwald make monitor 32*2d4acfc3SMatthias Ringwald 33*2d4acfc3SMatthias Ringwaldto get the debug output. You can quit the monitor with CTRL-] 34*2d4acfc3SMatthias Ringwald 35*2d4acfc3SMatthias Ringwald## Limitations 36*2d4acfc3SMatthias Ringwald 37*2d4acfc3SMatthias Ringwald### Broken Host Controller to Host Flow Control 38*2d4acfc3SMatthias RingwaldThere'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*2d4acfc3SMatthias Ringwald 40*2d4acfc3SMatthias Ringwald### Multi-threading 41*2d4acfc3SMatthias Ringwald 42*2d4acfc3SMatthias RingwaldBTstack 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*2d4acfc3SMatthias Ringwald 44*2d4acfc3SMatthias Ringwald- *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*2d4acfc3SMatthias Ringwald- 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*2d4acfc3SMatthias Ringwald 47*2d4acfc3SMatthias RingwaldWith 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. 48*2d4acfc3SMatthias RingwaldWe're considering different options to make BTstack thread-safe, but for now, please use one of the suggested options. 49*2d4acfc3SMatthias Ringwald 502d1ab7bfSMatthias Ringwald### Acknowledgments 51edbc01eeSMatthias Ringwald 526d9d5ca8SMatthias RingwaldFirst HCI Reset was sent to Bluetooth chipset by [@mattkelly](https://github.com/mattkelly) 53