Merge pull request #571 from arduino/Hannes7eicher/Cloud-Interface-Review

[MKC-1296] Hannes7eicher/cloud interface review

Author: Hannes7eicher

content/arduino-cloud/03.cloud-interface/00.sketches/sketches.md

@@ -9,15 +9,15 @@ A sketch is a file where we write programs to run on our Arduino boards. Sketche
 
 The Arduino Cloud has two categories of sketches:
 - **Regular sketch** - a single `.ino` file where you write a program. These sketches can be used for **any** Arduino board. 
-- **IoT Sketch** - a set of files that are automatically generated when creating a [Thing](/arduino-cloud/cloud-interface/things). This includes a `.ino` file, and two header (`.h`) files that contains your Thing configuration + credentials. Only available for boards with IoT support.
+- **IoT Sketch** - a set of files that are automatically generated when creating a [Thing](/arduino-cloud/cloud-interface/things). This includes an `.ino` file and two header (`.h`) files that contain your Thing configuration + credentials. Only available for boards with IoT support.
 
 In this document we will take a look at how to use sketches in the Arduino Cloud environment.
 
-***If you need help getting started with programming your Arduino in the online environment, check out the [Cloud Editor](/arduino-cloud/guides/cloud-editor) tutorial.
+***If you need help getting started with programming your Arduino in the online environment, check out the [Cloud Editor](/arduino-cloud/guides/cloud-editor) tutorial.***
 
 ## Access Your Sketches
 
-You can access all your sketches at [app.arduino.cc/sketches](app.arduino.cc/sketches), where you can easily select between your regular sketches, and IoT sketches.
+You can access all your sketches at [app.arduino.cc/sketches](https://app.arduino.cc/sketches), where you can easily select between your regular sketches and IoT sketches.
 
 ![Sketches in the Arduino Cloud.](assets/sketch.png)
 
@@ -27,7 +27,7 @@ Clicking on each sketch will direct you to the [Cloud Editor](https://create.ard
 
 ## Regular Sketches
 
-A regular sketch in the Arduino Cloud are exactly like sketches used in the [Arduino IDE](/software/ide-v2), with no difference whatsoever. You can take a sketch from the online IDE and compile it in the offline IDE. 
+A regular sketch in the Arduino Cloud is exactly like a sketch used in the [Arduino IDE](/software/ide-v2), with no difference whatsoever. You can take a sketch from the online IDE and compile it in the offline IDE. 
 
 A regular sketch only has two minimum requirements: the inclusion of the `void loop()` and `void setup()` functions, which are required for any Arduino sketch.
 
@@ -47,18 +47,18 @@ For specific features of a board, make sure to check out the [hardware documenta
 
 ## IoT Sketches
 
-IoT sketches are more complex, and are generated automatically when you create a Thing and variables.
+IoT sketches are more complex and are generated automatically when you create a Thing and variables.
 
 ***Read more about this in the [Automatic Sketch Generation](/arduino-cloud/cloud-interface/sketches) documentation.***
 
 ### Sketch File
 
-This sketch file is generated with a set of additional cloud specific methods included, the essentials being:
+The sketch file is generated with a set of additional cloud-specific methods included, the essentials being:
 - `initProperties()` - initializes properties/variables from your Thing.
 - `ArduinoCloud.begin()` starts the library with the preferred connection (e.g. Wi-Fi® or LoRaWAN®).
-- `ArduinoCloud.update()` - synchronizing all data between board and Arduino Cloud
+- `ArduinoCloud.update()` - synchronizes all data between the board and the Arduino Cloud.
 
-In addition, any variables created with a read/write permission will also generate a callback function that executes whenever the variable's value changes.
+In addition, any variable created with a read/write permission will also generate a callback function that executes whenever the variable's value changes.
 - If you create a variable called `test`, the function will render as `void onTestChange(){}`
 
 Below is an example of how a default sketch looks like:
@@ -96,17 +96,17 @@ void onTestChange(){
 The `thingProperties.h` file is a non-editable file that updates based on changes made in your Thing. For example:
 
 - Creating a variable will add it to this file, along with parameters such as permission, update policy, variable type etc. 
-- Changing from a Wi-Fi® device to LoRa® device will update the **connection method** stored in this file,
+- Changing from a Wi-Fi® device to a LoRa® device will update the **connection method** stored in this file,
 
 The file cannot be edited in the Arduino Cloud as it is in sync with the platform and changes frequently.
 
 ### Secret File
 
 The "Secret" File contains your secret credentials, such as Wi-Fi® network SSID/PASS or device secret key.
 
-This file will be visible as a "Secret" tab in the Cloud Editor, and is named `arduino_secrets.h`, which is not visible in the cloud platform.
+This file will be visible as a "Secret" tab in the Cloud Editor and is named `arduino_secrets.h`, which is not visible on the cloud platform.
 
-Note that if you are using the offline IDE / Arduino CLI instead, you will manually need to create this file. More information in the **Offline Sketches section** just below.
+Note that if you are using the offline IDE / Arduino CLI, you will need to manually create this file. More information is in the **Offline Sketches section** just below.
 
 ## Offline Sketches
 
@@ -144,11 +144,11 @@ ArduinoCloud.begin(ArduinoIoTPreferredConnection, false).
 
 ### Alternatives to Delays
 
-The `loop()` function includes the `ArduinoCloud.update();` call, which sends data to the cloud and receives updates. In order to get the best responsiveness in your cloud-connected projects, the `loop()` function should run as fast as possible. This means that no blocking commands should be used inside, and you should prefer a non-blocking programming approach whenever possible.
+The `loop()` function includes the `ArduinoCloud.update();` call, which sends data to the cloud and receives updates. To get the best responsiveness in your cloud-connected projects, the `loop()` function should run as fast as possible. This means that no blocking commands should be used inside, and you should prefer a non-blocking programming approach whenever possible.
 
 A common **blocking pattern** is the use of the `delay()` function which stops the execution of the function for the given time. We strongly advise to **get rid of this function** and achieve the same behavior in a non-blocking way with the `millis()` function as described below.
 
-Let's see how to blink a LED. The traditional way involves the `delay()` function:
+Let's see how to blink an LED. The traditional way involves the `delay()` function:
 
 ```arduino
 void loop() {
@@ -179,7 +179,7 @@ For a more complex and commented example, you can have a look at the [BlinkWitho
 
 ### I2C Usage
 
-Components connected via I²C (including the sensors onboard the [MKR IoT Carrier](https://store.arduino.cc/products/arduino-mkr-iot-carrier)) uses the same bus as the **ECCX08** cryptochip. As the crypto chip is an essential part of establishing a connection to the IoT Cloud (it contains the credentials), it is important that other I²C peripherals are initialized after the connection has been made.
+Components connected via I²C (including the sensors onboard the [MKR IoT Carrier](https://store.arduino.cc/products/arduino-mkr-iot-carrier)) uses the same bus as the **ECCX08** crypto chip. As the crypto chip is an essential part of establishing a connection to the IoT Cloud (it contains the credentials), it is important that other I²C peripherals are initialized after the connection has been made.
 
 For example, if you are initializing a library such as [Arduino_MKRENV](https://www.arduino.cc/reference/en/libraries/arduino_mkrenv), your `setup()` should be implemented as:
 
@@ -199,19 +199,20 @@ void setup() {
     Serial.println("Failed to initialize MKR ENV shield!");
     while (1);
   }
+}
 ```
 
 
 ### Avoid Blocking Serial Communication
 
 `while(!Serial) {}` loops endlessly until the Serial Monitor is opened. This is a useful practice in cases where you want to see all debug output from the start of the sketch execution. However, when building IoT systems using **`while(!Serial){}` can hinder our project from running autonomously**, stopping the board from connecting to the network and IoT Cloud before manually opening the Serial Monitor. Therefore, it is recommended to consider removing the `while(!Serial){}` loop if it's not necessary.
 
-A common trick is to add a **`delay(1500);` command after `Serial.begin(9600);`**. This will slightly slow down the initialization of your device, but will give you some time to open the serial monitor when you're interested in seeing its output within losing the very first lines.
+A common trick is to add a **`delay(1500);` command after `Serial.begin(9600);`**. This will slightly slow down the initialization of your device but will give you some time to open the serial monitor when you're interested in seeing its output without losing the very first lines.
 
 ## Create Agent
 
 The [Arduino Create Agent](https://github.com/arduino/arduino-create-agent) is a single binary that will appear on the menu bar and work in the background. It allows you to use the Arduino IoT Cloud and the Arduino Web Editor to seamlessly upload code to any board directly from the browser.
 
-Downloading and installing the Arduino Create Agent plugin can be simply done following [this quick and easy process](https://create.arduino.cc/getting-started/plugin/welcome).
+Downloading and installing the Arduino Create Agent plugin can be done following [this quick and easy process](https://create.arduino.cc/getting-started/plugin/welcome).
 
 The full documentation of the [Arduino Create Agent is available here](https://github.com/arduino/arduino-create-agent#readme) for more advanced usage.

content/arduino-cloud/03.cloud-interface/01.things/things.md

@@ -12,12 +12,12 @@ In the Thing interface you can:
 - select the main device you want to associate with,
 - enter network credentials (such as Wi-Fi network/password),
 - edit & upload sketches to your board,
-- set webhooks that trigger whenever data changes.
+- set webhooks that trigger whenever data changes,
 - edit the timezone.
 
 ## Thing Interface
 
-The Thing interface is designed for ease-of-use, and only has a few sections, which we will now go through.
+The Thing interface is designed for ease-of-use and only has a few sections, which we will now go through.
 
 ![Thing Interface](assets/thing-interface.png)
 
@@ -32,7 +32,7 @@ Below you will find more details on each of the sections.
 
 ## Variables
 
-The variables section is where you create **"Cloud Variables"**, a variable that exist in the Arduino Cloud as well as on your board/setup, and are synchronised continuously. You can configure a variable to be:
+The variables section is where you create **"Cloud Variables"**, a variable that exist in the Arduino Cloud as well as on your board/setup, and is synchronized continuously. You can configure a variable to be:
 - **Read/Write** - you can interact with the variable from a dashboard,
 - **Read Only** - you can only read data from the board.
 
@@ -48,18 +48,18 @@ temperature = sensor.readTemperature();
 
 There are a large number of variables available, including basic types such as `int`, `boolean` & `String`, but also complex types that hold multiple values, such as the `ColoredLight` variable. 
 
-Variables of the same type can also be synchronised across all devices. This is done when creating a new variable, where you check the variables you want to sync with. 
+Variables of the same type can also be synchronized across all devices. This is done when creating a new variable, where you check the variables you want to sync with. 
 
-***All variables are listed out in the [Variables](/arduino-cloud/cloud-interface/variables) section. See [Variable Synchronization](/arduino-cloud/cloud-interface/variables#variable-synchronisation) for linking together your devices' variables.***
+***All variables are listed in the [Variables](/arduino-cloud/cloud-interface/variables) section. See [Variable Synchronization](/arduino-cloud/cloud-interface/variables#variable-synchronisation) for linking together your devices' variables.***
 
 ## Device
 
-In the device section you can select either a previously configured device, or configure a new one. Associating a device means your device and Thing are now linked indefinitely, until you decide to detach them.
+In the device section, you can select either a previously configured device, or configure a new one. Associating a device means your device and Thing are now linked indefinitely until you decide to detach them.
 
 You can connect one of the following devices:
 - [Arduino Wi-Fi® devices](/arduino-cloud/hardware/wifi) - official Arduino devices with a Wi-Fi® enabled module.
 - [Arduino LoRaWAN® devices](/arduino-cloud/hardware/lora) - official Arduino devices with a LoRaWAN® module.
-- [Third party ESP32/ESP8266 devices](/arduino-cloud/hardware/wifi) - third party devices with an ESP32/ESP8266 SoC.
+- [Third-party ESP32/ESP8266 devices](/arduino-cloud/hardware/wifi) - third party devices with an ESP32/ESP8266 SoC.
 - [Manual devices](/arduino-cloud/hardware/devices#manual-devices) - a virtual device using MicroPython, Python or JavaScript. These devices do not have a sketch associated.
 
 The status of your device is also displayed in this section (online/offline).
@@ -68,11 +68,11 @@ The status of your device is also displayed in this section (online/offline).
 
 ## Network
 
-In the network section, you configure the credentials for your network, such as your Wi-Fi® network, secret key (for ESP32 boards) and other credentials for e.g. LoRaWAN® & cellular. The network details are securely stored.
+In the network section, you configure the credentials for your network, such as your Wi-Fi® network, secret key (for ESP32 boards) and other credentials e.g. LoRaWAN® & cellular. The network details are securely stored.
 
 ![Network configuration.](assets/network-creds.png)
 
-The credentials entered are automatically included in your sketch (see automatic sketch generation just below). 
+The credentials entered are automatically included in your sketch (see [automatic sketch generation](#automatic-sketch-generation)). 
 
 ## Sketch
 
@@ -95,7 +95,7 @@ The editor includes all cores for official Arduino boards, and over 6000+ librar
 
 ## Metadata
 
-In the metadata tab you will find your **Thing ID**, **Timezone** configuration, timestamp data (creation/last modified). Here you can also create tags 
+In the metadata tab, you will find your **Thing ID**, **Timezone** configuration, timestamp data (creation/last modified). Here you can also create tags.
 
 ### Thing ID
 
@@ -109,7 +109,7 @@ This ID is used when connecting with the [REST API](/arduino-cloud/api/arduino-i
 
 ### Timezone
 
-You can choose your timezone through a dropdown menu in the metadata tab, which includes many cities from the Americas, Europe, Asia, Africa, Oceania, Atlantic, Pacific and even Antarctica.
+You can choose your timezone through a dropdown menu in the metadata tab, which includes many cities in America, Europe, Asia, Africa, Oceania, Atlantic, Pacific and even Antarctica.
 
 This is particularly important when using the [scheduler](/arduino-cloud/features/cloud-scheduler) feature to trigger events at specific times.
 
@@ -121,14 +121,14 @@ Tags are used to organize and filter your Things. In a setup with many devices a
 
 ## Automatic Sketch Generation
 
-Things based on Arduino / C++ (the default way) benefits from **automatic sketch generation**. Whenever any configuration is done in your Thing, the changes are reflected in your sketch files.
+Things based on Arduino / C++ (the default way) benefit from **automatic sketch generation**. Whenever the configuration is done in your Thing, the changes are reflected in your sketch files.
 
 For example:
-- Associating a Wi-Fi board will automatically update the connection method,
-- creating a variable will add it to your `thingProperties.h` file,
-- creating a variable with **read/write** permission will also add a callback function at the bottom of your sketch. This will trigger anytime the value changes.
-- changing your network credentials will update the `arduino_secrets.h` file.
+- Associating a Wi-Fi board will automatically update the connection method.
+- Creating a variable will add it to your `thingProperties.h` file.
+- Creating a variable with **read/write** permission will also add a callback function at the bottom of your sketch. This will trigger any time the value changes.
+- Changing your network credentials will update the `arduino_secrets.h` file.
 
-This is implemented so that the connection and synchronisation between the board and cloud is handled automatically, meaning you do not need to do any networking code when using the Arduino / C++ language.
+This is implemented so that the connection and synchronization between the board and cloud is handled automatically, meaning you do not need to do any networking code when using the Arduino / C++ language.
 
 ***Please note that if you are using an offline environment, [Arduino IDE](/software/ide-v2), changes will only be made in the cloud environment and will manually need to be adjusted. If you plan on using the offline IDE, you make use of the [sketch synchronisation](/software/ide-v2/tutorials/ide-v2-cloud-sketch-sync) feature that allows you to push/pull your cloud sketches from the offline IDE.***