Merge branch 'main' into kateryna-lukina/certification-updates

Author: kateryna-lukina

.github/workflows/deploy-prd.yml

@@ -22,6 +22,17 @@ jobs:
           cache: "npm"
           cache-dependency-path: "**/package-lock.json"
 
+      - name: Render Datasheets
+        run: cd ${GITHUB_WORKSPACE}/scripts/datasheet-rendering;./render-datasheets.sh
+
+      - name: Copy Static Files
+        run: | 
+          mkdir -p static/resources/datasheets static/resources/schematics static/resources/pinouts
+          find ./content/hardware -type f -name "*-schematics.pdf" -exec cp {} ./static/resources/schematics/ \;
+          find ./content/hardware -type f -name "*-datasheet.pdf" -exec cp {} ./static/resources/datasheets/ \;
+          find ./content/hardware -type f -name "*-full-pinout.pdf" -exec cp {} ./static/resources/pinouts/ \;
+          find ./content/hardware -type f -name "*-pinout.png" -exec cp {} ./static/resources/pinouts/ \;
+
       - name: Gatsby main cache
         uses: actions/cache@v2
         id: gatsby-cache-folder
@@ -41,8 +52,7 @@ jobs:
             ${{ runner.os }}-public-gatsby-
 
       - run: npm install
-
-      - run: GENERATE_DATASHEETS=true npm run build
+      - run: npm run build
 
       - name: Configure AWS Credentials
         uses: aws-actions/configure-aws-credentials@v1

.github/workflows/deploy-stg.yml

@@ -20,6 +20,17 @@ jobs:
           node-version: 14
           cache: "npm"
           cache-dependency-path: "**/package-lock.json"
+      
+      - name: Render Datasheets
+        run: cd ${GITHUB_WORKSPACE}/scripts/datasheet-rendering;./render-datasheets.sh
+
+      - name: Copy Static Files
+        run: | 
+          mkdir -p static/resources/datasheets static/resources/schematics static/resources/pinouts
+          find ./content/hardware -type f -name "*-schematics.pdf" -exec cp {} ./static/resources/schematics/ \;
+          find ./content/hardware -type f -name "*-datasheet.pdf" -exec cp {} ./static/resources/datasheets/ \;
+          find ./content/hardware -type f -name "*-full-pinout.pdf" -exec cp {} ./static/resources/pinouts/ \;
+          find ./content/hardware -type f -name "*-pinout.png" -exec cp {} ./static/resources/pinouts/ \;
 
       - name: Gatsby main cache
         uses: actions/cache@v2
@@ -40,8 +51,7 @@ jobs:
             ${{ runner.os }}-public-gatsby-
 
       - run: npm install
-
-      - run: GENERATE_DATASHEETS=true npm run build
+      - run: npm run build
 
       - name: Configure AWS Credentials
         uses: aws-actions/configure-aws-credentials@v1

.github/workflows/render-datasheets.yaml

@@ -0,0 +1,23 @@
+name: Render datasheets
+
+on:
+  workflow_dispatch:
+
+jobs:
+  render-datasheets:
+    runs-on: ubuntu-latest
+    env:
+      REPO_ACCESS_TOKEN: ${{ secrets.REPO_ACCESS_TOKEN }}
+
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v2
+        with:
+          node-version: 14
+          cache: "npm"
+          cache-dependency-path: "**/package-lock.json"
+
+      - name: Render
+        run: |
+         cd scripts/datasheet-rendering
+         ./render-datasheets.sh

.gitignore

@@ -6,4 +6,5 @@ gatsby-*
 node_modules
 public
 src
-.DS_Store
+.DS_Store
+.vscode/settings.json

.vscode/tasks.json

@@ -87,7 +87,7 @@
                 "cwd": "${workspaceFolder}${pathSeparator}scripts${pathSeparator}validation"
             },
             "windows": {
-                "command": "node .\\fix-issues.js -p ..\\..\\content\\hardware\\"               
+                "command": "node .\\fix-issues.js -p '..\\..\\content\\hardware\\'"
             },
             "group": "none",
             "presentation": {
@@ -97,14 +97,14 @@
             "problemMatcher": []
         },
         {
-            "label": "Generate all datasheets",
+            "label": "Render all datasheets",
             "type": "shell",
-            "command": "./generate-datasheets.sh",
+            "command": "./render-datasheets.sh",
             "options": {
-                "cwd": "${workspaceFolder}${pathSeparator}scripts${pathSeparator}datasheet-generator"
+                "cwd": "${workspaceFolder}${pathSeparator}scripts${pathSeparator}datasheet-rendering"
             },
             "windows": {
-                "command": ".\\generate-datasheets.cmd"                
+                "command": ".\\render-datasheets.cmd"                
             },
             "group": "none",
             "presentation": {
@@ -114,14 +114,14 @@
             "problemMatcher": []
         },
         {
-            "label": "Generate datasheet (current document)",
+            "label": "Render datasheet (current document)",
             "type": "shell",
-            "command": "./generate-datasheets.sh '../../${relativeFileDirname}'",
+            "command": "./render-datasheets.sh '../../${relativeFileDirname}'",
             "options": {
-                "cwd": "${workspaceFolder}${pathSeparator}scripts${pathSeparator}datasheet-generator"
+                "cwd": "${workspaceFolder}${pathSeparator}scripts${pathSeparator}datasheet-rendering"
             },
             "windows": {
-                "command": ".\\generate-datasheets.cmd '..\\..\\${relativeFileDirname}'"                
+                "command": ".\\render-datasheets.cmd '..\\..\\${relativeFileDirname}'"                
             },
             "group": "none",
             "presentation": {
@@ -138,7 +138,7 @@
                 "cwd": "${workspaceFolder}"
             },
             "windows": {
-                "command": ".\\scripts\\spell-check.cmd"                
+                "command": ".\\scripts\\spell-check.cmd"
             },
             "group": "none",
             "presentation": {
@@ -163,6 +163,9 @@
             "options": {
                 "cwd": "${workspaceFolder}"
             },
+            "windows": {
+                "command": ".\\scripts\\spell-check-fix.cmd"
+            },
             "group": "none",
             "presentation": {
                 "reveal": "always",

CONTRIBUTING.md

@@ -4,9 +4,9 @@ The docs.arduino.cc website is built from the Markdown sources hosted in this re
 
 ## How to Contribute
 
-In order to contribute new or updated documentation, you must first create a GitHub account and fork the original repository to your own account. You can make changes, save them in your repository, then [make a pull request](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) against this repository. The pull request will appear [in the repository](https://github.com/arduino/docs.arduino.cc/pulls) where it can be assessed by the maintainers, copy edited, and if appropriate, merged.
+In order to contribute new or updated documentation, you must first create a GitHub account and fork the original repository to your own account. You can make changes, save them in your repository, then [make a pull request](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) against this repository. The pull request will appear [in the repository](https://github.com/arduino/docs-content/pulls) where it can be assessed by the maintainers, copy edited, and if appropriate, merged.
 
-**NOTE:** Unless you are opening a pull request which will only make small corrections, for instance to correct a typo, you are more likely to get traction for your changes if you [open an issue](https://github.com/arduino/docs.arduino.cc/issues) first to discuss the proposed changes.
+**NOTE:** Unless you are opening a pull request which will only make small corrections, for instance to correct a typo, you are more likely to get traction for your changes if you [open an issue](https://github.com/arduino/docs-content/issues) first to discuss the proposed changes.
 
 ## Type of Content
 

README.md

@@ -83,7 +83,9 @@ symbolic link created for AnalogInput <<===>> ..\..\..\..\..\built-in-examples\0
 ### Including Code Snippets
 
 Code snippets can be included by using the triple backticks syntax e.g. ` ```arduino` followed by the code and three closing backticks. The following syntaxes are supported:
+```
 arduino, bash, markup, clike, c, cpp, css, css-extras, javascript, jsx, js-extras, coffeescript, diff, git, go, graphql, handlebars, json, less, makefile, markdown, objectivec, ocaml, python, reason, sass, scss, sql, stylus, tsx, typescript, wasm, yaml
+```
 
 
 ## Previewing Changes

content/arduino-cloud/01.getting-started/01.iot-cloud-getting-started/assets/ethernet.png

@@ -53,14 +53,17 @@ To use the Arduino IoT Cloud, a **cloud compatible board** is required. You can
 
 The following boards connect to the Arduino IoT Cloud via Wi-Fi.
 
-- [MKR 1000 WiFi](https://store.arduino.cc/arduino-mkr1000-wifi)
+- [MKR 1000 WiFi](/hardware/mkr-1000-wifi)
 - [MKR WiFi 1010](https://store.arduino.cc/arduino-mkr-wifi-1010)
 - [Nano RP2040 Connect](https://store.arduino.cc/nano-rp2040-connect)
 - [Nano 33 IoT](https://store.arduino.cc/arduino-nano-33-iot)
 - [Portenta H7](https://store.arduino.cc/portenta-h7)
 - [Portenta H7 Lite Connected](https://store.arduino.cc/products/portenta-h7-lite-connected)
+- [Portenta Machine Control](https://store.arduino.cc/products/arduino-portenta-machine-control)
 - [Nicla Vision](https://store.arduino.cc/products/nicla-vision)
+- [Opta](https://docs.arduino.cc/hardware/opta).\* 
 
+\* The Opta is scheduled to be released soon, along with documentation how to use it. Read more at the [Opta communications page](https://store.arduino.cc/pages/opta).
 
 Connection via Wi-Fi is an easy alternative, and your credentials can safely be entered during the configuration of a project. This type of connection is most suitable for low-range projects, where you connect your board to the cloud via your home/work/school router.
 
@@ -96,6 +99,24 @@ The Arduino IoT Cloud supports a wide range of third party boards based on the E
 
 ***To learn more about ESP32/ESP8266 support and how to set it up, visit the [Connecting ESP32 & ESP8266 to Arduino Cloud IoT](/cloud/iot-cloud/tutorials/esp-32-cloud) guide.***
 
+### Ethernet
+
+The Arduino IoT Cloud supports connection via Ethernet on a number of devices. The options to connect via Ethernet are the following:
+- Connect with the [Portenta H7](https://store.arduino.cc/products/portenta-h7) in combination with an Ethernet compatible carrier/shield (see below).
+- Connect with the [Opta](https://docs.arduino.cc/hardware/opta).\* 
+
+\* The Opta is scheduled to be released soon, along with documentation how to use it. Read more at the [Opta communications page](https://store.arduino.cc/pages/opta).
+
+To connect with the **Portenta H7** board, you will need one of the following shields/carriers:
+- [Portenta Vision Shield Ethernet](https://store.arduino.cc/products/arduino-portenta-vision-shield-ethernet)
+- [Portenta Machine Control](https://store.arduino.cc/portenta-machine-control)
+
+To enable communication via Ethernet with the Portenta H7, while configuring your device, you need to select the "Ethernet" option. If your device is already configured as a Wi-Fi device, you need to remove it before configuring it to Ethernet communication.
+
+![Choose the Ethernet option.](assets/ethernet.png)
+
+***Please note that older hardware such as the [Ethernet Shield Rev2](https://store.arduino.cc/products/arduino-ethernet-shield-2) and [MKR ETH Shield](https://store.arduino.cc/products/arduino-mkr-eth-shield) are currently not supported by the Arduino IoT Cloud.***
+
 ## Support
 
 If you have any problems with the Arduino IoT Cloud, you can browse through common troubleshooting issues and find information on different features in the **Arduino Help Center**. If you don’t find the answer you are looking for, we are always happy to help you with any question regarding our products!

content/arduino-cloud/01.getting-started/01.iot-cloud-getting-started/iot-cloud-getting-started.md

@@ -107,16 +107,30 @@ A shortcut to add a device is also provided in **"Things" page** as explained in
 
 Below you will find a list of features that are available in the Arduino IoT Cloud.
 
-### Uploading over-the-air (OTA)
+### Uploading Over-The-Air (OTA)
 
-This feature allows for uploading sketches wirelessly to Arduino boards, without the need to connect the board physically. This feature is supported for the following **compatible Arduino boards**:
-
-![Over The Air compatible boards](./images/ota_compatible_boards.png)
+This feature allows for uploading sketches wirelessly to Arduino boards, without the need to connect the board physically. This feature is supported for the following boards:
 
 - [Arduino MKR WiFi 1010](https://store.arduino.cc/arduino-mkr-wifi-1010)
 - [Arduino NANO 33 IoT](https://store.arduino.cc/arduino-nano-33-iot)
 - [Arduino Nano RP2040 Connect](https://store.arduino.cc/products/arduino-nano-rp2040-connect-with-headers)
 - [Portenta H7](https://store.arduino.cc/products/portenta-h7)
+- Cloud compatible ESP32 boards (see list below).
+
+#### Verified ESP32 Boards Supporting OTA 
+
+The following ESP32 boards have been tested and verified to support OTA:
+
+- ESP32-S2-DevKitC
+- NODEMCU-32-S2
+- WEMOS LOLIN D32
+- ESP32-S3-DevKitC
+- WEMOS LOLIN D32
+- ESP32-CAM
+- NodeMCU-32S
+- Freenove ESP32 WROVER
+- ESP32-DevKitC32E
+- DOIT ESP32 DevKit v1
 
 ![Connecting the device with the OTA option](./images/device_OtA.png)
 
@@ -308,42 +322,89 @@ One or more **Things** can be added to a **Dashboard**, with all or some of thei
 
 ![Create widgets from a Thing](./images/create-widget-from-thing.png)
 
-***You can read more about [Dashboards & Widgets]().***
+***You can read more about [Dashboards & Widgets](/arduino-cloud/getting-started/dashboard-widgets).***
 
 ## Recommended Code Practices
 
-### Avoid blocking commands within the loop()
+This section highlights some important aspects of writing code with regard to the implementations in the [ArduinoIoTCloud](https://github.com/arduino-libraries/ArduinoIoTCloud).
+
+### Watchdog Timer (WDT)
+
+All IoT Cloud sketches use a **Watchdog Timer (WDT)** by default. The WDT can be used to automatically recover from hardware faults or unrecoverable software errors.
+
+A WDT is essentially a countdown timer, whereas it starts counting from a set value, and upon reaching zero, it resets the board. To prevent it from reaching zero, we continuously call it from the `loop()`, using the `ArduinoCloud.update()` function.
+
+This is why, it is very important to not use any long blocking code in your sketch. For example, using a long `delay()` inside the `loop()` is **strongly discouraged**, as the WDT can reach zero and reset the board.
+
+The WDT can however be disabled inside of the `setup()` function, by adding the `false` parameter:
+
+```arduino
+ArduinoCloud.begin(ArduinoIoTPreferredConnection, false).
+```
+
+***You can view the source code of this implementation [here](https://github.com/arduino-libraries/ArduinoIoTCloud/tree/master/src/utility/watchdog).***
+
+### 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.
 
 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:
 
-    void loop() {
-      ArduinoCloud.update();
-  
-      digitalWrite(LED_BUILTIN, HIGH);
-      delay(1000);
-      digitalWrite(LED_BUILTIN, LOW);
-      delay(1000);
-    }
+```arduino
+void loop() {
+  ArduinoCloud.update();
+
+  digitalWrite(LED_BUILTIN, HIGH);
+  delay(1000);
+  digitalWrite(LED_BUILTIN, LOW);
+  delay(1000);
+}
+```
 
 This works, but it will cause a delay of at least two seconds between one execution of `ArduinoCloud.update()` and the next one, thus causing bad performance of the cloud communication.
 
 This can be rewritten in a non-blocking way as follows:
 
-    void loop() {
-      ArduinoCloud.update();
-  
-      digitalWrite(LED_PIN, (millis() % 2000) < 1000);
-    }
+```arduino
+void loop() {
+  ArduinoCloud.update();
+
+  digitalWrite(LED_PIN, (millis() % 2000) < 1000);
+}
+```
 
 How does this work? It gets the current execution time provided by `millis()` and divides it by 2 seconds. If the remainder is smaller than one second it will turn the LED on, and if it's greater it will turn the LED off.
 
 For a more complex and commented example, you can have a look at the [BlinkWithoutDelay example](/built-in-examples/digital/BlinkWithoutDelay).
 
-### Avoid waiting for Serial Monitor to initialize connection
+### 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.
+
+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:
+
+```arduino
+void setup() {
+  Serial.begin(9600);
+  delay(1500);
+
+  initProperties();
+
+  ArduinoCloud.begin(ArduinoIoTPreferredConnection);
+  setDebugMessageLevel(2);
+  ArduinoCloud.printDebugInfo();
+
+  //initializing the Arduino_MKRENV library
+  if (!ENV.begin()) {
+    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.
 
@@ -358,7 +419,7 @@ We provide two Arduino Iot Cloud APIs:
 
  The Arduino IoT Cloud REST API can be called just with any **HTTP Client**, or using one of these clients:
   - [Javascript NPM package](https://www.npmjs.com/package/@arduino/arduino-iot-client).
-  - [Python PYPI Package](https://pypi.org/project/arduino-iot-client/).
+  - [Python® PYPI Package](https://pypi.org/project/arduino-iot-client/).
   - [Golang Module](https://github.com/arduino/iot-client-go).
 
 **2.** The second is the **Data API (MQTT)** which allows you to send/receive Variables' data. An example of this API's use is sending IoT Cloud Variables' updates to the browser. A full [documentation of the Arduino IoT Cloud Data API (MQTT)](https://www.npmjs.com/package/arduino-iot-js) is available for advanced users.