xref: /btstack/chipset/README.md (revision 4ce43359e6190a70dcb8ef079b902c1583c2abe4)
1c00c65faSMatthias RingwaldIn this chapter, we first explain how Bluetooth chipsets are connected physically and then provide information about popular Bluetooth chipset and their use with BTstack.
235e00af0SMatthias Ringwald
3c00c65faSMatthias Ringwald## HCI Interface
4c00c65faSMatthias Ringwald
5c00c65faSMatthias RingwaldThe communication between a Host (a computer or an MCU) and a Host Controller (the actual Bluetooth chipset) follows the Host Controller Interface (HCI), see {@fig:HostChipsetConnection}. HCI defines how commands, events, asynchronous and synchronous data packets are exchanged. Asynchronous packets (ACL) are used for data transfer, while synchronous packets (SCO) are used for Voice with the Headset and the Hands-Free Profiles.
635e00af0SMatthias Ringwald
77a656c79SMatthias Ringwald![Host Controller to Host connection](../doc/manual/docs/picts/host_chipset_connection.png){#fig:HostChipsetConnection}
835e00af0SMatthias Ringwald
9c00c65faSMatthias Ringwald### HCI H2
10c00c65faSMatthias RingwaldOn desktop-class computers incl. laptops, USB is mainly used as HCI transport layer. For USB Bluetooth chipsets, there is little variation: most USB dongles on the market currently contain a Broadcom BCM20702 or a CSR 851x chipset. It is also called H2.
11c00c65faSMatthias Ringwald
1235e00af0SMatthias RingwaldOn embedded systems, UART connections are used instead, although USB could be used as well.
1335e00af0SMatthias Ringwald
14c00c65faSMatthias RingwaldFor UART connections, different transport layer variants exist.
1535e00af0SMatthias Ringwald
16c00c65faSMatthias Ringwald### HCI H4
17c00c65faSMatthias RingwaldThe most common one is the official "UART Transport", also called H4. It requires hardware flow control via the CTS/RTS lines and assumes no errors on the UART lines.
18c00c65faSMatthias Ringwald
19c00c65faSMatthias Ringwald### HCI H5
20c00c65faSMatthias RingwaldThe "Three-Wire UART Transport", also called H5, makes use of the SLIP protocol to transmit a packet and can deal with packet loss and bit-errors by retransmission. While it is possible to use H5 really with "three wires" without hardware handshake, we recommend to use a full UART with hardware handshake. If your design lacks the hardware handshake, H5 is your only option.
21c00c65faSMatthias Ringwald
22daa2e90cSMatthias Ringwald### BCSP
23daa2e90cSMatthias RingwaldThe predecessor of H5. The main difference to H5 is that Even Parity is used for BCSP. To use BCSP with BTstack, you use the H5 transport and can call *hci_transport_h5_enable_bcsp_mode*
24daa2e90cSMatthias Ringwald
25c00c65faSMatthias Ringwald### eHCILL
26c00c65faSMatthias RingwaldFinally, Texas Instruments extended H4 to create the "eHCILL transport" layer that allows both sides to enter sleep mode without loosing synchronisation. While it is easier to implement than H5, it it is only supported by TI chipsets and cannot handle packet loss or bit-errors.
27c00c65faSMatthias Ringwald
287c5fbb27SMatthias Ringwald### H4 over SPI
297c5fbb27SMatthias RingwaldChipsets from Dialog Semiconductor and EM Marin allow to send H4 formatted HCI packets via SPI. SPI has the benefit of a simpler implementation for both Host Controller and Host as it does not require an exact clock. The SPI Master, here the Host, provides the SPI Clock and the SPI Slave (Host Controller) only has to read and update it's data lines when the clock line changes. The EM9304 supports an SPI clock of up to 8 Mhz. However, an additional protocol is needed to let the Host know when the Host Controller has HCI packet for it. Often, an additional GPIO is used to signal this.
307c5fbb27SMatthias Ringwald
31c00c65faSMatthias Ringwald### HCI Shortcomings
3235e00af0SMatthias Ringwald
3335e00af0SMatthias RingwaldUnfortunately, the HCI standard misses a few relevant details:
3435e00af0SMatthias Ringwald
35c00c65faSMatthias Ringwald  * For UART based connections, the initial baud rate isn't defined but most Bluetooth chipsets use 115200 baud. For better throughput, a higher baud rate is necessary, but there's no standard HCI command to change it. Instead, each vendor had to come up with their own set of vendor-specific commands. Sometimes, additional steps, e.g. doing a warm reset, are necessary to activate the baud rate change as well.
3635e00af0SMatthias Ringwald
3735e00af0SMatthias Ringwald  * Some Bluetooth chipsets don't have a unique MAC address. On start, the MAC address needs to be set, but there's no standard HCI command to set it.
3835e00af0SMatthias Ringwald
3935e00af0SMatthias Ringwald  * SCO data for Voice can either be transmitted via the HCI interface or via an explicit PCM/I2S interface on the chipset. Most chipsets default to the PCM/I2S interface. To use it via USB or for Wide-Band Speech in the Hands-Free Profile, the data needs to be delivered to the host MCU. Newer Bluetooth standards define a HCI command to configure the SCO routing, but it is not implemented in the chipsets we've tested so far. Instead, this is configured in a vendor-specific way as well.
4035e00af0SMatthias Ringwald
41c00c65faSMatthias Ringwald  * In addition, most vendors allow to patch or configure their chipsets at run time by sending custom commands to the chipset. Obviously, this is also vendor dependent.
4235e00af0SMatthias Ringwald
43c00c65faSMatthias Ringwald## Documentation and Support
4435e00af0SMatthias RingwaldThe level of developer documentation and support varies widely between the various Bluetooth chipset providers.
4535e00af0SMatthias Ringwald
4635e00af0SMatthias RingwaldFrom our experience, only Texas Instruments and EM Microelectronics provide all relevant information directly on their website. Nordic Semiconductor does not officially have Bluetooth chipsets with HCI interface, but their the documentation on their nRF5 series is complete and very informative. TI and Nordic also provide excellent support via their respective web forum.
4735e00af0SMatthias Ringwald
4835e00af0SMatthias RingwaldBroadcom, whose Bluetooth + Wifi division has been acquired by the Cypress Semiconductor Corporation, provides developer documentation only to large customers as far as we know. It's possible to join their Community forum and download the WICED SDK. The WICED SDK is targeted at Wifi + Bluetooth Combo chipsets and contains the necessary chipset patch files.
4935e00af0SMatthias Ringwald
5035e00af0SMatthias RingwaldCSR, which has been acquired by Qualcomm, provides all relevant information on their Support website after signing an NDA.
5135e00af0SMatthias Ringwald
52c00c65faSMatthias Ringwald## Chipset Overview
53c00c65faSMatthias Ringwald
54439b93a1SMatthias RingwaldChipset              | Type      | HCI Transport  | BD_ADDR (1)  | SCO over HCI (2) | LE DLE | Multiple LE Roles    | BTstack folder | Comment
5535e00af0SMatthias Ringwald-------------------- |-----------| ---------------|--------------|------------------|--------|----------------------|----------------|---------
562c37f7fbSMatthias RingwaldAtmel ATWILC3000     | LE        | H4             | Yes          | Don't know       | No     |         No           | atwilc3000     | BLE Firmware size: 60 kB
57*4ce43359SMatthias RingwaldBroadcom UART        | Dual mode | H4, H5         | Rarely       | Partially (2)    | No     |      Maybe (3)       | bcm            | Max UART baudrate 2 mbps
58d77060bdSMatthias RingwaldBroadcom USB Dongles | Dual mode | USB            | Yes          | Yes              | No     |         No           | bcm            |
59*4ce43359SMatthias RingwaldCSR UART             | Dual mode | H4, H5, BCSP   | Rarely       | Partially (2)    | No     |         No           | csr            |
6035e00af0SMatthias RingwaldCSR USB Dongles      | Dual mode | USB            | Mostly       | Yes              | No     |         No           | csr            |
61*4ce43359SMatthias RingwaldCypress CYW20704     | Dual mode | H4, H5, USB    | Don't know   | Partially (2)    | Yes    |        Yes           | bcm            |
6265b6e0cdSMatthias RingwaldDialog DA14581       | LE        | H4, SPI        | No           | n.a.             | No     |         No           | da14581        | Official HCI firmware included in BTstack
63ecde56a6SMatthias RingwaldDialog DA14585       | LE        | H4, SPI        | No           | n.a.             | Yes    |        Yes           | da14581        | Official HCI firmware included in BTstack
64*4ce43359SMatthias RingwaldDialog DA1469x       | LE        | H4, SPI        | No           | n.a.             | Yes    |        Yes           | da14581        | HCI Firmware part of DA1469x SDK
652c37f7fbSMatthias RingwaldEspressif ESP32      | Dual mode | VHCI           | Yes          | Not yet          | Yes    |        Yes           |                | SoC with Bluetooth and Wifi
667c5fbb27SMatthias RingwaldEM 9301              | LE        | SPI, H4        | No           | n.a.             | No     |         No           | em9301         | Custom HCI SPI implementation
674bdbd754SMatthias RingwaldEM 9304              | LE        | SPI, H4        | Yes          | n.a.             | Yes    |        Yes           | em9301         | Custom HCI SPI implementation
6853428cdeSMatthias RingwaldIntel Dual Wireless 8260, 8265 | Dual mode | USB  | Yes          | Probably         | Don't know | Don't know       | intel          | Firmware size: 400 kB
69410be61aSMatthias RingwaldNordic nRF           | LE        | H4             | Fixed Random | n.a.             | Yes    |        Yes           |                | Requires HCI firmware
7035e00af0SMatthias RingwaldSTM STLC2500D        | Classic   | H4             | No           | No (didn't try)  | n.a    |         n.a.         | stlc2500d      | Custom deep sleep management not supported
717f8d4ab1SMatthias RingwaldToshiba TC35661      | Dual mode | H4             | No           | No               | No     |         No           | tc3566         | Only -007/009 models provide full HCI. See below
72439b93a1SMatthias RingwaldTI CC256x, WL183x    | Dual mode | H4, H5, eHCILL | Yes          | Yes              | No     |    Yes for CC256XC   | cc256x         | Also WL185x, WL187x, and WL189x
7335e00af0SMatthias Ringwald
7435e00af0SMatthias Ringwald**Notes**:
7535e00af0SMatthias Ringwald
762c37f7fbSMatthias Ringwald  1. BD_ADDR: Indiates if Bluetooth chipset compes with its own valid MAC Addess. Better Broadcom and CSR dongles usually come with a MAC address from the dongle manufacturer, but cheaper ones might come with identical addresses.
77*4ce43359SMatthias Ringwald  2. SCO over HCI: All Bluetooth Classic chipsets support SCO over HCI in general. BTstack can receive SCO packets without problems. However, only TI CC256x has support for using SCO buffers in the Controller and a useful flow control. On CSR/Broadcom/Cypress Controllers, BTstack cannot queue multiple SCO packets in the Controller. Instead, the SCO packet must be sent periodically at the right time - without a clear indication about when this time is. The current implementation observes the timestamps of the received SCO packets to schedule sending packets. With full control over the system and no other Bluetooth data, this can be flawless, but it's rather fragile in general. For these, it's necessary to use the I2S/PCM interface for stable operation.
78*4ce43359SMatthias Ringwald  , for those that are marked with No, we either didn't try or didn't found enough information to configure it correctly.
79c00c65faSMatthias Ringwald  3. Multiple LE Roles: Apple uses Broadcom Bluetooth+Wifi in their iOS devices and newer iOS versions support multiple concurrent LE roles,
8035e00af0SMatthias Ringwald  so at least some Broadcom models support multiple concurrent LE roles.
81fbacaeecSMatthias Ringwald
82fbacaeecSMatthias Ringwald## Atmel/Microchip
83fbacaeecSMatthias Ringwald
842c37f7fbSMatthias RingwaldThe ATILC3000 Bluetooth/Wifi combo controller has been used with Linux on embedded devices by Atmel/Microchip. Drivers and documentation are available from a [GitHub repository](https://github.com/atwilc3000). The ATWILC3000 has a basic HCI implementation stored in ROM and requires a firmware image to be uploaded before it can be used. The BLE Controller is qualified as [QDID 99659](https://www.bluetooth.org/tpg/QLI_viewQDL.cfm?qid=36402). Please note: the BLE firmware is around 60 kB. It might need a separate Wifi firmware as well.
85fbacaeecSMatthias Ringwald
867d82eb50SMatthias Ringwald**BD Addr** can be set with vendor-specific command although all chipsets have an official address stored. The BD_ADDR lookup results in "Newport Media Inc." which was [acquired by Atmel](http://www.atmel.com/about/news/release.aspx?reference=tcm:26-62532) in 2014.
87fbacaeecSMatthias Ringwald
88fbacaeecSMatthias Ringwald**Baud rate** can be set with a custom command.
89fbacaeecSMatthias Ringwald
90fbacaeecSMatthias Ringwald**BTstack integration**: *btstack_chipset_atwilc3000.c* contains the code to download the Bluetooth firmware image into the RAM of the ATWILC3000. After that, it can be normally used by BTstack.
9135e00af0SMatthias Ringwald
9284827a69SMatthias Ringwald## Broadcom/Cypress Semiconductor
9335e00af0SMatthias Ringwald
9429c2a6e3SMatthias RingwaldBefore the Broadcom Wifi+Bluetooth division was taken over by Cypress Semiconductor, it was not possible to buy Broadcom chipset in low quantities. Nevertheless, module manufacturers like Ampak created modules that contained Broadcom BCM chipsets (Bluetooth as well as Bluetooth+Wifi combos) that might already have been pre-tested for FCC and similar certifications.
952c37f7fbSMatthias Ringwald
96c00c65faSMatthias RingwaldA popular example is the Ampak AP6212A module that contains an BCM 43438A1 and is used on the Raspberry Pi 3, the RedBear Duo, and the RedBear IoT pHAT for older Raspberry Pi models.
9735e00af0SMatthias Ringwald
982c37f7fbSMatthias RingwaldThe CYW20704 A2 controller supports both DLE as well as multiple LE roles and is available e.g. from [LairdTech](https://www.lairdtech.com/bt850-bt851-and-bt860-series-modules-adapter-dvks-0002) as UART module (BT860), USB module (BT850), and USB dongle.
992c37f7fbSMatthias Ringwald
100*4ce43359SMatthias RingwaldInterestingly, the CYW20704 exhibits the same UART flow control bug as the CC2564. You can add ENABLE_CYPRESS_BAUDRATE_CHANGE_FLOWCONTROL_BUG_WORKAROUND to activate a workaround and/or read the bug & workardound description in the TI section below.
101*4ce43359SMatthias Ringwald
102*4ce43359SMatthias RingwaldThe best source for documentation on vendor specific commands so far has been the source code for blueZ and the Bluedroid Bluetooth stack from Android, but with the takeover by Cypress, documentation is directly available.
10335e00af0SMatthias Ringwald
10435e00af0SMatthias RingwaldBroadcom USB dongles do not require special configuration, however SCO data is not routed over USB by default.
10535e00af0SMatthias Ringwald
10635e00af0SMatthias Ringwald**Init scripts**: For UART connected chipsets, an init script has to be uploaded after power on. For Bluetooth chipsets that are used in Broadcom Wifi+Bluetooth combos, this file often can be found as a binary file in Linux distributions with the ending *'.hcd'* or as part of the WICED SDK as C source file that contains the init script as a data array for use without a file system.
10735e00af0SMatthias Ringwald
10835e00af0SMatthias RingwaldTo find the correct file, Broadcom chipsets return their model number when asked for their local name.
10935e00af0SMatthias Ringwald
11094bb7abfSMatthias RingwaldBTstack supports uploading of the init script in two variants: using .hcd files looked up by name in the posix-h4 port and by linking against the init script in the WICED port. While the init script is processed, the chipsets RTS line goes high, but only 2 ms after the command complete event for the last command from the init script was sent. BTstack waits for 10 ms after receiving the command complete event for the last command to avoid sending before RTS goes high and the command fails.
11135e00af0SMatthias Ringwald
112c00c65faSMatthias Ringwald**BD Addr** can be set with a custom command. A fixed address is provided on some modules, e.g. the AP6212A, but not on others.
11335e00af0SMatthias Ringwald
11494bb7abfSMatthias Ringwald**SCO data** can be configured with a custom command found in the bluez sources. It works with USB chipsets. The chipsets don't implement the SCO Flow Control that is used by BTstack for UART connected devices. A forum suggests to send SCO packets as fast as they are received since both directions have the same constant speed.
11535e00af0SMatthias Ringwald
11629c2a6e3SMatthias Ringwald**Baud rate** can be set with custom command. The baud rate resets during the warm start after uploading the init script. So, the overall scheme is this: start at default baud rate, get local version info, send custom Broadcom baud rate change command, wait for response, set local UART to high baud rate, and then send init script. After sending the last command from the init script, reset the local UART. Finally, send custom baud rate change command, wait for response, and set local UART to high baud rate.
11735e00af0SMatthias Ringwald
11835e00af0SMatthias Ringwald**BTstack integration**: The common code for all Broadcom chipsets is provided by *btstack_chipset_bcm.c*. During the setup, *btstack_chipset_bcm_instance* function is used to get a *btstack_chipset_t* instance and passed to *hci_init* function.
11935e00af0SMatthias Ringwald
1202c37f7fbSMatthias RingwaldSCO Data can be routed over HCI for both USB dongles and UART connections, however BTstack does not support flow control for UART connections. HSP and HFP Narrow Band Speech is supported via I2C/PCM pins.
12135e00af0SMatthias Ringwald
12284827a69SMatthias Ringwald## CSR / Qualcomm Incorporated
12384827a69SMatthias Ringwald
12484827a69SMatthias RingwaldCSR plc has been acquired by Qualcomm Incorporated in August 2015.
12535e00af0SMatthias Ringwald
12635e00af0SMatthias RingwaldSimilar to Broadcom, the best source for documentation is the source code for blueZ.
12735e00af0SMatthias Ringwald
12835e00af0SMatthias RingwaldCSR USB dongles do not require special configuration and SCO data is routed over USB by default.
12935e00af0SMatthias Ringwald
13035e00af0SMatthias RingwaldCSR chipset do not require an actual init script in general, but they allow to configure the chipset via so-called PSKEYs. After setting one or more PSKEYs, a warm reset activates the new setting.
13135e00af0SMatthias Ringwald
13235e00af0SMatthias Ringwald**BD Addr** can be set via PSKEY. A fixed address can be provided if the chipset has some kind of persistent memory to store it. Most USB Bluetooth dongles have a fixed BD ADDR.
13335e00af0SMatthias Ringwald
13435e00af0SMatthias Ringwald**SCO data** can be configured via a set of PSKEYs. We haven't been able to route SCO data over HCI for UART connections yet.
13535e00af0SMatthias Ringwald
13629c2a6e3SMatthias Ringwald**Baud rate** can be set as part of the initial configuration and gets actived by the warm reset.
13735e00af0SMatthias Ringwald
13835e00af0SMatthias Ringwald**BTstack integration**: The common code for all Broadcom chipsets is provided by *btstack_chipset_csr.c*. During the setup, *btstack_chipset_csr_instance* function is used to get a *btstack_chipset_t* instance and passed to *hci_init* function. The baud rate is set during the general configuration.
13935e00af0SMatthias Ringwald
14035e00af0SMatthias RingwaldSCO Data is routed over HCI for USB dongles, but not for UART connections. HSP and HFP Narrow Band Speech is supported via I2C/PCM pins.
14135e00af0SMatthias Ringwald
14235e00af0SMatthias Ringwald
14335e00af0SMatthias Ringwald## Dialog Semiconductor
14435e00af0SMatthias Ringwald
14529c2a6e3SMatthias RingwaldDialog Semiconductor offers the DA14581, an LE-only SoC that can be programmed with an HCI firmware. The HCI firmware can be uploaded on boot into SRAM or stored in the OTP (One-time programmable) memory, or in an external SPI.
14635e00af0SMatthias Ringwald
147fbacaeecSMatthias RingwaldIt does not implement the Data Length Extension or supports multiple concurrent roles.
148c240379eSMatthias Ringwald
149ecde56a6SMatthias RingwaldThe newer DA14585 uses the same firmware upload mechanism as the 581 model. In addition, it supports both Data Length Extension as well as multiple concurrent roles.
150ecde56a6SMatthias Ringwald
151*4ce43359SMatthias RingwaldThe even newer DA1469x uses an external flash. The DA 1469x SDK contains a HCI firmware that can be compiled and downloaded into flash using the SmartSnippets Studio.
152*4ce43359SMatthias Ringwald
15365b6e0cdSMatthias Ringwald**BD Addr** fixed to 80:EA:CA:00:00:01. No command in HCI firmware to set it differently. Random addresses could be used instead.
15465b6e0cdSMatthias Ringwald
155*4ce43359SMatthias Ringwald**Baud rate**: The baud rate is fixed at 115200 with the provided firmware. A higher baud rate could be achieved by re-compiling the HCI firmware.
156c240379eSMatthias Ringwald
157*4ce43359SMatthias Ringwald**BTstack integration**: *btstack_chipset_da14581.c* contains the code to download the provided HCI firmware into the SRAM of the DA1458x. After that, it can be used as any other HCI chipset. No special support needed for DA1469x.
15835e00af0SMatthias Ringwald
1596e0288c2SMatthias Ringwald## Espressif ESP32
1606e0288c2SMatthias Ringwald
1612c37f7fbSMatthias RingwaldThe ESP32 is a SoC with a built-in Dual mode Bluetooth and Wifi radio. The HCI Controller is implemented in software and accessed via a so called Virtual HCI (VHCI) interface. It supports both LE Data Length Extensions (DLE) as well as multiple LE roles. SCO isn't supported currently, but [Espressif is working on it](https://github.com/espressif/esp-idf/issues/1118).
1622c37f7fbSMatthias Ringwald
1632c37f7fbSMatthias RingwaldBluetooth/Wifi Co-existance didn't work until recently and [seems to have been fixed](https://github.com/espressif/esp-idf/issues/1291)
1646e0288c2SMatthias Ringwald
16535e00af0SMatthias Ringwald## EM Microelectronic Marin
16635e00af0SMatthias Ringwald
167c00c65faSMatthias RingwaldFor a long time, the EM9301 has been the only Bluetooth Single-Mode LE chipset with an HCI interface. The EM9301 can be connected via SPI or UART. The UART interface does not support hardware flow control and is not recommended for use with BTstack. The SPI mode uses a proprietary but documented extension to implement flow control and signal if the EM9301 has data to send.
16835e00af0SMatthias Ringwald
169c1fc8abcSMatthias RingwaldIn December 2016, EM released the new EM9304 that also features an HCI mode and adds support for optional Bluetooth 4.2. features. It supports the Data Length Extension and up to 8 LE roles. The EM9304 is a larger MCU that allows to run custom code on it. For this, an advanced mechanism to upload configuration and firmware to RAM or into an One-Time-Programmable area of 128 kB is supported. It supports a superset of the vendor specific commands of the EM9301.
17035e00af0SMatthias Ringwald
171c1fc8abcSMatthias RingwaldEM9304 is used by the 'stm32-l053r8-em9304' port in BTstack. The port.c file also contains an IRQ+DMA-driven implementation of the SPI H4 protocol specified in the [datasheet](http://www.emmicroelectronic.com/sites/default/files/public/products/datasheets/9304-ds_0.pdf).
172f93a2017SMatthias Ringwald
1732c37f7fbSMatthias Ringwald**BD Addr** must be set during startup for EM9301 since it does not have a stored fix address. The EM9304 comes with an valid address stored in OTP.
17435e00af0SMatthias Ringwald
17535e00af0SMatthias Ringwald**SCO data** is not supported since it is LE only.
17635e00af0SMatthias Ringwald
1772c37f7fbSMatthias Ringwald**Baud rate** can be set for UART mode. For SPI, the master controls the speed via the SPI Clock line. With 3.3V, 16 Mhz is supported.
17835e00af0SMatthias Ringwald
1792c37f7fbSMatthias Ringwald**Init scripts** are not required although it is possible to upload small firmware patches to RAM or the OTP memory (EM9304 only).
18035e00af0SMatthias Ringwald
181c1fc8abcSMatthias Ringwald**BTstack integration**: The common code for the EM9304 is provided by *btstack_chipset_em9301.c*. During the setup, *btstack_chipset_em9301_instance* function is used to get a *btstack_chipset_t* instance and passed to *hci_init* function. It enables to set the BD Addr during start.
18235e00af0SMatthias Ringwald
1838174b66aSMatthias Ringwald## Intel Dual Wireless 8260, 8265
1848174b66aSMatthias Ringwald
1858174b66aSMatthias RingwaldWifi/Bluetooth combo cards mainly used in mobile computers. The Bluetooth part requires the upload of a firmware file and a configuration file. SCO, DLE, Multiple roles not tested.
1868174b66aSMatthias Ringwald
18735e00af0SMatthias Ringwald## Nordic nRF5 series
18835e00af0SMatthias Ringwald
189410be61aSMatthias RingwaldThe Single-Mode LE chipsets from the Nordic nRF5 series chipsets usually do not have an HCI interface. Instead, they provide an LE Bluetooth Stack as a binary library, the so-called *SoftDevices*. Developer can write their Bluetooth application on top of this library. Since the chipset can be programmed, it can also be loaded with a firmware that provides a regular HCI H4 interface for a Host.
19035e00af0SMatthias Ringwald
19135e00af0SMatthias RingwaldAn interesting feature of the nRF5 chipsets is that they can support multiple LE roles at the same time, e.g. being Central in one connection and a Peripheral in another connection. Also, the nRF52 SoftDevice implementation supports the Bluetooth 4.2 Data Length Extension.
19235e00af0SMatthias Ringwald
193410be61aSMatthias RingwaldBoth nRF5 series, the nRF51 and the nRF52, can be used with an HCI firmware. The nRF51 does not support encrypted connections at the moment (November 18th, 2016) although this might become supported as well.
19435e00af0SMatthias Ringwald
19535e00af0SMatthias Ringwald**BD ADDR** is not set automatically. However, during production, a 64-bit random number is stored in the each chip. Nordic uses this random number as a random static address in their SoftDevice implementation.
19635e00af0SMatthias Ringwald
19735e00af0SMatthias Ringwald**SCO data** is not supported since it is LE only.
19835e00af0SMatthias Ringwald
199c00c65faSMatthias Ringwald**Baud rate** is fixed to 115200 by the patch although the firmware could be extended to support a baud rate change.
20035e00af0SMatthias Ringwald
20135e00af0SMatthias Ringwald**Init script** is not required.
20235e00af0SMatthias Ringwald
203410be61aSMatthias Ringwald**BTstack integration**: Support for a nRF5 chipset with the Zephyr Controller is provided by *btstack_chipset_zephyr.c*. It queries the static random address during init.
20435e00af0SMatthias Ringwald
20535e00af0SMatthias RingwaldTo use these chipsets with BTstack, you need to install an arm-none-eabi gcc toolchain and the nRF5x Command Line Tools incl. the J-Link drivers, checkout the Zephyr project, apply a minimal patch to help with using a random static address, and flash it onto the chipset:
20635e00af0SMatthias Ringwald
20735e00af0SMatthias Ringwald  * Install [J-Link Software and documentation pack](https://www.segger.com/jlink-software.html).
20835e00af0SMatthias Ringwald  * Get nrfjprog as part of the [nRFx-Command-Line-Tools](http://www.nordicsemi.com/eng/Products/Bluetooth-low-energy/nRF52-DK). Click on Downloads tab on the top and look for your OS.
20929c2a6e3SMatthias Ringwald  * [Checkout Zephyr and install toolchain](https://www.zephyrproject.org/doc/getting_started/getting_started.html). We recommend using the [arm-non-eabi gcc binaries](https://launchpad.net/gcc-arm-embedded) instead of compiling it yourself. At least on OS X, this failed for us.
21035e00af0SMatthias Ringwald
21135e00af0SMatthias Ringwald  * In *samples/bluetooth/hci_uart* compile the firmware for nRF52 Dev Kit
21235e00af0SMatthias Ringwald
21335e00af0SMatthias Ringwald<!-- -->
21435e00af0SMatthias Ringwald
21535e00af0SMatthias Ringwald      $ make BOARD=nrf52_pca10040
21635e00af0SMatthias Ringwald
21735e00af0SMatthias Ringwald   * Upload the firmware
21835e00af0SMatthias Ringwald
21935e00af0SMatthias Ringwald      $ ./flash_nrf52_pca10040.sh
22035e00af0SMatthias Ringwald
22135e00af0SMatthias Ringwald   * For the nRF51 Dev Kit, use `make BOARD=nrf51_pca10028` and `./flash_nrf51_10028.sh` with the nRF51 kit.
22235e00af0SMatthias Ringwald   * The nRF5 dev kit acts as an LE HCI Controller with H4 interface.
22335e00af0SMatthias Ringwald
22435e00af0SMatthias Ringwald## STMicroelectronics
22535e00af0SMatthias Ringwald
22635e00af0SMatthias RingwaldSTMicroelectronics offers the Bluetooth V2.1 + EDR chipset STLC2500D that supports SPI and UART H4 connection.
22735e00af0SMatthias Ringwald
228c00c65faSMatthias Ringwald**BD Addr** can be set with custom command although all chipsets have an official address stored.
22935e00af0SMatthias Ringwald
23035e00af0SMatthias Ringwald**SCO data** might work. We didn't try.
23135e00af0SMatthias Ringwald
23229c2a6e3SMatthias Ringwald**Baud rate** can be set with custom command. The baud rate change of the chipset happens within 0.5 seconds. At least on BTstack, knowning exactly when the command was fully sent over the UART is non-trivial, so BTstack switches to the new baud rate after 100 ms to expect the command response on the new speed.
23335e00af0SMatthias Ringwald
23435e00af0SMatthias Ringwald**Init scripts** are not required although it is possible to upload firmware patches.
23535e00af0SMatthias Ringwald
23635e00af0SMatthias Ringwald**BTstack integration**: Support for the STLC2500C is provided by *btstack_chipset_stlc.c*. During the setup, *btstack_chipset_stlc2500d_instance* function is used to get a *btstack_chipset_t* instance and passed to *hci_init* function. It enables higher UART baud rate and to set the BD Addr during startup.
23735e00af0SMatthias Ringwald
23835e00af0SMatthias Ringwald
23935e00af0SMatthias Ringwald
24035e00af0SMatthias Ringwald## Texas Instruments CC256x series
24135e00af0SMatthias Ringwald
2424bdbd754SMatthias RingwaldThe Texas Instruments CC256x series is currently in its fourth iteration and provides a Classic-only (CC2560), a Dual-mode (CC2564), and a Classic + ANT (CC2567) model. A variant of the Dual-mode chipset is also integrated into TI's WiLink 8 Wifi+Bluetooth combo modules of the WL183x, WL185x, WL187x, and WL189x series. Some of the latter support ANT as well.
24335e00af0SMatthias Ringwald
24435e00af0SMatthias RingwaldThe CC256x chipset is connected via an UART connection and supports the H4, H5 (since third iteration), and eHCILL.
24535e00af0SMatthias Ringwald
246439b93a1SMatthias RingwaldThe latest generation CC256xC chipsets support multiple LE roles in parallel.
247439b93a1SMatthias Ringwald
248fb904c26SMatthias RingwaldThe different CC256x chipset can be identified by the LMP Subversion returned by the *hci_read_local_version_information* command. TI also uses a numeric way (AKA) to identify their chipsets. The table shows the LMP Subversion and AKA number for the CC256x and the WL18xx series.
2494f537631SMatthias Ringwald
2504f537631SMatthias RingwaldChipset | LMP Subversion |  AKA
25148093f19SMatthias Ringwald--------|----------------|-------
2524f537631SMatthias RingwaldCC2560  |         0x191f | 6.2.31
25324a96a28SMatthias RingwaldCC2560A, CC2564, CC2567 | 0x1B0F | 6.6.15
2544f537631SMatthias RingwaldCC256xB |         0x1B90 | 6.7.16
2554f537631SMatthias RingwaldCC256xC |         0x9a1a | 6.12.26
256fb904c26SMatthias RingwaldWL18xx  |         0xac20 | 11.8.32
2574f537631SMatthias Ringwald
25835e00af0SMatthias Ringwald**SCO data** is routed to the I2S/PCM interface but can be configured with the [HCI_VS_Write_SCO_Configuration](http://processors.wiki.ti.com/index.php/CC256x_VS_HCI_Commands#HCI_VS_Write_SCO_Configuration_.280xFE10.29) command.
25935e00af0SMatthias Ringwald
26039e7ee9fSMatthias Ringwald**Baud rate** can be set with [HCI_VS_Update_UART_HCI_Baudrate](http://processors.wiki.ti.com/index.php/CC256x_VS_HCI_Commands#HCI_VS_Update_UART_HCI_Baudrate_.280xFF36.29). The chipset confirms the change with a command complete event after which the local UART is set to the new speed. Oddly enough, the CC256x chipsets ignore the incoming CTS line during this particular command complete response.
26139e7ee9fSMatthias Ringwald
26239e7ee9fSMatthias RingwaldIf you've implemented the hal_uart_dma.h without an additional ring buffer (as recommended!) and you have a bit of delay, e.g. because of thread switching on a RTOS, this could cause a UART overrun. If this happens, BTstack provides a workaround in the HCI H4 transport implementation by adding #define ENABLE_CC256X_BAUDRATE_CHANGE_FLOWCONTROL_BUG_WORKAROUND to your btstack_config.h. If this is enabled, the H4 transport layer will resort to "deep packet inspection" to first check if its a TI controller and then wait for the HCI_VS_Update_UART_HCI_Baudrate. When detected, it will tweak the next UART read to expect the HCI Command Complete event.
26371aad618SMatthias Ringwald
2644e94d79fSMatthias Ringwald**BD Addr** can be set with [HCI_VS_Write_BD_Addr](2.2.1 HCI_VS_Write_BD_Addr (0xFC06)) although all chipsets have an official address stored.
2654e94d79fSMatthias Ringwald
2664e94d79fSMatthias Ringwald**Init Scripts.** In order to use the CC256x chipset an initialization script must be obtained and converted into a C file for use with BTstack. For newer revisions, TI provides a main.bts and a ble_add_on.bts that need to be combined.
2674e94d79fSMatthias Ringwald
2684e94d79fSMatthias RingwaldThe Makefile at *chipset/cc256x/Makefile.inc* is able to automatically download and convert the requested file. It does this by:
2694e94d79fSMatthias Ringwald
2704e94d79fSMatthias Ringwald-   Downloading one or more [BTS files](http://processors.wiki.ti.com/index.php/CC256x_Downloads) for your chipset.
2714e94d79fSMatthias Ringwald-   Running the Python script:
2724e94d79fSMatthias Ringwald
2734e94d79fSMatthias Ringwald<!-- -->
2744e94d79fSMatthias Ringwald
2754e94d79fSMatthias Ringwald    ./convert_bts_init_scripts.py main.bts [ble_add_on.bts] output_file.c
2764e94d79fSMatthias Ringwald
2774e94d79fSMatthias Ringwald**BTstack integration**: The common code for all CC256x chipsets is provided by *btstack_chipset_cc256x.c*. During the setup, *btstack_chipset_cc256x_instance* function is used to get a *btstack_chipset_t* instance and passed to *hci_init* function. *btstack_chipset_cc256x_lmp_subversion* provides the LMP Subversion for the selected init script.
2784e94d79fSMatthias Ringwald
2794e94d79fSMatthias RingwaldSCO Data can be routed over HCI, so HFP Wide-Band Speech is supported.
2804e94d79fSMatthias Ringwald
28135e00af0SMatthias Ringwald## Toshiba
28235e00af0SMatthias Ringwald
28359ac44afSMatthias RingwaldThe Toshiba TC35661 Dual-Mode chipset is available in three variants: standalone incl. binary Bluetooth stack, as a module with embedded stack or with a regular HCI interface. The HCI variant has the model number TC35661–007 resp TC35561-009 for the newer silicon.
28435e00af0SMatthias Ringwald
28559ac44afSMatthias RingwaldWe first tried their USB Evaluation Stick that contains an USB-to-UART adapter and the PAN1026 module that contains the TC35661 -501. While it does support the HCI interface and Bluetooth Classic operations worked as expected, LE HCI Commands are not supported. With the -007 and the -009 models, everything works as expected.
28635e00af0SMatthias Ringwald
2877f8d4ab1SMatthias Ringwald**SCO data** does not seem to be supported.
28835e00af0SMatthias Ringwald
28935e00af0SMatthias Ringwald**Baud rate** can be set with custom command.
29035e00af0SMatthias Ringwald
29135e00af0SMatthias Ringwald**BD Addr ** must be set with custom command. It does not have a stored valid public BD Addr.
29235e00af0SMatthias Ringwald
29335e00af0SMatthias Ringwald**Init Script** is not required. A patch file might be uploaded.
29435e00af0SMatthias Ringwald
29529c2a6e3SMatthias Ringwald**BTstack integration**: Support for the TC35661 series is provided by *btstack_chipset_tc3566x.c*. During the setup, *btstack_chipset_tc3566x_instance* function is used to get a *btstack_chipset_t* instance and passed to *hci_init* function. It enables higher UART baud rate and sets the BD Addr during startup.
296