Tutorial documentation update

Author: TaddyHC

content/hardware/04.pro/boards/portenta-h7/tutorials/over-the-air-update/assets/binary_export.png

@@ -5,7 +5,7 @@ difficulty: intermediate
 tags: 
   - OTA
   - Over-The-Air 
-  - Wi-Fi
+  - Wi-Fi®
   - Cloud
 author: 'Taddy Chung, José Bagur'
 libraries:
@@ -38,9 +38,9 @@ The goals of this tutorial are:
 ## Hardware and Software Needed
 
 - [Arduino Portenta H7](https://store.arduino.cc/portenta-h7)
-- Operating System: Linux, macOS, or Windows (with Python 3 installed)
+- Operating System: Linux, macOS, or Windows (with Python® 3 installed)
 - Arduino IDE 1.8.10+ or Arduino IDE 2.0+
-- USB-C® cable (either USB-A to USB-C® or USB-C® to USB-C®)
+- USB-C® cable (either USB-A to USB-C or USB-C to USB-C)
 - [Arduino_Portenta_OTA library](https://github.com/arduino-libraries/Arduino_Portenta_OTA)
 - SD card (optional, you can use QSPI instead)
 - Carrier or shield compatible with the Portenta H7 with an SD card slot (if using SD card method)
@@ -101,15 +101,15 @@ void loop()
 }
 ```
 
-This script will light up the RGB LED with 3 different colors in sequence. This code will need to be uploaded to the Arduino Portenta H7 first. This is to verify whether the sketch compiles and works correctly. After verifying this, in the Arduino IDE, you will search for **Sketch > Export Compiled Binary**.
+This script will light up the RGB LED with 3 different colors in sequence. This code will need to be uploaded to the Arduino Portenta H7 first. This is to verify whether the sketch compiles and works correctly. After verifying this, in the Arduino IDE, navigate to **Sketch > Export Compiled Binary** (or use the keyboard shortcut **Alt+Ctrl+S**).
 
 ![Exporting Binary for the Sketch](assets/binary_export.png)
 
 With the binary file ready, you can now create the OTA file needed to enable the Over-The-Air process.
 
 ### Creating the OTA File
 
-To create the OTA file, you will need a macOS, Linux, or Windows environment with Python 3 installed.
+To create the OTA file, you will need a macOS, Linux, or Windows environment with Python® 3 installed.
 
 Once you have a compatible environment, you will need the tools which can be found at the following link:
 
@@ -146,24 +146,24 @@ Convert your encoded file into `.ota` format
 
 You can use `OTA_Usage_Portenta.ino.PORTENTA_H7_M7` as a sketch name for easier identification of the file. After this, you will have the `.ota` file of the sketch that you will use with the OTA process.
 
-### Installing Python 3 On Linux
+### Installing Python® 3 On Linux
 
-If you are using Linux and cannot run the **`bin2ota.py`** script, you may need to install [Python 3](https://www.python.org/) and the necessary modules. To do this, execute the following command on your **Linux terminal**:
+If you are using Linux and cannot run the **`bin2ota.py`** script, you may need to install [Python® 3](https://www.python.org/) and the necessary modules. To do this, execute the following command on your **Linux terminal**:
 
 ```bash 
 sudo apt install python-is-python3
 ```
 
-You will also need to install the **`crccheck`** module for Python by following these instructions:
+You will also need to install the **`crccheck`** module for Python® by following these instructions:
 
-Installing pip on python:
+Installing pip on Python®:
 
 ```bash
 //Necessary to install python modules:
 sudo apt install python3-pip 
 ```
 
-Installing the `crccheck` necessary module on python:
+Installing the `crccheck` necessary module on Python®:
 
 ```bash
 //Necessary to run the script:
@@ -206,17 +206,24 @@ If you are going to use the example OTA file provided in this tutorial, you don'
 
 #### Setting Up
 
-To use the internal **QSPI** storage for downloading the binary file via OTA (Over-The-Air), you will only need the Arduino Portenta H7 board connected to the computer with the [Arduino IDE](https://www.arduino.cc/en/software). You will need to select the **Arduino Portenta H7 (M7 Core)** with the Flash split of **1 MB M7 + 1 MB M4** for the purpose of this tutorial and the corresponding port.
+To use the internal **QSPI** storage for downloading the binary file via OTA (Over-The-Air), you will only need the Arduino Portenta H7 board connected to the computer with the [Arduino IDE](https://www.arduino.cc/en/software).
+
+Before uploading the OTA sketch, configure the following settings in the Arduino IDE via the **Tools** menu:
+
+- **Board**: Select `Arduino Portenta H7`
+- **Flash split**: Select `1MB M7 + 1MB M4`
+- **Target core**: Select `Main Core` (M7 core)
+- **Port**: Select the appropriate COM port for your Portenta H7
 
 ![Arduino Portenta H7 Board Connection](assets/portenta_h7_board_selection.png)
 
 #### Writing the Script
 
 To proceed with OTA using the QSPI flash, you can open the sketch from **Examples > Arduino_Portenta_OTA > OTA_Qspi_Flash**.
 
-***Do not forget to fill in your Wi-Fi AP SSID and password in the `arduino_secrets.h` tab.***
+***Do not forget to fill in your Wi-Fi® AP SSID and password in the `arduino_secrets.h` tab.***
 
-This sketch will connect to your Wi-Fi, verify whether the OTA feature is available by checking the installed firmware on your Portenta.
+This sketch will connect to your Wi-Fi®, verify whether the OTA feature is available by checking the installed firmware on your Portenta.
 
 Then prepare the OTA storage, download the .ota file from the internet, decompress it, reset the board so that after the reboot, it will apply the new firmware
 
@@ -228,15 +235,20 @@ To use the **SD card** as the preferred OTA (Over-The-Air) storage device, you c
 
 ![Arduino Portenta H7 with Portenta Vision Shield - Ethernet](assets/portenta_h7_plus_vision_shield.svg)
 
-You will need to select the **Arduino Portenta H7 (M7 Core)** with the Flash split of **1 MB M7 + 1 MB M4** for the purpose of this tutorial and the corresponding port.
+Before uploading the OTA sketch, configure the following settings in the Arduino IDE via the **Tools** menu:
+
+- **Board**: Select `Arduino Portenta H7`
+- **Flash split**: Select `1MB M7 + 1MB M4`
+- **Target core**: Select `Main Core` (M7 core)
+- **Port**: Select the appropriate COM port for your Portenta H7
 
 #### Writing the Script
 
 Similar to the QSPI storage mode, to proceed with OTA using the SD Card, you can open the sketch from **Examples > Arduino_Portenta_OTA > OTA_SD_Portenta**.
 
-***Do not forget to fill in your Wi-Fi AP SSID and password in the `arduino_secrets.h` tab.***
+***Do not forget to fill in your Wi-Fi® AP SSID and password in the `arduino_secrets.h` tab.***
 
-This sketch will connect to your Wi-Fi, verify whether the OTA feature is available by checking the installed firmware on your Portenta.
+This sketch will connect to your Wi-Fi®, verify whether the OTA feature is available by checking the installed firmware on your Portenta.
 
 Then prepare the OTA storage, download the .ota file from the internet, decompress it, reset the board so that after the reboot, it will apply the new firmware
 
@@ -537,9 +549,213 @@ void loop()
 }
 ```
 
+## Understanding LZSS Compression and Decompression
+
+For those interested in the underlying compression mechanism or optimizing download performance, you can explore different decompression methods.
+
+The standard OTA examples use a two-step process:
+
+1. Download the compressed `.ota` file to storage
+2. Decompress the file before firmware update
+
+However, the `Arduino_Portenta_OTA` library also supports **on-the-fly decompression**, where the file is decompressed as it's being downloaded, which can be more efficient for certain use cases.
+
+The following example shows both methods and allows you to compare their performance:
+
+```cpp
+/*
+ * This example demonstrates how to download a lzss file and decompress it in two ways:
+ * -1 download the file on the filesystem and then decompress the downloaded file on the filesystem
+ * -2 download and decompress the file on the fly
+ * this sketch also provides a comparison in terms of speed and execution time
+ *
+ */
+
+/******************************************************************************
+ * INCLUDE
+ ******************************************************************************/
+
+#include <Arduino_Portenta_OTA.h>
+
+#include <WiFi.h>
+
+#include "arduino_secrets.h"
+#include <decompress/lzss.h>
+
+/******************************************************************************
+ * CONSTANT
+ ******************************************************************************/
+
+/* Please enter your sensitive data in the Secret tab/arduino_secrets.h */
+static char const SSID[] = SECRET_SSID;  /* your network SSID (name) */
+static char const PASS[] = SECRET_PASS;  /* your network password (use for WPA, or use as key for WEP) */
+
+
+#if defined(ARDUINO_NICLA_VISION)
+static char const URL_FILE[] = "https://downloads.arduino.cc/ota/OTA_Usage_Portenta.ino.NICLA_VISION.ota";
+#elif defined(ARDUINO_PORTENTA_H7_M7)
+static char const URL_FILE[] = "https://downloads.arduino.cc/ota/OTA_Usage_Portenta.ino.PORTENTA_H7_M7.ota";
+#elif defined(ARDUINO_OPTA)
+static char const URL_FILE[] = "https://downloads.arduino.cc/ota/OTA_Usage_Portenta.ino.OPTA.ota";
+#elif defined(ARDUINO_GIGA)
+static char const URL_FILE[] = "https://downloads.arduino.cc/ota/OTA_Usage_Portenta.ino.GIGA.ota";
+#else
+#error "Board not supported"
+#endif
+
+static char const DOWNLOAD_DESTINATION[] =      "/fs/UPDATE.BIN.LZSS";
+static char const DECOMPRESSED_DESTINATION[] =  "/fs/UPDATE.BIN";
+
+LZSSDecoder *decoder = nullptr;
+FILE* download_target = nullptr;
+
+/******************************************************************************
+ * SETUP/LOOP
+ ******************************************************************************/
+void decompress_on_the_fly_cbk(const char*, uint32_t);
+void putc_file(const uint8_t c);
+
+void setup() {
+  Serial.begin(115200);
+  while (!Serial) {}
+
+  if (WiFi.status() == WL_NO_SHIELD)
+  {
+      Serial.println("Communication with WiFi module failed!");
+      return;
+  }
+
+  int status = WL_IDLE_STATUS;
+  while (status != WL_CONNECTED)
+  {
+      Serial.print  ("Attempting to connect to '");
+      Serial.print  (SSID);
+      Serial.println("'");
+      status = WiFi.begin(SSID, PASS);
+      if(status != WL_CONNECTED) {
+          delay(10000);
+      }
+  }
+  Serial.print  ("You're connected to '");
+  Serial.print  (WiFi.SSID());
+  Serial.println("'");
+
+  // Init fs
+  mbed::BlockDevice * _bd_raw_qspi = mbed::BlockDevice::get_default_instance();;
+  auto _bd_qspi = new mbed::MBRBlockDevice(_bd_raw_qspi, 2);
+  auto _fs_qspi = new mbed::FATFileSystem("fs");
+  int const err_mount = _fs_qspi->mount(_bd_qspi);
+  if (err_mount) {
+      Serial.print("Error while mounting the filesystem. Err = ");
+      Serial.println(err_mount);
+      return;
+  }
+
+  MbedSocketClass * socket = static_cast<MbedSocketClass*>(&WiFi);
+  remove(DOWNLOAD_DESTINATION);
+  remove(DECOMPRESSED_DESTINATION);
+
+  uint32_t start;
+  int bytes;
+  float elapsed, speed;
+  start = millis();
+  Serial.println("Starting download to QSPI ...");
+  bytes = socket->download(URL_FILE, DOWNLOAD_DESTINATION, true /* is_https */);
+  if (bytes <= 0)
+  {
+      Serial.print  ("MbedSocketClass::download failed with error code ");
+      Serial.println(bytes);
+      return;
+  }
+  Serial.print  (bytes);
+  Serial.println(" bytes stored.");
+
+  elapsed = (millis()-start)/1000.0; // elapsed expressed in seconds
+  speed = (bytes/elapsed)/1024;
+
+  Serial.print("download elapsed ");
+  Serial.print(elapsed);
+  Serial.print("s speed: ");
+  Serial.print(speed);
+  Serial.println("KBps");
+
+  FILE* downloaded_file = fopen(DOWNLOAD_DESTINATION, "rb");
+  FILE* decompressed_file = fopen(DECOMPRESSED_DESTINATION, "wb");
+
+  start = millis();
+  lzss_init(downloaded_file, decompressed_file, bytes, nullptr);
+
+  lzss_decode();
+  /* Write the data remaining in the write buffer to
+  * the file.
+  */
+  lzss_flush();
+
+  elapsed = (millis()-start)/1000.0; // elapsed expressed in seconds
+
+  Serial.print("decompress elapsed ");
+  Serial.print(elapsed);
+  Serial.print("s");
+  Serial.print(" size ");
+  Serial.println(ftell(decompressed_file));
+
+  fclose(downloaded_file);
+  fclose(decompressed_file);
+
+  // On the fly decompression
+  remove(DOWNLOAD_DESTINATION);
+  remove(DECOMPRESSED_DESTINATION);
+
+  download_target = fopen(DECOMPRESSED_DESTINATION, "wb");
+  decoder = new LZSSDecoder(putc_file);
+
+  Serial.println("Starting download & decompress on the fly");
+  start = millis();
+  bytes = socket->download(URL_FILE, true /* is_https */, decompress_on_the_fly_cbk);
+  if (bytes <= 0)
+  {
+      Serial.print  ("MbedSocketClass::download failed with error code ");
+      Serial.println(bytes);
+      return;
+  }
+
+  Serial.print("downloaded ");
+  Serial.print(bytes);
+  Serial.print(" bytes ");
+
+  elapsed = (millis()-start)/1000.0; // elapsed expressed in seconds
+  speed = (bytes/elapsed)/1024;
+
+  Serial.print  (ftell(download_target));
+  Serial.println(" bytes stored.");
+
+  Serial.print("download elapsed ");
+  Serial.print(elapsed);
+  Serial.print("s speed: ");
+  Serial.print(speed);
+  Serial.println("KBps");
+
+  delete decoder;
+  fclose(download_target);
+}
+
+void loop() {
+}
+
+void decompress_on_the_fly_cbk(const char* buffer, uint32_t size) {
+    decoder->decompress((uint8_t*)buffer, size);
+}
+
+void putc_file(const uint8_t c) {
+    fwrite(&c, 1, 1, download_target);
+}
+
+
+```
+
 ## Troubleshooting
 
 For troubleshooting issues that might have arisen while following the tutorial, you can use the following tips to solve the issue.
 
-- If there has been an issue with the Wi-Fi module, it means the device may have lost the Wi-Fi firmware partition. To solve this, you will have to use the **WiFiFirmwareUpdater** sketch found in the Arduino IDE examples to fix the issue.
+- If there has been an issue with the Wi-Fi® module, it means the device may have lost the Wi-Fi® firmware partition. To solve this, you will have to use the **WiFiFirmwareUpdater** sketch found in the Arduino IDE examples to fix the issue.
 - QSPI storage may throw error -3 while running the Portenta H7 OTA QSPI example. To fix this, you can use the guide on [Reading and Writing Flash Memory](https://docs.arduino.cc/tutorials/portenta-h7/reading-writing-flash-memory) in the section **Programming the QSPI Flash**. At this point, run the example again, and the error -3 (OTA Storage initialization error) should be resolved.