Spelling fixes and some additional explanations

Author: sebromero

content/hardware/04.pro/boards/portenta-x8/tutorials/uploading-sketches-m4/content.md

@@ -1,10 +1,9 @@
 ---
-title: 'Upload Sketches to the Arduino Portenta X8'
-description: 'This tutorial will show how to upload Arduino sketches on the M4 processor'
+title: 'Uploading Sketches to the M4 Core on Arduino Portenta X8'
+description: 'This tutorial explains how to upload Arduino sketches to the M4 core.'
 difficulty: medium
-beta: true
 tags:
-  - Firmware
+  - firmware
   - M4
 author: 'Pablo Marquínez'
 hardware:
@@ -16,26 +15,26 @@ software:
 ---
 
 ## Overview
-This tutorial will explain how to upload a standard Arduino sketch to your Portenta X8's M4.
+In this tutorial we will go through the process of uploading sketches to the M4 core on the STM32H747XI MCU. For the user the process is the same as usual but it differs quite a bit in regards to what happens behind the scenes compared to other Arduino boards.
 
 ## Goals
-- Use the Arduino IDE to compile and upload.
-- Compile the sketch binaries with the Arduino IDE and upload it through ADB.
+- Learn how to use the Arduino IDE to compile and upload a sketch.
+- Learn how to compile the sketch binaries with the Arduino IDE and upload it manually via ADB.
 
 ### Required Hardware and Software
-- Portenta X8
+- [Portenta X8](https://store.arduino.cc/products/portenta-x8)
 - USB C cable (either USB A to USB C or USB C to USB C)
 - Arduino IDE 1.8.10+ or Arduino-cli
-- arduino-mbed portenta Core up to date (greater than 3.0.1)
+- Latest "Arduino Mbed OS Portenta Boards" Core > 3.0.1
 
 ## Instructions
 
 ### Standard Arduino IDE Upload
-Open the Arduino IDE, make sure you have selected the Portenta X8 on the boards selector.
+Open the Arduino IDE, make sure you have selected the Portenta X8 in the boards selector.
 
 ![IDE board selector](assets/x8-board-manager.png)
 
-Create your sketch, for example the blink sketch:
+Create a custom sketch or open one of the example sketches e.g. the blink sketch:
 ```arduino
 void setup(){
   pinMode(LED_BUILTIN ,OUTPUT);
@@ -49,15 +48,16 @@ void loop(){
 }
 ```
 
-Once your sketch it's completed, select the port of your device.
+- Select the port of your device in the port selector menu.
+- Press the Compile and Upload button.
 
-Press the Compile and Upload button.
+Behind the curtains, the sketch gets compiled into a binary. That binary file is then uploaded to the Linux side of the Portenta X8 via an `adb` SSH connection. The flashing itself is done on the board itself by a service running on Linux. When the sketch has bee uploaded successfully, check if the onboard LED is blinking at an interval of one second.
 
-To finalize, when you see that the sketch has bee uploaded successfully, check that every second you are getting the LED changing from OFF to ON.
+### Upload Manually Using ADB
 
-### Upload Using ADB
+To upload a firmware manually, you first need to compile the sketch. In the Arduino IDE select "Export compiled binary" from the Sketch menu. It will compile the sketch and save the binary file in the sketch folder. Alternatively you can use the [Arduino CLI](https://arduino.github.io/arduino-cli/) to create an elf file.
 
-To use ADB, it gets installed at `Arduino15\packages\arduino\tools\adb\32.0.0`.
+To upload the firmware you can use the ADB tool that has been installed as part of the Portenta X8 core. It can be found at `Arduino15\packages\arduino\tools\adb\32.0.0`.
 
 From that directory you can use the `adb` tool. To upload your compiled sketch you just need to type:
 ```
@@ -67,18 +67,16 @@ adb push <sketchBinaryPath> /tmp/arduino/m4-user-sketch.elf
 ![ADB upload with a terminal](assets/x8-terminal-ADB-push.png)
 
 ## How It Works?
-The Portenta X8 has some services that once the sketch has been pushed to the required folder, if it detects changes the device will flash the M4 after that happened!
+The Portenta X8 has a service that waits for a sketch to be uploaded to a folder. If it detects changes the device will flash the M4 with the uploaded firmware.
 
 This work thanks to the following services:
-* **monitor-m4-elf-file.service**: this service monitors the directory `/tmp/arduino/m4-user-sketch.elf` each time it detects a new file it will proceed to flash the M4 using the tool `openOCD` and providing the sketch that has been pushed.
+* **monitor-m4-elf-file.service**: this service monitors the directory `/tmp/arduino/m4-user-sketch.elf` and each time it detects a new file it will proceed to flash the M4 using  `openOCD` with the sketch that has been pushed.
 * **android-tools-adbd.service**: responsible of generating the needed interfaces for the different types of usb gadgets.
 * **create-docker-envfile.service**: Controls if the device has been plugged for example in some carrier and makes the info available at `/var/run/arduino_hw_info.env` and is meant to be used by the ´docker containers´.
 
 ## Conclusion
-You now have access to the M4 processor, so for example you are able to connect an I<sup>2</sup>C sensor and interact with it, also you could track the sensor from the Arduino Portenta X8 Linux side.
+In this tutorial you have learned how to upload a sketch to the M4 core. Now for example you are able to connect an I<sup>2</sup>C sensor and interact with it. 
 
 ## Troubleshooting
 
-### ADB Folder Empty
-
-If you cannot use the `ADB` tool and the folder `Arduino15\packages\arduino\tools\adb\32.0.0` is empty Remove the Mbed Portenta Core and install it again.
+- If you cannot use the `ADB` tool and the folder `Arduino15\packages\arduino\tools\adb\32.0.0` is empty Remove the Mbed Portenta Core and install it again.