Initial commit - Portenta Machine Control AO2 documentation update

TaddyHC · TaddyHC · commit 47d2cdc8b3dd · 2024-11-18T22:35:46.000-06:00
diff --git a/content/hardware/05.pro-solutions/solutions-and-kits/portenta-machine-control/datasheet/datasheet.md b/content/hardware/05.pro-solutions/solutions-and-kits/portenta-machine-control/datasheet/datasheet.md
@@ -41,6 +41,8 @@ Industry 4.0, system integrators
 - **4x Analog output channels**
   - DC Voltage output software configurable: 0-10V DC
   - Max 20mA per channel
+  - Analog Out Channel 2 with maximum period of ~1.3 ms (Recommended for high-frequency PWM signals)
+  - Analog Out Channels 0, 1, 3 with standard timers  
 - **12x Digital programmable channels**
   - Non-galvanic isolated 24V power input
   - 12x High-side switches with current limit and inductive load kick-back protection
@@ -191,6 +193,10 @@ The output signal is a DC whose amplitude is a function of the PWM duty cycle.
 
 The maximum output current is 20mA per channel.
 
+Analog Out Channel 2 (AO2) is connected to pin PG7 on the Portenta H7 and features an HRTIM (High-Resolution Timer) function. The HRTIM configuration includes a frequency of 200 MHz (tick time = 5 ns), a clock prescaler of 4, and a maximum period of 65533 ticks (1.31 ms). This results in a maximum period of ~1.3 ms, making AO2 suitable mainly for high-frequency PWM signals.
+
+For applications requiring periods longer than 1.3 ms, consider using Analog Out Channels 0, 1, or 3, which use standard timers.
+
 ### Temperature Measurements
 Three independent temperature measurement channels are available.
 
@@ -561,6 +567,7 @@ Hereby, Arduino S.r.l. declares that this product is in compliance with essentia
 
 | **Date**    | **Revision** | **Changes**                                                                                                                                                           |
 |-------------|:------------:|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| 19/11/2024  |      9       | Updated analog output channel details                                                                                                                                 |
 | 03/09/2024  |      8       | Cloud Editor updated from Web Editor                                                                                                                                  |
 | 06/02/2024  |      7       | MTBF information                                                                                                                                                      |
 | 08/05/2023  |      6       | RTD and thermocouples new information                                                                                                                                 |
diff --git a/content/hardware/05.pro-solutions/solutions-and-kits/portenta-machine-control/tech-specs.yml b/content/hardware/05.pro-solutions/solutions-and-kits/portenta-machine-control/tech-specs.yml
@@ -8,6 +8,8 @@ Input:
   Analog inputs: 3
 Output:
   Analog 0-10V: 4
+  Analog Out Channel 2: Maximum period ~1.3 ms (Recommended for high-frequency PWM signals)
+  Analog Out Channels 0, 1, 3: Standard timers  
 Other I/O:
   Programmable digital I/O (24V logic): 12
 Connectivity:
diff --git a/content/hardware/05.pro-solutions/solutions-and-kits/portenta-machine-control/tutorials/pmc-arduino-library/content.md b/content/hardware/05.pro-solutions/solutions-and-kits/portenta-machine-control/tutorials/pmc-arduino-library/content.md
@@ -169,6 +169,8 @@ In the new approach, the `begin()` function is explicitly called to initialize t
 
 This update enhances the user experience by making the code more intuitive and aligned with the familiar Arduino programming style.
 
+***When using the Analog Output channels, please consider following detail: The High-Resolution Timer (HRTIM) function on PG7 allows for high-frequency PWM signals with precise control over short periods. However, it is limited to a maximum period of __approximately 1.3 ms__. This constraint makes __Analog Out Channel 2__ optimal for high-frequency PWM applications but unsuitable for periods exceeding 1.3 ms. For longer periods, alternative __Analog Out channels (AO0, AO1, AO3)__ with standard timers are recommended. Please refer to the [Portenta Machine Control User Manual: Analog Outputs secion](https://docs.arduino.cc/tutorials/portenta-machine-control/user-manual/#analog-outputs) for more details.***
+
 ### Encoders
 
 The handling of encoders has been updated in the `Arduino_PortentaMachineControl` Library for a more streamlined and intuitive approach. One key new feature is the **removal of array object access**. In the previous library version, encoder objects were accessed using array notation (`[]`). The latest version has simplified this approach, enhancing code readability and reducing potential errors.
diff --git a/content/hardware/05.pro-solutions/solutions-and-kits/portenta-machine-control/tutorials/user-manual/content.md b/content/hardware/05.pro-solutions/solutions-and-kits/portenta-machine-control/tutorials/user-manual/content.md
@@ -372,6 +372,44 @@ The expected result of the generated sine wave measured with an oscilloscope in
 
 ![Generated sine wave using analog output channel AO0 of the Portenta Machine Control](assets/user-manual-11.png)
 
+### Working With Analog Output Channel 2 (AO2)
+
+**Analog output channel 2 (AO2)** of the Portenta Machine Control is connected to pin *PG7* on the Portenta H7, which features an **HRTIM (High-Resolution TIMer)** function. It is the only Analog Out pin on the Portenta Machine Control with an **HRTIM (High-Resolution Timer)** function.
+
+The *HRTIM* on *PG7* is mainly applicable for high-frequency PWM signals, which have constraints on the maximum period that can be achieved. With the availability of the *HRTIM_EEV2* function, which serves as an external event input, its configuration allows **AO2** to support high-resolution PWM signals with very short periods but also results in a constraint.
+
+The *HRTIM* is configured with a frequency of **200 MHz** (tick time = **5 ns**), a clock prescaler set to **4**, and a maximum period of **0xFFFD** ticks (**65533 * 5 ns * 4 = 1.31 ms**). This configuration results in a maximum allowed period of **1.31 ms** for *AO2*. 
+
+Knowing that the maximum allowable period for *AO2* is approximately **1.3 ms**, it makes it suitable only for high-frequency PWM signals. For applications requiring periods longer than *1.3 ms*, we recommend using other analog output channels, such as **Analog output channel 0 (AO0)**, **1 (AO1)**, or **3 (AO3)**, which can use standard timers. Please consider this characteristic when selecting the appropriate output channel for the development application.
+
+The following code shows the setup of the *Analog Out* channels, including *AO2*. Please be aware that attempting to set a period longer than *1.3 ms* for *AO2* is not recommended.
+
+```cpp
+#include <Arduino_PortentaMachineControl.h>
+
+#define PERIOD_MS_AO2 1   /* 1 ms for AO2 */
+#define PERIOD_MS 4       /* 4 ms - 250Hz for other channels */
+
+void setup() {
+  Serial.begin(9600);
+
+  MachineControl_AnalogOut.begin();
+
+  MachineControl_AnalogOut.setPeriod(0, PERIOD_MS);
+  MachineControl_AnalogOut.setPeriod(1, PERIOD_MS);
+  MachineControl_AnalogOut.setPeriod(2, PERIOD_MS_AO2);  // AO2 - Adjusted period to fit limitation
+  MachineControl_AnalogOut.setPeriod(3, PERIOD_MS);
+
+  MachineControl_AnalogOut.write(0, 5);
+  MachineControl_AnalogOut.write(1, 5);
+  MachineControl_AnalogOut.write(2, 5);
+  MachineControl_AnalogOut.write(3, 5);
+}
+
+void loop() {
+}
+```
+
 ## Digital Inputs
 
 The Portenta Machine Control has up to eight digital input channels, as shown in the image below. Each channel incorporates a voltage divider comprising a 680 kΩ and a 100 kΩ resistor, which scales an input from 0 to 24 VDC down to 0 to 3 VDC.
