xref: /btstack/README.md (revision f61339ea81eeccfafe4eeece09018b94ef761419)
12d04a09aSmilamikica# Welcome to BTstack
22d04a09aSmilamikica
3bac2979aSMilanka RingwaldBTstack is [BlueKitchen's](http://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.
62d04a09aSmilamikicaA minimal configuration for an SPP server on a MSP430 can run in 32 kB FLASH and only 4 kB of RAM.
72d04a09aSmilamikica
843a197a7SMatthias 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.
92d04a09aSmilamikica
102d04a09aSmilamikicaOn smaller embedded systems, a minimal run loop implementation allows to use BTstack without a Real Time OS (RTOS).
112d04a09aSmilamikicaIf a RTOS is already provided, BTstack can be integrated and run as a single thread.
122d04a09aSmilamikica
132d04a09aSmilamikicaOn larger systems, BTstack provides a daemon that connects to a Bluetooth module.
142d04a09aSmilamikicaMultiple applications can communicate with this daemon over different inter-process communication methods.
152d04a09aSmilamikica
16fcb4fb02SMatthias RingwaldBTstack supports the Central and the Peripheral Role of Bluetooth 4.2 Low Energy specification incl. LE Secure Connections, LE Data Channels, and LE Data Lenght Extension. It can be configured to run as either single-mode stack or a dual-mode stack.
172d04a09aSmilamikica
1843a197a7SMatthias 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.
1943a197a7SMatthias Ringwald
20be78c079SMatthias Ringwald**Documentation:** [HTML](http://bluekitchen-gmbh.com/btstack/develop/), [PDF](http://bluekitchen-gmbh.com/btstack_develop.pdf)
21be78c079SMatthias Ringwald
22be78c079SMatthias Ringwald**Discussion and Community Support:** [BTstack Google Group](http://groups.google.com/group/btstack-dev)
23be78c079SMatthias Ringwald
24be78c079SMatthias Ringwald### Supported Protocols and Profiles
2543a197a7SMatthias Ringwald
26989d4dafSMatthias Ringwald**Protocols:** L2CAP (incl. LE Data Channels), RFCOMM, SDP, BNEP, AVDTP, AVCTP, ATT, SM (incl. LE Secure Connections).
2743a197a7SMatthias Ringwald
28989d4dafSMatthias Ringwald**Profiles:** GAP, IOP, HFP, HSP, SPP, PAN, A2DP, AVRCP, GATT.
2943a197a7SMatthias Ringwald
30989d4dafSMatthias Ringwald**Beta Stage:** HID, HOGP.
31c209eb1eSMilanka Ringwald
32185fb1d2SMilanka Ringwald**In Development:** BLE Mesh, AVRCP Browsing and more.
3343a197a7SMatthias Ringwald
34989d4dafSMatthias RingwaldIt has been qualified with the Bluetooth SIG (QDID 110883) for GAP, IOP, HFP, HSP, SPP, PAN, A2DP, AVRCP profiles and
35989d4dafSMatthias RingwaldGATT, SM of the Bluetooth 5 specification. For information on MFi/iAP2 support, please <a href="mailto:[email protected]">contact us</a>.
362d04a09aSmilamikica
37439fcdeaSmilamikica
382fe24f3eSMatthias Ringwald## Evaluation Platforms
39bac2979aSMilanka Ringwald
40cd07fdb2SMilanka Ringwald#### Embedded Platforms:
4160b111adSMatthias RingwaldBuild Status               | Port | Platform
4260b111adSMatthias Ringwald---------------------| -----| ------
43e576eb56SMatthias Ringwald[<img src="http://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](http://www.espressif.com/products/hardware/esp32/overview) 2.4 GHz Wi-Fi and Bluetooth Dual-Mode combo chip using [FreeRTOS](http://www.freertos.org)
44e576eb56SMatthias Ringwald[<img src="http://buildbot.bluekitchen-gmbh.com/btstack/badges/port-ez430-rf2560-develop.svg">](https://buildbot.bluekitchen-gmbh.com/btstack/#/builders/port-ez430-rf2560-develop) | [ez430-rf2560](https://github.com/bluekitchen/btstack/tree/develop/port/ez430-rf2560) | [EZ430-RF256x Bluetooth Evaluation Tool for MSP430](http://www.ti.com/tool/ez430-rf256x)
45e576eb56SMatthias Ringwald[<img src="http://buildbot.bluekitchen-gmbh.com/btstack/badges/port-msp-exp430f5438-cc2564b-develop.svg">](https://buildbot.bluekitchen-gmbh.com/btstack/#/builders/port-msp-exp430f5438-cc2564b-develop) | [msp-exp430f5438-cc2564b](https://github.com/bluekitchen/btstack/tree/develop/port/msp-exp430f5438-cc2564b) |[MSP430F5438 Experimenter Board for MSP430](http://www.ti.com/tool/msp-exp430f5438) with [Bluetooth CC2564 Module Evaluation Board](http://www.ti.com/tool/cc2564modnem)
46e576eb56SMatthias Ringwald[<img src="http://buildbot.bluekitchen-gmbh.com/btstack/badges/port-msp430f5229lp-cc2564b-develop.svg">](https://buildbot.bluekitchen-gmbh.com/btstack/#/builders/port-msp430f5229lp-cc2564b-develop)     | [msp430f5529lp-cc2564b](https://github.com/bluekitchen/btstack/tree/develop/port/msp430f5229lp-cc2564b) | [MSP-EXP430F5529LP LaunchPad](http://www.ti.com/ww/en/launchpad/launchpads-msp430-msp-exp430f5529lp.html#tabs) with [Bluetooth CC2564 Module Evaluation Board](http://www.ti.com/tool/cc2564modnem) and [EM Adapter BoosterPack](http://www.ti.com/tool/boost-ccemadapter) with additional 32768Hz quartz oscillator
4720af858fSMatthias Ringwald[<img src="http://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](http://www.ti.com/product/cc2564)
48e576eb56SMatthias Ringwald[<img src="http://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](http://www.atmel.com/tools/atsamv71-xult.aspx) evaluation kit with [ATWILC3000 SHIELD](http://www.microchip.com/DevelopmentTools/ProductDetails.aspx?PartNO=ATWILC3000-SHLD)
49e576eb56SMatthias Ringwald[<img src="http://buildbot.bluekitchen-gmbh.com/btstack/badges/port-stm32-f103rb-nucleo-develop.svg">](https://buildbot.bluekitchen-gmbh.com/btstack/#/builders/port-stm32-f103rb-nucleo-develop)       | [stm32-f103rb-nucleo](https://github.com/bluekitchen/btstack/tree/develop/port/stm32-f103rb-nucleo) | [STM32 Nucleo development board NUCLEO-F103RB](http://www.st.com/web/catalog/tools/FM116/SC959/SS1532/LN1847/PF259875) with [Bluetooth CC2564 Module Evaluation Board](http://www.ti.com/tool/cc2564modnem) and [EM Adapter BoosterPack](http://www.ti.com/tool/boost-ccemadapter) with additional 32768Hz quartz oscillator
5020af858fSMatthias Ringwald[<img src="http://buildbot.bluekitchen-gmbh.com/btstack/badges/port-stm32-f4discovery-cc2564b-develop.svg">](https://buildbot.bluekitchen-gmbh.com/btstack/#/builders/port-stm32-f4discovery-cc2564b) | [stm32-f4discovery-cc2564b](https://github.com/bluekitchen/btstack/tree/develop/port/stm32-f4discovery-cc256x) | [STM32 F4 Discovery Board](http://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)
5120af858fSMatthias Ringwald[<img src="http://buildbot.bluekitchen-gmbh.com/btstack/badges/port-stm32-l053r8-em9304-develop.svg">](https://buildbot.bluekitchen-gmbh.com/btstack/#/builders/port-stm32-l053r8-em9304)  | [stm32-l053r8-em9304](https://github.com/bluekitchen/btstack/tree/develop/port/stm32-l053r8-em9304) | EM9304 DVK: [STM32 Nucleo development board NUCELO-L053R](http://www.st.com/en/evaluation-tools/nucleo-l053r8.html) with [EM9304  Bluetooth Controller](http://www.emmicroelectronic.com/products/wireless-rf/standard-protocols/em9304)
52e576eb56SMatthias Ringwald[<img src="http://buildbot.bluekitchen-gmbh.com/btstack/badges/port-pic32-harmony-develop.svg">](https://buildbot.bluekitchen-gmbh.com/btstack/#/builders/port-pic32-harmony-develop)                |  [pic32-harmony](https://github.com/bluekitchen/btstack/tree/develop/port/pic32-harmony)  | [Microchip's PIC32 Bluetooth Audio Development Kit](http://www.microchip.com/Developmenttools/ProductDetails.aspx?PartNO=DV320032)
53b78fcc89SMatthias Ringwald[<img src="http://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://redbear.cc/product/wifi-ble/redbear-duo.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)
542888825aSMatthias RingwaldNo build server | [wiced-h5](https://github.com/bluekitchen/btstack/tree/develop/port/wiced-h5) | Broadcom platforms that support the WICED SDK via H5 UART, see wiced-h4
55cd07fdb2SMilanka Ringwald
56cd07fdb2SMilanka Ringwald#### Other Platforms:
5760b111adSMatthias RingwaldStatus             | Port  | Platform
5860b111adSMatthias Ringwald-------------------| ------|---------
59e576eb56SMatthias Ringwald[<img src="http://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
6060b111adSMatthias RingwaldNo 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
61ecde56a6SMatthias RingwaldNo 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
6260b111adSMatthias RingwaldNo 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
6360b111adSMatthias RingwaldNo build server | [posix-h5-bcm](https://github.com/bluekitchen/btstack/tree/develop/port/posix-h5) | Unix-based system connected to Broadcom/Cypress Bluetooth module via H5 over serial port
64e576eb56SMatthias Ringwald[<img src="http://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
657eac9e22SMatthias RingwaldNo build server | [libusb-intel](https://github.com/bluekitchen/btstack/tree/develop/port/libusb-inttel) | Unix-based system with Intel Wireless 8260/8265 Controller
6660b111adSMatthias RingwaldNo build server | [windows-h4](https://github.com/bluekitchen/btstack/tree/develop/port/windows-h4) | Win32-based system connected to Bluetooth module via serial port
6760b111adSMatthias RingwaldNo build server | [windows-winusb](https://github.com/bluekitchen/btstack/tree/develop/port/windows-winusb) | Win32-based system with dedicated USB Bluetooth dongle
68*f61339eaSMatthias RingwaldNo 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
696e4c47b0SMatthias RingwaldNo 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
70e576eb56SMatthias Ringwald[<img src="http://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
71e576eb56SMatthias Ringwald[<img src="http://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
72e576eb56SMatthias Ringwald[<img src="http://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
73e576eb56SMatthias Ringwald[<img src="http://buildbot.bluekitchen-gmbh.com/btstack/badges/port-ios-develop.svg">](https://buildbot.bluekitchen-gmbh.com/btstack/#/builders/port-ios-develop)           | [ios](https://github.com/bluekitchen/btstack/tree/develop/port/ios) | daemon for iOS jailbreak devices, C client-server API
7460b111adSMatthias RingwaldNo build server | [freertos](https://github.com/bluekitchen/btstack/tree/develop/platform/freertos) | [FreeRTOS](http://www.freertos.org): Run BTstack on a dedicated thread, not thread-safe.
7560b111adSMatthias Ringwald
76bac2979aSMilanka Ringwald## Supported Chipsets
77273591abSMatthias Ringwald
782c37f7fbSMatthias RingwaldChipset                      | Type      | HCI Transport   | SCO over HCI     | BTstack folder | Comment
796797047dSMatthias Ringwald---------------------------- |-----------| ----------------|------------------|----------------|---------
8013c41231SMatthias RingwaldAtmel ATWILC3000             | LE        | H4              | n.a.             | atwilc3000     | Firmware size: 60 kB
8194bb7abfSMatthias RingwaldBroadcom UART                | Dual mode | H4, H5          | Probably         | bcm            | Max UART baudrate 2 mbps
8294bb7abfSMatthias RingwaldBroadcom USB Dongles         | Dual mode | USB             | Yes              | bcm            |
83daa2e90cSMatthias RingwaldCSR UART                     | Dual mode | H4, H5, BCSP    | No (didn't work) | csr            |
84273591abSMatthias RingwaldCSR USB Dongles              | Dual mode | USB             | Yes              | csr            |
852c37f7fbSMatthias RingwaldCypress CYW20704             | Dual mode | H4, H5, USB     | Probably         | bcm            |
86ecde56a6SMatthias RingwaldDialog Semiconductor DA14581, DA14585 | LE        | H4, SPI         | n.a.             | da14581        | Official HCI firmware used
872c37f7fbSMatthias RingwaldEspressif ESP32              | Dual mode | VHCI            | Not yet          |                | SoC with Bluetooth and Wifi
888cc6abc3SMatthias RingwaldEM 9301, 9304                | LE        | SPI             | n.a.             | em9301         | Custom HCI SPI implementation
8953428cdeSMatthias RingwaldIntel Dual Wireless 8260, 8265 | Dual mode | USB           | Probably         | intel          | Firmware size: 400 kB
90273591abSMatthias RingwaldNordic nRF                   | LE        | H4              | n.a.             |                | Requires custom HCI firmware
91273591abSMatthias RingwaldSTM STLC2500D                | Classic   | H4              | No (didn't try)  | stlc2500d      | Custom deep sleep management not supported
927f8d4ab1SMatthias RingwaldToshiba TC35661              | Dual mode | H4              | No               | tc3566         |
93273591abSMatthias RingwaldTI CC256x, WL183x            | Dual mode | H4, H5, eHCILL  | Yes              | cc256x         | Also WL185x, WL187x, and WL189x
94273591abSMatthias Ringwald
95273591abSMatthias Ringwald[More infos on supported chipsets](https://bluekitchen-gmbh.com/btstack/develop/chipsets/)
9640276177SMatthias Ringwald
9740276177SMatthias Ringwald## Source Tree Overview
9840276177SMatthias RingwaldPath				| Description
9940276177SMatthias Ringwald--------------------|---------------
10040276177SMatthias Ringwaldchipset             | Support for individual Bluetooth chipsets
10140276177SMatthias Ringwalddoc                 | Sources for BTstack documentation
102b3d63497SMatthias Ringwaldexample             | Example applications available for all ports
10340276177SMatthias Ringwaldplatform            | Support for special OSs and/or MCU architectures
1047a33c82fSMatthias Ringwaldport                | Complete port for a MCU + Chipset combinations
10540276177SMatthias Ringwaldsrc                 | Bluetooth stack implementation
10640276177SMatthias Ringwaldtest                | Unit and PTS tests
10740276177SMatthias Ringwaldtool                | Helper tools for BTstack
108