12d04a09aSmilamikica# Welcome to BTstack 22d04a09aSmilamikica 30a8d3146SMatthias RingwaldBTstack is [BlueKitchen's](https://bluekitchen-gmbh.com) implementation of the official Bluetooth stack. 4bac2979aSMilanka RingwaldIt is well suited for small, resource-constraint devices 52d04a09aSmilamikicasuch as 8 or 16 bit embedded systems as it is highly configurable and comes with an ultra small memory footprint. 62d04a09aSmilamikica 743a197a7SMatthias RingwaldTargeting a variety of platforms is as simple as providing the necessary UART, CPU, and CLOCK implementations. BTstack is currently capable of connecting to Bluetooth-modules via: (H2) HCI USB, (H4) HCI UART + TI's eHCILL, and (H5) HCI Three-Wire UART. 82d04a09aSmilamikica 92d04a09aSmilamikicaOn smaller embedded systems, a minimal run loop implementation allows to use BTstack without a Real Time OS (RTOS). 102d04a09aSmilamikicaIf a RTOS is already provided, BTstack can be integrated and run as a single thread. 112d04a09aSmilamikica 126d743f9aSMatthias RingwaldOn larger systems, BTstack provides a server that connects to a Bluetooth module. 136d743f9aSMatthias RingwaldMultiple applications can communicate with this server over different inter-process communication methods. As sockets are used for client/server communication, it's easy to interact via higher-level level languages, e.g. there's already a Java binding for use in desktop environments. 142d04a09aSmilamikica 15e6a6f76bSMatthias RingwaldBTstack supports the Central and the Peripheral Role of Bluetooth 5 Low Energy specification incl. LE Secure Connections, LE Data Channels, and LE Data Length Extension. It can be configured to run as either single-mode stack or a dual-mode stack. 162d04a09aSmilamikica 1743a197a7SMatthias RingwaldBTstack is free for non-commercial use. However, for commercial use, <a href="mailto:[email protected]">tell us</a> a bit about your project to get a quote. 1843a197a7SMatthias Ringwald 19fa58ca9cSMatthias Ringwald**Documentation:** [HTML](https://bluekitchen-gmbh.com/btstack/), [PDF](https://bluekitchen-gmbh.com/btstack.pdf) 20be78c079SMatthias Ringwald 2116f6f81aSMatthias Ringwald**Third-party libraries (FOSS):** [List of used libraries and their licenses](https://github.com/bluekitchen/btstack/blob/master/3rd-party/README.md) 22ca8ea3f5SMatthias Ringwald 230a8d3146SMatthias Ringwald**Discussion and Community Support:** [BTstack Google Group](https://groups.google.com/group/btstack-dev) 24be78c079SMatthias Ringwald 25ca8ea3f5SMatthias Ringwald 26be78c079SMatthias Ringwald### Supported Protocols and Profiles 2743a197a7SMatthias Ringwald 2841da4229SMatthias Ringwald**Protocols:** L2CAP (incl. Enhanced Retransmission Mode and LE Data Channels), RFCOMM, SDP, BNEP, AVDTP, AVCTP, ATT, SM (incl. LE Secure Connections and Cross-transport key derivation). 2943a197a7SMatthias Ringwald 308aa34dc6SMatthias Ringwald**Profiles:** A2DP, AVRCP incl. Browsing (CT+TG) and Cover Art (CT), GAP, GATT, HFP, HID, HSP, IOP, OPP, SPP, PAN, PBAP. 3143a197a7SMatthias Ringwald 3258fb2150SMatthias Ringwald**GATT Service Servers:** Battery (BAS), Bond Management (BMS), Cycling Power (CPS), Cycling Speed and Cadence (CSCS), Device Information (DID), Heart Rate (HRS), HID over GATT (HIDS) Device , Mesh Provisioning, Mesh Proxy, Nordic SPP, Scan Parameters (SCPS), TX Power (TPS), u-Blox SPP. 331c4a5e73SMilanka Ringwald 3441da4229SMatthias Ringwald**GATT Service Clients:**: ANCS, Battery (BAS), Device Information (DID), HID-over-GATT (HOGP) Host, Scan Parameters (SCPP). 35e632231eSMilanka Ringwald 3675e53860SMatthias RingwaldGATT Services are in general easy to implement and require short development time. For more GATT Services please contact us, or follow the [implementation guidelines](https://bluekitchen-gmbh.com/btstack/profiles/#gatt-generic-attribute-profile). 37e632231eSMilanka Ringwald 388b78f356SMatthias Ringwald**In Development:** LE Audio and more. 3943a197a7SMatthias Ringwald 409e81dea2SMatthias RingwaldIt has been qualified with the Bluetooth SIG (QDID 166433) for A2DP 1.3.2, AVCTP 1.4, AVDTP 1.3, AVRCP 1.6.2, DID 1.3, GAVDP 1.3, HFP 1.8, HSP 1.2, PAN 1.0, PBAP Client 1.2, RFCOMM 1.2, SPP 1.2 BR/EDR protocol/profiles, 41b3c4561cSMatthias RingwaldBAS 1.0, CPP 1.1, CPS 1.1, CSCP 1.0, CSCS 1.0, DIS 1.1, HIDS 1.0, HOGP 1.0, HRP 1.0, HRS 1.0, SCPP 1.0, SCPS 1.0 GATT profiles as well as and ATT, GAP, GATT, IOP, L2CAP, SDP, SM of the Bluetooth Core 5.2 specification. 428b78f356SMatthias Ringwald 438b78f356SMatthias RingwaldFor information on Apple's MFi/iAP2 and Find My profiles, please <a href="mailto:[email protected]">contact us directly</a>. 442d04a09aSmilamikica 452fe24f3eSMatthias Ringwald## Evaluation Platforms 46bac2979aSMilanka Ringwald 47cd07fdb2SMilanka Ringwald#### Embedded Platforms: 4859200c1cSMatthias Ringwald| Build Status | Port | Platform | 4959200c1cSMatthias Ringwald|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 50c007977cSMatthias Ringwald| [<img src="https://buildbot.bluekitchen-gmbh.com/btstack/badges/port-esp32-master.svg">](https://buildbot.bluekitchen-gmbh.com/btstack/#/builders/port-esp32-master) | [esp32](https://github.com/bluekitchen/btstack/tree/master/port/esp32) | [Espressif ESP32](https://www.espressif.com/products/hardware/esp32/overview) 2.4 GHz Wi-Fi and Bluetooth Dual-Mode combo chip using [FreeRTOS](https://www.freertos.org) | 511c6f668bSMatthias Ringwald| [<img src="https://buildbot.bluekitchen-gmbh.com/btstack/badges/port-max32630-fthr-master.svg">](https://buildbot.bluekitchen-gmbh.com/btstack/#/builders/port-max32630-fthr) | [max32630-fthr](https://github.com/bluekitchen/btstack/tree/master/port/max32630-fthr) | [MAX32630FTHR ARM Cortex M4F Board](https://www.maximintegrated.com/en/products/digital/microcontrollers/MAX32630FTHR.html) with onboard [Panasonic PAN1326 module](https://na.industrial.panasonic.com/products/wireless-connectivity/bluetooth/multi-mode/series/pan13261316-series/CS467) containing [TI CC2564B Bluetooth controller](https://www.ti.com/product/cc2564) | 52c007977cSMatthias Ringwald| [<img src="https://buildbot.bluekitchen-gmbh.com/btstack/badges/port-msp432p401lp-cc256x-master.svg">](https://buildbot.bluekitchen-gmbh.com/btstack/#/builders/port-msp432p401lp-cc256x-master) | [msp432p401lp-cc256x](https://github.com/bluekitchen/btstack/tree/master/port/msp432p401lp-cc256x) | [TI MSP432P401R LaunchPad](https://www.ti.com/tool/MSP-EXP432P401R) with [CC2564C Dual-mode Bluetooth® Controller Evaluation Module](https://store.ti.com/CC256XCQFN-EM-CC2564C-Dual-Mode-Bluetooth-Controller-Evaluation-Module-P51277.aspx) and [EM Adapter BoosterPack](https://www.ti.com/tool/boost-ccemadapter) with additional 32768Hz quartz oscillator | 531c6f668bSMatthias Ringwald| No build server | [rrenesas-ek-ra6m4a-da14531](https://github.com/bluekitchen/btstack/tree/master/port/rrenesas-ek-ra6m4a-da14531) | [Renesas EK-RA6M4](https://www.renesas.com/us/en/products/microcontrollers-microprocessors/ra-cortex-m-mcus/ek-ra6m4-evaluation-kit-ra6m4-mcu-group) with [MikroeE BLE Tiny Click board](https://www.mikroe.com/ble-tiny-click) | 541c6f668bSMatthias Ringwald| No build server | [renesas-tb-s1ja-cc256x](https://github.com/bluekitchen/btstack/tree/master/port/renesas-tb-s1ja-cc256x) | [Renesas TB-S1JA](https://www.renesas.com/eu/en/products/synergy/hardware/kits/tb-s1ja.html) with with [Dual-mode Bluetooth® CC2564 evaluation board](https://www.ti.com/tool/CC256XQFNEM) and [EM Adapter BoosterPack](https://www.ti.com/tool/boost-ccemadapter) with additional 32768Hz quartz oscillator | 55c007977cSMatthias Ringwald| [<img src="https://buildbot.bluekitchen-gmbh.com/btstack/badges/port-samv71-xplained-atwilc3000-master.svg">](https://buildbot.bluekitchen-gmbh.com/btstack/#/builders/port-samv71-xplained-atwilc3000-master) | [samv71-xplained-atwilc3000](https://github.com/bluekitchen/btstack/tree/master/port/samv71-xplained-atwilc3000) | [SAMV71 Ultra Xplained Ultra](https://www.microchip.com/DevelopmentTools/ProductDetails/PartNO/ATSAMV71-XULT) evaluation kit with [ATWILC3000 SHIELD](https://www.microchip.com/DevelopmentTools/ProductDetails/ATWILC3000-SHLD) | 56c007977cSMatthias Ringwald| [<img src="https://buildbot.bluekitchen-gmbh.com/btstack/badges/port-stm32-f4discovery-cc256x-master.svg">](https://buildbot.bluekitchen-gmbh.com/btstack/#/builders/port-stm32-f4discovery-cc256x-master) | [stm32-f4discovery-cc2564b](https://github.com/bluekitchen/btstack/tree/master/port/stm32-f4discovery-cc256x) | [STM32 F4 Discovery Board](https://www.st.com/en/evaluation-tools/stm32f4discovery.html) with [CC256xEM Bluetooth Adapter Kit for ST](https://store.ti.com/CC256XEM-STADAPT-CC256xEM-Bluetooth-Adapter-Kit-P45158.aspx) and [CC2564B Dual-mode Bluetooth® Controller Evaluation Module](https://store.ti.com/cc2564modnem.aspx) | 57c007977cSMatthias Ringwald| [<img src="https://buildbot.bluekitchen-gmbh.com/btstack/badges/port-stm32-l073rz-nucleo-em9304-master.svg">](https://buildbot.bluekitchen-gmbh.com/btstack/#/builders/port-stm32-l073rz-nucleo-em9304) | [stm32-l073rz-nucleo-em9304](https://github.com/bluekitchen/btstack/tree/master/port/stm32-l073rz-nucleo-em9304) | EM9304 DVK: [STM32 Nucleo development board NUCELO-L73RZ](https://www.st.com/en/evaluation-tools/nucleo-l073rz.html) with [EM9304 Bluetooth Controller](https://www.emmicroelectronic.com/product/standard-protocols/em9304) | 58c007977cSMatthias Ringwald| No build server | [stm32-wb55xx-nucleo-freertos](https://github.com/bluekitchen/btstack/tree/master/port/stm32-wb55xx-nucleo-freertos) | [P-NUCLEO-WB55 kit](https://www.st.com/en/evaluation-tools/p-nucleo-wb55.html) | 59c007977cSMatthias Ringwald| [<img src="https://buildbot.bluekitchen-gmbh.com/btstack/badges/port-wiced-h4-master.svg">](https://buildbot.bluekitchen-gmbh.com/btstack/#/builders/port-wiced-h4-master) | [wiced-h4](https://github.com/bluekitchen/btstack/tree/master/port/wiced-h4) | Broadcom/Cypress platforms that support the WICED SDK via H4 UART, e.g. [RedBear Duo](https://www.seeedstudio.com/RedBear-DUO-Wi-Fi-BLE-IoT-Board-p-2635.html) (BCM43438 A1), [Inventek Systems ISM4334x](https://www.inventeksys.com/wifi/wifi-modules/ism4343-wmb-l151/) (BCM43438 A1), [Inventek Systems ISM4343](https://www.inventeksys.com/products-page/wifi-modules/serial-wifi/ism43341-m4g-l44-cu-embedded-serial-to-wifi-ble-nfc-module/) (BCM43340) | 609e39e819SMatthias Ringwald 61cd07fdb2SMilanka Ringwald#### Other Platforms: 6259200c1cSMatthias Ringwald| Status | Port | Platform | 6359200c1cSMatthias Ringwald|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------| 64*200e95e4SMatthias Ringwald| No build server | [freebsd-netgraph](https://github.com/bluekitchen/btstack/tree/master/port/freebsd-netgraph) | FreeBSD port that uses kernel netgraph HCI node 65c007977cSMatthias Ringwald| [<img src="https://buildbot.bluekitchen-gmbh.com/btstack/badges/port-libusb-master.svg">](https://buildbot.bluekitchen-gmbh.com/btstack/#/builders/port-libusb-master) | [libusb](https://github.com/bluekitchen/btstack/tree/master/port/libusb) | Unix-based system with dedicated USB Bluetooth dongle | 66c007977cSMatthias Ringwald| No build server | [libusb-intel](https://github.com/bluekitchen/btstack/tree/master/port/libusb-intel) | Unix-based system with Intel Wireless 8260/8265 Controller | 67c007977cSMatthias Ringwald| [<img src="https://buildbot.bluekitchen-gmbh.com/btstack/badges/port-posix-h4-master.svg">](https://buildbot.bluekitchen-gmbh.com/btstack/#/builders/port-posix-h4-master) | [posix-h4](https://github.com/bluekitchen/btstack/tree/master/port/posix-h4) | Unix-based system connected to Bluetooth module via H4 over serial port | 681c6f668bSMatthias Ringwald| No build server | [posix-h4-nxp](https://github.com/bluekitchen/btstack/tree/master/port/posix-h4-bcm) | Unix-based system connected to Cypress controllers via H4 over serial port | 69c007977cSMatthias Ringwald| No build server | [posix-h4-da14581](https://github.com/bluekitchen/btstack/tree/master/port/posix-h4-da14581) | Unix-based system connected to Dialog Semiconductor DA14581 via H4 over serial port | 70c007977cSMatthias Ringwald| No build server | [posix-h4-da14585](https://github.com/bluekitchen/btstack/tree/master/port/posix-h4-da14585) | Unix-based system connected to Dialog Semiconductor DA14585 via H4 over serial port | 711c6f668bSMatthias Ringwald| No build server | [posix-h4-nxp](https://github.com/bluekitchen/btstack/tree/master/port/posix-h4-nxp) | Unix-based system connected to NXP controllers via H4 over serial port | 721c6f668bSMatthias Ringwald| No build server | [posix-h4-zephyr](https://github.com/bluekitchen/btstack/tree/master/port/posix-h4-zephyr) | Unix-based system connected to Bluetooth module with Zephyr HCI firmware via H4 over serial port | 73c007977cSMatthias Ringwald| No build server | [posix-h5](https://github.com/bluekitchen/btstack/tree/master/port/posix-h5) | Unix-based system connected to Bluetooth module via H5 over serial port | 74c007977cSMatthias Ringwald| No build server | [qt-h4](https://github.com/bluekitchen/btstack/tree/master/port/qt-h4) | Unix- or Win32-based [Qt application](https://qt.io) connected to Bluetooth module via H4 over serial port | 75c007977cSMatthias Ringwald| No build server | [qt-usb](https://github.com/bluekitchen/btstack/tree/master/port/qt-usb) | Unix- or Win32-based [Qt application](https://qt.io) with dedicated USB Bluetooth dongle | 76c007977cSMatthias Ringwald| No build server | [windows-h4](https://github.com/bluekitchen/btstack/tree/master/port/windows-h4) | Win32-based system connected to Bluetooth module via serial port | 77c007977cSMatthias Ringwald| No build server | [windows-h4-da14585](https://github.com/bluekitchen/btstack/tree/master/port/windows-h4-da14585) | Win32-based system connected to Dialog Semiconductor DA14585 via H4 over serial port | 78c007977cSMatthias Ringwald| No build server | [windows-winusb](https://github.com/bluekitchen/btstack/tree/master/port/windows-winusb) | Win32-based system with dedicated USB Bluetooth dongle | 79c007977cSMatthias Ringwald| No build server | [windows-winusb-intel](https://github.com/bluekitchen/btstack/tree/master/port/windows-winusb-intel) | Win32-based system with Intel Wireless 8260/8265 Controller | 80c007977cSMatthias Ringwald| No build server | [raspi](https://github.com/bluekitchen/btstack/tree/master/port/raspi) | Raspberry Pi 3 or Raspberry Pi Zero W with built-in BCM4343 Bluetooth/Wifi Controller | 81c007977cSMatthias Ringwald| [<img src="https://buildbot.bluekitchen-gmbh.com/btstack/badges/port-daemon-master.svg">](https://buildbot.bluekitchen-gmbh.com/btstack/#/builders/port-daemon-master) | [daemon](https://github.com/bluekitchen/btstack/tree/master/port/daemon) | TCP and Unix domain named socket client-server architecture supporting multiple clients | 82c007977cSMatthias Ringwald| [<img src="https://buildbot.bluekitchen-gmbh.com/btstack/badges/java-master.svg">](https://buildbot.bluekitchen-gmbh.com/btstack/#/builders/java-master) | [java](https://github.com/bluekitchen/btstack/tree/master/platform/daemon/binding/java) | Java wrapper for daemon | 83c007977cSMatthias Ringwald| [<img src="https://buildbot.bluekitchen-gmbh.com/btstack/badges/port-mtk-master.svg">](https://buildbot.bluekitchen-gmbh.com/btstack/#/builders/port-mtk-master) | [mtk](https://github.com/bluekitchen/btstack/tree/master/port/mtk) | daemon for rooted Android devices, based on Mediatek MT65xx processor, Java and C client-server API | 84c007977cSMatthias Ringwald| No build server | [freertos](https://github.com/bluekitchen/btstack/tree/master/platform/freertos) | [FreeRTOS](https://www.freertos.org): Run BTstack on a dedicated thread, not thread-safe. | 8560b111adSMatthias Ringwald 86bac2979aSMilanka Ringwald## Supported Chipsets 87273591abSMatthias Ringwald 8859200c1cSMatthias Ringwald| Chipset | Type | HCI Transport | SCO over HCI | BTstack folder | Comment | 8959200c1cSMatthias Ringwald|--------------------------------------|------------------|----------------|------------------|----------------|------------------------------------------------| 9059200c1cSMatthias Ringwald| Atmel ATWILC3000 | LE | H4 | n.a. | atwilc3000 | Firmware size: 60 kB | 9159200c1cSMatthias Ringwald| Broadcom UART | Dual mode | H4, H5 | Probably | bcm | Max UART baudrate 2 mbps | 9259200c1cSMatthias Ringwald| Broadcom USB Dongles | Dual mode | USB | Yes | bcm | | 9359200c1cSMatthias Ringwald| CSR UART | Dual mode | H4, H5, BCSP | No (didn't work) | csr | | 9459200c1cSMatthias Ringwald| CSR USB Dongles | Dual mode | USB | Yes | csr | | 95c63d0213SMatthias Ringwald| Infineon CYW207xx | Dual mode | H4, H5, USB | Probably | bcm | | 96c63d0213SMatthias Ringwald| Infineon CYW20819 | Dual mode | H4, H5, USB | Probably | bcm | Keep CTS high during power cycle | 97c63d0213SMatthias Ringwald| Infineon CYW43xxx | Dual mode + Wifi | H4, H5 | Don't know | bcm | Bluetooth + Wifi Combo Controller | 989277963bSMatthias Ringwald| Infineon CYW5557x | Dual mode + Wifi | H4 | Yes | bcm | autobaud-mode needed, see posix-h4-bcm | 99c63d0213SMatthias Ringwald| Infineon PSoC 4 | LE | H4 | n.a. | | HCI Firmware part of PSoC Creator kit examples | 10059200c1cSMatthias Ringwald| Dialog Semiconductor DA145xx | LE | H4, SPI | n.a. | da14581 | Official HCI firmware used | 10159200c1cSMatthias Ringwald| Dialog Semiconductor DA1469x | LE | H4, SPI | n.a | | HCI Firmware part of DA1469x SDK | 102eccd9dc9SMatthias Ringwald| Espressif ESP32 | Dual mode + Wifi | VHCI, H4 | Yes | | SoC with Bluetooth and Wifi | 103eccd9dc9SMatthias Ringwald| Espressif ESP32-S3, ESP32-C3 | LE + Wifi | VHCI, H4 | Yes | | SoC with Bluetooth and Wifi | 104c63d0213SMatthias Ringwald| EM 9301, 9304, 9305 | LE | SPI | n.a. | em9301 | Custom HCI SPI implementation | 10559200c1cSMatthias Ringwald| Intel Dual Wireless 3165, 8260, 8265 | Dual mode | USB | Probably | intel | Firmware size: 400 kB | 10659200c1cSMatthias Ringwald| Nordic nRF | LE | H4 | n.a. | | Requires custom HCI firmware | 1079a0af64aSMatthias Ringwald| NXP 88W88997, IW416, IW61x | Dual mode + Wifi | H4 | Yes | nxp | Requires initial firmware | 10859200c1cSMatthias Ringwald| Realtek RTL8822CS | Dual mode + Wifi | H5 | Yes | | Requires initial firmware and config | 10959200c1cSMatthias Ringwald| Realtek USB Dongles | Dual mode + Wifi | USB | Yes | realtek | Requires initial firmware and config | 11059200c1cSMatthias Ringwald| Renesas RX23W | LE | H4 | n.a. | | HCI Firmware part of BTTS | 11159200c1cSMatthias Ringwald| STM STLC2500D | Classic | H4 | No (didn't try) | stlc2500d | Custom deep sleep management not supported | 11259200c1cSMatthias Ringwald| STM32-WB5x | LE | VHCI | n.a. | | SoC with multi-protocol Radio co-processor | 11359200c1cSMatthias Ringwald| Toshiba TC35661 | Dual mode | H4 | No | tc3566 | | 11459200c1cSMatthias Ringwald| TI CC256x, WL183x | Dual mode | H4, H5, eHCILL | Yes | cc256x | Also WL185x, WL187x, and WL189x | 115273591abSMatthias Ringwald 1161c6f668bSMatthias Ringwald[More infos on supported chipsets](https://bluekitchen-gmbh.com/btstack/master/chipsets/) 11740276177SMatthias Ringwald 11840276177SMatthias Ringwald## Source Tree Overview 11959200c1cSMatthias Ringwald| Path | Description | 12059200c1cSMatthias Ringwald|----------|--------------------------------------------------| 12159200c1cSMatthias Ringwald| chipset | Support for individual Bluetooth chipsets | 12259200c1cSMatthias Ringwald| doc | Sources for BTstack documentation | 12359200c1cSMatthias Ringwald| example | Example applications available for all ports | 12459200c1cSMatthias Ringwald| platform | Support for special OSs and/or MCU architectures | 12559200c1cSMatthias Ringwald| port | Complete port for a MCU + Chipset combinations | 12659200c1cSMatthias Ringwald| src | Bluetooth stack implementation | 12759200c1cSMatthias Ringwald| test | Unit and PTS tests | 12859200c1cSMatthias Ringwald| tool | Helper tools for BTstack | 129
