README.md

   1 # ESP-Hosted
   2
   3 # Index
   4 * [**1. Introduction**](#1-introduction)
   5         * [Connectivity Feature](#11-connectivity-features)
   6         * [Supported ESP boards](#12-supported-esp-boards)
   7         * [Supported Hosts](#13-supported-hosts)
   8         * [Supported Transports](#14-supported-transports)
   9         * [Feature Matrix](#15-feature-matrix)
  10 * [**2. Get Started**](#2-get-started)
  11         * [Getting Started With Linux Host](#21-getting-started-with-linux-host)
  12         * [Getting Started With MCU host](#22-getting-started-with-mcu-host)
  13 * [**3. Design**](#3-design)
  14         * [System Architecture](#31-system-architecture)
  15         * [Transport layer communication protocol](#32-transport-layer-communication-protocol)
  16         * [Integration Guide](#33-integration-guide)
  17 * [**4. Performance And Validation**](#4-performance-and-validation)
  18
  19 ---
  20
  21
  22 # 1. Introduction
  23
  24 ESP-Hosted solution provides a way to use ESP board as a communication processor for Wi-Fi and Bluetooth/BLE connectivity. It basically adds a network interface and a HCI interface to host, allowing it to communicate with other devices.
  25
  26 Following features are provided as a part of this solution:
  27 * A standard 802.3 network interface is provided to host for transmitting and receiving 802.3 frames
  28 * A standard HCI interface is provided to host over which Bluetooth/BLE is supported
  29 * A control interface to configure and control Wi-Fi on ESP board
  30
  31 For end to end working of this solution, host needs to be equipped with corresponding TCP/IP, TLS and Bluetooth/BLE stack.
  32
  33 Please note that this project doesn't provide a standard 802.11 interface to the host. For the control path between the host and ESP board, ESP-Hosted uses a custom implementation based on [Protobuf](https://developers.google.com/protocol-buffers).
  34
  35 ### 1.1 Connectivity Features
  36
  37 ESP-Hosted solution provides following WLAN and BT/BLE features to host:
  38 - WLAN Features:
  39         - 802.11b/g/n
  40         - WLAN Station
  41         - WLAN Soft AP
  42 - BT/BLE Features:
  43         - ESP32 supports v4.2 BR/EDR and BLE
  44         - ESP32-C3 supports v5.0 BLE
  45
  46 ### 1.2 Supported ESP boards
  47
  48 ESP-Hosted solution is supported on following ESP boards:
  49 - ESP32
  50 - ESP32S2
  51 - ESP32C3
  52
  53 ### 1.3 Supported Hosts
  54
  55 * ESP-Hosted solution supports following Linux based and MCU based hosts out of the box.
  56         * Linux Based Hosts
  57                 * Raspberry-Pi 3 Model B
  58                 * Raspberry-Pi 3 Model B+
  59                 * Raspberry-Pi 4 Model B
  60         * MCU Based Hosts
  61                 * STM32 Discovery Board (STM32F469I-DISCO)
  62 * It is relatively easy to port this solution to other Linux and MCU platforms.
  63
  64 ### 1.4 Supported Transports
  65
  66 ESP-Hosted uses SDIO or SPI bus for interfacing ESP boards and host platform. Not all host platforms support both these interfaces. Further section depicts supported host platforms and corresponding transport interface, ESP boards and feature set.
  67
  68 ### 1.5 Feature Matrix
  69 ##### 1.5.1 Linux Host
  70 Below table explains which feature is supported on which transport interface for Linux based host.
  71
  72 | ESP device | Transport Interface | WLAN support | Virtual serial interface | Bluetooth support |
  73 |:---------:|:-------:|:---------:|:--------:|:--------:|
  74 | ESP32 | SDIO | Yes | Yes | BT/BLE 4.2 |
  75 | ESP32 | SPI | Yes | Yes | BT/BLE 4.2 |
  76 | ESP32 | UART | No | No | BT/BLE 4.2 |
  77 | ESP32-S2 | SDIO | NA | NA | NA |
  78 | ESP32-S2 | SPI | Yes | Yes | NA |
  79 | ESP32-S2 | UART | No | No | NA |
  80 | ESP32-C3 | SDIO | NA | NA | NA |
  81 | ESP32-C3 | SPI | Yes | Yes | BLE 5.0 |
  82 | ESP32-C3 | UART | No | No | BLE 5.0 |
  83
  84 Note:
  85 * BT stands for Bluetooth BR/EDR and BLE stands for Bluetooth Low Energy specifications.
  86 * ESP-Hosted related BR/EDR 4.2 and BLE 4.2 functionalities are tested with bluez 5.43+. Whereas BLE 5.0 functionalities are tested with bluez 5.45+.
  87 * We suggest latest stable bluez version to be used. Any other bluetooth stack instead of bluez also could be used.
  88 * bluez 5.45 on-wards BLE 5.0 HCI commands are supported.
  89 * BLE 5.0 has backward compability of BLE 4.2.
  90
  91 ##### 1.5.2 MCU Host
  92 Below table explains which feature is supported on which transport interface for MCU based host.
  93
  94 | ESP device | Transport Interface | WLAN support | Virtual serial interface | Bluetooth support |
  95 |:------------:|:-------:|:---------:|:--------:|:--------:|
  96 | ESP32 | SDIO | No | No | No |
  97 | ESP32 | SPI | Yes | Yes | BT/BLE 4.2\* |
  98 | ESP32 | UART | No | No | BT/BLE 4.2\*\* |
  99 | ESP32-S2 | SDIO | NA | NA | NA |
 100 | ESP32-S2 | SPI | Yes | Yes | NA |
 101 | ESP32-S2 | UART | No | No | NA |
 102 | ESP32-C3 | SDIO | NA | NA | NA |
 103 | ESP32-C3 | SPI | Yes | Yes | BLE 5.0\* |
 104 | ESP32-C3 | UART | No | No | BLE 5.0\*\* |
 105
 106 Note: BT stands for Bluetooth BR/EDR and BLE stands for Bluetooth Low Energy specifications.
 107
 108 \* BT/BLE over SPI
 109 > BT/BLE support over SPI is not readily available. In order to implement it, one needs to:
 110 >
 111 > Port BT/BLE stack to MCU, \
 112 > Add a new virtual serial interface using the serial interface API's provided in host driver of ESP-Hosted solution.
 113 > HCI implementation in Linux Driver `host/linux/host_driver/esp32` could be used as reference. Search keyword: `ESP_HCI_IF`
 114 > Register this serial interface with BT/BLE stack as a HCI interface.
 115
 116 \*\* BT/BLE over UART
 117 > BT/BLE support over UART is not readily available. In order to implement this, one needs to:
 118 >
 119 > Port BT/BLE stack to MCU, \
 120 > Register the UART serial interface as a HCI interface with BT/BLE stack
 121 > With the help of this UART interface, BT/BLE stack can directly interact with BT controller present on ESP32 bypassing host driver and firmware
 122 > ESP Hosted host driver and a firmware plays no role in this communication
 123
 124 * Linux hosts support OTA update (Over The Air ESP32 firmware update) in C and python. MCU hosts can refer the same for their development. For detailed documentation please read
 125 [ota_update.md](docs/Linux_based_host/ota_update.md).
 126
 127 ---
 128
 129 # 2. Get Started
 130 This section describes how to setup and use ESP-Hosted solution. Since ESP-Hosted solution supports two distinct platforms, procedure to use it vastly differs.
 131
 132 ### 2.1 Getting Started With Linux Host
 133 Please refer [Getting Started](docs/Linux_based_host/Linux_based_readme.md) guide for Linux host.
 134
 135 ### 2.2 Getting Started With MCU Host
 136 Please refer [Getting Started](docs/MCU_based_host/MCU_based_readme.md) guide for MCU host.
 137
 138 ---
 139
 140 # 3. Design
 141 This section describes the overall design of ESP-Hosted solution. There are 3 aspects to it:
 142 * System Architecture
 143 * Transport layer communication protocol
 144 * Integration Guide
 145
 146 ### 3.1 System Architecture
 147
 148 This section discusses building blocks of the ESP-Hosted solution for the supported host platforms.
 149
 150 These building blocks can be broadly classified as:
 151 * ESP Host Software
 152 This includes ESP Host driver and control interface implementation.
 153
 154 * ESP Firmware
 155 This includes ESP peripheral driver and implementation of control commands.
 156
 157 * Third party components
 158 This includes components that are essential for end to end working of entire system but are not maintained or implemented as a part of this project.
 159
 160
 161 ##### 3.1.1 ESP Host Software
 162
 163 The components of ESP host software are dependent on host platform that is being used. Please refer following documents:
 164
 165 1. [System Architecture: Linux based host](docs/Linux_based_host/Linux_based_architecture.md)
 166 2. [System Architecture: MCU based host](docs/MCU_based_host/MCU_based_architecture.md)
 167
 168
 169 ##### 3.1.2 ESP Firmware
 170 This implements ESP-Hosted solution part that runs on ESP boards. ESP firmware is agnostic of the host platform. It consists of following.
 171
 172 * ESP Application
 173 This implements:
 174         * SDIO transport layer
 175         * SPI transport layer
 176         * Virtual serial interface driver
 177         * Control interface command implementation
 178         * Bridges data path between Wi-Fi, HCI controller driver of ESP and Host platform
 179 * ESP-IDF Components
 180 ESP firmware mainly uses following components from ESP-IDF. Please check [ESP-IDF documentation](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/index.html) for more details.
 181         * SDIO Slave driver
 182         * SPI Slave driver
 183         * Wi-Fi driver
 184         * HCI controller driver
 185         * Protocomm Layer
 186
 187
 188 ##### 3.1.3 Third Party Components
 189 Third components such as following are essential for end to end working of ESP-Hosted Solution. Implementation or porting of these third party compoenent is not in scope of this project.
 190 * TCP/IP and TLS stack
 191 * BT/BLE stack
 192 * UART driver
 193 * Protobuf
 194
 195
 196 ### 3.2 Transport layer communication protocol
 197 This section describes the data communication protocol used at the transport layer. This protocol is agnostic of host platforms that is being used. Please refer following links to get more information on communication protocol per transport interface type.
 198 * [SDIO Communication Protocol](docs/sdio_protocol.md)
 199 * [SPI Communication Protocol](docs/spi_protocol.md)
 200
 201 ##### 3.2.1 Payload Format
 202 This section explains the payload format used for data transfer on SDIO and SPI interfaces.
 203
 204 * Host and peripheral makes use of 12 byte payload header which preceeds every data packet.
 205 * This payload header provides additional information about the data packet. Based on this header, host/peripheral consumes transmitted data packet.
 206 * Payload format is as below
 207
 208 | Field | Length | Description |
 209 |:-------:|:---------:|:--------|
 210 | Interface type | 4 bits | Possible values: STA(0), SoftAP(1), Serial interface(2), HCI (3), Priv interface(4). Rest all values are reserved |
 211 | Interface number | 4 bits | Unused |
 212 | Flags | 1 byte | Additional flags like `MORE_FRAGMENT` in fragmentation |
 213 | Packet length | 2 bytes | Actual length of data packet |
 214 | Offset to packet | 2 bytes | Offset of actual data packet |
 215 | Checksum | 2 bytes | checksum for complete packet (Includes header and payload) |
 216 | Reserved2 | 1 byte | Not in use |
 217 | seq_num | 2 bytes | Sequence number for serial inerface |
 218 | Packet type | 1 byte | reserved when interface type is 0,1 and 2. Applicable only for interface type 3 and 4 |
 219
 220 ### 3.3 Integration Guide
 221
 222 ##### 3.3.1 Control Path
 223 When [section 2. Get Started](#2-get-started) above is followed, ESP-Hosted transport would be setup. Getting control path working is the first step to verify if the transport is setup correctly. When any sample control request is complete, i.e. control response is received, we can focus on getting Wi-Fi and Bluetooth working as you follow subsequent documentation there. Design details of control path could be found [here](docs/common/contrl_path.md)
 224
 225 ##### 3.3.2 Control Interface APIs
 226 This section describes control interface API's provided by ESP-Hosted Solution For higher layer applications. These are common for **MPU** and **MCU** based solution. One can easily integrate ESP-Hosted solution with other projects using these API's. There are two flavors of these API's:
 227
 228 * [Python API's](docs/python_api.md)
 229 * [C API's](docs/c_api.md)
 230
 231 ##### 3.3.3 API's for MCU Based ESP-Hosted Solution
 232 Below document explains the API's provided for MCU based ESP-Hosted solution
 233 * [API's for MCU based host](docs/MCU_based_host/mcu_api.md)
 234
 235 # 4. Performance And Validation
 236 ### 4.1 Wi-Fi Performance in shielded environment
 237 Following performance numbers are taken on Linux based ESP-Hosted solution.
 238 These numbers are tested with older release, [Release 0.3](releases/tag/release%2Fv0.3)
 239
 240 ![alt text](esp_hosted_performance.png "ESP Hosted performance matrix")