Skip to content

Commit 6cd21f8

Browse files
mantriyogeshmantriyogesh
committed
Merge branch 'feat/esp_as_mcu_host_docs' into 'feature/esp_as_mcu_host'
feat/esp_as_mcu_host_docs Added documentation See merge request app-frameworks/esp_hosted!477
2 parents bf2919b + 894b373 commit 6cd21f8

17 files changed

+1851
-171
lines changed

‎README.md

Lines changed: 359 additions & 136 deletions
Large diffs are not rendered by default.

‎docs/bluetooth_implementation.md

Lines changed: 283 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,283 @@
1+
# Bluetooth Implementation in ESP-Hosted
2+
3+
**Table of Contents**
4+
5+
- [1. Introduction](#1-introduction)
6+
- [2. Bluetooth Controller](#2-bluetooth-controller)
7+
- [3. Bluetooth Interface](#3-bluetooth-interface)
8+
- [4. NimBLE Host Stack](#4-nimble-host-stack)
9+
- [5. Transporting HCI data using vHCI](#5-transporting-hci-data-using-vhci)
10+
- [5.1. Bluetooth Host vHCI Initialization](#51-bluetooth-host-vhci-initialization)
11+
- [5.2. Bluetooth Host Sending Data through vHCI](#52-bluetooth-host-sending-data-through-vhci)
12+
- [5.3. Bluetooth Host Receiving Data from vHCI](#53-bluetooth-host-receiving-data-from-vhci)
13+
- [6. Transporting HCI data using UART](#6-transporting-hci-data-using-uart)
14+
- [6.1. Bluetooth Host HCI Initialization](#61-bluetooth-host-hci-initialization)
15+
- [6.2. Bluetooth Host Sending Data using HCI](#62-bluetooth-host-sending-data-using-hci)
16+
- [6.3. Bluetooth Host Receiving Data using HCI](#63-bluetooth-host-receiving-data-using-hci)
17+
- [7. References](#7-references)
18+
19+
## 1. Introduction
20+
21+
ESP-Hosted can transport Bluetooth HCI packets between the Bluetooth
22+
Host on the Hosted Master and the Bluetooth Controller on the Hosted
23+
Slave. The Host MCU implement the Bluetooth app and Bluetooth Host
24+
Stack and the Slave runs the Bluetooth controller and hardware.
25+
26+
> [!NOTE]
27+
> Check that the memory requirement for your preferred Bluetooth host
28+
> stack can be satisfied on the Host.
29+
30+
ESP-Hosted has not preferred Bluetooth stack. To showcase ESP-Hosted's
31+
Bluetooth support, `esp-nimble` is used here. Users can use their own
32+
preferred Bluetooth stack with some porting effort.
33+
34+
`esp-nimble` is a fork of Apache NimBLE and available from
35+
ESP-IDF. The NimBLE Bluetooth slack proves Bluetooth Low Energy (BLE)
36+
only functionality.
37+
38+
See [References](#7-references) for links with more information.
39+
40+
## 2. Bluetooth Controller
41+
42+
ESP-Hosted uses the Bluetooth controller running on the slave. The Slave
43+
is expected to be configured to use BT Controller-only mode.
44+
45+
As ESP-Hosted is just communication medium, it doesn't limit to BLE
46+
only. Classic BT stacks are also supported, given the slave has
47+
Classic-BT controller. The Classic-BT or BLE or both availability
48+
depends upon the Bluetooth stack support and ESP chipset chosen. As of
49+
today, ESP32 supports Classic-BT+BLE, whereas, the other ESP slave
50+
chipsets support BLE only.
51+
52+
## 3. Bluetooth Interface
53+
54+
Hosted provides two ways to let the Bluetooth Host stack running on
55+
the Host to communicate with the Bluetooth controller on the Slave.
56+
57+
**vHCI**
58+
59+
- vHCI is standard HCI with extra headers or metadata added
60+
- vHCI embeds the ESP-Hosted header and re-uses the underlying
61+
ESP-Hosted transport, such as SPI/SDIO
62+
- this option is easier to set up. Once the existing SPI or SDIO
63+
transport has been set up, Bluetooth works
64+
65+
Use this option if you want:
66+
67+
- complete control of Bluetooth messages
68+
- extra flexibility of debugging
69+
- no extra GPIOs (required for Standard HCI)
70+
71+
**Standard HCI**
72+
73+
- standard HCI is a transparent way of handling HCI messages
74+
- HCI messages originating from the Bluetooth stack on the Host are
75+
sent through an interface (like UART) to the Bluetooth controller on
76+
the Slave
77+
- requires extra GPIO for the HCI interface, independent of the GPIOs
78+
used for the ESP-Hosted interface
79+
80+
Use this option if you want:
81+
82+
- transparency: no extra data added to the HCI messages
83+
- portability: because it is standard HCI, you can replace the Slave
84+
with any other co-processor (ESP or otherwise) that has a Bluetooth
85+
controller
86+
87+
> [!NOTE]
88+
> If Hosted is configured as the Bluetooth transport (vHCI), then your
89+
> Bluetooth over HCI configuration must be disabled, and vice
90+
> versa.
91+
92+
## 4. NimBLE Host Stack
93+
94+
The ESP-Hosted Master implements the set of API calls required by the
95+
NimBLE Bluetooth stack to initialize, send and receive Bluetooth data:
96+
97+
- `hci_drv_init`
98+
- `ble_transport_ll_init`
99+
- `ble_transport_to_ll_acl_impl`
100+
- `ble_transport_to_ll_cmd_impl`
101+
- `ble_transport_to_hs_evt`
102+
- `ble_transport_to_hs_acl`
103+
104+
The following sequence diagrams show how to send and receive Bluetooth
105+
on both the Hosted Master and Slave.
106+
107+
## 5. Transporting HCI data using vHCI
108+
109+
### 5.1. Bluetooth Host vHCI Initialization
110+
111+
```mermaid
112+
sequenceDiagram
113+
box Grey Hosted Master
114+
participant ble as NimBLE Host Bluetooth Stack
115+
participant vhci as VHCI Driver
116+
participant master as SPI/SDIO Interface
117+
end
118+
119+
box Grey Hosted Slave
120+
participant sinterface as SPI/SDIO Interface
121+
participant slave as Bluetooth Controller
122+
end
123+
124+
ble ->> +vhci : hci_drv_init()
125+
Note over vhci: do any init required
126+
vhci -->> -ble :
127+
128+
ble ->> +vhci : ble_transport_ll_init()
129+
Note over vhci : do any transport init required
130+
vhci -->> -ble :
131+
```
132+
133+
**Bluetooth Host Initialization**
134+
135+
### 5.2. Bluetooth Host Sending Data through vHCI
136+
137+
```mermaid
138+
sequenceDiagram
139+
box Grey Hosted Master
140+
participant ble as NimBLE Host Bluetooth Stack
141+
participant vhci as VHCI Driver
142+
participant master as SPI/SDIO Interface
143+
end
144+
145+
box Grey Hosted Slave
146+
participant sinterface as SPI/SDIO Interface
147+
participant slave as Bluetooth Controller
148+
end
149+
150+
ble ->> +vhci : ble_transport_to_ll_acl_impl()
151+
Note over vhci : convert ACL data to HCI
152+
vhci ->> +master : esp_hosted_tx()
153+
Note over master : add Hosted header
154+
master ->> +sinterface: SPI/SDIO
155+
Note over master,sinterface : (VHCI data)
156+
master -->> -vhci :
157+
vhci -->> -ble :
158+
159+
Note over sinterface : remove Hosted header
160+
sinterface ->> -slave : HCI data
161+
```
162+
163+
**Bluetooth Host Sending Data**
164+
165+
### 5.3. Bluetooth Host Receiving Data from vHCI
166+
167+
```mermaid
168+
sequenceDiagram
169+
box Grey Hosted Master
170+
participant ble as NimBLE Host Bluetooth Stack
171+
participant vhci as VHCI Driver
172+
participant master as SPI/SDIO Interface
173+
end
174+
175+
box Grey Hosted Slave
176+
participant sinterface as SPI/SDIO Interface
177+
participant slave as Bluetooth Controller
178+
end
179+
180+
slave ->> +sinterface : HCI data
181+
Note over sinterface : Add Hosted header
182+
sinterface ->> -master : SPI/SDIO
183+
Note over sinterface,master : (VHCI data)
184+
Note over master : Remove Hosted header
185+
186+
master ->> +vhci : hci_rx_handler()
187+
188+
alt Receive Event Data
189+
Note over vhci: convert HCI data to Event
190+
vhci ->> ble : ble_transport_to_hs_evt()
191+
ble -->> vhci :
192+
else Receive ACL Data
193+
Note over vhci: convert HCI data to ACL
194+
vhci ->> ble : ble_transport_to_hs_acl()
195+
ble -->> vhci :
196+
end
197+
198+
vhci -->> -master :
199+
```
200+
201+
**Bluetooth Host Receiving Data**
202+
203+
## 6. Transporting HCI data using UART
204+
205+
### 6.1. Bluetooth Host HCI Initialization
206+
207+
```mermaid
208+
sequenceDiagram
209+
box Grey Master
210+
participant ble as NimBLE Host Bluetooth Stack
211+
participant huart as UART Driver
212+
end
213+
214+
box Grey Slave
215+
participant slave as Bluetooth Controller with UART Interface
216+
end
217+
218+
ble ->> huart : hci_drv_init()
219+
Note over huart : do any init required
220+
huart -->> ble :
221+
222+
ble ->> huart : ble_transport_ll_init()
223+
Note over huart : do any transport init required
224+
huart --> ble :
225+
```
226+
227+
**Bluetooth Host Initialization**
228+
229+
### 6.2. Bluetooth Host Sending Data using HCI
230+
231+
```mermaid
232+
sequenceDiagram
233+
box Grey Master
234+
participant ble as NimBLE Host Bluetooth Stack
235+
participant huart as UART Driver
236+
end
237+
238+
box Grey Slave
239+
participant slave as Bluetooth Controller with UART Interface
240+
end
241+
242+
ble ->> huart : ble_transport_to_ll_acl_impl()
243+
Note over huart : convert ACL data to HCI
244+
huart ->> slave : UART TX
245+
Note over huart,slave : (standard HCI)
246+
huart -->> ble :
247+
```
248+
249+
**Bluetooth Host Sending Data**
250+
251+
### 6.3. Bluetooth Host Receiving Data using HCI
252+
253+
```mermaid
254+
sequenceDiagram
255+
box Grey Master
256+
participant ble as NimBLE Host Bluetooth Stack
257+
participant huart as UART Driver
258+
end
259+
260+
box Grey Slave
261+
participant slave as Bluetooth Controller with UART Interface
262+
end
263+
264+
slave ->> huart : UART RX
265+
Note over slave,huart: (standard HCI)
266+
267+
alt Receive Event Data
268+
Note over huart : convert HCI data to Event
269+
huart ->> ble : ble_transport_to_hs_evt()
270+
ble -->> huart :
271+
else Receive ACL Data
272+
Note over huart : convert HCI data to ACL
273+
huart ->> ble : ble_transport_to_hs_acl()
274+
ble -->> huart :
275+
end
276+
```
277+
278+
**Bluetooth Host Receiving Data**
279+
280+
## 7. References
281+
282+
- esp-nimble: https://github.com/espressif/esp-nimble
283+
- ESP-IDF NimBLE-based Host APIs: https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-reference/bluetooth/nimble/index.html

0 commit comments

Comments
 (0)