Merge branch 'docfix/fg_references' into 'master'

Minor fixes in documentation See merge request app-frameworks/esp_hosted!263
espressif · Oct 21, 2022 · 3769eea · 3769eea
2 parents e0bb23b + 8a77b73
commit 3769eea
Show file tree

Hide file tree

Showing 10 changed files with 66 additions and 246 deletions.
diff --git a/esp_hosted_fg/docs/Linux_based_host/Getting_started.md b/esp_hosted_fg/docs/Linux_based_host/Getting_started.md
@@ -33,9 +33,9 @@ Wi-Fi can be configured as either as `STATION` mode or `SOFTAP` mode or `STATION
 - C based solution also could be used from [C based demo app](../common/c_demo.md). For simplicity, 
 
 
-Python App is placed in [host/linux/host_control/python_support/](../../host/linux/host_control/python_support/) directory. Use below command to navigate to this directory.
+Python App is placed in [esp_hosted_fg/host/linux/host_control/python_support/](../../host/linux/host_control/python_support/) directory. Use below command to navigate to this directory.
 ```sh
-$ cd host/linux/host_control/python_support/
+$ cd esp_hosted_fg/host/linux/host_control/python_support/
 ```
 
 #### 2.1.1 Wi-Fi Station Mode Operations

diff --git a/esp_hosted_fg/docs/Linux_based_host/Linux_based_readme.md b/esp_hosted_fg/docs/Linux_based_host/Linux_based_readme.md
@@ -50,14 +50,17 @@ Make sure that Raspberry-Pi is equipped with following:
 		```sh
 		$ sudo apt install python3
 		```
-* Clone ESP-Hosted code repository
+* Using released codebase
+	* Download pre-built ESP-Hosted firmware release binaries from [releases](https://github.com/espressif/esp-hosted/releases)
+	* :warning: Make sure that you use `Source code (zip)` in `Assets` fold with associated release for host building.
+* Using latest master
+	* Clone ESP-Hosted code repository
 	```
 	$ git clone --recurse-submodules <url_of_esp_hosted_repository>
 	$ cd esp-hosted
 	$ git submodule update --init --recursive
 	```
-* Download pre-built ESP-Hosted firmware release binaries from [releases](https://github.com/espressif/esp-hosted/releases)
-
+	* Please use the exact same git commit for ESP flashing using source code.
 
 ### 1.3 Setup
 
@@ -70,7 +73,7 @@ Prepare connections based on interface requirements and setup host as below.
 		* Prepare Raspberry-Pi as per section [1.2 Raspberry-Pi Software Setup](SDIO_setup.md#12-raspberry-pi-software-setup) of [SDIO setup document](SDIO_setup.md)
 		* Compile and load host driver as below:
 			```sh
-			$ cd host/linux/host_control/
+			$ cd esp_hosted_fg/host/linux/host_control/
 			$ ./rpi_init.sh sdio
 			```
 * **Wi-Fi and Bluetooth over SPI**
@@ -80,7 +83,7 @@ Prepare connections based on interface requirements and setup host as below.
 		* Prepare Raspberry-Pi as per [1.2 Raspberry-Pi Software Setup](SPI_setup.md#12-raspberry-pi-software-setup) of [SPI Setup document](SPI_setup.md)
 		* Compile and load host driver as below:
 			```sh
-			$ cd host/linux/host_control/
+			$ cd esp_hosted_fg/host/linux/host_control/
 			$ ./rpi_init.sh spi
 			```
 * **Wi-Fi over SDIO and Bluetooth over UART**
@@ -92,7 +95,7 @@ Prepare connections based on interface requirements and setup host as below.
 		* Prepare Raspberry-Pi for UART operations as per section [1.2 Raspberry-Pi Software Setup](UART_setup.md#12-raspberry-pi-software-setup) of [UART setup document](UART_setup.md)
 		* Compile and load host driver as below:
 			```sh
-			$ cd host/linux/host_control/
+			$ cd esp_hosted_fg/host/linux/host_control/
 			$ ./rpi_init.sh sdio btuart
 			```
 		* After loading ESP firmware, execute below command to create `hci0` interface
@@ -108,7 +111,7 @@ Prepare connections based on interface requirements and setup host as below.
 		* Prepare Raspberry-Pi for UART operations as per section [1.2 Raspberry-Pi Software Setup](UART_setup.md#12-raspberry-pi-software-setup) of [UART setup document](UART_setup.md)
 		* Compile and load host driver as below:
 			```sh
-			$ cd host/linux/host_control/
+			$ cd esp_hosted_fg/host/linux/host_control/
 			$ ./rpi_init.sh spi btuart
 			```
 		* After loading ESP firmware, execute below command to create `hci0` interface
@@ -117,21 +120,9 @@ Prepare connections based on interface requirements and setup host as below.
 			```
 
 #### 1.3.1 ESP Firmware Setup
-* Flash pre-built binaries as below.
-
-```sh
-$ esptool.py -p <serial_port> -b 960000 --before default_reset --after hard_reset \
-write_flash --flash_mode dio --flash_freq 40m --flash_size detect \
-0x8000 esp_hosted_partition-table_<esp_peripheral>_<interface_type>_v<release_version>.bin \
-0x1000 esp_hosted_bootloader_<esp_peripheral>_<interface_type>_v<release_version>.bin \
-0x10000 esp_hosted_firmware_<esp_peripheral>_<interface_type>_v<release_version>.bin
-
-Where,
-	<serial_port>    : serial port of ESP peripheral
-	<esp_peripheral> : esp32/esp32s2/esp32c2/esp32c3/esp32s3
-	<interface_type> : sdio/spi/sdio_uart
-	<release_version>: 0.1,0.2 etc
-```
+* Download pre-built firmware binaries from [releases](https://github.com/espressif/esp-hosted/releases)
+* Follow `readme.txt` from release tarball to flash the ESP binary
+* :warning: Make sure that you use `Source code (zip)` in `Assets` fold with associated release for host building.
 
 #### 1.3.2 Setup Validation
 Once everything is setup and host software and ESP firmware are loaded
@@ -204,6 +195,7 @@ This section identifies Raspberry-Pi specific setup requirements.
 :warning:`Note: ESP-IDF is needed to compile ESP-Hosted firmware source. Skip this step if you are planning to use pre-built release binaries.`  
 
 - Clone the ESP-IDF [release/v5.0](https://github.com/espressif/esp-idf/tree/release/v5.0) and git checkout to `release/v5.0` branch.
+- [Set-up the ESP-IDF](https://docs.espressif.com/projects/esp-idf/en/release-v5.0/esp32/get-started/index.html)
 - The control path between MCU host and ESP peripheral is based on `protobuf`. For that, corresponding stack layer, `protocomm` from ESP-IDF is used. It will be already present in ESP-IDF, no extra setup required for that.
 
 ### 2.3 ESP-Hosted Code Repository
@@ -213,6 +205,7 @@ $ git clone --recurse-submodules <url_of_esp_hosted_repository>
 $ cd esp-hosted
 $ git submodule update --init --recursive
 ```
+Please make sure that ESP and host checkeout to **same git commit**.
 
 ### 2.4 ESP-Hosted Setup and Load Project
 

diff --git a/esp_hosted_fg/docs/Linux_based_host/SDIO_setup.md b/esp_hosted_fg/docs/Linux_based_host/SDIO_setup.md
@@ -32,7 +32,7 @@ Please reboot Raspberry-Pi after changing this file.
 ### 2.1 Host Software
 * Execute following commands in root directory of cloned ESP-Hosted repository on Raspberry-Pi
 ```sh
-$ cd host/linux/host_control/
+$ cd esp_hosted_fg/host/linux/host_control/
 $ ./rpi_init.sh sdio
 ```
 * This script compiles and loads host driver on Raspberry-Pi. It also creates virtual serial interface `/dev/esps0` which is used as a control interface for Wi-Fi on ESP peripheral
@@ -42,31 +42,19 @@ One can load pre-built release binaries on ESP peripheral or compile those from
 
 #### 2.2.1 Load Pre-built Release Binaries
 * Download pre-built firmware binaries from [releases](https://github.com/espressif/esp-hosted/releases)
-* Linux users can run below command to flash these binaries. Edit <serial_port> with ESP peripheral's serial port.
-```sh
-$ python esptool.py --chip esp32 --port <serial_port> --baud <flash_baud_rate> --before default_reset \
---after hard_reset write_flash --flash_mode dio --flash_size detect --flash_freq 40m \
-0x1000 esp_hosted_bootloader_esp32_sdio_v<release_version>.bin \
-0x8000 esp_hosted_partition-table_esp32_sdio_v<release_version>.bin \
-0xd000 esp_hosted_ota_data_initial_esp32_sdio_v<release_version>.bin \
-0x10000 esp_hosted_firmware_esp32_sdio_v<release_version>.bin
-
-Where,
-	<serial_port>      : serial port of ESP peripheral
-	<flash_baud_rate>  : flash baud rate of ESP peripheral, ex.115200, 921600, 2Mbps
-	<release_version>  : 0.1,0.2 etc. Latest from [release page](https://github.com/espressif/esp-hosted/releases)
-```
-* This command will flash `SDIO` interface binaries on `esp32` chip.
-
+* Follow `readme.txt` from release tarball to flash the ESP binary
+* :warning: Make sure that you use `Source code (zip)` in `Assets` fold with associated release for host building.
 * Windows user can use ESP Flash Programming Tool to flash the pre-built binary.
 
 
 #### 2.2.2 Source Compilation
-:warning:<code>Note:Please check [ESP-IDF Setup](Linux_based_readme.md#22-esp-idf-setup) and use appropriate ESP-IDF version</code>
-* In root directory of ESP-Hosted repository, execute below command
+- Note: Please use the same git commit both at ESP and Host
+- Clone the ESP-IDF [release/v5.0](https://github.com/espressif/esp-idf/tree/release/v5.0) and git checkout to `release/v5.0` branch.
+- [Set-up the ESP-IDF](https://docs.espressif.com/projects/esp-idf/en/release-v5.0/esp32/get-started/index.html)
+- In root directory of ESP-Hosted repository, execute below command
 
 ```sh
-$ cd esp/esp_driver/network_adapter
+$ cd esp_hosted_fg/esp/esp_driver/network_adapter
 ```
 
 ##### Using cmake

diff --git a/esp_hosted_fg/docs/Linux_based_host/SPI_setup.md b/esp_hosted_fg/docs/Linux_based_host/SPI_setup.md
@@ -105,7 +105,7 @@ Please reboot Raspberry-Pi after changing this file.
 ### 2.1 Host Software
 * Execute following commands in root directory of cloned ESP-Hosted repository on Raspberry-Pi
 ```sh
-$ cd host/linux/host_control/
+$ cd esp_hosted_fg/host/linux/host_control/
 $ ./rpi_init.sh spi
 ```
 * This script compiles and loads host driver on Raspberry-Pi. It also creates virtual serial interface `/dev/esps0` which is used as a control interface for Wi-Fi on ESP peripheral
@@ -115,100 +115,18 @@ One can load pre-built release binaries on ESP peripheral or compile those from
 
 #### 2.2.1 Load Pre-built Release Binaries
 * Download pre-built firmware binaries from [releases](https://github.com/espressif/esp-hosted/releases)
-* Linux users can run below command to flash these binaries.
-##### ESP32
-```sh
-$ python esptool.py --chip esp32 --port <serial_port> --baud <flash_baud_rate> --before default_reset \
---after hard_reset write_flash --flash_mode dio --flash_size detect --flash_freq 40m \
-0x1000 esp_hosted_bootloader_esp32_spi_v<release_version>.bin \
-0x8000 esp_hosted_partition-table_esp32_spi_v<release_version>.bin \
-0xd000 esp_hosted_ota_data_initial_esp32_spi_v<release_version>.bin \
-0x10000 esp_hosted_firmware_esp32_spi_v<release_version>.bin
-
-Where,
-	<serial_port>     : serial port of ESP peripheral
-	<flash_baud_rate> : flash baud rate of ESP peripheral, ex.115200, 921600, 2Mbps
-	<release_version> : 0.1,0.2 etc. Latest from [release page](https://github.com/espressif/esp-hosted/releases)
-```
-* This command will flash `SPI` interface binaries on `esp32` chip.
-
-##### ESP32-S2
-```sh
-$ python esptool.py --chip esp32s2 --port <serial_port> --baud <flash_baud_rate> --before default_reset \
---after hard_reset write_flash --flash_mode dio --flash_size detect --flash_freq 80m \
-0x1000 esp_hosted_bootloader_esp32s2_spi_v<release_version>.bin \
-0x8000 esp_hosted_partition-table_esp32s2_spi_v<release_version>.bin \
-0xd000 esp_hosted_ota_data_initial_esp32s2_spi_v<release_version>.bin \
-0x10000 esp_hosted_firmware_esp32s2_spi_v<release_version>.bin
-
-Where,
-	<serial_port>     : serial port of ESP peripheral
-	<flash_baud_rate> : flash baud rate of ESP peripheral, ex.115200, 921600, 2Mbps
-	<release_version> : 0.1,0.2 etc. Latest from [release page](https://github.com/espressif/esp-hosted/releases)
-```
-* This command will flash `SPI` interface binaries on `esp32s2` chip.
-
-##### ESP32-C2
-```sh
-$ python esptool.py --chip esp32c2 --port <serial_port> --baud <flash_baud_rate> --before default_reset \
---after hard_reset write_flash --flash_mode dio --flash_size detect --flash_freq 80m \
-0x0 esp_hosted_bootloader_esp32c2_spi_v<release_version>.bin \
-0x8000 esp_hosted_partition-table_esp32c2_spi_v<release_version>.bin \
-0xd000 esp_hosted_ota_data_initial_esp32c2_spi_v<release_version>.bin \
-0x10000 esp_hosted_firmware_esp32c2_spi_v<release_version>.bin
-
-Where,
-	<serial_port>     : serial port of ESP peripheral
-	<flash_baud_rate> : flash baud rate of ESP peripheral, ex.115200, 921600, 2Mbps
-	<release_version> : 0.1,0.2 etc. Latest from [release page](https://github.com/espressif/esp-hosted/releases)
-```
-* This command will flash `SPI` interface binaries on `esp32c2` chip.
-
-* Windows user can use ESP Flash Programming Tool to flash the pre-built binary.
-
-##### ESP32-C3
-```sh
-$ python esptool.py --chip esp32c3 --port <serial_port> --baud <flash_baud_rate> --before default_reset \
---after hard_reset write_flash --flash_mode dio --flash_size detect --flash_freq 80m \
-0x0 esp_hosted_bootloader_esp32c3_spi_v<release_version>.bin \
-0x8000 esp_hosted_partition-table_esp32c3_spi_v<release_version>.bin \
-0xd000 esp_hosted_ota_data_initial_esp32c3_spi_v<release_version>.bin \
-0x10000 esp_hosted_firmware_esp32c3_spi_v<release_version>.bin
-
-Where,
-	<serial_port>     : serial port of ESP peripheral
-	<flash_baud_rate> : flash baud rate of ESP peripheral, ex.115200, 921600, 2Mbps
-	<release_version> : 0.1,0.2 etc. Latest from [release page](https://github.com/espressif/esp-hosted/releases)
-```
-* This command will flash `SPI` interface binaries on `esp32c3` chip.
-
-* Windows user can use ESP Flash Programming Tool to flash the pre-built binary.
-
-##### ESP32-S3
-```sh
-$ python esptool.py --chip esp32s3 --port <serial_port> --baud <flash_baud_rate> --before default_reset \
---after hard_reset write_flash --flash_mode dio --flash_size detect --flash_freq 80m \
-0x0 esp_hosted_bootloader_esp32s3_spi_v<release_version>.bin \
-0x8000 esp_hosted_partition-table_esp32s3_spi_v<release_version>.bin \
-0xd000 esp_hosted_ota_data_initial_esp32s3_spi_v<release_version>.bin \
-0x10000 esp_hosted_firmware_esp32s3_spi_v<release_version>.bin
-
-Where,
-	<serial_port>     : serial port of ESP peripheral
-	<flash_baud_rate> : flash baud rate of ESP peripheral, ex.115200, 921600, 2Mbps
-	<release_version> : 0.1,0.2 etc. Latest from [release page](https://github.com/espressif/esp-hosted/releases)
-```
-* This command will flash `SPI` interface binaries on `esp32s3` chip.
-
+* Follow `readme.txt` from release tarball to flash the ESP binary
+* :warning: Make sure that you use `Source code (zip)` in `Assets` fold with associated release for host building.
 * Windows user can use ESP Flash Programming Tool to flash the pre-built binary.
 
 #### 2.2.2 Source Compilation
-:warning:<code>Note: Please check [ESP-IDF Setup](Linux_based_readme.md#22-esp-idf-setup) and use appropriate ESP-IDF version</code>
-
-* In root directory of ESP-Hosted repository, execute below command
+- Note: Please use the same git commit both at ESP and Host
+- Clone the ESP-IDF [release/v5.0](https://github.com/espressif/esp-idf/tree/release/v5.0) and git checkout to `release/v5.0` branch.
+- [Set-up the ESP-IDF](https://docs.espressif.com/projects/esp-idf/en/release-v5.0/esp32/get-started/index.html)
+- In root directory of ESP-Hosted repository, execute below command
 
 ```sh
-$ cd esp/esp_driver/network_adapter
+$ cd esp_hosted_fg/esp/esp_driver/network_adapter
 ```
 
 ##### Using cmake