Merge branch 'document' into 'master'

OTA documentation changes, documentation changes for BLE

See merge request app-frameworks/esp_hosted!163

README.md

@@ -81,7 +81,12 @@ Below table explains which feature is supported on which transport interface for
 | 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.
+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.
@@ -116,6 +121,8 @@ Note: BT stands for Bluetooth BR/EDR and BLE stands for Bluetooth Low Energy spe
 > 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).
 
 ---
 

docs/Linux_based_host/Getting_started.md

@@ -116,6 +116,12 @@ hci0:	Type: Primary  Bus: SDIO
 * This interface supports all standard HCI commands. Use standard hci tools to control and configure this interface.
 
 ### 2.1 BT/BLE Test procedure
+
+* 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.
+* To upgrade `bluez` for particular version, follow this [link](https://scribles.net/updating-bluez-on-raspberry-pi-from-5-43-to-5-50/). Replace bluez `older version` to `expected version` while following mentioned link.
+
 #### 2.1.1 GATT server
 
 1. Go to `bluez-5.xx` folder. Run `./test/example-gatt-server`. This will start GATT server on Raspberry-Pi.
@@ -152,15 +158,15 @@ Only ESP32C3 HCI controller supports BLE 5.0. Several new features are introduce
 5. LE Advertising Extensions
 6. LE Channel Selection Algorithm #2
 
-To test BLE 5.0 on RPi minimum `bluez` version `5.56` and above required. Check current `bluez` version by running following command on RPi:
+To test BLE 5.0 on RPi minimum `bluez` version `5.45` and above required. If `bluez` version is less than 5.45 ,then upgrade `bluez` version.
+
+Check current `bluez` version by running following command on RPi:
 
 ```
 bluetoothctl -v
 ```
 :warning: `hcitool lescan` is deprecated. Please dont use it.
 
-If `bluez` version is less than 5.56 then follow [this](https://scribles.net/updating-bluez-on-raspberry-pi-from-5-43-to-5-50/) link to update bluez to 5.56. Replace `bluez` version `5.50` to `5.56` while following mentioned link.
-
 ### 2.2.1 Basic scan, pair, connect
 
 Execute following steps on linux host.
@@ -230,7 +236,12 @@ Steps:
 
 BLE5.0 supports 1M, 2M and CODED phy. To use 2M and CODED phy for gatt read/write procedure as follow:
 
-Note: Default selected phy is 1M. To perform gatt read/write with BLE5.0 peripheral, both host and peripheral must have same phy configuration.
+Note:
+* Default selected phy is 1M. To perform gatt read/write with BLE5.0 peripheral, both host and peripheral must have same phy configuration.
+
+* 'PHY' feature in BLE 5.0 is verified with btmgmt tool from bluez version 5.56+.
+
+* If `bluez` version is less than 5.56 ,then upgrade `bluez` version.
 
 #####  Using 1M phy:
 1M phy is default phy for BLE5.0. Follow above mentioned steps in section 2.2.1
@@ -246,21 +257,29 @@ Steps:
 4. while executing connect command, there is `LE Enhanced Connection Complete` event in `btmon` log. Note down `handle` value.
 5. After connection, exit form bluetoothctl. Run `exit` in bluetoothctl.
 6. Now configure phy into 2M. Run `sudo hcitool cmd 08 32 <handle_value> 03 02 02 00`.
-7. Follow gatt read/write from gatt menu in bluetoothctl.
+7. Follow gatt read/write from `gatt menu` in bluetoothctl.
 
 ##### Using CODED phy:
 Configure CODED phy on host and peripheral side.
 
 Steps:
-1. To configure phy as 1M and 2M both, run `sudo hcitool cmd 08 31 03 03 03`.
+1. To configure phy as CODED phy, run `sudo hcitool cmd 08 31 03 04 04`.
 2. To check selected phy, Go to `bluez-5.56` directory. Run `sudo ./tools/btmgmt --index hci0` and run `phy`.
 3. Connect to BLE5.0 device using above mentioned steps in section 2.2.1.
-4. while executing connect command, there is `LE Enhanced Connection Complete` event in `btmon` log. Note down `handle` value.
-5. After connection, exit form bluetoothctl. Run `exit` in bluetoothctl.
-6. Now configure phy into 2M. Run `sudo hcitool cmd 08 32 <handle_value> 03 02 02 00`.
-7. Follow gatt read/write from gatt menu in bluetoothctl.
+4. Follow gatt read/write from gatt menu in bluetoothctl.
+
+## 3. OTA operation
+
+OTA (Over The Air) update performs following operations.
+* Erase ota flash partition of ESP32
+* Download chunk from URL and write that chunk into flash, one by one, till whole binary is written
+* Validate the complete written binary in flash
+* Sets newly written OTA partition as boot partition
+* Reboot the ESP32 after 5 second
+
+Please follow [OTA update documentation](ota_update.md) for further details.
 
-## 3. Troubleshoot Instructions
+## 4. Troubleshoot Instructions
 
 Please refer following for troubleshoot instructions if something goes wrong.
 

docs/Linux_based_host/Linux_based_architecture.md

@@ -127,3 +127,12 @@ Following are few ready to use convenience script provided in the repository. Th
 	python connected_stations_list.py
 	```
 
+* **OTA update**
+	`ota_update.py` script updates ESP32 firmware with provided URL of binary file. This script will perform following operation.
+		- Erase ota flash partition of ESP32
+		- Download chunk from URL and write that chunk into flash, one by one, till whole binary is written
+		- Validate the complete written binary in flash
+		- Sets newly written OTA partition as boot partition
+		- Reboot the ESP32 after 5 second
+
+	Please refer [ota](ota_update.md) for detailed documentation.

docs/Linux_based_host/Linux_based_readme.md

@@ -190,12 +190,13 @@ This section identifies Raspberry-Pi specific setup requirements.
 	* Git
 	* Python 2.x or 3.x: We have tested ESP-Hosted solution with python 2.7.13 and 3.5.3
 	* Bluetooth Stack and utilities:
-	  :warning:`Note: We have tested ESP-Hosted solution with bluez 5.43+`
+	  :warning:`Note: 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+.`
 		* bluetooth
 		* bluez
 		* bluez-tools
 		* rfkill
 		* bluez-firmware
+	* We suggest latest stable bluez version to be used. Any other bluetooth stack instead of bluez also could be used.
 
 ### 2.2 ESP-IDF Setup
 :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.`  

docs/Linux_based_host/ota_update.md

@@ -0,0 +1,38 @@
+## **ESP-Hosted OTA update ESP32 image**
+
+Please note, Maximum size of New OTA image binary depends upon -
+1. Total flash size available
+2. OTA partition size in partition table
+As per current limits, upto 1MB binary size is supported which is configurable using custom partition table CSV. Please refer [partition tables](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/partition-tables.html) for more info.
+
+There are basic three control path commands for OTA are provided in C and python, as follows:
+* esp_ota_begin() -- Sets available OTA partition in flash for OTA write operation and erase it.
+* esp_ota_write() -- Write chunk of OTA image data on OTA partition in flash.
+* esp_ota_end()   -- Validate written OTA image, set OTA partition for next boot and reboot ESP32 after 5 sec.
+
+Definition of these commands are present in [commands.c](host/host_common/commands.c) and [commands_lib.py](host/linux/host_control/python_support/commands_lib.py) files.
+
+## **How to use**
+
+### On ESP32 side
+Build and flash ESP-Hosted application using `idf.py build flash monitor`.
+
+### On Host side
+
+#### Note
+1. Please stop ongoing BT/BLE operations before starting OTA process.
+2. OTA operation should not get interrupted by any other control path command.
+3. OTA update using HTTP URL is only supported in python. In case HTTP based OTA update is desired, user can do the same using third party HTTP client library.
+4. The OTA update using C currently assumes the complete binary is downloaded locally.
+
+### Python Implementation
+User can skip step 1, if station is connected to AP and IP is assigned to `ethsta0` interface.
+
+1. Perform station connect using [wifi station mode operations](Getting_started.md#111-wi-fi-station-mode-operations)
+-> Connect to external access point.
+
+2. For further details follow this [Link](../python_demo.md#ota-update).
+
+### C Implementation
+
+For Further details follow this [Link](../c_demo.md#c-demo-application).

docs/c_api.md

@@ -1,6 +1,6 @@
 # Control Interface: C API's
 
-This document describes C API's provided for control path interface. Please refer [commands.c](../host/host_common/commands.c) for API's defination. [c_demo.md](c_demo.md) gives overview of how to test control path interface in application also how to perform stress testing of control path interface.
+This document describes C API's provided for control path interface. Please refer [commands.c](../host/host_common/commands.c) for API's definition. [c_demo.md](c_demo.md) gives overview of how to test control path interface in application also how to perform stress testing of control path interface.
 
 A [stress.c](../host/linux/host_control/c_support/stress.c) can use for stress testing of control path commands. In which, `STRESS_TEST_COUNT` variable represents number of iterations and `STRESS_TEST` variable defines which test should get executed.
 
@@ -531,6 +531,43 @@ Current WiFi transmitting power, unit is 0.25dBm.
 #### **Note**
 It is possible that the current wifi transmit power is lesser than that of the requested max transmit power as part of `wifi_set_max_tx_power` API.
 
+#### Return
+
+- 0 : SUCCESS
+- -1 : FAILURE
+
+---
+
+### 2.20 `int esp_ota_begin()`
+
+esp ota begin function performs an OTA begin operation for ESP32 which erases and prepares existing flash partition for new flash writing.
+
+#### Return
+- 0 : SUCCESS
+- -1 : FAILURE
+
+---
+
+### 2.21 `int esp_ota_write(uint8_t* ota_data, uint32_t ota_data_len)`
+
+esp ota write function performs an OTA write operation for ESP32, It writes bytes from `ota_data` buffer with `ota_data_len` number of bytes to OTA partition in flash. Number of bytes can be small than size of complete binary to be flashed. In that case, this caller is expected to repeatedly call this function till total size written equals size of complete binary.
+
+#### Parameters
+
+- `ota_data` : OTA data buffer
+- `ota_data_len` : length of OTA data buffer
+
+#### Return
+
+- 0 : SUCCESS
+- -1 : FAILURE
+
+---
+
+### 2.22 `int esp_ota_end()`
+
+esp ota end function performs an OTA end operation for ESP32, It validates written OTA image, sets newly written OTA partition as boot partition for next boot, Creates timer which reset ESP32 after 5 sec.
+
 #### Return
 - 0 : SUCCESS
 - -1 : FAILURE

docs/c_demo.md

@@ -12,6 +12,7 @@
 | sta_list | List external stations connected to softAP |
 | ap_vendor_ie | Set vendor information element for ESP32 softAP |
 | wifi_tx_power | sets WiFi maximum transmitting power and get WiFi current transmitting power |
+| ota </path/to/ota_image.bin> | performs OTA operation using local OTA binary file |
 
 It uses APIs present in [test_api.c](../host/linux/host_control/c_support/test_api.c). User should first modify configuration parameters in [test_config.h](../host/linux/host_control/c_support/test_config.h). Then run `make` in [c_support](../host/linux/host_control/c_support) to compile `test.c`.
 
@@ -44,6 +45,15 @@ sudo dnsmasq --no-daemon --no-resolv --no-poll --dhcp-script=/system/bin/dhcp_an
 sudo ifconfig ethap0 192.168.4.5
 ```
 
+* OTA -
+The OTA update using C currently assumes the complete binary is downloaded locally.
+OTA update using HTTP URL is only supported in [python](python_demo.md#ota-update). In case HTTP based OTA update is desired, user can do the same using third party HTTP client library.
+
+```
+ex.
+./test.out ota </path/to/ota_image.bin>
+```
+
 # C stress Application
 
 [stress.c](../host/linux/host_control/c_support/stress.c) use for stress testing of control path APIs. It provides basic command line arguments as follows: