Merge branch 'espressif:master' into master

espressif · Jan 12, 2022 · 67c7edc · 67c7edc
2 parents fa2de53 + ac312aa
commit 67c7edc
Show file tree

Hide file tree

Showing 75 changed files with 7,539 additions and 4,356 deletions.
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
@@ -31,3 +31,23 @@ deploy_master_github:
       - git remote remove github &>/dev/null || true
       - git remote add github git@github.com:espressif/esp-hosted.git
       - git push github "${CI_COMMIT_SHA}:refs/heads/${CI_COMMIT_REF_NAME}"
+
+.deploy_force_master_github:
+  stage: deploy
+  image: $CI_DOCKER_REGISTRY/esp32-ci-env
+  tags:
+    - deploy
+  when: manual
+  only:
+    - master
+  script:
+      - mkdir -p ~/.ssh
+      - chmod 700 ~/.ssh
+      - echo -n $GH_KEY > ~/.ssh/id_rsa_base64
+      - base64 --decode --ignore-garbage ~/.ssh/id_rsa_base64 > ~/.ssh/id_rsa
+      - chmod 600 ~/.ssh/id_rsa
+      - echo -e "Host github.com\n\tStrictHostKeyChecking no\n" >> ~/.ssh/config
+      - git remote remove github &>/dev/null || true
+      - git remote add github git@github.com:espressif/esp-hosted.git
+      - git push -f github "${CI_COMMIT_SHA}:refs/heads/${CI_COMMIT_REF_NAME}"
+
diff --git a/README.md b/README.md
@@ -40,7 +40,8 @@ ESP-Hosted solution provides following WLAN and BT/BLE features to host:
 	- WLAN Station
 	- WLAN Soft AP
 - BT/BLE Features:
-	- v4.2 BR/EDR and BLE
+	- ESP32 supports v4.2 BR/EDR and BLE
+	- ESP32-C3 supports v5.0 BLE
 
 ### 1.2 Supported ESP boards
 
@@ -68,32 +69,60 @@ ESP-Hosted uses SDIO or SPI bus for interfacing ESP boards and host platform. No
 ##### 1.5.1 Linux Host
 Below table explains which feature is supported on which transport interface for Linux based host.
 
-| ESP device | Transport Interface | WLAN support | Virtual serial interface | BT/BLE support |
+| ESP device | Transport Interface | WLAN support | Virtual serial interface | Bluetooth support |
 |:---------:|:-------:|:---------:|:--------:|:--------:|
-| ESP32 | SDIO | Yes | Yes | Yes |
-| ESP32 | SPI | Yes | Yes | Yes |
-| ESP32 | UART | No | No | Yes |
+| ESP32 | SDIO | Yes | Yes | BT/BLE 4.2 |
+| ESP32 | SPI | Yes | Yes | BT/BLE 4.2 |
+| ESP32 | UART | No | No | BT/BLE 4.2 |
 | ESP32-S2 | SDIO | NA | NA | NA |
 | ESP32-S2 | SPI | Yes | Yes | NA |
 | ESP32-S2 | UART | No | No | NA |
 | ESP32-C3 | SDIO | NA | NA | NA |
-| ESP32-C3 | SPI | Yes | Yes | No |
-| ESP32-C3 | UART | No | No | No |
+| ESP32-C3 | SPI | Yes | Yes | BLE 5.0 |
+| ESP32-C3 | UART | No | No | BLE 5.0 |
+
+Note:
+* BT stands for Bluetooth BR/EDR and BLE stands for Bluetooth Low Energy specifications.
+* 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+.
+* We suggest latest stable bluez version to be used. Any other bluetooth stack instead of bluez also could be used.
+* bluez 5.45 on-wards BLE 5.0 HCI commands are supported.
+* BLE 5.0 has backward compability of BLE 4.2.
 
 ##### 1.5.2 MCU Host
 Below table explains which feature is supported on which transport interface for MCU based host.
 
-| ESP device | Transport Interface | WLAN support | Virtual serial interface | BT/BLE support |
+| ESP device | Transport Interface | WLAN support | Virtual serial interface | Bluetooth support |
 |:------------:|:-------:|:---------:|:--------:|:--------:|
 | ESP32 | SDIO | No | No | No |
-| ESP32 | SPI | Yes | Yes | HCI interface can be implemented over virtual serial interface |
-| ESP32 | UART | No | No | No |
+| ESP32 | SPI | Yes | Yes | BT/BLE 4.2\* |
+| ESP32 | UART | No | No | BT/BLE 4.2\*\* |
 | ESP32-S2 | SDIO | NA | NA | NA |
 | ESP32-S2 | SPI | Yes | Yes | NA |
 | ESP32-S2 | UART | No | No | NA |
 | ESP32-C3 | SDIO | NA | NA | NA |
-| ESP32-C3 | SPI | Yes | Yes | No |
-| ESP32-C3 | UART | No | No | No |
+| ESP32-C3 | SPI | Yes | Yes | BLE 5.0\* |
+| ESP32-C3 | UART | No | No | BLE 5.0\*\* |
+
+Note: BT stands for Bluetooth BR/EDR and BLE stands for Bluetooth Low Energy specifications.
+
+\* BT/BLE over SPI
+> BT/BLE support over SPI is not readily available. In order to implement it, one needs to:
+> 
+> Port BT/BLE stack to MCU, \
+> Add a new virtual serial interface using the serial interface API's provided in host driver of ESP-Hosted solution.
+> HCI implementation in Linux Driver `host/linux/host_driver/esp32` could be used as reference. Search keyword: `ESP_HCI_IF`
+> Register this serial interface with BT/BLE stack as a HCI interface.
+
+\*\* BT/BLE over UART
+> BT/BLE support over UART is not readily available. In order to implement this, one needs to:
+>
+> Port BT/BLE stack to MCU, \
+> Register the UART serial interface as a HCI interface with BT/BLE stack
+> With the help of this UART interface, BT/BLE stack can directly interact with BT controller present on ESP32 bypassing host driver and firmware
+> ESP Hosted host driver and a firmware plays no role in this communication
+
+* 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
+[ota_update.md](docs/Linux_based_host/ota_update.md).
 
 ---
 
@@ -172,18 +201,20 @@ This section describes the data communication protocol used at the transport lay
 ##### 3.2.1 Payload Format
 This section explains the payload format used for data transfer on SDIO and SPI interfaces.
 
-* Host and peripheral makes use of 8 byte payload header which preceeds every data packet.
+* Host and peripheral makes use of 12 byte payload header which preceeds every data packet.
 * This payload header provides additional information about the data packet. Based on this header, host/peripheral consumes transmitted data packet.
 * Payload format is as below
 
 | Field | Length | Description |
 |:-------:|:---------:|:--------|
 | Interface type | 4 bits | Possible values: STA(0), SoftAP(1), Serial interface(2), HCI (3), Priv interface(4). Rest all values are reserved |
-| Reserved | 4 bits | Not in use |
-| Reserved | 1 byte | Not in use |
+| Interface number | 4 bits | Unused |
+| Flags | 1 byte | Additional flags like `MORE_FRAGMENT` in fragmentation |
 | Packet length | 2 bytes | Actual length of data packet |
 | Offset to packet | 2 bytes | Offset of actual data packet |
-| Reserved | 1 byte  | Not in use |
+| Checksum | 2 bytes | checksum for complete packet (Includes header and payload) |
+| Reserved2 | 1 byte | Not in use |
+| seq_num | 2 bytes | Sequence number for serial inerface |
 | Packet type | 1 byte | reserved when interface type is 0,1 and 2. Applicable only for interface type 3 and 4 |
 
 ### 3.3 Integration Guide