diff --git a/README.md b/README.md index 8ea3e47c2f..e1e8da961e 100644 --- a/README.md +++ b/README.md @@ -87,6 +87,15 @@ Code snippets can be included by using the triple backticks syntax e.g. ` ```ard 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 ``` +### Including Code Blocks fetching Github pages + +CodeBlocks are custom components that can be added directly in the Markdown on docs-content. +Using this component, the code block will be fetched directly from Github pages. + +Syntax: +` ` + +Broken URL will show error alert. URL must be in Github domain and must be public. ## Previewing Changes diff --git a/content/hardware/04.pro/boards/portenta-c33/datasheets/assets/Portenta_C33_Bottom_View_Connectors.png b/content/hardware/04.pro/boards/portenta-c33/datasheets/assets/Portenta_C33_Bottom_View_Connectors.png deleted file mode 100644 index c5c6191c6f..0000000000 Binary files a/content/hardware/04.pro/boards/portenta-c33/datasheets/assets/Portenta_C33_Bottom_View_Connectors.png and /dev/null differ diff --git a/content/hardware/04.pro/boards/portenta-c33/datasheets/assets/Portenta_C33_Mechanical_1.png b/content/hardware/04.pro/boards/portenta-c33/datasheets/assets/Portenta_C33_Mechanical_1.png new file mode 100644 index 0000000000..02bf465d4a Binary files /dev/null and b/content/hardware/04.pro/boards/portenta-c33/datasheets/assets/Portenta_C33_Mechanical_1.png differ diff --git a/content/hardware/04.pro/boards/portenta-c33/datasheets/assets/Portenta_C33_Mechanical_2.png b/content/hardware/04.pro/boards/portenta-c33/datasheets/assets/Portenta_C33_Mechanical_2.png new file mode 100644 index 0000000000..2536001985 Binary files /dev/null and b/content/hardware/04.pro/boards/portenta-c33/datasheets/assets/Portenta_C33_Mechanical_2.png differ diff --git a/content/hardware/04.pro/boards/portenta-c33/datasheets/assets/Portenta_C33_Pinout_HDC.png b/content/hardware/04.pro/boards/portenta-c33/datasheets/assets/Portenta_C33_Pinout_HDC.png new file mode 100644 index 0000000000..606a951493 Binary files /dev/null and b/content/hardware/04.pro/boards/portenta-c33/datasheets/assets/Portenta_C33_Pinout_HDC.png differ diff --git a/content/hardware/04.pro/boards/portenta-c33/datasheets/assets/Portenta_C33_Pinout_MKR.png b/content/hardware/04.pro/boards/portenta-c33/datasheets/assets/Portenta_C33_Pinout_MKR.png new file mode 100644 index 0000000000..bf29e9052b Binary files /dev/null and b/content/hardware/04.pro/boards/portenta-c33/datasheets/assets/Portenta_C33_Pinout_MKR.png differ diff --git a/content/hardware/04.pro/boards/portenta-c33/datasheets/assets/Portenta_C33_Power_Tree.svg b/content/hardware/04.pro/boards/portenta-c33/datasheets/assets/Portenta_C33_Power_Tree.svg new file mode 100644 index 0000000000..c335c11d4f --- /dev/null +++ b/content/hardware/04.pro/boards/portenta-c33/datasheets/assets/Portenta_C33_Power_Tree.svg @@ -0,0 +1,186 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/content/hardware/04.pro/boards/portenta-c33/datasheets/assets/Portenta_C33_Top_View_Connectors.png b/content/hardware/04.pro/boards/portenta-c33/datasheets/assets/Portenta_C33_Top_View_Connectors.png deleted file mode 100644 index d0163c483a..0000000000 Binary files a/content/hardware/04.pro/boards/portenta-c33/datasheets/assets/Portenta_C33_Top_View_Connectors.png and /dev/null differ diff --git a/content/hardware/04.pro/boards/portenta-c33/datasheets/assets/Portenta_C33_Top_View_Dimensions.png b/content/hardware/04.pro/boards/portenta-c33/datasheets/assets/Portenta_C33_Top_View_Dimensions.png deleted file mode 100644 index 1b1f0a2583..0000000000 Binary files a/content/hardware/04.pro/boards/portenta-c33/datasheets/assets/Portenta_C33_Top_View_Dimensions.png and /dev/null differ diff --git a/content/hardware/04.pro/boards/portenta-c33/datasheets/datasheet.md b/content/hardware/04.pro/boards/portenta-c33/datasheets/datasheet.md index b1e1a65148..153b6de7f4 100644 --- a/content/hardware/04.pro/boards/portenta-c33/datasheets/datasheet.md +++ b/content/hardware/04.pro/boards/portenta-c33/datasheets/datasheet.md @@ -2,6 +2,7 @@ identifier: ABX00074 title: Arduino® Portenta C33 type: pro +author: José Bagur --- ![](assets/Portenta_C33_Top_View.png) @@ -25,6 +26,7 @@ Thanks to its high-performance processor, the Portenta C33 supports many applica - **Machine monitoring to track OEE/OPE:** Track Overall Equipment Efficiency (OEE) and Overall Process Effectiveness (OPE) with the Portenta C33 as an IoT node. Collect data and get alerted on machine uptime and unplanned downtime to provide reactive maintenance and improve production rate. - **Inline Quality Assurance:** Leverage full compatibility between Portenta C33 and Nicla family to carry out quality control in your production lines. Collect Nicla smart sensing data with the Portenta C33 to catch defects early and resolve them before they travel down the line. - **Prototyping:** The Portenta C33 can assist Portenta and MKR developers with their IoT prototypes by integrating ready-to-use Wi-Fi®/Bluetooth® connectivity and various peripheral interfaces, including CAN, SAI, SPI, and I2C. Moreover, the Portenta C33 can be promptly programmed with high-level languages like MicroPython, allowing for rapid prototyping of IoT applications. + - **Building Automation:** The Portenta C33 can be used in multiple building automation applications: - **Energy Consumption Monitoring:** Collect and monitor consumption data from all services (e.g., gas, water, electricity) in a single system. Display usage trends in Arduino IoT Cloud charts, providing an overall image for energy management optimization and cost reduction. - **Appliances Control System**: Leverage high-performing Portenta C33 microcontroller to control in real-time your appliances. Adjust HVAC heating or improve the efficiency of your ventilation system, control the motors of your curtains, and switch on/off lights. The onboard Wi-Fi® connectivity easily allows Cloud integration, so that everything is under control even from the remote. @@ -294,11 +296,20 @@ The Portenta C33 is a powerful microcontroller board designed for low-cost IoT a ### Related Products -- ESLOV connector - Arduino® Portenta H7 (SKU: ABX00042) - Arduino® Portenta H7 Lite (SKU: ABX00045) - Arduino® Portenta H7 Lite Connected (SKU: ABX00046) - Arduino® Nicla Sense ME (SKU: ABX00050) +- Arduino® Nicla Vision (SKU: ABX00051) +- Arduino® Nicla Voice (SKU: ABX00061) +- Arduino® Portenta Max Carrier (SKU: ABX00043) +- Arduino® Portenta CAT.M1/NB IoT GNSS Shield (SKU: ABX00043) +- Arduino® Portenta Vision Shield - Ethernet (SKU: ABX00021) +- Arduino® Portenta Vision Shield - LoRa® (SKU: ABX00026) +- Arduino® Portenta Breakout (SKU: ABX00031) +- Arduino® boards with an onboard ESLOV connector + +**Note**: The Portenta Vision Shields (Ethernet and LoRa® variants) are compatible with the Portenta C33 except for the camera, which is not supported by the Portenta C33 microcontroller. ## Ratings @@ -320,31 +331,98 @@ Table 7 provides a comprehensive guideline for the optimal use of the Portenta C **Table 7: Recommended Operating Conditions** -
+### Current Consumption + +

+Table 8 summarizes the power consumption of the Portenta C33 on different test cases. Notice that the operating current of the board will depend greatly on the application. +

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterSymbolMinTypMaxUnit
Deep Sleep Mode Current Consumption1IDS-86-µA
Normal Mode Current Consumption2INM-180-mA
+ +**Table 8: Board Current Consumption** + +
+ +1 All peripherals off, wake-up on RTC interrupt.\ +2 All peripherals on, continuous data download via Wi-Fi®. + +
-## Hardware +## Functional Overview

The core of the Portenta C33 is the R7FA6M5BH2CBG microcontroller from Renesas. The board also contains several peripherals connected to its microcontroller.

+### Pinout + +The MKR-styled connectors pinout is shown in Figure 1. + +**![Figure 1. Portenta C33 pinout (MKR-styled connectors)](assets/Portenta_C33_Pinout_MKR.png)** + +
+ +The High-Density connectors pinout is shown in Figure 2. + +**![Figure 2. Portenta C33 pinout (High-Density connectors)](assets/Portenta_C33_Pinout_HDC.png)** + +
+ ### Block Diagram -An overview of the Portenta C33 high-level architecture is illustrated in Figure 1. +An overview of the Portenta C33 high-level architecture is illustrated in Figure 3. + +**![Figure 3. High-level architecture of the Portenta C33](assets/Portenta_C33_Block_Diagram.svg)** -**![Figure 1. High-level architecture of the Portenta C33](assets/Portenta_C33_Block_Diagram.svg)** + +
### Power Supply +
+ The Portenta C33 can be powered through one of these interfaces: - USB-C® port -- 3.7V single-cell lithium-ion/lithium-polymer battery, connected through the onboard battery connector -- External 5V power supply connected through the MKR-styled pins +- 3.7 V single-cell lithium-ion/lithium-polymer battery, connected through the onboard battery connector +- External 5 V power supply connected through the MKR-styled pins -

-The recommended minimum battery capacity is 700 mAh. The battery is connected to the board via a disconnectable crimp-style connector as shown in Figure 4. The battery connector part number is BM03B-ACHSS-GAN-TF(LF)(SN). -

+The recommended minimum battery capacity is 700 mAh. The battery is connected to the board via a disconnectable crimp-style connector as shown in Figure 3. The battery connector part number is BM03B-ACHSS-GAN-TF(LF)(SN). + +Figure 4 shows the power options available on the Portenta C33 and illustrates the main system power architecture. +
+ +**![Figure 4. Power architecture of the Portenta C33](assets/Portenta_C33_Power_Tree.svg)** ## Device Operation @@ -380,25 +458,26 @@ The Portenta C33 is a double-sided 66.04 mm x 25.40 mm board with a USB-C® port castellated/through-hole pins around the two long edges and two High-Density connectors on the bottom side of the board. The onboard wireless antenna connector is located on the bottom edge of the board.

-

-The Portenta C33 is designed to be usable as a surface-mount module as well as presenting a dual inline package (DIP) format with the MKR-styled connectors on a 2.54 mm pitch grid with 1 mm holes. The Portenta C33 also has four 1.12 mm drilled mounting holes to provide for mechanical fixing. -

- -
- ### Board Dimensions -Portenta C33 board main dimensions can be seen in Figure 2. +Portenta C33 board outline and mounting holes dimensions can be seen in Figure 5. -**![Figure 2. Portenta C33 dimensions (top view on the left and bottom view on the right)](assets/Portenta_C33_Top_View_Dimensions.png)** +**![Figure 5. Portenta C33 board outline (left) and mounting holes dimensions (right)](assets/Portenta_C33_Mechanical_1.png)** + +The Portenta C33 has four 1.12 mm drilled mounting holes to provide for mechanical fixing. ### Board Connectors -Connectors of the Portenta C33 are placed on the top and bottom side of the board, their placement can be seen in Figures 3 and 4. +Connectors of the Portenta C33 are placed on the top and bottom side of the board, their placement can be seen in Figure 6. + +**![Figure 6. Portenta C33 connectors placement (top view left, bottom view right)](assets/Portenta_C33_Mechanical_2.png)** + -**![Figure 3. Portenta C33 connectors placement (top view)](assets/Portenta_C33_Top_View_Connectors.png)** +

+The Portenta C33 is designed to be usable as a surface-mount module as well as presenting a dual inline package (DIP) format with the MKR-styled connectors on a 2.54 mm pitch grid with 1 mm holes. +

-**![Figure 4. Portenta C33 connectors placement (bottom view)](assets/Portenta_C33_Bottom_View_Connectors.png)** +
## Certifications @@ -415,8 +494,6 @@ Connectors of the Portenta C33 are placed on the top and bottom side of the boar | RoHS | Yes | | REACH | Yes | | WEEE | Yes | -| SRRC (China) | Yes | -| CCC (China) | Yes | ### Declaration of Conformity CE DoC (EU) @@ -513,6 +590,8 @@ Hereby, Arduino S.r.l. declares that this product is in compliance with essentia ## Document Revision History -| **Date** | **Revision** | **Changes** | -|:----------:|:------------:|:-------------:| -| 14/03/2023 | 1 | First release | +| **Date** | **Revision** | **Changes** | +|:----------:|:------------:|:------------------------------------------------------:| +| 20/06/2023 | 3 | Power tree added, related products information updated | +| 09/06/2023 | 2 | Board's power consumption information added | +| 14/03/2023 | 1 | First release | diff --git a/content/hardware/04.pro/boards/portenta-c33/downloads/ABX00074-full-pinout.pdf b/content/hardware/04.pro/boards/portenta-c33/downloads/ABX00074-full-pinout.pdf new file mode 100644 index 0000000000..4bd4d48c3f Binary files /dev/null and b/content/hardware/04.pro/boards/portenta-c33/downloads/ABX00074-full-pinout.pdf differ diff --git a/content/hardware/04.pro/boards/portenta-c33/downloads/ABX00074-schematics.pdf b/content/hardware/04.pro/boards/portenta-c33/downloads/ABX00074-schematics.pdf new file mode 100644 index 0000000000..c44325f11c Binary files /dev/null and b/content/hardware/04.pro/boards/portenta-c33/downloads/ABX00074-schematics.pdf differ diff --git a/content/hardware/04.pro/boards/portenta-c33/downloads/ABX00074-step.zip b/content/hardware/04.pro/boards/portenta-c33/downloads/ABX00074-step.zip new file mode 100644 index 0000000000..26c8e447b5 Binary files /dev/null and b/content/hardware/04.pro/boards/portenta-c33/downloads/ABX00074-step.zip differ diff --git a/content/hardware/04.pro/boards/portenta-c33/essentials.md b/content/hardware/04.pro/boards/portenta-c33/essentials.md index e333c3a9d8..fe911981cf 100644 --- a/content/hardware/04.pro/boards/portenta-c33/essentials.md +++ b/content/hardware/04.pro/boards/portenta-c33/essentials.md @@ -7,7 +7,8 @@ - The Wi-Fi® library is designed to use the ESP32-C3-MINI-1U module, which allows your Arduino to connect to the Internet. + The Wi-Fi® library is designed to use the ESP32-C3-MINI-1U module, which allows your Arduino to connect to the Internet. + Bluetooth® 4.0 includes both traditional Bluetooth®, now labeled " Bluetooth® Classic", and Bluetooth® Low Energy. diff --git a/content/hardware/04.pro/boards/portenta-c33/features.md b/content/hardware/04.pro/boards/portenta-c33/features.md index fe511f135d..b378265e88 100644 --- a/content/hardware/04.pro/boards/portenta-c33/features.md +++ b/content/hardware/04.pro/boards/portenta-c33/features.md @@ -15,7 +15,7 @@ The board also supports MicroPython and other high-level programming languages, - The Portenta C33 main microcontroller is the Arm® Cortex®-M33, a 32-bit processor that offers efficient performance, low power consumption, and advanced security features, making it an ideal choice for a wide range of embedded systems applications. + The R7FA6M5BH2CBG microcontroller of the Portenta C33 uses the Arm® Cortex®-M33, a 32-bit processor that offers efficient performance, low power consumption, and advanced security features, making it an ideal choice for a wide range of embedded systems applications. @@ -42,7 +42,7 @@ The board also supports MicroPython and other high-level programming languages, - The Portenta C33 was designed with low power consumption in mind, making it well-suited for battery-powered IoT devices that require long battery life. Its microcontroller is designed for efficient power usage, allowing it to perform real-time processing tasks while consuming minimal energy. + The Portenta C33 was designed with low power consumption in mind, making it well qualified for battery-powered IoT devices that require long battery life. Its microcontroller is designed for efficient power usage, allowing it to perform real-time processing tasks while consuming minimal energy. diff --git a/content/hardware/04.pro/boards/portenta-c33/interactive/ABX00074-pinout.png b/content/hardware/04.pro/boards/portenta-c33/interactive/ABX00074-pinout.png new file mode 100644 index 0000000000..eb64362961 Binary files /dev/null and b/content/hardware/04.pro/boards/portenta-c33/interactive/ABX00074-pinout.png differ diff --git a/content/hardware/04.pro/boards/portenta-c33/tech-specs.yml b/content/hardware/04.pro/boards/portenta-c33/tech-specs.yml index a487af0e38..6d0453a7f4 100644 --- a/content/hardware/04.pro/boards/portenta-c33/tech-specs.yml +++ b/content/hardware/04.pro/boards/portenta-c33/tech-specs.yml @@ -6,31 +6,34 @@ USB connector: USB-C® High-Density Pins: Digital I/O pins: 78 Analog input pins: 8 - ADC resolution: 12 bits PWM pins: 10 - DAC resolution: 12 bits SPI pins: 8 I2C pins: 6 UART pins: 16 CAN pins: 4 I2S pins: 4 - USB2: 3 + USB pins: 8 + JTAG/SWD pins: 6 MKR-styled Pins: Digital I/O pins: 22 Analog input pins: 7 - ADC resolution: 12 bits PWM pins: 7 - DAC resolution: 12 bits SPI pins: 4 I2C pins: 2 UART pins: 2 Wireless connectivity: Chipset: ESP32-C3-MINI-1U - Wi-Fi®: 2.4GHz Wi-Fi® (802.11 b/g/n) + Wi-Fi®: 2.4 GHz Wi-Fi® (802.11 b/g/n) Bluetooth®: Bluetooth® Low Energy 5.0 Ethernet connectivity: Chipset: LAN8742AI-CZ-TR - Interface: 10/100Mbit Ethernet interface (PHY) + Interface: RMII 10/100 Mbps Ethernet interface (PHY) +Analog-to-digital converter (ADC): + Channels: 8 + Resolution: 12 bits +Digital-to-analog converter (DAC): + Channels: 2 + Resolution: 12 bits Secure element: NXP® SE050C2 Communication: I2C: 3 @@ -41,12 +44,15 @@ Communication: PWM: 10 USB: 2 (1x USB 2.0 Full Speed + 1x USB 2.0 High Speed) Power: - Circuit operating voltage: 3.3 V - Input voltage (VIN): 5 V + Board operating voltage: 3.3 V + Board input voltage (VIN): 5 V + Supported battery: Li-ion/Li-Po Single Cell 3.7 V + Battery connector: JST 3-pin 1.2 mm pitch Clock speed: 200 MHz Memory: Internal: 2 MB Flash, 512 KB RAM External: 16 MB (QSPI Flash) +Hardware debugging interface: JTAG/SWD Dimensions: Width: 25.40 mm Length: 66.04 mm \ No newline at end of file diff --git a/content/hardware/04.pro/boards/portenta-c33/tutorials/energy-meter-application-note/assets/C33_application_1.png b/content/hardware/04.pro/boards/portenta-c33/tutorials/energy-meter-application-note/assets/C33_application_1.png new file mode 100644 index 0000000000..536487b8a6 Binary files /dev/null and b/content/hardware/04.pro/boards/portenta-c33/tutorials/energy-meter-application-note/assets/C33_application_1.png differ diff --git a/content/hardware/04.pro/boards/portenta-c33/tutorials/energy-meter-application-note/assets/C33_application_2.png b/content/hardware/04.pro/boards/portenta-c33/tutorials/energy-meter-application-note/assets/C33_application_2.png new file mode 100644 index 0000000000..4095baa627 Binary files /dev/null and b/content/hardware/04.pro/boards/portenta-c33/tutorials/energy-meter-application-note/assets/C33_application_2.png differ diff --git a/content/hardware/04.pro/boards/portenta-c33/tutorials/energy-meter-application-note/assets/C33_application_3.gif b/content/hardware/04.pro/boards/portenta-c33/tutorials/energy-meter-application-note/assets/C33_application_3.gif new file mode 100644 index 0000000000..9ce6059ff3 Binary files /dev/null and b/content/hardware/04.pro/boards/portenta-c33/tutorials/energy-meter-application-note/assets/C33_application_3.gif differ diff --git a/content/hardware/04.pro/boards/portenta-c33/tutorials/energy-meter-application-note/assets/C33_application_4.png b/content/hardware/04.pro/boards/portenta-c33/tutorials/energy-meter-application-note/assets/C33_application_4.png new file mode 100644 index 0000000000..60a90e42db Binary files /dev/null and b/content/hardware/04.pro/boards/portenta-c33/tutorials/energy-meter-application-note/assets/C33_application_4.png differ diff --git a/content/hardware/04.pro/boards/portenta-c33/tutorials/energy-meter-application-note/assets/C33_application_cloud.gif b/content/hardware/04.pro/boards/portenta-c33/tutorials/energy-meter-application-note/assets/C33_application_cloud.gif new file mode 100644 index 0000000000..3e796f4dcc Binary files /dev/null and b/content/hardware/04.pro/boards/portenta-c33/tutorials/energy-meter-application-note/assets/C33_application_cloud.gif differ diff --git a/content/hardware/04.pro/boards/portenta-c33/tutorials/energy-meter-application-note/assets/C33_application_cloud_mobile.jpg b/content/hardware/04.pro/boards/portenta-c33/tutorials/energy-meter-application-note/assets/C33_application_cloud_mobile.jpg new file mode 100644 index 0000000000..5ed0b06fe8 Binary files /dev/null and b/content/hardware/04.pro/boards/portenta-c33/tutorials/energy-meter-application-note/assets/C33_application_cloud_mobile.jpg differ diff --git a/content/hardware/04.pro/boards/portenta-c33/tutorials/energy-meter-application-note/assets/current_transformer.zip b/content/hardware/04.pro/boards/portenta-c33/tutorials/energy-meter-application-note/assets/current_transformer.zip new file mode 100644 index 0000000000..c15e5edfb3 Binary files /dev/null and b/content/hardware/04.pro/boards/portenta-c33/tutorials/energy-meter-application-note/assets/current_transformer.zip differ diff --git a/content/hardware/04.pro/boards/portenta-c33/tutorials/energy-meter-application-note/assets/equation_1.png b/content/hardware/04.pro/boards/portenta-c33/tutorials/energy-meter-application-note/assets/equation_1.png new file mode 100644 index 0000000000..59a64236dd Binary files /dev/null and b/content/hardware/04.pro/boards/portenta-c33/tutorials/energy-meter-application-note/assets/equation_1.png differ diff --git a/content/hardware/04.pro/boards/portenta-c33/tutorials/energy-meter-application-note/assets/equation_2.png b/content/hardware/04.pro/boards/portenta-c33/tutorials/energy-meter-application-note/assets/equation_2.png new file mode 100644 index 0000000000..cc355639a4 Binary files /dev/null and b/content/hardware/04.pro/boards/portenta-c33/tutorials/energy-meter-application-note/assets/equation_2.png differ diff --git a/content/hardware/04.pro/boards/portenta-c33/tutorials/energy-meter-application-note/assets/equation_3.png b/content/hardware/04.pro/boards/portenta-c33/tutorials/energy-meter-application-note/assets/equation_3.png new file mode 100644 index 0000000000..4408a49c69 Binary files /dev/null and b/content/hardware/04.pro/boards/portenta-c33/tutorials/energy-meter-application-note/assets/equation_3.png differ diff --git a/content/hardware/04.pro/boards/portenta-c33/tutorials/energy-meter-application-note/content.md b/content/hardware/04.pro/boards/portenta-c33/tutorials/energy-meter-application-note/content.md new file mode 100644 index 0000000000..785b88c41e --- /dev/null +++ b/content/hardware/04.pro/boards/portenta-c33/tutorials/energy-meter-application-note/content.md @@ -0,0 +1,494 @@ +--- +title: 'Energy Metering with the Portenta C33' +description: "This application note describes how to implement a simple energy meter with the Portenta C33." +difficulty: intermediate +compatible-products: [portenta-c33] +tags: + - Energy meter + - Application note + - Portenta C33 +author: 'José Bagur and Taddy Chung' +hardware: + - hardware/04.pro/boards/portenta-c33 +software: + - ide-v1 + - ide-v2 + - IoT-Cloud +--- + +## Introduction + +This application note explores the implementation of a simple yet useful energy meter using the Arduino® Portenta C33 and a non-invasive current transformer. The proposed energy meter enables real-time measurement and monitoring of electrical current consumption, providing valuable and useful insights into energy usage patterns to the user. + +Non-invasive current transformers offer several advantages, including electrical safety, easy installation, and the ability to measure current in existing electrical circuits without interrupting the flow of current. These characteristics make them well-suited for applications such as energy metering, power monitoring, and load management. + +The Portenta C33 features a powerful microcontroller and onboard wireless connectivity, making it an ideal choice for energy monitoring applications. The Portenta C33's onboard Wi-Fi® module enables seamless integration with wireless networks and facilitates communication with the [Arduino IoT Cloud platform](https://create.arduino.cc/iot/). + +![Portenta C33 with a non-invasive current transformer](assets/C33_application_1.png) + +By combining the Portenta C33 and the SCT013-000 current transformer, you can quickly build an energy meter that can measure Root Means Square (RMS) current, power consumption, and communicates the data to the Arduino IoT Cloud platform for further analysis and visualization. + +## Goals + +The main goals of this application note are as follows: + +- Develop a functional energy meter that can provide real-time insights into energy usage patterns, allowing users to track and analyze their energy consumption. +- Showcase the integration of the Portenta C33 board with a non-invasive current transformer to measure AC current. +- Calculate the RMS (Root Mean Square) value of a current waveform, providing an accurate representation of the actual current flowing through the circuit. +- Use the measured RMS current and a known AC voltage to calculate power consumption in Watts. +- Establish a connection between the Portenta C33 and the Arduino IoT Cloud to send the measured RMS current data for further analysis, visualization, and remote monitoring. + +## Hardware and Software Requirements + +### Hardware Requirements + +- [Portenta C33](https://store.arduino.cc/products/portenta-c33) (x1) +- USB-C® cable (x1) +- Wi-Fi® W.FL antenna (x1) +- SCT013-000 current transformer (x1) +- [Conditioner circuit](#hardware-setup-overview) (x1) + +### Software Requirements + +- [Arduino IDE 1.8.10+](https://www.arduino.cc/en/software), [Arduino IDE 2.0+](https://www.arduino.cc/en/software), or [Arduino Web Editor](https://create.arduino.cc/editor) +- For the Wi-Fi® connectivity feature of Portenta C33, we will use [Arduino IoT Cloud](https://create.arduino.cc/iot/things). In case you do not have an account, create one for free [here](https://cloud.arduino.cc/). +- The [energy meter example sketch](assets/current_transformer.zip) + +## Hardware Setup Overview + +The electrical connections of the intended application design are shown in the diagram below: + +![Application's electrical connection overview](assets/C33_application_4.png) + +The overview illustrates the connection from the sensor passing through a conditioner circuit and interfacing with the Portenta C33. + +**Take into account that only one AC wire must pass in between the current transformer**, as shown below: + + +![Correct usage of a non-invasive current transformer](assets/C33_application_2.png) + +## Measuring Current Using Non-Invasive Current Transformers +Non-invasive current transformers, such as the SCT013-000 current transformer used in this application note, provide a safe and convenient method for measuring electrical current, without the need for direct electrical connections. These transformers work on the principle of [electromagnetic induction](https://en.wikipedia.org/wiki/Electromagnetic_induction) and consist of a primary winding and a secondary winding. + +As shown in the animation below, the primary winding typically consists of a single turn or a few turns of a conductor, while the secondary winding consists of a large number of turns wound around a magnetic core. When an alternating current flows through the primary winding, it induces a proportional current in the secondary winding. This induced current can be measured and used to determine the magnitude of the primary current. + + +As shown in the animation below, the primary winding is typically a single turn or a few turns of a conductor, while the secondary winding is a large number of turns wound around a magnetic core. When an alternating current flows through the primary winding, it induces a proportional current in the secondary winding. This induced current can be measured and used to determine the magnitude of the primary current. + +![Working principle of a non-invasive current transformer](assets/C33_application_3.gif) + +To accurately measure the induced current, a **burden resistor** is connected in parallel with the secondary winding of the current transformer. The burden resistor creates a voltage drop proportional to the secondary current, which can be measured using an analog or digital sensor, for example, the analog input pins of the Portenta C33. In this application note, the measured secondary current is converted into an RMS current value using appropriate calibration ratios and calculations. + +***The value of the burden resistor must be carefully chosen to match the physical characteristics of your current transformer and measurement sensor.*** + +To calculate the ideal burden resistor some math is required. Below you can find the calculations done for the SCT013-000 current transformer used this the application note: + +- Primary winding peak current (IP): + +![Primary winding peak current calculation](assets/equation_1.png) + +- Secondary winding peak current (IS): + +![Secondary winding peak current calculation](assets/equation_2.png) + +- Ideal burden resistor (RBurden): + +![Ideal burden resistor calculation](assets/equation_3.png) + +For this application note and the used non-invasive current transformer, the ideal burden resistor RBurden is 21.9 Ω; you can use a commercially available resistor value, for example, 22 Ω. + +Non-invasive current transformers offer several advantages, including electrical safety, easy installation, and the ability to measure current in existing electrical circuits without interrupting the current flow. These characteristics make them well-suited for applications such as: + +- Energy metering +- Power monitoring +- Load management + +## Non-Invasive Current Transformer Example Sketch + +The non-invasive current transformer sketch has a simple structure which is explained below. + +```arduino +/** + Energy metering application note + Name: current_cloud.ino + Purpose: This sketch interfaces the Portenta C33 with the SCT013-000 current transformer + to measure RMS current and power. + + @author Arduino Team + @version 1.0 20/06/23 +*/ + +// Import the properties and definitions for the Arduino IoT Cloud integration +#include "thingProperties.h" + +// Define a floating-point conversion factor for the SCT013-000 current transformer configuration +float Sensor_Factor = 51.8; + +// Define floating-point variables for the Root Mean Square (RMS) current and apparent Power +float Irms, AP; + +// Define an integer for the specific voltage of the geographical region +int Region_Voltage = 110; + +// Define a boolean variable to control whether or not the sampling process is active +bool Sample_Switch = true; + +// Define the pin where the current transformer is connected +#define TRANSFORMER_PIN A0 + +void setup() { + // Initialize the serial communication with a baud rate of 115200 + Serial.begin(115200); + + // Set the current transformer pin as input + // Set the resolution of the analog read to 12 bits + // Pause the execution of the program for one second + pinMode(TRANSFORMER_PIN, INPUT); + analogReadResolution(12); + delay(1000); + + // Call the function to setup the Arduino IoT Cloud + iot_cloud_setup(); +} + +void loop() { + // Update the status of the Arduino Cloud + ArduinoCloud.update(); + + // If the sampling switch is active, calculate the RMS current + if (Sample_Switch == true) { + Irms = getCurrent(); + + // Calculate apparent power + AP = Irms * Region_Voltage; + + // Print RMS current and apparent power to the IDE's Serial Monitor + Serial.print(F("- I_rms [A]: ")); + Serial.print(Irms); + Serial.print(F("- Apparent Power [VA]: ")); + Serial.print(AP); + } else { + // If the sampling switch is not active, print a message saying the energy measurement has been paused + Serial.println(F("- Energy measurement has been paused!")); + } + + // Update the RMS current and apparent power in the Arduino IoT Cloud + cloud_Current = Irms; + cloud_ApparentPower = AP; + + // Pause the execution of the program for one second + delay(1000); +} + +/** + This function is executed every time a new value is received from the Arduino IoT Cloud + + @param none + @return none +*/ +void onCloudCurrentChange() { + // Print a debug message + Serial.print(F("- Updated I_RMS value for IoT Cloud")); +} + +/** + Reads the designated analog pin, connected to a SCT013-000 current transformer and calculates RMS Current + + @param none + @return RMS current (amperes) +*/ +float getCurrent() { + float Current = 0; + float I_Sum = 0; + int N = 0; + long time = millis(); + + // Collect samples for 0.5 seconds (approx. 30 cycles at 60 Hz) + while(millis() - time < 500) { + + // Read the analog pin + int sensorValue = analogRead(TRANSFORMER_PIN); + + // Convert the analog reading to voltage + float sensorVoltage = sensorValue * (3.1 / 4096.0); + + // Convert the sensor voltage to current + Current = sensorVoltage * Sensor_Factor; + + // Calculate the sum of the squares of the current + I_Sum += sq(Current); + N++; + delay(1); + } + + // Compensate for the negative semi-cycle quadratics + I_Sum = I_Sum * 2; + + // Calculate RMS current (average) + Current = sqrt((I_Sum)/N); + return(Current); +} + +/** + Sets up the connection to the Arduino IoT Cloud + + @param none + @return none +*/ +void iot_cloud_setup() { + // Defined in thingProperties.h + initProperties(); + + // Connect to Arduino IoT Cloud + ArduinoCloud.begin(ArduinoIoTPreferredConnection); + + /* + The following function allows you to obtain more information + related to the state of network and IoT Cloud connection and errors + the higher number the more granular information you’ll get. + The default is 0 (only errors). + Maximum is 4 + */ + setDebugMessageLevel(2); + ArduinoCloud.printDebugInfo(); + + sct_ratio = Sensor_Factor; + system_Voltage = Region_Voltage; + sample_Control = Sample_Switch; +} + +/** + This function is executed every time a new value from sct_ratio is received from the Arduino IoT Cloud + + @param none + @return none +*/ +void onSctRatioChange() { + Sensor_Factor = sct_ratio; +} + +/* + This function is executed every time a new value from system_Voltage is received from the Arduino IoT Cloud +*/ +void onSystemVoltageChange() { + Region_Voltage = system_Voltage; +} + +* + This function is executed every time a new value from sample_Control is received from the Arduino IoT Cloud +*/ +void onSampleControlChange() { + Sample_Switch = sample_Control; + + if (Sample_Switch == true){ + Serial.println(F("Energy measurement started - Arduino Cloud triggered")); + } + if (Sample_Switch == false){ + Serial.println(F("Eenrgy measurement paused - Arduino Cloud triggered")); + } +} +``` + +The following sections will help you to understand the main parts of the code. + +### Variables and Constants + +The key variables and constants used in the sketch are: + +```arduino +// Conversion factor for the specific sensor configuration +float Sensor_Factor = 51.8; + +// RMS Current and Apparent Power variable +float Irms, AP; + +// Voltage specific to the geographical region in volts +int Region_Voltage = 110; + +// Boolean variable to control measurement sampling +bool Sample_Switch = true; + +// Analog pin to which the current transformer is connected +#define TRANSFORMER_PIN A0 +``` + +- `Sensor_Factor`: A conversion factor used to convert the raw current transformer reading to an RMS current value. +- `Irms` and `AP`: Variables used to store the RMS current and apparent power respectively. +- `Region_Voltage`: The voltage of the power system you are monitoring. This varies depending on the country and the type of power system. +- `Sample_Switch`: A boolean switch to control whether or not your Portenta C33 should be measuring power. If it is true, your Portenta C33 will measure power. +- `TRANSFORMER_PIN`: The pin on your Portenta C33 board that the current transformer is connected to. + +### Initialization Function + +The `setup()` function helps set up the communication with the Arduino IoT Cloud, as well as the communication settings of the board itself: + +```arduino +void setup() { + // Initialize the serial communication with a baud rate of 115200 + Serial.begin(115200); + + // Set the current transformer pin as input + // Set the resolution of the analog read to 12 bits + // Pause the execution of the program for one second + pinMode(TRANSFORMER_PIN, INPUT); + analogReadResolution(12); + delay(1000); + + // Call the function to setup the Arduino IoT Cloud + iot_cloud_setup(); +} +``` + +This function runs once when the Portenta C33 starts: + +* It initializes the serial communication. +* Sets the pin mode of the current transformer input pin to input. +* Sets the ADC resolution to 12 bits and waits for a second for the system to stabilize. +* Finally calls the `iot_cloud_setup()` function to set up the Arduino IoT Cloud connection. + +### The Main Loop + +The main loop of the sketch is as follows: + +```arduino +void loop() { + // Update the status of the Arduino Cloud + ArduinoCloud.update(); + + // If the sampling switch is active, calculate the RMS current + if (Sample_Switch == true) { + Irms = getCurrent(); + + // Calculate apparent power + AP = Irms * Region_Voltage; + + // Print RMS current and apparent power to the IDE's Serial Monitor + Serial.print(F("- I_RMS [A]: ")); + Serial.print(Irms); + Serial.print(F("- Apparent power [VA]: ")); + Serial.print(AP); + } else { + // If the sampling switch is not active, print a message saying the energy measurement has been paused + Serial.println(F("- Energy measurement has been paused!")); + } + + // Update the RMS current and apparent power in the Arduino IoT Cloud + cloud_Current = Irms; + cloud_ApparentPower = AP; + + // Pause the execution of the program for one second + delay(1000); +} +``` + +The main `loop()` function executes continuously. At each iteration: + +* It first updates the Arduino IoT Cloud connection. +* If the `Sample_Switch` is true, it measures current, calculates apparent power, and prints them to the IDE's Serial Monitor. +* If `Sample_Switch` is false, it simply prints that the energy measurement is paused. +* It then updates the `cloud_Current` and `cloud_ApparentPower` variables with the local values of current and apparent power, then waits for a second before the next iteration. + +### User Functions + +The `iot_cloud_setup()` function groups the initial configuration process of the Arduino Cloud as follows: + +```arduino +void iot_cloud_setup() { + // Defined in thingProperties.h + initProperties(); + + // Connect to Arduino IoT Cloud + ArduinoCloud.begin(ArduinoIoTPreferredConnection); + + /* + The following function allows you to obtain more information + related to the state of network and IoT Cloud connection and errors + the higher number the more granular information you’ll get. + The default is 0 (only errors). + Maximum is 4 + */ + setDebugMessageLevel(2); + ArduinoCloud.printDebugInfo(); + + sct_ratio = Sensor_Factor; + system_Voltage = Region_Voltage; + sample_Control = Sample_Switch; +} +``` + +This function is responsible for setting up the connection with the Arduino IoT Cloud: +* It initiates the properties of the cloud connection. +* Begins the cloud connection with the preferred connection method. +* Sets the debug message level to 2 for detailed debugging, and prints the debug information. + +The variables `sct_ratio`, `system_Voltage`, and `sample_Control` are used to synchronize the local values with the Arduino IoT Cloud. + +Now, let's talk about the `getCurrent()` function: + +```arduino +float getCurrent() { + float Current = 0; + float I_Sum = 0; + int N = 0; + long time = millis(); + + // Collect samples for 0.5 seconds (approx. 30 cycles at 60 Hz) + while(millis() - time < 500) { + + // Read the analog pin + int sensorValue = analogRead(TRANSFORMER_PIN); + + // Convert the analog reading to voltage + float sensorVoltage = sensorValue * (3.1 / 4096.0); + + // Convert the sensor voltage to current + Current = sensorVoltage * Sensor_Factor; + + // Calculate the sum of the squares of the current + I_Sum += sq(Current); + N++; + delay(1); + } + + // Compensate for the negative semi-cycle quadratics + I_Sum = I_Sum * 2; + + // Calculate RMS current (average) + Current = sqrt((I_Sum)/N); + return(Current); +} +``` + +The `getCurrent()` function calculates the RMS current from the sensor reading. It reads the sensor value, converts it to voltage, then calculates the current. The square of the current is summed over 0.5 seconds (approximately 30 cycles at 60 Hz). This sum is compensated for the negative semi-cycle quadratics and then used to calculate the RMS current. This value is returned to the user. + +Finally, `onSctRatioChange()`, `onSystemVoltageChange()`, and `onSampleControlChange()` functions: These functions get executed every time the corresponding value is changed from the Arduino IoT Cloud. For example, if `onSctRatioChange()` is executed, the `Sensor_Factor` will be updated with the new value received from the cloud, and similarly for the others. + +### Full Example Code + +The complete example code can be downloaded [here](assets/current_transformer.zip). The `thingProperties.h` header is already included for your reference, and it is based on the variables of the example code. The header is generated automatically with Arduino IoT Cloud. If you desire to modify the requirements of the application environment, it is recommended to make changes within the Arduino Cloud environment. + +### Arduino Cloud Dashboard + +The Arduino Cloud allows to create a dashboard with professional real-time Human-Computer Interaction (HCI) as can be seen in the following animation, showing an active Portenta C33 board: + +![Arduino Cloud Dashboard Example](assets/C33_application_cloud.gif) + +One of the standout features of the Arduino Cloud Dashboard is the ability to update the current transformer's ratio in real time. This feature becomes particularly useful when you need to switch to a different current transformer in a live deployment scenario. Different current transformers can possess different electrical characteristics more or less convenient for different scenarios, and the real-time update capability simplifies the swap between them. + +Additionally, the dashboard lets you select the installation voltage to meet the requirements of your site. This adaptability underscores the flexibility and user-friendliness of the Arduino Cloud Dashboard, making it an invaluable tool for handling real-time sensor data. + +![Arduino Cloud Modbile Dashboard Example](assets/C33_application_cloud_mobile.jpg) + +On a mobile phone, the Arduino Cloud dashboard displays the information as the previous figure. It provides the complete interface you would use on a desktop platform, making it a very useful feature to access the dashboard wherever you are. + +## Conclusions + +In this application note, we delved into the interaction between a Portenta C33 board and the SCT013-000 current transformer. We examined how the Arduino IoT Cloud enables us to visualize and analyze real-time and historical sensor data intuitively. + +By using the Portenta C33 board and the Arduino IoT Cloud, you can transform raw sensor data into meaningful insights. Whether it is reading the RMS current and apparent power information, altering the current transformer configurations in real-time, or adapting to unique site requirements, this application note offers a robust and versatile system for handling these tasks. + +One of the key takeaways from this application note is its potential for this application in various real-world scenarios. By integrating IoT and Cloud capabilities, we can effectively monitor and manage energy usage, leading to more efficient power consumption and contributing to a sustainable future. + +### Next Steps + +Now that you have learned to deploy a Portenta C33 with SCT013-000 current transformer, using the on-demand remote actuation and real-time data visualization of the Arduino Cloud platform, you will be able to expand the application further by adding new measurement equipment with similar characteristics. You could also deploy multiple sensors connected to different boards, creating a cluster to gather energy measurements from every point of interest in an electrical installation. \ No newline at end of file diff --git a/content/hardware/04.pro/boards/portenta-c33/tutorials/energy-meter-application-note/hero-banner.png b/content/hardware/04.pro/boards/portenta-c33/tutorials/energy-meter-application-note/hero-banner.png new file mode 100644 index 0000000000..5fa5d8b082 Binary files /dev/null and b/content/hardware/04.pro/boards/portenta-c33/tutorials/energy-meter-application-note/hero-banner.png differ diff --git a/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/ABX00074-pinout-HDC.png b/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/ABX00074-pinout-HDC.png new file mode 100644 index 0000000000..b353012896 Binary files /dev/null and b/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/ABX00074-pinout-HDC.png differ diff --git a/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/ABX00074-pinout-MKR.png b/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/ABX00074-pinout-MKR.png new file mode 100644 index 0000000000..bf29e9052b Binary files /dev/null and b/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/ABX00074-pinout-MKR.png differ diff --git a/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-1.png b/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-1.png new file mode 100644 index 0000000000..6d580140dc Binary files /dev/null and b/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-1.png differ diff --git a/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-10.png b/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-10.png new file mode 100644 index 0000000000..944f488afd Binary files /dev/null and b/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-10.png differ diff --git a/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-11.png b/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-11.png new file mode 100644 index 0000000000..847ef39150 Binary files /dev/null and b/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-11.png differ diff --git a/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-12.png b/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-12.png new file mode 100644 index 0000000000..72493b8beb Binary files /dev/null and b/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-12.png differ diff --git a/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-2.png b/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-2.png new file mode 100644 index 0000000000..73ebb02c70 Binary files /dev/null and b/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-2.png differ diff --git a/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-3.png b/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-3.png new file mode 100644 index 0000000000..276d397506 Binary files /dev/null and b/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-3.png differ diff --git a/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-4.png b/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-4.png new file mode 100644 index 0000000000..a175e89dd2 Binary files /dev/null and b/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-4.png differ diff --git a/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-5.png b/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-5.png new file mode 100644 index 0000000000..8250ec04d4 Binary files /dev/null and b/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-5.png differ diff --git a/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-6.png b/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-6.png new file mode 100644 index 0000000000..178fefb3f2 Binary files /dev/null and b/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-6.png differ diff --git a/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-7.png b/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-7.png new file mode 100644 index 0000000000..64b8b92ab5 Binary files /dev/null and b/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-7.png differ diff --git a/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-8.png b/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-8.png new file mode 100644 index 0000000000..7e7b409a17 Binary files /dev/null and b/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-8.png differ diff --git a/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-9.png b/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-9.png new file mode 100644 index 0000000000..dffe0066c8 Binary files /dev/null and b/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-9.png differ diff --git a/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-gif-1.gif b/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-gif-1.gif new file mode 100644 index 0000000000..6c1c797bc1 Binary files /dev/null and b/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-gif-1.gif differ diff --git a/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-gif-2.gif b/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-gif-2.gif new file mode 100644 index 0000000000..4fb4fffd8e Binary files /dev/null and b/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-gif-2.gif differ diff --git a/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-gif-3.gif b/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-gif-3.gif new file mode 100644 index 0000000000..3ab95f0170 Binary files /dev/null and b/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/assets/user-manual-gif-3.gif differ diff --git a/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/content.md b/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/content.md new file mode 100644 index 0000000000..242c5ea33e --- /dev/null +++ b/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/content.md @@ -0,0 +1,1449 @@ +--- +title: 'Portenta C33 User Manual' +difficulty: beginner +compatible-products: [portenta-c33] +description: 'Learn about the hardware and software features of the Arduino® Portenta C33.' +tags: + - Cheat sheet + - User manual + - Portenta C33 +author: 'José Bagur' +hardware: + - hardware/04.pro/boards/portenta-c33 +software: + - ide-v1 + - ide-v2 + - web-editor + - iot-cloud +--- + +## Overview + +This user manual will provide a comprehensive overview of the Portenta C33 board, covering its major hardware and software elements. With this user manual, you will learn how to set up, configure and use all the main features of the board. + +## Hardware and Software Requirements + +### Hardware Requirements + +- [Portenta C33](https://store.arduino.cc/products/portenta-c33) (x1) +- USB-C® cable (x1) +- Wi-Fi® W.FL antenna (x1) + +### Software Requirements + +- [Arduino IDE 1.8.10+](https://www.arduino.cc/en/software), [Arduino IDE 2.0+](https://www.arduino.cc/en/software), or [Arduino Web Editor](https://create.arduino.cc/editor) + +## Product Overview + +The Portenta C33 is a powerful System-on-Module (SOM) designed for cost-effective Internet of Things (IoT) applications and devices. Based on the R7FA6M5BH2CBG microcontroller from Renesas®, it shares the same form factor as the Portenta H7 board. It is backward-compatible with the MKR and Portenta family shields and carriers through its MKR-styled and High-Density connectors. The Portenta C33 is ideal for a wide range of applications, from smart home devices to connected industrial sensors. + + +### Board Architecture Overview + +The Portenta C33 features a robust and efficient architecture that enables it for low-cost, battery-powered, IoT applications and devices. + +![The Portenta C33 main components (top view)](assets/user-manual-1.png) + +![The Portenta C33 main components (bottom view)](assets/user-manual-2.png) + +Here is an overview of the board's main components shown in the images above: + +- **Microcontroller**: At the heart of the Portenta C33 is the [R7FA6M5BH2CBG](https://www.renesas.com/us/en/document/dst/ra6m5-group-datasheet?r=1493931), a powerful and versatile SOM from Renesas®. The R7FA6M5BH2CBG is built around a 32-bit Arm® Cortex®-M33 processor running at 200 MHz, with 2 MB of Flash memory and 512 kB of SRAM. +- **External memory**: The board features an onboard 16 MB QSPI Flash memory. +- **Wireless connectivity**: The board supports 2.4 GHz Wi-Fi® (802.11 b/g/n) and Bluetooth® 5.0, provided by the ESP32-C3-MINI-1U module developed by Espressif Systems®. This high-performance Wi-Fi® and Bluetooth® module allows the Portenta C33 to communicate wirelessly with other devices and systems. Note: `ArduinoBLE` library support is limited to Bluetooth® 4.0 only actually. +- **Ethernet connectivity**: The board features an onboard, high-performance 10/100 Mbps Ethernet transceiver accessible through its High-Density connectors. +- **Security**: The board features an onboard ready-to-use secure element, the SE050C2 from NXP®, specifically designed for IoT devices and provides advanced security features. +- **USB connectivity**: The board features a USB-C port for power and data, which is also accessible through the board's High-Density connectors. +- **Power management**: The Portenta C33 is designed for low-power operation to meet the demands of always-connected IoT devices. It features a power management integrated circuit (PMIC), the PF1550 from NXP®, designed specifically for low-power, portable, and battery-powered IoT applications. +- **Analog and digital peripherals**: The board features analog peripherals such as two 8-channel 12-bit analog-to-digital converters (ADC) and two 12-bit digital-to-analog converters (DAC). It also features the following digital peripherals: GPIO (x7), I2C (x1), UART (x4), SPI (x2), PWM (x10), CAN (x2), I2S (x1), SPDIF (x1), PDM (x1), and SAI (x1). +- **Debugging**: The board features a JTAG/SWD debug port accessible through its High-Density connectors. +- **Surface mount**: The castellated pins of the board allows it to be positioned as a surface-mountable module. +- **MKR-styled connectors**: The MKR-styled connectors of the board makes it compatible with all the MKR family boards. 2.54 mm pitch headers can be easily soldered to the board. + +### Board Core and Libraries + +The **Arduino Renesas Boards** core contains the libraries and examples to work with the Portenta C33's peripherals and onboard components, such as its external QSPI Flash memory and Wi-Fi® and Bluetooth® module. To install the core for the Portenta C33 board, navigate to **Tools > Board > Boards Manager** or click the Boards Manager icon in the left tab of the IDE. In the Boards Manager tab, search for `renesas` and install the latest Arduino Renesas Boards version. + +![Installing the Arduino Renesas Boards core in the Arduino IDE](assets/user-manual-3.png) + +### Pinout + +![Portenta C33 MKR-styled connectors pinout](assets/ABX00074-pinout-MKR.png) + +The complete pinout is available and downloadable as PDF from the link below: + +- Portenta C33 pinout + +### Datasheet + +The complete datasheet is available and downloadable as PDF from the link below: + +- [Portenta C33 datasheet](https://docs.arduino.cc/resources/datasheets/ABX00074-datasheet.pdf) + +### Schematics + +The complete schematics are available and downloadable as PDF from the link below: + +- [Portenta C33 schematics](https://docs.arduino.cc/static/baeb885ab6554722072a7a5a75183282/ABX00074-schematics.pdf) + +### STEP Files + +The complete STEP files are available and downloadable from the link below: + +- [Portenta C33 STEP files](https://docs.arduino.cc/static/ce20870743b1638d819713953770dcc8/ABX00074-step.zip) + +## First Use + +### Powering the Board + +The Portenta C33 can be powered by the following: + +- Using a USB-C® cable (not included). +- Using an external **4.1 to 6 V power supply** connected to the `VIN` pin located in the MKR-styled connectors pins of the board (please, refer to the [board pinout section](#pinout) of the user manual). +- Using an external **5 V power supply** connected to the `5V` pin located in the MKR-styled connectors of the board (please, refer to the [board pinout section](#pinout) of the user manual). +- Using a **3.7 V Lithium Polymer (Li-Po) battery** connected to the board through the onboard battery connector; the manufacturer part number of the battery connector is BM03B-ACHSS-GAN-TF(LF)(SN), and its matching receptacle manufacturer part number is ACHR-03V-S. The **recommended minimum battery capacity for the Portenta C33 is 800 mAh**. A Li-Po battery with an integrated NTC thermistor is also recommended for thermal protection. +- Using the onboard **ESLOV connector**, which has a dedicated 5 V power line. +- Using an Arduino Pro carrier board, such as the [Portenta Max Carrier](https://store.arduino.cc/collections/pro-family/products/portenta-max-carrier) and the [Portenta Breakout](https://store.arduino.cc/collections/pro-family/products/arduino-portenta-breakout). +- Using your custom boards to power the board through the board's castellated pins, MKR-styled or High-Density connectors. Check out the [board pinout](#pinout) and its schematic to know more about it. + +![Different ways to power the Portenta C33 board](assets/user-manual-4.png) + +### Hello World Example + +Let's program the Portenta C33 with the classic `hello world` example used in the Arduino ecosystem: the `Blink` sketch. We will use this example to verify the board's connection to the Arduino IDE and that the Portenta C33 core and the board itself are working as expected. + +There are two ways to program this example in the board: + +- Navigate to **File > Examples > 01.Basics > Blink**. +- Copy and paste the code below into a new sketch in the Arduino IDE. + +```arduino +void setup() { + // Initialize LED_BUILTIN as an output (this will turn on the LED) + pinMode(LED_BUILTIN, OUTPUT); +} + +void loop() { + // Turn the built-in LED off + digitalWrite(LED_BUILTIN, HIGH); + delay(1000); + // Turn the built-in LED on + digitalWrite(LED_BUILTIN, LOW); + delay(1000); +} +``` + +For the Portenta C33, the `LED_BUILTIN` macro represents the **green LED** of the built-in RGB LED of the board. + +![Built-in RGB LED of the Portenta C33 board](assets/user-manual-5.png) + +***The built-in RGB LED on the Portenta C33 needs to be pulled to ground to make them light up. This means that a voltage level of `LOW` on each of their pins will turn the specific color of the LED on, and a voltage level of `HIGH` will turn them off. Furthermore, invoking the `pinMode(LED_BUILTIN, OUTPUT)` instruction pulls the built-in LED LOW, which means it turns it on.*** + +To upload the code to the Portenta C33, click the **Verify** button to compile the sketch and check for errors; then click the **Upload** button to program the board with the sketch. + +![Uploading a sketch to the Portenta C33 in the Arduino IDE.](assets/user-manual-6.png) + +You should see now the green LED of the built-in RGB LED turn on for one second, then off for one second, repeatedly. + +![Hello World example running in the Portenta C33](assets/user-manual-gif-1.gif) + +## Pins + +The Portenta C33 has been designed with two types of connectors, the MKR-styled connectors, intended for prototyping and debugging, and the High-Density connectors, intended to be used across Arduino Pro boards or custom boards. The Portenta C33 MKR-styled connectors pinout is shown in the image below: + +![Portenta C33 MKR-styled connectors pinout](assets/ABX00074-pinout-MKR.png) + +The Portenta C33 High-Density connectors pinout is shown in the image below: + +![Portenta C33 High-Density connectors pinout](assets/ABX00074-pinout-HDC.png) + +### Analog Pins + +The Portenta C33 has eight analog input pins mapped as follows: + +| **Arduino Pin Mapping** | **Microcontroller Pin** | +|:-----------------------:|:-----------------------:| +| `A0` | `P006` | +| `A1` | `P005` | +| `A2` | `P004` | +| `A3` | `P002` | +| `A4` | `P001` | +| `A5`/`DAC1` | `P015` | +| `A6`/`DAC0` | `P014` | +| `A7` | `P000` | + +The eight analog input pins can be used through the built-in functions of the Arduino programming language ([`analogRead()` function](https://reference.arduino.cc/reference/en/language/functions/analog-io/analogread/)). + +Please, refer to the [board pinout section](#pinout) of the user manual to find the analog pins on the board: + +- MKR-style connectors: pins `A0`, `A1`, `A2`, `A3`, `A4`, `A5`, and `A6` are accessible thought these connectors. +- High-Density connectors: pins `A0`, `A1`, `A2`, `A3`, `A4`, `A5`, `A6`, and `A7` are accessible thought these connectors. + +The example code shown below reads the voltage value from a potentiometer connected to `A0` and displays it on the Arduino IDE Serial Monitor: + +```arduino +// Define the potentiometer pin and variable to store its value +int potentiometerPin = A0; +int potentiometerValue = 0; + +void setup() { + // Initialize Serial communication + Serial.begin(9600); +} + +void loop() { + // Read the voltage value from the potentiometer + potentiometerValue = analogRead(potentiometerPin); + + // Print the potentiometer voltage value to the Serial Monitor + Serial.print("- Potentiometer voltage value: "); + Serial.println(potentiometerValue); + + // Wait for 1000 milliseconds + delay(1000); +} +``` + +### Digital Pins + +The Portenta C33 has 91 digital input/output pins, mapped as described in the following tables. **The first 14 digital pins are available through the MKR-styled connectors of the board**: + +| **Arduino Pin Mapping** | **Pin Functionality** | **Microcontroller Pin** | +|:-----------------------:|:---------------------:|:-----------------------:| +| `0` | GPIO | `P105` | +| `1` | GPIO | `P106` | +| `2` | GPIO | `P11` | +| `3` | GPIO | `P303` | +| `4` | GPIO | `P401` | +| `5` | GPIO | `P210` | +| `6` | GPIO | `P601` | +| `7`/`CS0` | GPIO/SPI | `P402` | +| `8`/`MOSI0` | GPIO/SPI | `P900` | +| `9`/`SCK0` | GPIO/SPI | `P204` | +| `10`/`MISO0` | GPIO/SPI | `P315` | +| `11`/`SDA0` | GPIO/I2C | `P407` | +| `12`/`SCL0` | GPIO/I2C | `P408` | +| `13`/`RX0` | GPIO/UART | `P110` | +| `14`/`TX0` | GPIO/UART | `P602` | + +The following eight digital pins also have **analog functionalities**; they are available through the MKR-styled and High-Density connectors of the board: + +| **Arduino Pin Mapping** | **Pin Functionality** | **Microcontroller Pin** | +|:-----------------------:|:---------------------:|:-----------------------:| +| `15`/`A0` | GPIO/Analog | `P006` | +| `16`/`A1` | GPIO/Analog | `P005` | +| `17`/`A2` | GPIO/Analog | `P004` | +| `18`/`A3` | GPIO/Analog | `P002` | +| `19`/`A4` | GPIO/Analog | `P001` | +| `20`/`A5`/`DAC1` | GPIO/Analog | `P015` | +| `21`/`A6`/`DAC0` | GPIO/Analog | `P014` | +| `22`/`A7` | GPIO/Analog | `P000` | + +The following four digital pins are **PWM-capable**; they are available through the High-Density connectors of the board: + +| **Arduino Pin Mapping** | **Pin Functionality** | **Microcontroller Pin** | +|:-----------------------:|:---------------------:|:-----------------------:| +| `23` | GPIO | `P605` | +| `24` | GPIO | `P608` | +| `25` | GPIO | `P311` | +| `26` | GPIO | `P600` | + +The following seven pins are **Interrupt Request (IRQ) capable**; they are available through the High-Density connectors of the board: + +| **Arduino Pin Mapping** | **Pin Functionality** | **Microcontroller Pin** | +|:-----------------------:|:---------------------:|:-----------------------:| +| `27` | GPIO/IRQ | `P009` | +| `28` | GPIO/IRQ | `P409` | +| `29` | GPIO/IRQ | `P505` | +| `30` | GPIO/IRQ | `P706` | +| `31` | GPIO/IRQ | `P707` | +| `32` | GPIO/IRQ | `P708` | +| `33` | GPIO/IRQ | `P802` | + +The following three pins are the digital pins used to control the **built-in RGB LED** of the board: + +| **Arduino Pin Mapping** | **Pin Functionality** | **Microcontroller Pin** | +|:-----------------------:|:---------------------:|:-----------------------:| +| `34`/`LEDR` | GPIO | `P107` | +| `35`/`LEDG` | GPIO | `P400` | +| `36`/`LEDB` | GPIO | `P800` | + +The following four digital pins are **I2C-capable**; they are available through the High-Density connectors of the board: + +| **Arduino Pin Mapping** | **Pin Functionality** | **Microcontroller Pin** | +|:-----------------------:|:---------------------:|:-----------------------:| +| `37`/`SDA1` | GPIO/I2C | `P511` | +| `38`/`SCL1` | GPIO/I2C | `P512` | +| `39`/`SDA2` | GPIO/I2C | `P302` | +| `40`/`SCL2` | GPIO/I2C | `P301` | + +The following four digital pins are **CAN-capable**; they are available through the High-Density connectors of the board: + +| **Arduino Pin Mapping** | **Pin Functionality** | **Microcontroller Pin** | +|:-----------------------:|:---------------------:|:-----------------------:| +| `41` | GPIO/CAN RX | `P202` | +| `42` | GPIO/CAN TX | `P203` | +| `43` | GPIO/CAN1 RX | `P610` | +| `44` | GPIO/CAN1 TX | `P609` | + +The following four digital pins are **SPI-capable**; they are available through the High-Density connectors of the board: + +| **Arduino Pin Mapping** | **Pin Functionality** | **Microcontroller Pin** | +|:-----------------------:|:---------------------:|:-----------------------:| +| `45` | GPIO/MISO1 | `P100` | +| `46` | GPIO/MOSI1 | `P101` | +| `47` | GPIO/SCLK1 | `P102` | +| `48` | GPIO/CS1 | `P103` | + +The following 14 digital pins are **UART-capable**; they are available through the High-Density connectors of the board: + +| **Arduino Pin Mapping** | **Pin Functionality** | **Microcontroller Pin** | +|:-----------------------:|:---------------------:|:-----------------------:| +| `49` | GPIO/TX2 | `P613` | +| `50` | GPIO/RX2 | `P614` | +| `51` | GPIO/RTS2 | `P611` | +| `52` | GPIO/CTS2 | `P404` | +| `53` | GPIO/TX3 | `P506` | +| `54` | GPIO/RX3 | `P304` | +| `55` | GPIO/RTS3 | `P503` | +| `56` | GPIO/CTS3 | `P502` | +| `57` | GPIO/TX4 | `P805` | +| `58` | GPIO/RX4 | `P513` | +| `59` | GPIO/RTS4 | `P508` | +| `60` | GPIO/CTS4 | `P500` | +| `61` | GPIO/RTS0 | `P603` | +| `62` | GPIO/CTS0 | `P604` | + +The following four digital pins are **SSI-capable**; they are available through the High-Density connectors of the board: + +| **Arduino Pin Mapping** | **Pin Functionality** | **Microcontroller Pin** | +|:-----------------------:|:---------------------:|:-----------------------:| +| `63` | GPIO/SSI CK | `P112` | +| `64` | GPIO/SSI WS | `P113` | +| `65` | GPIO/SSI SDI | `P114` | +| `66` | GPIO/SSI SDO | `P115` | + +The following 17 digital pins are **generic GPIO pins**; they are available through the High-Density connectors of the board: + +| **Arduino Pin Mapping** | **Pin Functionality** | **Microcontroller Pin** | +|:-----------------------:|:---------------------:|:-----------------------:| +| `67` | GPIO | `P908` | +| `68` | GPIO | `P403` | +| `69` | GPIO | `P901` | +| `70` | GPIO | `P612` | +| `71` | GPIO | `P312` | +| `72` | GPIO | `P313` | +| `73` | GPIO | `P314` | +| `74` | GPIO | `PA01` | +| `75` | GPIO | `PA08` | +| `76` | GPIO | `PA09` | +| `77` | GPIO | `PA10` | +| `78` | GPIO | `P507` | +| `79` | GPIO | `PB00` | +| `80` | GPIO | `P615` | +| `81` | GPIO | `P003` | +| `82` | GPIO | `P007` | +| `83` | GPIO | `P008` | + +And the last eight digital pins are **SD-card-capable**; they are available through the High-Density connectors of the board: + +| **Arduino Pin Mapping** | **Pin Functionality** | **Microcontroller Pin** | +|:-----------------------:|:---------------------:|:-----------------------:| +| `84` | GPIO/SDHI CLK | `P413` | +| `85` | GPIO/SDHI CMD | `P412` | +| `86` | GPIO/SDHI D0 | `P411` | +| `87` | GPIO/SDHI D1 | `P410` | +| `88` | GPIO/SDHI D2 | `P206` | +| `89` | GPIO/SDHI D3 | `P205` | +| `90` | GPIO/SDHI CD | `P415` | +| `91` | GPIO/SDHI WP | `P414` | + +The basic functionality of the Portenta C33's digital pins can be implemented through the built-in functions of the Arduino programming language. The configuration of a digital pin is done in the `setup()` function with the [built-in function `pinMode()`](https://www.arduino.cc/reference/en/language/functions/digital-io/pinmode/), as shown below: + +```arduino +// Pin configured as an input +pinMode(pin, INPUT); + +// Pin configured as an output +pinMode(pin, OUTPUT); + +// Pin configured as an input, internal pull-up resistor enabled +pinMode(pin, INPUT_PULLUP); +``` + +The state of a digital pin, configured as an input, can be read using the [built-in function `digitalRead()`](https://www.arduino.cc/reference/en/language/functions/digital-io/digitalread/) as shown below: + +```arduino +// Reads pin state, stores value in state variable +state = digitalRead(pin); +``` + +The state of a digital pin, configured as an output, can be changed using the [built-in function `digitalWrite()`](https://www.arduino.cc/reference/en/language/functions/digital-io/digitalwrite/) as shown below: + +```arduino +// Set pin on +digitalWrite(pin, HIGH); + +// Set pin off +digitalWrite(pin, LOW); +``` + +The example code shown below uses digital pin `3` to control an LED depending on the state of a button connected to digital pin `2`: + +```arduino +// Define button and LED pin +int buttonPin = 2; +int ledPin = 3; + +// Variable to store the button state +int buttonState = 0; + +void setup() { + // Configure button and LED pins + pinMode(buttonPin, INPUT_PULLUP); + pinMode(ledPin, OUTPUT); + + // Initialize Serial communication + Serial.begin(9600); +} + +void loop() { + // Read the state of the button + buttonState = digitalRead(buttonPin); + + // If the button is pressed, turn on the LED and print its state to the Serial Monitor + if (buttonState == LOW) { + digitalWrite(ledPin, HIGH); + Serial.println("- Button is pressed. LED is on."); + } else { + // If the button is not pressed, turn off the LED and print to the Serial Monitor + digitalWrite(ledPin, LOW); + Serials.println("- Button is not pressed. LED is off."); + } + + // Wait for 1000 milliseconds + delay(1000); +} +``` + +### PWM Pins + +The Portenta C33 has 10 digital pins with PWM functionality, mapped as follows: + +| **Arduino Pin Mapping** | **Microcontroller Pin** | +|:-----------------------:|:-----------------------:| +| `0` or `D0` | `P105` | +| `1` or `D1` | `P106` | +| `2` or `D2` | `P111` | +| `3` or `D3` | `P303` | +| `4` or `D4` | `P401` | +| `5` or `D5` | `P210` | +| `6` or `D6` | `P601` | +| `7` or `D7` | `P402` | +| `8` | `P900` | +| `9` | `P204` | +| `23` | `P605` | +| `24` | `P608` | +| `25` | `P311` | +| `26` | `P600` | + +The 10 PWM pins can be used through the built-in ([`analogWrite()` function](https://www.arduino.cc/reference/en/language/functions/analog-io/analogwrite)) of the Arduino programming language. + +Please, refer to the [board pinout section](#pinout) of the user manual to find them on the board. + +- MKR-styled connectors: pins `0`, `1`, `2`, `3`, `4`, `5`, and `6` are accessible through these connectors. +- High-Density connectors: pins `0`, `1`, `2`, `3`, `4`, `5`, `7`, `8`, `9`, `23`, `24`, `25`, and `26` are accessible through these connectors. + +The example code shown below uses digital pin `9` PWM functionality to control the brightness of the board's built-in RGB LED (green LED) connected to it: + +```arduino +// Define the LED pin, brightness, and fade amount variables +int brightness = 0; +int fadeAmount = 5; + +void setup() { + // Configure the LED pin as an output + pinMode(LEDG, OUTPUT); +} + +void loop() { + // Set the brightness of the LED + analogWrite(LEDG, brightness); + + // Update the brightness value + brightness += fadeAmount; + + // Reverse the fade direction when reaching the limits + if (brightness <= 0 || brightness >= 255) { + fadeAmount = -fadeAmount; + } + + // Wait for 30 milliseconds + delay(30); +} +``` +You should now see the built-in RGB LED's green LED fade in, then fade out repeatedly. + +![PWM example running in the Portenta C33](assets/user-manual-gif-2.gif) + +## Actuators + +This user manual section covers the Portenta C33 built-in actuators, showing their main hardware and software characteristics. + +### RGB LED + +The Portenta C33 features a built-in RGB LED that can be used as a visual feedback indicator for the user. + +![Built-in RGB LED of the Portenta C33 board](assets/user-manual-5.png) + +The built-in RGB LED can be accessed through the following macro definitions: + +| **Built-in LED** | **Macro Definition** | +|:----------------:|:-----------------------:| +| Red LED | `LEDR` | +| Blue LED | `LEDB` | +| Green LED | `LEDG` or `LED_BUILTIN` | + +***The built-in RGB LED on the Portenta C33 needs to be pulled to ground to make them light up. This means that a voltage level of `LOW` on each of their pins will turn the specific color of the LED on, and a voltage level of `HIGH` will turn them off. Furthermore, invoking the `pinMode(LED_BUILTIN, OUTPUT)` instruction pulls the built-in LED LOW, which means it turns it on.*** + +The following example code blinks each of the LEDs at an interval of 500 ms: + +```arduino +void setup() { + // Initialize LEDR, LEDG and LEDB as outputs + pinMode(LEDR, OUTPUT); + pinMode(LEDG, OUTPUT); + pinMode(LEDB, OUTPUT); +} + +void loop() { + // Turn on the built-in red LED and turn off the rest + digitalWrite(LEDR, LOW); + digitalWrite(LEDG, HIGH); + digitalWrite(LEDB, HIGH); + delay(500); + // Turn on the built-in green LED and turn off the rest + digitalWrite(LEDR, HIGH); + digitalWrite(LEDG, LOW); + digitalWrite(LEDB, HIGH); + delay(500); + // Turn on the built-in blue LED and turn off the rest + digitalWrite(LEDR, HIGH); + digitalWrite(LEDG, HIGH); + digitalWrite(LEDB, LOW); + delay(500); +} +``` + +You should now see the built-in RGB LED blinking each of its LEDs repeatedly. + +![Built-in RGB LED example running in the Portenta C33](assets/user-manual-gif-3.gif) + +## Communication + +This section of the user manual covers the different communication protocols that are supported by the Portenta C33 board, including the Serial Peripheral Interface (SPI), Inter-Integrated Circuit (I2C), Universal Asynchronous Receiver-Transmitter (UART), and Wi-Fi®; JTAG interface and communication via the onboard ESLOV connector is also explained in this section. + +The Portenta C33 features dedicated pins for each communication protocol, accessible through the MKR-styled connectors and the High-Density connectors, making connecting and communicating with different components, peripherals, and sensors easy. + +### SPI + +The Portenta C33 supports SPI communication via two dedicated ports named `SPI0` and `SPI1`, which allows data transmission between the board and other SPI-compatible devices. The pins used in the Portenta C33 for the SPI communication protocol are the following: + +| **Arduino Pin Mapping** | **Microcontroller Pin** | +|:-----------------------:|:-----------------------:| +| `8` or `MOSI` | `P900` | +| `10` or `MISO` | `P315` | +| `9` or `SCK` | `P204` | +| `7` or `CS`/`SS` | `P402` | +| `46` or `PIN_SPI1_MOSI` | `P101` | +| `45` or `PIN_SPI1_MISO` | `P100` | +| `47` or `PIN_SPI1_SCK` | `P102` | +| `48` or `PIN_SPI1_CS` | `P103` | + +Please, refer to the [board pinout section](#pinout) of the user manual to find them on the board. Include the [`SPI` library](https://reference.arduino.cc/reference/en/language/functions/communication/spi/) at the top of your sketch to use the SPI communication protocol. The SPI library provides functions for SPI communication: + +```arduino +#include +``` + +In the `setup()` function, initialize the SPI library, define and configure the chip select (`CS`) pin: + +```arduino +void setup() { + // Set the chip select pin as output + pinMode(SS, OUTPUT); + + // Pull the CS pin HIGH to unselect the device + digitalWrite(SS, HIGH); + + // Initialize the SPI communication + SPI.begin(); +} +``` + +To transmit data to an SPI-compatible device, you can use the following commands: + +```arduino +// Replace with the target device's address +byte address = 0x00; + +// Replace with the value to send +byte value = 0xFF; + +// Pull the CS pin LOW to select the device +digitalWrite(SS, LOW); + +// Send the address +SPI.transfer(address); + +// Send the value +SPI.transfer(value); + +// Pull the CS pin HIGH to unselect the device +digitalWrite(SS, HIGH); +``` + +### I2C + +The Portenta C33 supports I2C communication, which allows data transmission between the board and other I2C-compatible devices. The pins used in the Portenta C33 for the I2C communication protocol are the following: + +| **Arduino Pin Mapping** | **Microcontroller Pin** | +|:-----------------------:|:-----------------------:| +| `11`/`SDA0` | `P407` | +| `12`/`SCL0` | `P408` | +| `37`/`SDA1` | `P511` | +| `38`/`SCL1` | `P512` | +| `39`/`SDA2` | `P302` | +| `40`/`SCL2` | `P301` | + +Please, refer to the [board pinout section](#pinout) of the user manual to find them on the board. The I2C pins are also available through the onboard ESLOV connector of the Portenta C33. + +To use I2C communication, include the [`Wire` library](https://reference.arduino.cc/reference/en/language/functions/communication/wire/) at the top of your sketch. The `Wire` library provides functions for I2C communication: + +```arduino +#include +``` + +In the `setup()` function, initialize the I2C library: + +```arduino +// Initialize the I2C communication +Wire.begin(); +``` + +To transmit data to an I2C-compatible device, you can use the following commands: + + +```arduino +// Replace with the target device's I2C address +byte deviceAddress = 0x1; + +// Replace with the appropriate instruction byte +byte instruction = 0x00; + +// Replace with the value to send +byte value = 0xFF; + +// Begin transmission to the target device +Wire.beginTransmission(deviceAddress); + +// Send the instruction byte +Wire.write(instruction); + +// Send the value +Wire.write(value); + +// End transmission +Wire.endTransmission(); +``` + +To read data from an I2C-compatible device, you can use the `requestFrom()` function to request data from the device and the `read()` function to read the received bytes: + +```arduino +// The target device's I2C address +byte deviceAddress = 0x1; + +// The number of bytes to read +int numBytes = 2; + +// Request data from the target device +Wire.requestFrom(deviceAddress, numBytes); + +// Read while there is data available +while (Wire.available()) { + byte data = Wire.read(); +} +``` + +### UART + +The Portenta C33 supports UART communication. The pins used in the Portenta C33 for the UART communication protocol are the following: + +| **Arduino Pin Mapping** | **Microcontroller Pin** | +|:-----------------------:|:-----------------------:| +| `13`/`RX0` | `P110` | +| `14`/`TX0` | `P602` | +| `49` | `P613` | +| `50` | `P614` | +| `53` | `P506` | +| `54` | `P304` | +| `57` | `P805` | +| `58` | `P513` | +| `92` | `P603` | +| `93` | `P604` | + +Please, refer to the board pinout section of the user manual to find them on the board. The UART pins can be used through the built-in ([Serial](https://www.arduino.cc/reference/en/language/functions/communication/serial/)) library functions. + + +To begin with UART communication, you'll need to configure it first. In the `setup()` function, set the baud rate (bits per second) for UART communication: + +```arduino +// Start UART communication at 9600 baud +Serial.begin(9600); +``` + +To read incoming data, you can use a `while()` loop to continuously check for available data with the `Serial.available()` function and read individual characters with the `Serial.read()` function. The code shown above stores the incoming characters in a String variable and process the data when a line-ending character is received: + +```arduino +// Variable for storing incoming data +String incoming = ""; + +void loop() { + // Check for available data and read individual characters + while (Serial.available()) { + // Allow data buffering and read a single character + delay(2); + char c = Serial.read(); + + // Check if the character is a newline (line-ending) + if (c == '\n') { + // Process the received data + processData(incoming); + + // Clear the incoming data string for the next message + incoming = ""; + } else { + // Add the character to the incoming data string + incoming += c; + } + } +} +``` + +To transmit data to another device via UART, you can use the `Serial.write()` function: + +```arduino +// Transmit the string "Hello world! +Serial.write("Hello world!"); +``` + +You can also use the `Serial.print()` and `Serial.println()` functions to send a String without a newline character or followed by a newline character: + +```arduino +// Transmit the string "Hello world!" +Serial.print("Hello world!"); + +// Transmit the string "Hello world!" followed by a newline character +Serial.println("Hello world!"); +``` + +### Wi-Fi® + +The Portenta C33 board features an onboard Wi-Fi® module, the ESP32-C3-MINI-1U module from Espressif Systems®. The ESP32-C3-MINI-1U is a low-power, highly integrated Wi-Fi® and Bluetooth® System-on-Chip (SoC) solution designed for many IoT applications. + +![Onboard Wi-Fi® module of the Portenta C33 board](assets/user-manual-10.png) + +Some of the key capabilities of the ESP32-C3-MINI-1U module are the following: + +- **Wi-Fi® and Bluetooth® connectivity**: The module supports 2.4 GHz Wi-Fi® (802.11 b/g/n) and Bluetooth® 5.0 connectivity. `ArduinoBLE` library support is limited to luetooth® 4.0 at this time. +- **CPU and memory**: It contains a 32-bit RISC-V single-core processor with a clock speed of up to 160 MHz. The chip also has 400 KB of SRAM and 384 KB of ROM. +- **Security features**: It supports various security features, including secure boot, flash encryption, and cryptographic hardware acceleration. +- **Low-power operation**: It supports multiple power modes for different low-power applications, making it suitable for battery-powered devices. + +The Arduino Renesas Core has a built-in library that lets you use the onboard Wi-Fi® module, the `WiFiC3` library, right out of the box. Let's walk through an example code demonstrating some of the module's capabilities. + +***Always connect your board's Wi-Fi® module with its W.FL antenna (included with your board) to avoid damaging it.*** + +The code below showcases how to connect to a Wi-Fi® network, check Wi-Fi® status, connect to a server, send HTTP requests, and receive and print HTTP responses, which are common tasks for an IoT device. + +```arduino +/** + Web Client (Wi-Fi version) + Name: WiFiWebClient.ino + Purpose: This sketch connects to a website via Wi-Fi + + @author Arduino Team + @version 2.0 31/05/12 +*/ + +// Include the necessary libraries for Wi-Fi management and HTTP communication +#include "WiFiC3.h" +#include "WiFiClient.h" +#include "IPAddress.h" +#include "arduino_secrets.h" + +// Define the credentials of the Wi-Fi network to connect to +char ssid[] = SECRET_SSID; // Network SSID +char pass[] = SECRET_PASS; // Network password + +// Define a variable for storing the status of the Wi-Fi connection +int status = WL_IDLE_STATUS; + +// Define the server to which we'll connect +// This can be an IP address or a URL +char server[] = "www.google.com"; + +// Initialize the Wi-Fi client object +// This will be used to interact with the server +WiFiClient client; + +void setup() { + // Begin serial communication at a baud rate of 115200 + Serial.begin(115200); + + // Wait for the serial port to connect + // This is necessary for boards that have native USB + while (!Serial) {} + + // Check for the onboard Wi-Fi module + // If the module isn't found, halt the program + if (WiFi.status() == WL_NO_MODULE) { + Serial.println("- Communication with Wi- Fi module failed!"); + while (true); + } + + // Check if the Wi-Fi module's firmware is up to date + String fv = WiFi.firmwareVersion(); + if (fv < WIFI_FIRMWARE_LATEST_VERSION) { + Serial.println("- Please upgrade the firmware!"); + } + + // Attempt to connect to the defined Wi-Fi network + // Wait for the connection to be established + while (status != WL_CONNECTED) { + Serial.print("- Attempting to connect to SSID: "); + Serial.println(ssid); + status = WiFi.begin(ssid, pass); + delay(10000); + } + + // Print the Wi-Fi connection status + printWifiStatus(); + + // Attempt to connect to the server at port 80 (the standard port for HTTP). + // If the connection is successful, print a message and send a HTTP GET request. + // If the connection failed, print a diagnostic message. + Serial.println("\n- Starting connection to server..."); + if (client.connect(server, 80)) { + Serial.println("- Connected to server!"); + client.println("GET /search?q=arduino HTTP/1.1"); + client.println("Host: www.google.com"); + client.println("Connection: close"); + client.println(); + } else { + Serial.println("- Connection failed!"); + } +} + +/** + Reads data from the client while there's data available + + @param none + @return none +*/ +void read_response() { + uint32_t received_data_num = 0; + while (client.available()) { + + // Actual data reception + char c = client.read(); + + // Print data to serial port + Serial.print(c); + + // Wrap data to 80 columns + received_data_num++; + if (received_data_num % 80 == 0) { + Serial.println(); + } + } +} + +void loop() { + // Read and print the server's response + read_response(); + + // If the server has disconnected, disconnect the client and halt the program + if (!client.connected()) { + Serial.println(); + Serial.println("- Disconnecting from server..."); + client.stop(); + while (true); + } +} + +/** + Prints data from the Wi-Fi connection status + + @param none + @return none +*/ +void printWifiStatus() { + // Print network SSID + Serial.print("- SSID: "); + Serial.println(WiFi.SSID()); + + // Print board's IP address + IPAddress ip = WiFi.localIP(); + Serial.print("- IP Address: "); + Serial.println(ip); + + // Print signal strength + long rssi = WiFi.RSSI(); + Serial.print("- Signal strength (RSSI):"); + Serial.print(rssi); + Serial.println(" dBm"); +} +``` + +First, the necessary libraries are included: + + - The `WiFiC3.h` and `WiFiClient.h` are included at the start, those libraries contains the functionalities required to communicate via Wi-Fi®. + - The SSID and password for the Wi-Fi® network are defined. + +Then, the server is defined ( "www.google.com" in this case) and the Wi-Fi® client object is created to manage the connection to the server. + +Next, in the `setup()` function: + +- The serial port is initialized at a baud rate of 115200. +- The sketch checks for Wi-Fi® module availability and its firmware version, then attempts to connect to the Wi-Fi® network with the defined SSID and password. If the connection is successful, it prints the Wi-Fi® status and attempts to connect to the defined server. If the server connection is successful, it sends a GET request. +- The `read_reponse()` function reads data from the client while there's data available. It wraps the data to 80 columns and prints it to the IDE's Serial Monitor. + +Finally, in the loop() function: + +- The `read_response()` function is called to read any available data. If the server is disconnected, it disconnects the client and enters an infinite loop, halting the sketch. +- The `printWifiStatus()` function prints the connected network SSID, the IP address of the board, and the signal strength (RSSI) to the IDE's Serial Monitor. + +### Ethernet + +The Portenta C33 board features an Ethernet physical layer (PHY) transceiver, the LAN8742AI from Microchip®. The LAN8742AI is a low-power 10BASE-T/100BASE-TX physical layer (PHY) transceiver. This device is responsible for transmitting and receiving data over an Ethernet connection. The transceiver complies with the IEEE 802.3 and 802.3u standards and supports communication with an Ethernet MAC through a standard RMII interface. + +![Onboard Ethernet PHY transceiver of the Portenta C33 board](assets/user-manual-9.png) + +Some of the key capabilities of the LAN8742AI are the following: + +- **Speed and duplex mode**: It can operate at 10 Mbps (10BASE-T) or 100 Mbps (100BASE-TX). It also features auto-negotiation, which means it can automatically determine the best speed and duplex mode for communication. +- **HP Auto-MDIX**: This feature allows you to use a straight-through or crossover Ethernet cable. +- **Wake on LAN (WoL)**: The device can be programmed to detect certain types of packets and trigger an interrupt. +- **Cable diagnostics**: The transceiver can detect issues with the Ethernet cable and determine its location. + +The Arduino Renesas Core has a built-in library that lets you use the onboard Ethernet PHY transceiver right out of the box, the `EthernetC33` library. Let's walk through an example code demonstrating some of the transceiver's capabilities. You can access your board's Ethernet pins through its High-Density connectors or an Arduino Pro carrier board like the [Portenta Breakout](https://store.arduino.cc/products/arduino-portenta-breakout). + +```arduino +/** + Web Client (Ethernet version) + Name: WebClient.ino + Purpose: This sketch connects to a website via Ethernet + + @author Arduino Team + @version 4.0 01/06/18 +*/ + +// Include the Ethernet library +#include + +// Define the server to which we'll connect +// This can be an IP address or a URL +char server[] = "www.google.com"; + +// Set a static IP address to use if the DHCP fails to assign one automatically +IPAddress ip(10, 130, 22, 84); + +// Initialize the Ethernet client object +// This will be used to interact with the server +EthernetClient client; + +void setup() { + // Begin serial communication at a baud rate of 115200 + Serial.begin(115200); + + // Wait for the serial port to connect + // This is necessary for boards that have native USB + while (!Serial); + + // Attempt to start Ethernet connection via DHCP + // If DHCP failed, print a diagnostic message + if (Ethernet.begin() == 0) { + Serial.println("- Failed to configure Ethernet using DHCP!"); + + // Try to configure Ethernet with the predefined static IP address + Ethernet.begin(ip); + } + + delay(2000); + + // Attempt to connect to the server at port 80 (the standard port for HTTP). + // If the connection is successful, print a message and send a HTTP GET request. + // If the connection failed, print a diagnostic message. + Serial.println("- Connecting..."); + if (client.connect(server, 80)) { + Serial.println("- Connected!"); + client.println("GET /search?q=arduino HTTP/1.1"); + client.println("Host: www.google.com"); + client.println("Connection: close"); + client.println(); + } else { + Serial.println("- Connection failed!"); + } +} + +/** + Reads data from the client while there's data available + + @param none + @return none +*/ +void read_request() { + uint32_t received_data_num = 0; + while (client.available()) { + + // Actual data reception + char c = client.read(); + + // Print data to serial port + Serial.print(c); + + // Wrap data to 80 columns + received_data_num++; + if (received_data_num % 80 == 0) { + Serial.println(); + } + } +} + +void loop() { + // Read data from the client + read_request(); + + // If there's data available from the server, read it and print it to the Serial Monitor + while (client.available()) { + char c = client.read(); + Serial.print(c); + } + + // If the server has disconnected, disconnect the client and stop + if (!client.connected()) { + Serial.println(); + Serial.println("- Disconnecting..."); + client.stop(); + + // Halt the sketch by entering an infinite loop + while (true); + } +} +``` + + +First, the necessary libraries are included: + +- The `EthernetC33` library which contains the functionality required to communicate via Ethernet is included in the beginning. + + +Then, the server is defined, which is "www.google.com" in this case: + +- The static IP address which will be used if the DHCP fails to assign an IP address is set. + +- The Ethernet client is initialized with the server's IP address and port. + +Next, in the `setup()` function: + +- The serial port is initialized at a baud rate of 115200. +- An Ethernet connection is attempted; if the DHCP configuration fails, the sketch tries to configure the connection using the static IP address defined before. The usage of a DNS server depends also on the success of the DHCP configuration. +- If the DNS server is used, it connects to the server using the server name; otherwise, it uses the server IP address. If the connection is successful, it sends a `HTTP GET` request to the server. If not, it outputs an error message to the IDE's Serial Monitor. +- The `read_request()` function reads data from the client while there's data available. It wraps the data to 80 columns and prints it to the IDE's Serial Monitor. + +Finally, in the `loop()` function: + +- The `read_request()` function is called to read any available data. If the server is disconnected, it disconnects the client and enters an infinite loop, halting the sketch. + +### Bluetooth® + +The Portenta C33 board features an onboard Bluetooth® module, the ESP32-C3-MINI-1U module from Espressif Systems®. The ESP32-C3-MINI-1U is a low-power, highly integrated Wi-Fi® and Bluetooth® System-on-Chip (SoC) solution designed for many IoT applications. + +![Onboard Bluetooth® module of the Portenta C33 board](assets/user-manual-12.png) + +***Always connect your board's Bluetooth® module with its W.FL antenna (included with your board) to avoid damaging it.*** + +To enable Bluetooth® communication on the Portenta C33, you can use the [`ArduinoBLE` library](https://github.com/arduino-libraries/ArduinoBLE)`ArduinoBLE` library. Let's walk through an example code demonstrating some of its Bluetooth® module's capabilities. Here is an example of how to use the `ArduinoBLE` to create a voltage level monitor application: + +```arduino +// Define the voltage service and its characteristic +BLEService voltageService("1101"); +BLEUnsignedCharCharacteristic voltageLevelChar("2101", BLERead | BLENotify); + +const int analogPin = A0; + +/** + Read voltage level from an analog input of the Nicla Voice, + then maps the voltage reading to a percentage value ranging from 0 to 100. + + @param none + @return the voltage level percentage (int). +*/ +int readVoltageLevel() { + int voltage = analogRead(analogPin); + int voltageLevel = map(voltage, 0, 1023, 0, 100); + return voltageLevel; +} + +void setup() { + // Initialize LEDR as an output + pinMode(LEDR, OUTPUT); + digitalWrite(LEDR, HIGH); + + Serial.begin(9600); + // Wait for the serial connection to be established + while (!Serial) + ; + + // Initialize the BLE module + if (!BLE.begin()) { + Serial.println("- Starting BLE failed!"); + while (1) + ; + } + + // Set the local name and advertised service for the BLE module + BLE.setLocalName("VoltageMonitor"); + BLE.setAdvertisedService(voltageService); + voltageService.addCharacteristic(voltageLevelChar); + BLE.addService(voltageService); + + // Start advertising the BLE service + BLE.advertise(); + Serial.println("- Bluetooth device active, waiting for connections..."); +} + +void loop() { + // Check for incoming BLE connections + BLEDevice central = BLE.central(); + + // If a central device is connected + if (central) { + Serial.print("- Connected to central: "); + Serial.println(central.address()); + + // Set the LED color to red when connected + digitalWrite(LEDR, LOW); + + // While the central device is connected + while (central.connected()) { + // Read the voltage level and update the BLE characteristic with the level value + int voltageLevel = readVoltageLevel(); + + Serial.print("- Voltage level is: "); + Serial.println(voltageLevel); + voltageLevelChar.writeValue(voltageLevel); + + delay(200); + } + } + + // Turn off the LED when disconnected + digitalWrite(LEDR, HIGH); + + Serial.print("- Disconnected from central: "); + Serial.println(central.address()); +} +``` + +The example code shown above creates a Bluetooth® Low Energy service and characteristic for transmitting a voltage value read by one of the analog pins of the Portenta C33 to a central device. + +- The code begins by importing all the necessary libraries and defining the Bluetooth® Low Energy service and characteristic. +- In the setup() function, the code initializes the Portenta C33 board and sets up the Bluetooth® Low Energy service and characteristic; then, it begins advertising the defined Bluetooth® Low Energy service. +- A Bluetooth® Low Energy connection is constantly verified in the loop() function; when a central device connects to the Portenta C33, its built-in red LED is turned on. The code then enters into a loop that constantly reads the voltage level from an analog input and maps it to a percentage value between 0 and 100. The voltage level is printed to the Serial Monitor and transmitted to the central device over the defined Bluetooth® Low Energy characteristic. + +### JTAG + +The Portenta C33 board features a JTAG/SWD debug port accessible through its High-Density connectors. The pins used for the JTAG/SWD debug port are the following: + +| **Functionality** | **Microcontroller Pin** | +|:-----------------:|:-----------------------:| +| `TMS/SWD` | `P108` | +| `TCK/SCK` | `P300` | +| `TDO/SWO` | `P109` | + +You can use a [Portenta Breakout](https://store.arduino.cc/products/arduino-portenta-breakout) with your Portenta C33 board to easily access your board's JTAG/SWD debug port through the individual pins or a dedicated MIPI 20-pin JTAG connector with trace capability. + +### ESLOV Connector + +The Portenta C33 board features an onboard ESLOV connector to extend the I2C communication bus. This connector simplifies connecting various sensors, actuators, and other modules to the Portenta C33 without soldering or wiring; Nicla family boards can also be connected to the Portenta C33 through this connector. + +![Portenta C33 built-in ESLOV connector](assets/user-manual-8.png) + +The ESLOV connector is a small 5-pin connector with a 1.00 mm pitch. The mechanical details of the connector can be found in the [connector's datasheet](https://www.jst-mfg.com/product/pdf/eng/eSH.pdf). + +The pin layout of the ESLOV connector is the following: + +1. VCC +2. INT +3. SCL +4. SDA +5. GND + +`VCC` pin works as a 5 V output if the board is connected to a USB-C® cable. The manufacturer part number of the ESLOV connector is SM05B-SRSS, and its matching receptacle manufacturer part number is SHR-05V-S-B. + +## External Memory + +The Portenta C33 board features an onboard 16 MB QSPI Flash memory, the MX25L12833F from Macronix®. Having an onboard QSPI Flash memory enhances the capabilities of the Portenta C33, enabling you to develop and run more complex and data-intensive applications. + +![Onboard QSPI Flash memory of the Portenta C33 board](assets/user-manual-11.png) + +Some key advantages of having an onboard QSPI Flash memory are the following: + +- **Storage capacity**: The MX25L12833F QSPI Flash memory adds significant non-volatile storage to the board. +- **Extended functionality**: The additional memory space allows more complex applications to be developed and run on your Portenta C33. This application includes data logging, image processing, audio processing, and executing complex algorithms. +- **Firmware updates**: The MX25L12833F QSPI Flash memory can also store firmware or software updates for your Arduino board. This means you can update the firmware without requiring a complete reprogramming of the board. + +The Arduino Renesas Core has built-in libraries and drivers that let you use the onboard QSPI Flash memory immediately. Let's walk through an example code demonstrating some of the onboard Flash memory capabilities; the main tasks performed in the sketch are initializing the Flash memory, writing to a file, and reading from a file. + +```arduino +/** + QSPI Flash File System test + Name: QSPI_Flash_FileSystem_Test.ino + Purpose: This sketch test the onboard QSPI Flash memory + file system by writing and reading a file. + + @author Arduino Team + @version 1.0 20/06/23 +*/ + +// Include necessary libraries and drivers +#include "QSPIFlashBlockDevice.h" +#include "FATFileSystem.h" + +// Define constants for file system and test file name +#define QSPI_FS_NAME "qspi" +#define TEST_FILE "test.txt" + +// Instantiate flash block device and file system +QSPIFlashBlockDevice block_device(PIN_QSPI_CLK, PIN_QSPI_SS, PIN_QSPI_D0, PIN_QSPI_D1, PIN_QSPI_D2, PIN_QSPI_D3); +FATFileSystem fs(QSPI_FS_NAME); + +// Define full path to the test file +std::string file_test_name = std::string("/") + std::string(QSPI_FS_NAME) + std::string("/") + std::string(TEST_FILE); + +void setup() { + // Initialize serial communication and wait a connection + Serial.begin(9600); + while(!Serial); + + // Print test start message + Serial.println(); + Serial.println("- SIMPLE QSPI FLASH TEST"); + Serial.println(); + + // Try to mount the QSPI Flash file system + // If mounting fails, try to format the file system + int err = fs.mount(&block_device); + if (err) { + Serial.println("- No filesystem found, formatting... "); + err = fs.reformat(&block_device); + } + if (err) { + // If formatting fails, print error and halt + Serial.println("- Error formatting QSPI Flash "); + while(1); + } + + // Try to open a test file for writing + // If file opened successfully, write some text to the file + FILE* fp = fopen(file_test_name.c_str(), "w"); + if(fp != NULL) { + Serial.println("- Opened file for writing!"); + char text[] = "Hello from QSPI Flash!\n"; + fwrite(text, sizeof(char), strlen(text), fp); + // Always close the file after writing to save changes + fclose(fp); + } + else { + // If file opening fails, print an error message + Serial.print("- Failed to open file for writing: "); + Serial.println(file_test_name.c_str()); + } + + // Try to open the test file for reading + // If file opened successfully, read and print its content + fp = fopen(file_test_name.c_str(), "r"); + if(fp != NULL) { + Serial.println("- Opened file for reading!"); + char ch; + while(fread(&ch, sizeof(char), 1, fp) == 1) { + Serial.print(ch); + } + // Always close the file after reading + fclose(fp); + } + else { + // If file opening fails, print an error message + Serial.print("Failed to open file for reading: "); + Serial.println(file_test_name.c_str()); + } +} + +void loop() {} +``` + +Here's what each section of the example code does: + +- **Initialize the onboard Flash memory**: After setting up the Serial port, the sketch tries to mount the QSPI Flash file system. If the file system is not found, the code formats the memory to set up a new file system. If there's an error during this process, the code will halt and print an error message to the IDE's Serial Monitor. +- **Write to a file**: Next, the sketch attempts to open a file named `test.txt` in `write` mode. If this process is successful, it writes the string `Hello from QSPI Flash!` to the file and then closes it. If it cannot open the file, it will print an error message to the IDE's Serial Monitor. +- **Read from a file**: After writing to the file, the sketch attempts to open the same file, but this time in 'read' mode. If successful, it will read the content of the file one character at a time and print each character to the IDE's Serial Monitor. After reading, it closes the file. If it cannot open the file for reading, it will print an error message to the IDE's Serial Monitor. + +## Secure Element + +The Portenta C33 features a secure element onboard, the SE050 from NXP®. A secure element is a component that can store sensitive data and run secure apps; it acts as a vault, protecting what is inside the secure element from attacks. A secure element simplifies the implementation of robust security mechanisms, reducing time to market without requiring specialized security expertise. + + +![Onboard secure element of the Portenta C33 board](assets/user-manual-7.png) + +The SE050 is a ready-to-use IoT secure element that provides a root of trust at the IC level and gives an IoT system state-of-the-art, edge-to-cloud security capability. It allows for securely storing and provisioning credentials and performing cryptographic operations for security-critical communication and control functions. The Arduino Renesas Core has a built-in library that lets you use the secure onboard element right out of the box, the `SE05X` library. + +The Arduino sketch below can help you start with the SE050 and demonstrate its capabilities. The example code generates a new Elliptic Curve (EC) key pair (NIST Curve P-256), signs a SHA256 hash of a predefined input with the private key, and verifies the signature with the public key. + +```arduino +/** + SE05X Import and Verify + Name: import_public_key.ino + Purpose: This sketch generates a new EC NIST P-256 key pair, + signs a SHA256 hash of a predefined input with the private key, + and verifies the signature with the public key. + + @author Arduino HW/FW team, modified by Arduino PRO Content Team + @version 1.0 08/06/23 +*/ + +// Include the SE05X library +#include + +// Define IDs for the private and public keys +const int PRIVATE_KEY_ID = 999; +const int PUBLIC_KEY_ID = 899; + +// Define the input buffer +const byte input[64] = { + 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f, + 0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f, + 0x20, 0x21, 0x22, 0x23, 0x24, 0x25, 0x26, 0x27, 0x28, 0x29, 0x2a, 0x2b, 0x2c, 0x2d, 0x2e, 0x2f, + 0x30, 0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37, 0x38, 0x39, 0x3a, 0x3b, 0x3c, 0x3d, 0x3e, 0x3f +}; + +/** + Print a buffer in hexadecimal format. + + @param input buffer to print in hexadecimal format. + @param inputLenght input buffer length. + @return none. +*/ + +// Function to print a buffer in hexadecimal format +void printBufferHex(const byte input[], size_t inputLength) { + for (size_t i = 0; i < inputLength; i++) { + Serial.print(input[i] >> 4, HEX); // Print the high nibble + Serial.print(input[i] & 0x0f, HEX); // Print the low nibble + } + Serial.println(); +} + +void setup() { + // Initialize serial port with a baud rate of 9600, wait for a connection. + Serial.begin(9600); + while (!Serial); + + // Initialize the secure element. If the initialization fails, print an error message and halt. + if (!SE05X.begin()) { + Serial.println("- Failed to communicate with secure element!"); + while(1); + } + + // Create a buffer for DER-encoded key and define its size. + byte derBuf[256]; + size_t derSize; + + // Generate a new private key with the defined ID. + SE05X.generatePrivateKey(PRIVATE_KEY_ID, derBuf, sizeof(derBuf), &derSize); + + // Print the input buffer on the Serial Monitor. + Serial.print("- Input is: "); + printBufferHex(input, sizeof(input)); + + // Calculate and print the SHA256 hash of the input buffer on the Serial Monitor. + byte sha256[256]; + size_t sha256Len; + SE05X.SHA256(input, sizeof(input), sha256, sizeof(sha256), &sha256Len); + Serial.print("- Input SHA256 is: "); + printBufferHex(sha256, sha256Len); + + // Sign the SHA256 hash with the generated private key. + byte signature[256]; + size_t signatureLen; + SE05X.Sign(PRIVATE_KEY_ID, sha256, sha256Len, signature, sizeof(signature), &signatureLen); + + // Print the signature on the Serial Monitor. + Serial.print("Signature using KeyId "); + Serial.print(PRIVATE_KEY_ID); + Serial.print(" is: "); + printBufferHex(signature, signatureLen); + Serial.println(); + + // Import the public key to the secure element using the public key ID and the DER-encoded key. + SE05X.importPublicKey(PUBLIC_KEY_ID, derBuf, derSize); + + // To make the signature verification fail, uncomment the next line: + // signature[0] = 0x00; + + // Verify the signature. If the verification fails, print an error message on the Serial Monitor. + if (SE05X.Verify(PUBLIC_KEY_ID, sha256, sha256Len, signature, signatureLen)) { + Serial.println("Verified signature successfully :D"); + } else { + Serial.println("- Failed to verify signature!"); + } +} + +// Loop function +void loop() { + // This function remains empty, as no repetitive task needs to be done in this example. +} +``` + +Here's what each section of the example code does: + +- **Input buffer initialization**: The sketch begins by initializing a 64-byte input buffer. +- **Buffer print function**: A function named `printBufferHex()` is defined to print the contents of a buffer in hexadecimal format to the IDE's Serial Monitor. +- **Secure element initialization**: In the `setup()` function, communication with the secure element is initiated. If it fails, an error message is shown in the IDE's Serial Monitor, and the program is halted. +- **Private key generation**: The secure element generates an Elliptic Curve (EC) NIST P-256 private key. The key ID is set to 999, and the generated key is returned in DER format. +- **Input hash and signature**: The SHA256 hash of the input buffer is computed and printed, then signed using the generated private key. +- **Public key import**: The public key derived from the generated private key is imported to the secure element with key ID 899. +- **Signature verification**: The example code then verifies the signature using the imported public key and prints a success or failure message accordingly. + +## Support + +If you encounter any issues or have questions while working with the Portenta C33, we provide various support resources to help you find answers and solutions. + +### Help Center + +Explore our Help Center, which offers a comprehensive collection of articles and guides for the Portenta C33. The Arduino Help Center is designed to provide in-depth technical assistance and help you make the most of your device. + +- Portenta C33 help center page + +### Forum + +Join our community forum to connect with other Portenta C33 users, share your experiences, and ask questions. The forum is an excellent place to learn from others, discuss issues, and discover new ideas and projects related to the Portenta C33. + +- [Portenta C33 category in the Arduino Forum](https://forum.arduino.cc/c/hardware/portenta/portenta-c33/183) + +### Contact Us + +Please get in touch with our support team if you need personalized assistance or have questions not covered by the help and support resources described before. We're happy to help you with any issues or inquiries about the Portenta C33. + +- [Contact us page](https://www.arduino.cc/en/contact-us/) \ No newline at end of file diff --git a/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/hero-banner.png b/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/hero-banner.png new file mode 100644 index 0000000000..8f5a7db24a Binary files /dev/null and b/content/hardware/04.pro/boards/portenta-c33/tutorials/user-manual/hero-banner.png differ diff --git a/content/software/plc-ide/tutorials/plc-programming-introduction/assets/plcide-library-management.gif b/content/software/plc-ide/tutorials/plc-programming-introduction/assets/plcide-library-management.gif new file mode 100644 index 0000000000..81a74302b7 Binary files /dev/null and b/content/software/plc-ide/tutorials/plc-programming-introduction/assets/plcide-library-management.gif differ diff --git a/content/software/plc-ide/tutorials/plc-programming-introduction/content.md b/content/software/plc-ide/tutorials/plc-programming-introduction/content.md index 3d5ccd25db..9200df814b 100644 --- a/content/software/plc-ide/tutorials/plc-programming-introduction/content.md +++ b/content/software/plc-ide/tutorials/plc-programming-introduction/content.md @@ -1,5 +1,5 @@ --- -title: 'Programming Introduction With Arduino® PLC IDE' +title: 'Programming Introduction with Arduino® PLC IDE' difficulty: intermediate description: "Create programs with all the IEC-61131-3 languages on the Arduino PLC IDE." tags: @@ -27,9 +27,10 @@ The goals of this tutorial are: ### Required Hardware and Software -- [Arduino® Portenta Machine Control](https://store.arduino.cc/products/arduino-portenta-machine-control) +- [Portenta Machine Control](https://store.arduino.cc/products/arduino-portenta-machine-control) ## Common Features + ### Variables Addition There are 2 types of variables: @@ -37,6 +38,7 @@ There are 2 types of variables: * Local variables: Only one program has access to it. #### Global Variable + Click inside the **Project** tab and click the **Global_vars** section, a table is available to see the full list of global variables on your project. To add a new one, right-click on the table and click the **insert** button. @@ -61,6 +63,7 @@ Following the same steps explained previously, you can right-click the table, an A new variable will be added with default settings, double-click each of them to change them as you need. ### Adding Blocks + The blocks are features or functions available from libraries and the PLC IDE. These will help you to perform tasks, like AND gates, ADD function, etc... @@ -71,6 +74,7 @@ To add a block to your program (only possible with LD, SFC, FBD) you can drag an Once you drag and drop it on your canvas it will generate a block with some input and output pins fully customizable, most of the time you can right-click the block and add more pins in case you need more than the default. ### Task Attachment + Once you have your programs you can attach them to a task inside the runtime. There are 4 Tasks: @@ -100,10 +104,28 @@ Inside the **Tool window** you can drag and drop variables, or click the **Inser ![Watch a variable](assets/watch.png) +### Library Management + +In contrast to the conventional Arduino IDE, the PLC IDE manages the library add-on and usage differently. To add the desired library, go to **Resources** tab and click the **Libraries** listed under the **Sketch**. + +![Adding a library to the PLC IDE Arduino Sketch](assets/plcide-library-management.gif) + +With the 'Sketch Libraries' window open, click the **Add** option and fill out the library name. You will have to fill in the needed library version as well. + +For example, if you want to add the 1.1.1 version of the 'Arduino_MachineControl' library, respective information must be introduced to its fields accordingly. + +It is possible to find this information using the [Arduino Library List](https://www.arduinolibraries.info/) or referencing the indexed library on your development environment if you have downloaded it to use within Arduino IDE. By navigating manually to the local libraries directory on your development environment, you can access the meta-data from the 'library.properties' of the desired library. + +***Currently only publicly available libraries can be added to the PLC IDE Arduino Sketch, and you can check its availability by searching in the [Arduino Library List](https://www.arduinolibraries.info/).*** + +Once you have followed the previous steps, the libraries will be available for use. A library of choice can be removed by clicking on the **Remove** option within the 'Sketch Libraries' window. + ## Sample Program + The program will be a simple counter, increasing the count by X over time. ### Arduino Sketch + ```cpp int count = 0; const int addition = 1; @@ -115,6 +137,7 @@ void loop(){ ``` ### IEC-61131-3 Languages + To create a new program open your project tab, go to the toolbar **Project > New object > New program**, set a name for your program and select its language. ![New program from Project's drop-down menu](assets/newProgram.png) @@ -131,6 +154,7 @@ There are 5 languages available: * Function Block Diagram (FBD) ### Structured Text + This language is similar to C, the code to assign a value to a variable is the following: ``` count := count + addition; @@ -139,6 +163,7 @@ count := count + addition; ![Structured Text counter program](assets/STprogram.png) ### Instruction List + This programming language is similar to Assembly programming. The code for a counter script is: @@ -151,6 +176,7 @@ ST count ![Instruction List counter program](assets/ILprogram.png) ### Ladder Diagram + This programming environment is based on lines and blocks, a line has a path from left to right that needs to pass all the in between blocks in order to continue towards the right, if it does pass all the different blocks (like AND gates) it will end on the right on a brackets symbol (coil) triggering whatever you have set up to do, which could be for example a relay latching to Normally-Open (NO). This is how a counter program looks: @@ -160,11 +186,13 @@ Here is a video doing that from scratch: ### Sequential Function Chart + This language approaches the script in a similar way as a flowchart, meaning you have blocks that do some work, you check the result of that work, and afterward you keep flowing with the choices. SFC language can not interact directly with the machine, meaning you can not make an output be OFF directly, to do so you will need to create **actions** #### Actions + An action is a script in another language (i.e. structured text) that performs the work, this will get triggered depending on the chart. To create one go to your project tree, right-click the SFC script and click the "New action" button. @@ -172,6 +200,7 @@ To create one go to your project tree, right-click the SFC script and click the ![Creating new action](assets/newAction.png) #### SFC Program + You have blocks available by right-clicking inside the canvas or on the top bar, you can drag and drop them. The SFC program has one rule which is following the order of **Step0 > Transition0 > Stepn > Transitionn > ... > Jump** @@ -187,6 +216,7 @@ Here is a video doing that from scratch: ### Functional Block Diagram + This is similar to the SFC Programming, but in this case there is no sequential path on the program, you add blocks to do the needed work. For example, adding the **Add** block will do the Add function each cycle. @@ -200,6 +230,7 @@ Here is a video doing that from scratch: ***In the previous programs, we used local variables, remember to select the program's specific variables to be watched, or you will not see any data*** ## Conclusion + You have: * Created a simple counter with each language * Learned how to watch live variable's value diff --git a/package-lock.json b/package-lock.json index 1e6dececb2..e1e6b460e2 100644 --- a/package-lock.json +++ b/package-lock.json @@ -10,7 +10,7 @@ "hasInstallScript": true, "license": "ISC", "dependencies": { - "@arduino/docs-arduino-cc": "^1.8.97", + "@arduino/docs-arduino-cc": "^1.9.1", "gatsby": "^4.9.2" } }, @@ -319,9 +319,9 @@ } }, "node_modules/@arduino/docs-arduino-cc": { - "version": "1.8.97", - "resolved": "https://npm.pkg.github.com/download/@arduino/docs-arduino-cc/1.8.97/75db39fc671f3f7cba9bc280d6c6510a17a97b2e", - "integrity": "sha512-MPH4ukZd71itAMfKJ1FJP6y0hf1N2Fq9zm7mYbsYLKUuQG6fPOVHipGOwUfiQLRpadaytf4dsyGoGvu/ldU67w==", + "version": "1.9.1", + "resolved": "https://npm.pkg.github.com/download/@arduino/docs-arduino-cc/1.9.1/883b298b5b67195b3638d2b80eb80ea77ffbbfd5", + "integrity": "sha512-2AxAodcyPyzLii05hqlY4yQH16E2weISxJIndzKngWmZbnbiP60L4uteqL19i9H0ngS6gTT1FiLN/B1BWl8e1w==", "dependencies": { "@algolia/autocomplete-core": "^1.5.3", "@algolia/autocomplete-preset-algolia": "^1.5.3", @@ -330,14 +330,15 @@ "@bcmi-labs/sass": "^3.0.1", "@mdx-js/mdx": "^1.6.22", "@mdx-js/react": "^1.6.22", + "@parcel/core": "^2.8.3", + "@parcel/plugin": "^2.8.3", "@serjlee/gatsby-plugin-algolia": "0.21.1-sharedindex", "algoliasearch": "^4.12.2", "animated-scroll-to": "^2.2.0", "classnames": "^2.3.1", "date-fns": "^2.28.0", "deepmerge": "^4.2.2", - "dotenv": "^16.1.4", - "gatsby": "^4.9.2", + "gatsby": "^4.9.0", "gatsby-background-image": "^1.6.0", "gatsby-image": "^3.11.0", "gatsby-plugin-gatsby-cloud": "^4.9.0", @@ -13173,11 +13174,11 @@ } }, "node_modules/dotenv": { - "version": "7.0.0", - "resolved": "https://registry.npmjs.org/dotenv/-/dotenv-7.0.0.tgz", - "integrity": "sha512-M3NhsLbV1i6HuGzBUH8vXrtxOk+tWmzWKDMbAVSUp3Zsjm7ywFeuwrUXhmhQyRK1q5B5GGy7hcXPbj3bnfZg2g==", + "version": "8.6.0", + "resolved": "https://registry.npmjs.org/dotenv/-/dotenv-8.6.0.tgz", + "integrity": "sha512-IrPdXQsk2BbzvCBGBOTmmSH5SodmqZNt4ERAZDmW4CT+tL8VtvinqywuANaFu4bOMWki16nqf0e4oC0QIaDr/g==", "engines": { - "node": ">=6" + "node": ">=10" } }, "node_modules/dotenv-expand": { @@ -28559,9 +28560,9 @@ } }, "@arduino/docs-arduino-cc": { - "version": "1.8.97", - "resolved": "https://npm.pkg.github.com/download/@arduino/docs-arduino-cc/1.8.97/75db39fc671f3f7cba9bc280d6c6510a17a97b2e", - "integrity": "sha512-MPH4ukZd71itAMfKJ1FJP6y0hf1N2Fq9zm7mYbsYLKUuQG6fPOVHipGOwUfiQLRpadaytf4dsyGoGvu/ldU67w==", + "version": "1.9.1", + "resolved": "https://npm.pkg.github.com/download/@arduino/docs-arduino-cc/1.9.1/883b298b5b67195b3638d2b80eb80ea77ffbbfd5", + "integrity": "sha512-2AxAodcyPyzLii05hqlY4yQH16E2weISxJIndzKngWmZbnbiP60L4uteqL19i9H0ngS6gTT1FiLN/B1BWl8e1w==", "requires": { "@algolia/autocomplete-core": "^1.5.3", "@algolia/autocomplete-preset-algolia": "^1.5.3", @@ -28570,14 +28571,15 @@ "@bcmi-labs/sass": "^3.0.1", "@mdx-js/mdx": "^1.6.22", "@mdx-js/react": "^1.6.22", + "@parcel/core": "^2.8.3", + "@parcel/plugin": "^2.8.3", "@serjlee/gatsby-plugin-algolia": "0.21.1-sharedindex", "algoliasearch": "^4.12.2", "animated-scroll-to": "^2.2.0", "classnames": "^2.3.1", "date-fns": "^2.28.0", "deepmerge": "^4.2.2", - "dotenv": "^16.1.4", - "gatsby": "^4.9.2", + "gatsby": "^4.9.0", "gatsby-background-image": "^1.6.0", "gatsby-image": "^3.11.0", "gatsby-plugin-gatsby-cloud": "^4.9.0", diff --git a/package.json b/package.json index 20a82f927f..9c185c0c99 100644 --- a/package.json +++ b/package.json @@ -18,7 +18,7 @@ }, "homepage": "https://github.com/arduino/docs-content#readme", "dependencies": { - "@arduino/docs-arduino-cc": "^1.8.97", + "@arduino/docs-arduino-cc": "^1.9.1", "gatsby": "^4.9.2" }, "volta": {