Merge remote-tracking branch 'docs-private/main' into marqdevx/nicla-voice/launch

Author: marqdevx

.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

.github/workflows/sync-pull-request.yml

@@ -28,7 +28,7 @@ jobs:
       - name: Sync PR
         env:
           GITHUB_TOKEN: ${{ secrets.SYNC_GITHUB_CLI_TOKEN }}
-        run: gh pr create --title "$(gh pr view $GITHUB_REF_NAME --json title --jq .title)" --body "$(gh pr view $GITHUB_REF_NAME --json body --jq .body)"  --label "$(gh pr view $GITHUB_REF_NAME --json labels --jq .labels[].name)" --reviewer "$(gh pr view $GITHUB_REF_NAME --json reviewRequests --jq .reviewRequests[].login)" --label "arduino" --assignee "$(gh pr view $GITHUB_REF_NAME --json assignees --jq .assignees[].login)" --repo arduino/docs-content
+        run: gh pr create --repo arduino/docs-content --head sync/${GITHUB_REF_NAME} --title "$(gh pr view $GITHUB_REF_NAME --json title --jq .title)" --body "$(gh pr view $GITHUB_REF_NAME --json body --jq .body)"  --label "$(gh pr view $GITHUB_REF_NAME --json labels --jq .labels[].name)" --reviewer "$(gh pr view $GITHUB_REF_NAME --json reviewRequests --jq .reviewRequests[].login)" --label "arduino" --assignee "$(gh pr view $GITHUB_REF_NAME --json assignees --jq .assignees[].login)"
 
       - name: Close PR
         env:

.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",

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

@@ -59,8 +59,11 @@ The following boards connect to the Arduino IoT Cloud via Wi-Fi.
 - [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

@@ -131,6 +131,19 @@ This feature allows Arduino devices to communicate with each other by sharing va
 Using this feature you can link variables of the same data type between **two or more cloud-enabled devices**, and Arduino IoT Cloud will automatically ensure any change to their value is propagated among all linked boards.
 For example, one button could set three smart bulbs to the same color by just setting a variable on one device and reading it on the others. Or you could turn on a heater when temperature sensors in your room or outside in your weather station drop below a certain level.
 
+### Local Time
+
+To retrieve local time, use the `ArduinoCloud.getLocalTime()` method in your sketch. The value returned represents the current local time expressed as a Unix timestamp (i.e. seconds from the epoch), and it automatically takes your time zone settings and DST (Daylight Saving Time) into account. Time zone can be set in the Thing configuration page within the Arduino IoT Cloud platform.
+
+The returned timestamp can be displayed in a dashboard using a `CloudTime` variable and the [Time Picker widget](/arduino-cloud/getting-started/technical-reference#time-picker), or can be parsed with a third-party library such as [Time](https://www.arduino.cc/reference/en/libraries/time/) in case you want to show it on a display.
+
+```arduino
+myTimeVariable = ArduinoCloud.getLocalTime()
+```
+
+***Note that when using a board equipped with a hardware Real-Time Clock (RTC) the [Arduino_IoTCloud](https://github.com/arduino-libraries/ArduinoIoTCloud) library will use it automatically, thus communicating with the RTC from within your sketch or other libraries is not recommended. You can use the `getLocalTime()` and `getInternalTime()` methods provided by Arduino_IoTCloud instead.
+*** 
+
 ## Things
 
 In order to use your devices in IoT Cloud, you need to associate a Thing to each of them. A Thing is an abstract concept which holds the configuration of the variables and other settings, as well as the history of the data collected for the variables.
@@ -153,7 +166,7 @@ The steps below can be used as guidance when **setting up a Thing**:
 
 ## Variables
 
-***Visit the main article on [Cloud Variables](arduino-cloud/getting-started/cloud-variables) for a more detailed coverage.***
+***Visit the main article on [Cloud Variables](/arduino-cloud/getting-started/cloud-variables) for a more detailed coverage.***
 
 A thing can have one or more variables. A variable can be used for multiple purposes:
 
@@ -295,42 +308,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.
 
@@ -345,7 +405,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.

content/arduino-cloud/01.getting-started/02.technical-reference/iot-cloud-tech-ref.md

@@ -270,7 +270,7 @@ You can visit the [Activate an Arduino Pro Gateway with IoT Cloud](https://suppo
 ###  Migrate Existing Gateway
 
 
-If you had a gateway setup prior to the [A2A to TTS migration](linktoblogpost.com ), you will need to complete the following steps to use the Pro Gateway.
+If you had a gateway setup prior to the A2A to TTS migration, you will need to complete the following steps to use the Pro Gateway.
 
 To perform the Arduino Pro gateway migration: