README.md (42da4a89da4922020276970c4d49ec119428f6ad) README.md (43a197a7caea9356e35ab5095c560d5258d7cad3)
1**_Note: Major API Changes. For older projects, you may use the [v0.9 branch](https://github.com/bluekitchen/btstack/tree/v0.9).
2Please see [Migration notes](https://github.com/bluekitchen/btstack/blob/master/doc/manual/docs/appendix/migration.md)_**
3
4# Welcome to BTstack
5
6BTstack is [BlueKitchen's](http://bluekitchen-gmbh.com) implementation of the official Bluetooth stack.
7It is well suited for small, resource-constraint devices
8such as 8 or 16 bit embedded systems as it is highly configurable and comes with an ultra small memory footprint.
9A minimal configuration for an SPP server on a MSP430 can run in 32 kB FLASH and only 4 kB of RAM.
10
1**_Note: Major API Changes. For older projects, you may use the [v0.9 branch](https://github.com/bluekitchen/btstack/tree/v0.9).
2Please see [Migration notes](https://github.com/bluekitchen/btstack/blob/master/doc/manual/docs/appendix/migration.md)_**
3
4# Welcome to BTstack
5
6BTstack is [BlueKitchen's](http://bluekitchen-gmbh.com) implementation of the official Bluetooth stack.
7It is well suited for small, resource-constraint devices
8such as 8 or 16 bit embedded systems as it is highly configurable and comes with an ultra small memory footprint.
9A minimal configuration for an SPP server on a MSP430 can run in 32 kB FLASH and only 4 kB of RAM.
10
11It connects to the Bluetooth modules via a different Bluetooth HCI transport layers (e.g., HCI H4 UART and
12H5 the "Tree-Wire" protocol, HCI H2 USB). Various platforms can be easily targeted by providing the necessary
13UART, CPU, and CLOCK implementations.
11Targeting 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.
14
15On smaller embedded systems, a minimal run loop implementation allows to use BTstack without a Real Time OS (RTOS).
16If a RTOS is already provided, BTstack can be integrated and run as a single thread.
17
18On larger systems, BTstack provides a daemon that connects to a Bluetooth module.
19Multiple applications can communicate with this daemon over different inter-process communication methods.
20
12
13On smaller embedded systems, a minimal run loop implementation allows to use BTstack without a Real Time OS (RTOS).
14If a RTOS is already provided, BTstack can be integrated and run as a single thread.
15
16On larger systems, BTstack provides a daemon that connects to a Bluetooth module.
17Multiple applications can communicate with this daemon over different inter-process communication methods.
18
21BTstack supports both, the Central and the Peripheral Role of Bluetooth 4.2 Low Energy specification.
22It can be configures as both a single mode or a dual mode stack.
19BTstack supports the Central and the Peripheral Role of Bluetooth 4.2 Low Energy specification.
20It can be configured to run as either single-mode stack or a dual-mode stack.
23
21
24BTstack is free for non-commercial use. For commercial use, <a href="mailto:[email protected]">tell us</a>
25a bit about your project to get a quote.
26It has been qualified with the the Bluetooth SIG for GAP, IOP, HFP, HSP, SPP, PAN profiles and
27GATT, SM of the Bluetooth 4.2 LE Central and Peripheral roles (QD ID 25340).
22BTstack 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.
28
23
29## Documentation
30- [HTML](http://bluekitchen-gmbh.com/btstack/)
31- [PDF](http://bluekitchen-gmbh.com/btstack.pdf)
24#### Supported Protocols and Profiles
32
25
33## Discussion and Community Support
34[BTstack Google Group](http://groups.google.com/group/btstack-dev)
26**Protocols:** L2CAP, RFCOMM, SDP, BNEP, ATT, SM (incl. LE Secure Connections).
35
27
36## Supported Protocols and Profiles
28**Profiles** GAP, IOP, HFP, HSP, SPP, PAN, GATT.
37
29
38Protocols: L2CAP, RFCOMM, SDP, BNEP, ATT, SM (incl. LE Secure Connections).
30**Coming next** A2DP, AVRCP, HID, HOGP, BLE Mesh, and more.
39
31
40Profiles: GAP, IOP, HFP, HSP, SPP, PAN, GATT.
32It has been qualified with the the Bluetooth SIG for GAP, IOP, HFP, HSP, SPP, PAN profiles and
33GATT, SM of the Bluetooth 4.2 LE Central and Peripheral roles (QD ID 25340). For information on MFi/iAP2 support, please <a href="mailto:[email protected]">contact us</a>.
41
34
42Coming next: A2DP, AVRCP, HID, HOGP, BLE Mesh, and more.
35#### Documentation: [HTML](http://bluekitchen-gmbh.com/btstack/develop/), [PDF](http://bluekitchen-gmbh.com/btstack_develop.pdf)
43
36
44For information on MFi/iAP2 support, please <a href="mailto:[email protected]">contact us</a>.
37#### Discussion and Community Support: [BTstack Google Group](http://groups.google.com/group/btstack-dev)
45
38
39
46## Evaluation Platforms
47
48#### Embedded Platforms:
49Status | Platform
50-------------- | ------
40## Evaluation Platforms
41
42#### Embedded Platforms:
43Status | Platform
44-------------- | ------
51[<img src="http://buildbot.bluekitchen-gmbh.com/btstack/badge.png?builder=port-ez430-rf2560-master">](https://buildbot.bluekitchen-gmbh.com/btstack/builders/port-ez430-rf2560-master) | [EZ430-RF256x Bluetooth Evaluation Tool for MSP430](http://www.ti.com/tool/ez430-rf256x)
52[<img src="http://buildbot.bluekitchen-gmbh.com/btstack/badge.png?builder=port-msp-exp430f5438-cc2564b-master">](https://buildbot.bluekitchen-gmbh.com/btstack/builders/port-msp-exp430f5438-cc2564b-master) | [MSP430F5438 Experimenter Board for MSP430](http://www.ti.com/tool/msp-exp430f5438) with [Bluetooth CC2564 Module Evaluation Board](http://www.ti.com/tool/cc2564modnem)
53[<img src="http://buildbot.bluekitchen-gmbh.com/btstack/badge.png?builder=port-msp430f5229lp-cc2564b-master">](https://buildbot.bluekitchen-gmbh.com/btstack/builders/port-msp430f5229lp-cc2564b-master) | [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
54[<img src="http://buildbot.bluekitchen-gmbh.com/btstack/badge.png?builder=port-stm32-f103rb-nucleo-master">](https://buildbot.bluekitchen-gmbh.com/btstack/builders/port-stm32-f103rb-nucleo-master) | [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
55[<img src="http://buildbot.bluekitchen-gmbh.com/btstack/badge.png?builder=port-pic32-harmony-master">](https://buildbot.bluekitchen-gmbh.com/btstack/builders/port-pic32-harmony-master) | [Microchip's PIC32 Bluetooth Audio Development Kit](http://www.microchip.com/Developmenttools/ProductDetails.aspx?PartNO=DV320032)
56[<img src="http://buildbot.bluekitchen-gmbh.com/btstack/badge.png?builder=port-wiced-master">](https://buildbot.bluekitchen-gmbh.com/btstack/builders/port-wiced-master) | [RedBear Duo](https://github.com/redbear/WICED-SDK) with Broadcom BCM43438 A1
45[<img src="http://buildbot.bluekitchen-gmbh.com/btstack/badge.png?builder=port-ez430-rf2560-develop">](https://buildbot.bluekitchen-gmbh.com/btstack/builders/port-ez430-rf2560-develop) | [EZ430-RF256x Bluetooth Evaluation Tool for MSP430](http://www.ti.com/tool/ez430-rf256x)
46[<img src="http://buildbot.bluekitchen-gmbh.com/btstack/badge.png?builder=port-msp-exp430f5438-cc2564b-develop">](https://buildbot.bluekitchen-gmbh.com/btstack/builders/port-msp-exp430f5438-cc2564b-develop) | [MSP430F5438 Experimenter Board for MSP430](http://www.ti.com/tool/msp-exp430f5438) with [Bluetooth CC2564 Module Evaluation Board](http://www.ti.com/tool/cc2564modnem)
47[<img src="http://buildbot.bluekitchen-gmbh.com/btstack/badge.png?builder=port-msp430f5229lp-cc2564b-develop">](https://buildbot.bluekitchen-gmbh.com/btstack/builders/port-msp430f5229lp-cc2564b-develop) | [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
48[<img src="http://buildbot.bluekitchen-gmbh.com/btstack/badge.png?builder=port-stm32-f103rb-nucleo-develop">](https://buildbot.bluekitchen-gmbh.com/btstack/builders/port-stm32-f103rb-nucleo-develop) | [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
49[<img src="http://buildbot.bluekitchen-gmbh.com/btstack/badge.png?builder=port-pic32-harmony-develop">](https://buildbot.bluekitchen-gmbh.com/btstack/builders/port-pic32-harmony-develop) | [Microchip's PIC32 Bluetooth Audio Development Kit](http://www.microchip.com/Developmenttools/ProductDetails.aspx?PartNO=DV320032)
50[<img src="http://buildbot.bluekitchen-gmbh.com/btstack/badge.png?builder=port-wiced-develop">](https://buildbot.bluekitchen-gmbh.com/btstack/builders/port-wiced-develop) | [RedBear Duo](https://github.com/redbear/WICED-SDK) with Broadcom BCM43438 A1
57
58
59#### Other Platforms:
60Status | Platform
61-------------- | ------
51
52
53#### Other Platforms:
54Status | Platform
55-------------- | ------
62[<img src="http://buildbot.bluekitchen-gmbh.com/btstack/badge.png?builder=port-posix-h4-master">](https://buildbot.bluekitchen-gmbh.com/btstack/builders/port-posix-h4-master) | posix: Unix-based system talking to Bluetooth module via serial port
63[<img src="http://buildbot.bluekitchen-gmbh.com/btstack/badge.png?builder=port-libusb-master">](https://buildbot.bluekitchen-gmbh.com/btstack/builders/port-libusb-master) | libusb: Unix-based system talking via USB Bluetooth dongle
64[<img src="http://buildbot.bluekitchen-gmbh.com/btstack/badge.png?builder=port-daemon-master">](https://buildbot.bluekitchen-gmbh.com/btstack/builders/port-daemon-master) | daemon: TCP and Unix domain named socket client-server architecture supporting multiple clients
65[<img src="http://buildbot.bluekitchen-gmbh.com/btstack/badge.png?builder=java-master">](https://buildbot.bluekitchen-gmbh.com/btstack/builders/java-master) | java: Java wrapper for daemon
66[<img src="http://buildbot.bluekitchen-gmbh.com/btstack/badge.png?builder=port-ios-master">](https://buildbot.bluekitchen-gmbh.com/btstack/builders/port-ios-master) | iOS: daemon for iOS jailbreak devices, C client-server API
67[<img src="http://buildbot.bluekitchen-gmbh.com/btstack/badge.png?builder=port-mtk-master">](https://buildbot.bluekitchen-gmbh.com/btstack/builders/port-mtk-master) | mtk: daemon for rooted Android devices, based on Mediatek MT65xx processor, Java and C client-server API
68[<img src="http://buildbot.bluekitchen-gmbh.com/btstack/badge.png?builder=port-wiced-master">](https://buildbot.bluekitchen-gmbh.com/btstack/builders/port-wiced-master) | wiced: Broadcom platforms that support the WICED SDK
56[<img src="http://buildbot.bluekitchen-gmbh.com/btstack/badge.png?builder=port-posix-h4-develop">](https://buildbot.bluekitchen-gmbh.com/btstack/builders/port-posix-h4-develop) | posix: Unix-based system connected to Bluetooth module via serial port
57[<img src="http://buildbot.bluekitchen-gmbh.com/btstack/badge.png?builder=port-libusb-develop">](https://buildbot.bluekitchen-gmbh.com/btstack/builders/port-libusb-develop) | libusb: Unix-based system with dedicated USB Bluetooth dongle
58[<img src="http://buildbot.bluekitchen-gmbh.com/btstack/badge.png?builder=port-daemon-develop">](https://buildbot.bluekitchen-gmbh.com/btstack/builders/.. | windows-h4: Win32-based system connected to Bluetooth module via serial port
59.. | windwos-winusb: Win32-based system with dedicated USB Bluetooth dongle
60port-daemon-develop) | daemon: TCP and Unix domain named socket client-server architecture supporting multiple clients
61[<img src="http://buildbot.bluekitchen-gmbh.com/btstack/badge.png?builder=java-develop">](https://buildbot.bluekitchen-gmbh.com/btstack/builders/java-develop) | java: Java wrapper for daemon
62[<img src="http://buildbot.bluekitchen-gmbh.com/btstack/badge.png?builder=port-ios-develop">](https://buildbot.bluekitchen-gmbh.com/btstack/builders/port-ios-develop) | iOS: daemon for iOS jailbreak devices, C client-server API
63[<img src="http://buildbot.bluekitchen-gmbh.com/btstack/badge.png?builder=port-mtk-develop">](https://buildbot.bluekitchen-gmbh.com/btstack/builders/port-mtk-develop) | mtk: daemon for rooted Android devices, based on Mediatek MT65xx processor, Java and C client-server API
64[<img src="http://buildbot.bluekitchen-gmbh.com/btstack/badge.png?builder=port-wiced-develop">](https://buildbot.bluekitchen-gmbh.com/btstack/builders/port-wiced-develop) | wiced: Broadcom platforms that support the WICED SDK
69
70## Supported Chipsets
71
72Chipset | Type | HCI Transport | SCO over HCI (2) | BTstack folder | Comment
73-------------------- |-----------| ----------------|------------------|----------------|---------
74Broadcom UART | Dual mode | H4, H5 | Probably | bcm | Max UART baudrate 2 mbps
75Broadcom USB Dongles | Dual mode | USB | Yes | bcm |
76CSR UART | Dual mode | H4, H5 | No (didn't work) | csr |
77CSR USB Dongles | Dual mode | USB | Yes | csr |
78EM 9301 | LE | SPI | n.a. | em9301 | Custom HCI SPI implementation
79Nordic nRF | LE | H4 | n.a. | | Requires custom HCI firmware
80STM STLC2500D | Classic | H4 | No (didn't try) | stlc2500d | Custom deep sleep management not supported
81Toshiba TC35661 | Dual mode | H4 | No (didn't try) | tc3566 | HCI version not tested.
82TI CC256x, WL183x | Dual mode | H4, H5, eHCILL | Yes | cc256x | Also WL185x, WL187x, and WL189x
83
65
66## Supported Chipsets
67
68Chipset | Type | HCI Transport | SCO over HCI (2) | BTstack folder | Comment
69-------------------- |-----------| ----------------|------------------|----------------|---------
70Broadcom UART | Dual mode | H4, H5 | Probably | bcm | Max UART baudrate 2 mbps
71Broadcom USB Dongles | Dual mode | USB | Yes | bcm |
72CSR UART | Dual mode | H4, H5 | No (didn't work) | csr |
73CSR USB Dongles | Dual mode | USB | Yes | csr |
74EM 9301 | LE | SPI | n.a. | em9301 | Custom HCI SPI implementation
75Nordic nRF | LE | H4 | n.a. | | Requires custom HCI firmware
76STM STLC2500D | Classic | H4 | No (didn't try) | stlc2500d | Custom deep sleep management not supported
77Toshiba TC35661 | Dual mode | H4 | No (didn't try) | tc3566 | HCI version not tested.
78TI CC256x, WL183x | Dual mode | H4, H5, eHCILL | Yes | cc256x | Also WL185x, WL187x, and WL189x
79
84[More infos on supported chipsets](https://bluekitchen-gmbh.com/btstack/chipsets/)
80[More infos on supported chipsets](https://bluekitchen-gmbh.com/btstack/develop/chipsets/)
85
86## Source Tree Overview
87Path | Description
88--------------------|---------------
89chipset | Support for individual Bluetooth chipsets
90doc | Sources for BTstack documentation
91example | Example applications available for all ports
92platform | Support for special OSs and/or MCU architectures
93port | Complete port for a MCU + Chipset combinations
94src | Bluetooth stack implementation
95test | Unit and PTS tests
96tool | Helper tools for BTstack
81
82## Source Tree Overview
83Path | Description
84--------------------|---------------
85chipset | Support for individual Bluetooth chipsets
86doc | Sources for BTstack documentation
87example | Example applications available for all ports
88platform | Support for special OSs and/or MCU architectures
89port | Complete port for a MCU + Chipset combinations
90src | Bluetooth stack implementation
91test | Unit and PTS tests
92tool | Helper tools for BTstack