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 190a8d3146SMatthias Ringwald**Documentation:** [HTML](https://bluekitchen-gmbh.com/btstack/develop/), [PDF](https://bluekitchen-gmbh.com/btstack_develop.pdf) 20be78c079SMatthias Ringwald 214c65e7e5SMatthias Ringwald**Third-party libraries (FOSS):** [List of used libraries and their licenses](https://github.com/bluekitchen/btstack/blob/develop/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 30b0723cecSMilanka Ringwald**Profiles:** A2DP, AVRCP incl. Browsing, GAP, GATT, HFP, HID, HSP, IOP, SPP, PAN, PBAP Client. 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, 418b78f356SMatthias 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 GAP, GATT, IOP, 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: 48*59200c1cSMatthias Ringwald| Build Status | Port | Platform | 49*59200c1cSMatthias Ringwald|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 50*59200c1cSMatthias Ringwald| [<img src="https://buildbot.bluekitchen-gmbh.com/btstack/badges/port-esp32-develop.svg">](https://buildbot.bluekitchen-gmbh.com/btstack/#/builders/port-esp32-develop) | [esp32](https://github.com/bluekitchen/btstack/tree/develop/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) | 51*59200c1cSMatthias Ringwald| [<img src="https://buildbot.bluekitchen-gmbh.com/btstack/badges/port-max32630-fthr-develop.svg">](https://buildbot.bluekitchen-gmbh.com/btstack/#/builders/port-max32630-fthr) | [max32630-fthr](https://github.com/bluekitchen/btstack/tree/develop/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) | 52*59200c1cSMatthias Ringwald| [<img src="https://buildbot.bluekitchen-gmbh.com/btstack/badges/port-msp432p401lp-cc256x-develop.svg">](https://buildbot.bluekitchen-gmbh.com/btstack/#/builders/port-msp432p401lp-cc256x-develop) | [msp432p401lp-cc256x](https://github.com/bluekitchen/btstack/tree/develop/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 | 53*59200c1cSMatthias Ringwald| No build server | [renesas-tb-s1ja-cc256x](https://github.com/bluekitchen/btstack/tree/develop/port/renesas-tb-s1ja-cc256x) | [TB-S1JA Target Board Kit](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 | 54*59200c1cSMatthias Ringwald| [<img src="https://buildbot.bluekitchen-gmbh.com/btstack/badges/port-samv71-xplained-atwilc3000-develop.svg">](https://buildbot.bluekitchen-gmbh.com/btstack/#/builders/port-samv71-xplained-atwilc3000-develop) | [samv71-xplained-atwilc3000](https://github.com/bluekitchen/btstack/tree/develop/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) | 55*59200c1cSMatthias Ringwald| [<img src="https://buildbot.bluekitchen-gmbh.com/btstack/badges/port-stm32-f4discovery-cc256x-develop.svg">](https://buildbot.bluekitchen-gmbh.com/btstack/#/builders/port-stm32-f4discovery-cc256x-develop) | [stm32-f4discovery-cc2564b](https://github.com/bluekitchen/btstack/tree/develop/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) | 56*59200c1cSMatthias Ringwald| [<img src="https://buildbot.bluekitchen-gmbh.com/btstack/badges/port-stm32-l073rz-nucleo-em9304-develop.svg">](https://buildbot.bluekitchen-gmbh.com/btstack/#/builders/port-stm32-l073rz-nucleo-em9304) | [stm32-l073rz-nucleo-em9304](https://github.com/bluekitchen/btstack/tree/develop/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) | 57*59200c1cSMatthias Ringwald| No build server | [stm32-wb55xx-nucleo-freertos](https://github.com/bluekitchen/btstack/tree/develop/port/stm32-wb55xx-nucleo-freertos) | [P-NUCLEO-WB55 kit](https://www.st.com/en/evaluation-tools/p-nucleo-wb55.html) | 58*59200c1cSMatthias Ringwald| [<img src="https://buildbot.bluekitchen-gmbh.com/btstack/badges/port-wiced-h4-develop.svg">](https://buildbot.bluekitchen-gmbh.com/btstack/#/builders/port-wiced-h4-develop) | [wiced-h4](https://github.com/bluekitchen/btstack/tree/develop/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) | 599e39e819SMatthias Ringwald 60cd07fdb2SMilanka Ringwald#### Other Platforms: 61*59200c1cSMatthias Ringwald| Status | Port | Platform | 62*59200c1cSMatthias Ringwald|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------| 63*59200c1cSMatthias Ringwald| [<img src="https://buildbot.bluekitchen-gmbh.com/btstack/badges/port-libusb-develop.svg">](https://buildbot.bluekitchen-gmbh.com/btstack/#/builders/port-libusb-develop) | [libusb](https://github.com/bluekitchen/btstack/tree/develop/port/libusb) | Unix-based system with dedicated USB Bluetooth dongle | 64*59200c1cSMatthias Ringwald| No build server | [libusb-intel](https://github.com/bluekitchen/btstack/tree/develop/port/libusb-intel) | Unix-based system with Intel Wireless 8260/8265 Controller | 65*59200c1cSMatthias Ringwald| [<img src="https://buildbot.bluekitchen-gmbh.com/btstack/badges/port-posix-h4-develop.svg">](https://buildbot.bluekitchen-gmbh.com/btstack/#/builders/port-posix-h4-develop) | [posix-h4](https://github.com/bluekitchen/btstack/tree/develop/port/posix-h4) | Unix-based system connected to Bluetooth module via H4 over serial port | 66*59200c1cSMatthias Ringwald| No build server | [posix-h4-da14581](https://github.com/bluekitchen/btstack/tree/develop/port/posix-h4-da14581) | Unix-based system connected to Dialog Semiconductor DA14581 via H4 over serial port | 67*59200c1cSMatthias Ringwald| No build server | [posix-h4-da14585](https://github.com/bluekitchen/btstack/tree/develop/port/posix-h4-da14585) | Unix-based system connected to Dialog Semiconductor DA14585 via H4 over serial port | 68*59200c1cSMatthias Ringwald| No build server | [posix-h5](https://github.com/bluekitchen/btstack/tree/develop/port/posix-h5) | Unix-based system connected to Bluetooth module via H5 over serial port | 69*59200c1cSMatthias Ringwald| No build server | [qt-h4](https://github.com/bluekitchen/btstack/tree/develop/port/qt-h4) | Unix- or Win32-based [Qt application](https://qt.io) connected to Bluetooth module via H4 over serial port | 70*59200c1cSMatthias Ringwald| No build server | [qt-usb](https://github.com/bluekitchen/btstack/tree/develop/port/qt-usb) | Unix- or Win32-based [Qt application](https://qt.io) with dedicated USB Bluetooth dongle | 71*59200c1cSMatthias Ringwald| No build server | [windows-h4](https://github.com/bluekitchen/btstack/tree/develop/port/windows-h4) | Win32-based system connected to Bluetooth module via serial port | 72*59200c1cSMatthias Ringwald| No build server | [windows-h4-da14585](https://github.com/bluekitchen/btstack/tree/develop/port/windows-h4-da14585) | Win32-based system connected to Dialog Semiconductor DA14585 via H4 over serial port | 73*59200c1cSMatthias Ringwald| No build server | [windows-winusb](https://github.com/bluekitchen/btstack/tree/develop/port/windows-winusb) | Win32-based system with dedicated USB Bluetooth dongle | 74*59200c1cSMatthias Ringwald| No build server | [windows-winusb-intel](https://github.com/bluekitchen/btstack/tree/develop/port/windows-winusb-intel) | Win32-based system with Intel Wireless 8260/8265 Controller | 75*59200c1cSMatthias Ringwald| No build server | [raspi](https://github.com/bluekitchen/btstack/tree/develop/port/raspi) | Raspberry Pi 3 or Raspberry Pi Zero W with built-in BCM4343 Bluetooth/Wifi Controller | 76*59200c1cSMatthias Ringwald| [<img src="https://buildbot.bluekitchen-gmbh.com/btstack/badges/port-daemon-develop.svg">](https://buildbot.bluekitchen-gmbh.com/btstack/#/builders/port-daemon-develop) | [daemon](https://github.com/bluekitchen/btstack/tree/develop/port/daemon) | TCP and Unix domain named socket client-server architecture supporting multiple clients | 77*59200c1cSMatthias Ringwald| [<img src="https://buildbot.bluekitchen-gmbh.com/btstack/badges/java-develop.svg">](https://buildbot.bluekitchen-gmbh.com/btstack/#/builders/java-develop) | [java](https://github.com/bluekitchen/btstack/tree/develop/platform/daemon/binding/java) | Java wrapper for daemon | 78*59200c1cSMatthias Ringwald| [<img src="https://buildbot.bluekitchen-gmbh.com/btstack/badges/port-mtk-develop.svg">](https://buildbot.bluekitchen-gmbh.com/btstack/#/builders/port-mtk-develop) | [mtk](https://github.com/bluekitchen/btstack/tree/develop/port/mtk) | daemon for rooted Android devices, based on Mediatek MT65xx processor, Java and C client-server API | 79*59200c1cSMatthias Ringwald| No build server | [freertos](https://github.com/bluekitchen/btstack/tree/develop/platform/freertos) | [FreeRTOS](https://www.freertos.org): Run BTstack on a dedicated thread, not thread-safe. | 8060b111adSMatthias Ringwald 81bac2979aSMilanka Ringwald## Supported Chipsets 82273591abSMatthias Ringwald 83*59200c1cSMatthias Ringwald| Chipset | Type | HCI Transport | SCO over HCI | BTstack folder | Comment | 84*59200c1cSMatthias Ringwald|--------------------------------------|------------------|----------------|------------------|----------------|------------------------------------------------| 85*59200c1cSMatthias Ringwald| Atmel ATWILC3000 | LE | H4 | n.a. | atwilc3000 | Firmware size: 60 kB | 86*59200c1cSMatthias Ringwald| Broadcom UART | Dual mode | H4, H5 | Probably | bcm | Max UART baudrate 2 mbps | 87*59200c1cSMatthias Ringwald| Broadcom USB Dongles | Dual mode | USB | Yes | bcm | | 88*59200c1cSMatthias Ringwald| CSR UART | Dual mode | H4, H5, BCSP | No (didn't work) | csr | | 89*59200c1cSMatthias Ringwald| CSR USB Dongles | Dual mode | USB | Yes | csr | | 90*59200c1cSMatthias Ringwald| Cypress CYW20704 | Dual mode | H4, H5, USB | Probably | bcm | | 91*59200c1cSMatthias Ringwald| Cypress CYW20819 | Dual mode | H4, H5, USB | Probably | bcm | Keep CTS high during power cycle | 92*59200c1cSMatthias Ringwald| Cypress CYW43xxx | Dual mode + Wifi | H4, H5 | Don't know | bcm | Bluetooth + Wifi Combo Controller | 93*59200c1cSMatthias Ringwald| Cypress PSoC 4 | LE | H4 | n.a. | | HCI Firmware part of PSoC Creator kit examples | 94*59200c1cSMatthias Ringwald| Dialog Semiconductor DA145xx | LE | H4, SPI | n.a. | da14581 | Official HCI firmware used | 95*59200c1cSMatthias Ringwald| Dialog Semiconductor DA1469x | LE | H4, SPI | n.a | | HCI Firmware part of DA1469x SDK | 96*59200c1cSMatthias Ringwald| Espressif ESP32 | Dual mode + Wifi | VHCI | Yes | | SoC with Bluetooth and Wifi | 97*59200c1cSMatthias Ringwald| Espressif ESP32-S3, ESP32-C3 | LE + Wifi | VHCI | Yes | | SoC with Bluetooth and Wifi | 98*59200c1cSMatthias Ringwald| EM 9301, 9304 | LE | SPI | n.a. | em9301 | Custom HCI SPI implementation | 99*59200c1cSMatthias Ringwald| Intel Dual Wireless 3165, 8260, 8265 | Dual mode | USB | Probably | intel | Firmware size: 400 kB | 100*59200c1cSMatthias Ringwald| Nordic nRF | LE | H4 | n.a. | | Requires custom HCI firmware | 101*59200c1cSMatthias Ringwald| Realtek RTL8822CS | Dual mode + Wifi | H5 | Yes | | Requires initial firmware and config | 102*59200c1cSMatthias Ringwald| Realtek USB Dongles | Dual mode + Wifi | USB | Yes | realtek | Requires initial firmware and config | 103*59200c1cSMatthias Ringwald| Renesas RX23W | LE | H4 | n.a. | | HCI Firmware part of BTTS | 104*59200c1cSMatthias Ringwald| STM STLC2500D | Classic | H4 | No (didn't try) | stlc2500d | Custom deep sleep management not supported | 105*59200c1cSMatthias Ringwald| STM32-WB5x | LE | VHCI | n.a. | | SoC with multi-protocol Radio co-processor | 106*59200c1cSMatthias Ringwald| Toshiba TC35661 | Dual mode | H4 | No | tc3566 | | 107*59200c1cSMatthias Ringwald| TI CC256x, WL183x | Dual mode | H4, H5, eHCILL | Yes | cc256x | Also WL185x, WL187x, and WL189x | 108273591abSMatthias Ringwald 109273591abSMatthias Ringwald[More infos on supported chipsets](https://bluekitchen-gmbh.com/btstack/develop/chipsets/) 11040276177SMatthias Ringwald 11140276177SMatthias Ringwald## Source Tree Overview 112*59200c1cSMatthias Ringwald| Path | Description | 113*59200c1cSMatthias Ringwald|----------|--------------------------------------------------| 114*59200c1cSMatthias Ringwald| chipset | Support for individual Bluetooth chipsets | 115*59200c1cSMatthias Ringwald| doc | Sources for BTstack documentation | 116*59200c1cSMatthias Ringwald| example | Example applications available for all ports | 117*59200c1cSMatthias Ringwald| platform | Support for special OSs and/or MCU architectures | 118*59200c1cSMatthias Ringwald| port | Complete port for a MCU + Chipset combinations | 119*59200c1cSMatthias Ringwald| src | Bluetooth stack implementation | 120*59200c1cSMatthias Ringwald| test | Unit and PTS tests | 121*59200c1cSMatthias Ringwald| tool | Helper tools for BTstack | 122
