diff --git a/content/arduino-cloud/09.business/09.arduino-cloud-for-business/content.md b/content/arduino-cloud/09.business/09.arduino-cloud-for-business/content.md new file mode 100644 index 0000000000..555d0ce7e4 --- /dev/null +++ b/content/arduino-cloud/09.business/09.arduino-cloud-for-business/content.md @@ -0,0 +1,428 @@ +--- +beta: true +title: 'Getting started with Arduino Cloud for Business' +description: 'Get a general overview of Arduino Cloud for Business and its features' +difficulty: intermediate +tags: + - Arduino Cloud + - Fleet Management + - RBAC +author: 'Marta Barbero' +software: + - iot-cloud +--- + + +## Overview + +The [Arduino Cloud for Business](https://www.arduino.cc/pro/software-arduino-iot-cloud/) is an Arduino Cloud plan dedicated to companies and industrial clients wanting enhanced features in terms of device management, Role-Based Access Control (RBAC), fleet management, and safe remote access. + +In this article, you will get a general overview of the major features of the Arduino Cloud for Business. + +If you are not familiar with Arduino Cloud, we strongly recommend you to take a look at the following documentation: + +* To find all tutorials & articles, visit the [Arduino Cloud Documentation page](https://docs.arduino.cc/cloud/iot-cloud). +* For API & SDK Documentation, visit the developer reference at [Arduino Cloud API](https://www.arduino.cc/reference/en/iot/api/). + +## Goals + +* Get in-depth information about how the Arduino Cloud for Business works +* Learn about the multiple dedicated features Arduino Cloud for Business provides +* Learn how to get started with Arduino Cloud for Business + +## Required Software + +* [Arduino Cloud for Business](https://cloud.arduino.cc/plans#business) + +## Purchase An Arduino Cloud For Business Plan + +In order to get started with Arduino Cloud for Business, you need to [subscribe to a plan](https://cloud.arduino.cc/plans#business). + +The Arduino Cloud for Business plan consists of two main subscriptions: + +* **Enterprise Base Plan.** It includes all the Arduino Cloud for Business features, like data plane, fleet management, Role-Based-Access-Control, Web Editor with Over-the-air updates, IoT Cloud with dashboards, etc. Multiples of 50 devices can be connected under the Enterprise Base Plan – and you can always [contact our team](https://www.arduino.cc/pro/contact-us) for a tailored plan to accelerate your IoT solutions. + +* **Optional Add-Ons.** To address additional needs, Arduino Cloud for Business can be customized with optional add-ons. Check the [dedicated section](#optional-add-ons) of this tutorial to learn more. + +If you do not need any tailored plan, go to [Arduino Cloud for Business page](https://cloud.arduino.cc/plans#business) and select **Purchase**. You will be then asked to log in with your Arduino credentials. If you do not have an account yet, feel free to create a new one. + +![Arduino Cloud login](assets/arduino-account-login.png "Arduino Cloud login") + +It is now time to customize your plan. Select the billing frequency you prefer and the number of Things (and so devices) that you would like to connect with your Arduino Cloud for Business workspace. Click on **Continue**. + +![Customize your plan](assets/plan-customization.png "Customize your plan") + +Proceed by marking the optional add-ons you may need in your projects and click on **Add billing information**. To learn more about these add-ons, check the [dedicated section](#optional-add-ons) of the present getting started guide. + +![Add-ons section](assets/add-on-selection.png "Add-ons section") + +In the next steps, add all your billing and payment information and then purchase your plan. + +Now you are ready to get started with your brand new Arduino Cloud for Business plan. + +Check the next sections to understand how to set up your account and which features are included in your plan. + +## Manage Your Spaces + +Once your plan has been successfully activated, you will be asked to define the company/space name for your workspace. You are free to modify it later by navigating to `Arduino Cloud > Space Settings > General` and clicking on `Edit Info` within the three dots located at the top right side. + +![Create new shared space](assets/create-new-space.png "Create new shared space") + +Your Arduino Cloud for Business plan comes with two spaces by default: + +* **My Cloud**. My Cloud is an automatically created private space once the Arduino Cloud for Business plan is purchased. You can use this space for personal projects you do not want to share with all your team. This space is free and includes two Things, unlimited dashboards, and 100MB of Sketch storage by default, but it can be further extended and customized within *My plans* settings. Have a look at the [Arduino IT Cloud Getting Started](https://docs.arduino.cc/arduino-cloud/guides/overview) if you would like to start using your private space. + +* **Shared Space**. A *Shared Space* is a company space you can use with all your team. It can have any number of members, who can all access the resources within its space. The access level and specific permissions can be customized by the *Space Admin* (see [Invite members into your space section](#invite-members-into-your-space) to learn more). + +In the next sections, you will learn more about Shared Space features and functionalities. + +### Switch Between Spaces + +If you are the owner of more than one Shared Space or have been invited into a Shared Space by another user, you can switch to other Shared Spaces at any time using the corresponding menu. + +Move your mouse over the account button, which you can find at the top left-hand corner, and click on it. All the Spaces you have access to will be listed there. + +![Switch between Spaces](assets/switch-spaces.png "Switch between Spaces") + +If you have four shared spaces or more, it will show you a button named **Switch space**. + +![Switch Space Selector](assets/switch-spaces-multiple-option.png "Switch Space Selector") + +Clicking on the **Switch space** option will display all your spaces within the account. + +![Multiple Spaces](assets/switch-spaces-multiple.png "Multiple Spaces") + +The Space-Selector shows you which space you are currently working on at any time, in this case, *Test*. To switch to another Space, select the space you would like to work on. + +### Change Shared Space Settings + +To change the current settings of your Shared Space, navigate to the **Space Settings** tab using the sidebar. + +![Shared Space settings](assets/shared-space-settings.png "Shared space settings") + +There, you will find multiple options to customize your Shared Space: + +* **General** tab to view shared space information and to edit space name +* **Custom Branding** to assign custom logo +* **Manage Members** for space member management +* **Roles & Permissions** for Role-Based-Access-Control management +* **Plan Usage** to view features usage + +### Create Additional Spaces + +The Arduino Cloud for Business plan allows you to create and manage one Shared Space and one Private Space. If you need additional Spaces, you have to purchase a new Arduino Cloud plan. Check the available plans [here](https://cloud.arduino.cc/plans). + +### Invite Members Into Your Space + +To add more members to your Shared Space, use the sidebar to navigate to the **Manage Members** item under **Space Settings**. + +![List of Shared Space Members](assets/members-home.png "List of Shared Space Members") + +There you will find the complete list of all members who have access to your Shared Space, as well as the role of each member. + +#### Members Types + +There are multiple role types in Arduino Cloud for Business to allow the admin to have full control of the rights/permissions each user has in the Shared Space. In this way, the admin can set up Role-Based-Access-Control (RBAC) by assigning profiles and sharing with any number of users. + +By default the member who has activated the plan and created the workspace is set as Admin. The Role-Based-Access-Control can support multiple Admins with same permissions. + +The table below reports the list of supported roles and corresponding permissions. + +| **Things** | **Admin** | **Editor** | **Service Account** | +|-----------------------------------|-----------|------------|---------------------| +| Create/edit/delete things | X | X | | +| Create/edit/delete variables | X | X | | +| Create/edit/delete webhooks (API) | | | X | +| View Things | X | X | | +| Edit sketches | X | X \[1\] | | +| Change associated devices | X | X | | +| Change network | X | X \[2\] | | + +| **Dashboards** | **Admin** | **Editor** | **Service Account** | +|-------------------------------|-----------|------------|---------------------| +| Create/edit/delete dashboards | X | X | | +| Create/edit/delete widgets | X | X | | +| View dashboards | X | X | | +| Widgets interaction | X | X | | +| Download historic data | X | X | | + +| **Devices** | **Admin** | **Editor** | **Service Account** | +|-------------------------|-----------|------------|---------------------| +| Add/edit/delete devices | X | X | | +| View devices | X | X | | + +| **Members Management** | **Admin** | **Editor** | **Service Account** | +|-----------------------------|-----------|------------|---------------------| +| Add members to organization | X | | | +| Assign members’ roles | X | | | + +| **Plan Management** | **Admin** | **Editor** | **Service Account** | +|---------------------|-----------|------------|---------------------| +| Payment | X | | | + +\[1\] It can add/remove only Sketch owner. +\[2\] It can add/remove only Thing owner. + +In addition to editor role, we added a Service Account, which should be one dedicated to the creation and maintenance of API Keys Tokens. We recommend having at least one Service Account for each Shared Space and linking it to a non-personal email account. In this way, API Keys do not risk getting lost with the cancellation of a personal email address. + +#### Add A New Member + +To add a new member, click on **ADD MEMBERS** in the top right-hand corner. + +![Add a new member](assets/members-home.png "Add a new member") + +The following page will appear to allow you to send an email invitation to all the members you would like to join your Space. + +![New member invitation](assets/new-member-invitation.png "New member invitation") + +Type the email addresses of all your team and define which role they will cover in your Space based on the available options. Click on **INVITE**. + +The users you added will get the invitation by email with a link to join your Shared Space. You are now ready to start working all together on your Arduino Cloud projects. + +## Device Management + +The Arduino Cloud for Business allows for device management with Over-The-Air updates, secure provisioning to connect boards leveraging their secure element, and easy verification of their status (connected, not connected) and maintenance. + +### Compatible Hardware + +The Arduino Cloud for Business is compatible with multiple Arduino boards or devices based on the ESP32 / ESP8266 microcontrollers. The Arduino Cloud currently supports devices connected via Wi-Fi®, Ethernet, LoRaWAN® (via The Things Network), and cellular connectivity. + +To check the full list of compatible Hardware, have a look at [this tutorial](https://docs.arduino.cc/arduino-cloud/guides/overview). + +### Device Provisioning + +Arduino Cloud allows you to securely provision your devices through two different tools: + +* **Arduino Cloud.** Arduino Cloud is an App integrated into your Arduino Cloud Space, guaranteeing straightforward provisioning of Arduino or other Cloud-compatible devices. It is provided with a dedicated User Interface which will guide you step-by-step during the onboarding process. This is a great choice in case you need to provision a few devices or you are not an advanced user. + +* **Arduino Cloud CLI.** As explained in [this section](#arduino-cloud-cli), Arduino has developed a command line tool enabling the access of all Arduino Cloud features from a terminal window. Arduino Cloud CLI is the right choice when you need to provision multiple devices at the same time and you are an advanced user. + +#### Device Provisioning With Arduino Cloud + +If your device is compatible with Arduino Cloud, you can start provisioning it into your Shared Space by connecting it to your computer through a USB cable. + +In addition, Arduino Cloud requires your computer to have the [Arduino Create Agent installed](https://create.arduino.cc/getting-started/plugin/welcome). + +Let's begin by relocating to your Shared Space when you are all set up correctly. + +![Arduino Cloud button](assets/iot-cloud-button.png "Arduino Cloud button") + +Go to the **Devices** item within the sidebar, where it will list all the added devices. Since no devices have been added yet, it will show the option to add a device as the main option on the page. + +![Devices page](assets/devices-list-page.png "Devices page") + +click on **ADD DEVICE** and decide which type of device you would like to onboard. In this case, a Portenta H7 board will be used. + +![Device selection](assets/device-onboarding.png "Device selection") + +The agent will start looking for your board. When your board has been found, the following screen will appear. Click on **CONFIGURE**. + +![Device configuration during provisioning](assets/portenta-found.png "Device configuration during provisioning") + +Select a board name to be able to correctly identify your device and click on **NEXT**. + +![Device name configuration](assets/device-name-configuration.png "Device name configuration") + +Define the connection type you want to use with your board and click on **NEXT**. The agent will start securely provisioning your device by leveraging the secure element embedded in your board. This way, your security keys will be stored in the secure element and full data encryption will be guaranteed during data exchanges between Arduino devices and the Cloud. + +***If you want to learn more about security in Arduino Cloud, please check the [dedicated documentation](https://docs.arduino.cc/arduino-cloud/features/security-considerations).*** + +If the onboarding proceeds as expected, the following page will appear confirming that your device has been successfully provisioned in Arduino Cloud. + +![Successful provisioning](assets/provisioning-success.png "Successful provisioning") + +You can now check its status under the Devices section. This section displays the name, status, and linked Things for each of the configured devices. Clicking on the device allows for renaming it, as well as accessing more information about the device, such as its ID number, type, FQBN, firmware version, associated Thing, latest activity, and the date when the device was added. + +The device status indicates whether it is connected to the Arduino Cloud (online), or not connected (offline). + +![List of devices in your Arduino Cloud](assets/devices-list.png "List of devices in your Arduino Cloud") + +If you click on the added device, it is possible to look into its details. The details can be its device properties, device status history, and device Over-The-Air updates. + +![Device detail](assets/device-detail-information.png "Device detail") + +### Assign A Thing To Your Device + +As already said, once a device is successfully configured, it appears in the "Devices" list and can be used to create a Thing, or can be linked to an existing Thing. + +To use your devices in IoT Cloud, you need to associate a Thing with each of them. A Thing is the digital twin of your device, holding the configuration of some variables and other settings, as well as the history of the data collected for those variables. + +To create a Thing, click on **CREATE THING** found within **Things** page accessed via the Shared Space sidebar. + +![Create a new Thing](assets/create-thing.png "Create a new Thing") + +***If you want to understand how to work with your Things, check the dedicated documentation available [here](https://docs.arduino.cc/arduino-cloud/guides/overview#3-creating-a-thing).*** + +***Do you want to learn more about the different types of Variables and their features? Have a look at [this tutorial](https://docs.arduino.cc/arduino-cloud/getting-started/cloud-variables).*** + +### Device Programming + +It is now time to start uploading sketches on your devices. + +The Arduino Cloud has a feature capable of creating some pre-built sections of the sketch related to a Thing, including some libraries necessary to interact with the cloud variables, as well as directly populating and updating the sketch once the new cloud variables are created and defined. + +The sketch related to the thing is visible from the tab "Sketch" next to the "Setup" view, where the Thing's list of cloud variables is shown. + +![Web Editor - Full Editor](assets/sketch-full-editor.png "Get started with the Web Editor") + +From this sketch view, by clicking the **Open full editor**, it is fast and smooth to access the Arduino Cloud integrated [Web Editor](https://docs.arduino.cc/learn/starting-guide/the-arduino-web-editor), which allows you to program your boards from any browser and use the latest Arduino IDE features and libraries without having to install any software locally. + +Otherwise, to open the Web Editor to retrieve your sketches directly, go to Arduino Cloud Home and click on the [New Sketch File](https://create.arduino.cc/editor) button. + +![Get started with the Web Editor](assets/web-editor-button.png "Get started with the Web Editor") + +It can also be accessed directly by navigating to **Sketches** within the Shared Space sidebar. It will list all the available developed sketches. Clicking on one of the sketches will directly take you to the [Web Editor](https://docs.arduino.cc/learn/starting-guide/the-arduino-web-editor). + +***To get started with the Web Editor, check the dedicated tutorial at [this link](https://docs.arduino.cc/arduino-cloud/getting-started/getting-started-web-editor). However, if you have already developed your sketch and you would like to import it into the Web Editor, see the corresponding documentation [here](https://docs.arduino.cc/arduino-cloud/tutorials/import-your-sketchbook-and-libraries-to-the-web-editor)*** + +All the created sketches are individual and owned by the user that created them. Other members of the Shared Space can access your sketch in their Web Editor only if you share it with them. If you would like to do so, have a look at [this tutorial](https://docs.arduino.cc/arduino-cloud/tutorials/share-your-sketches) on how to do it. + +Keep in mind that your sketch may contain some sensitive data that you do not want to share with other members, like Wi-Fi® credentials or API keys. If this is the case, check [this tutorial](https://docs.arduino.cc/arduino-cloud/tutorials/store-your-sensitive-data-safely-when-sharing) to learn how to share sketches without sharing sensitive data. + +### OTA Updates + +Arduino Cloud for Business integrates an amazing feature: Over-The-Air updates. This feature allows you to upload sketches wirelessly to your Arduino boards. This way, as soon as you have a compatible board connected to a Wi-Fi®/Ethernet network and configured to work with OTA, you will not need to physically connect the board to your computer to upload new sketches to it; instead, everything will work Over-The-Air, even from remote. + +***Are you interested in learning how to perform an OTA update? Check [this tutorial](https://docs.arduino.cc/arduino-cloud/features/ota-getting-started#how-does-it-work). If you prefer to use the Arduino Cloud CLI instead, go to [this link](https://docs.arduino.cc/arduino-cloud/getting-started/arduino-cloud-cli#ota-over-the-air).*** + +## Fleet Management + +Now it is time for you to start managing your fleet of devices/Things. The Arduino Cloud for Business fleet management features allow you to filter your devices/Things by status, add tags to more efficiently identify your projects, search between boards, and list and order them. + +Get started with this awesome feature by going to **Things** or **Devices** tab in [Arduino Cloud](https://app.arduino.cc/devices) and start searching and filtering among your Things/devices. + +![Search and filter among devices](assets/search-things.png "Search and filter among devices") + +If you want to create your tag, which you can use as a filtering option, go to **Things** tab, click on the Thing you would like to tag and go to the Metadata tab as shown in the figure below. + +![Thing metadata](assets/thing-metadata.png "Thing metadata") + +Click on **ADD**. You will be asked to customize your tag through two fields: + +* **Key**. The Key is the filter name which you will see among the list of available filtering options. E.g. Location. +* **Value**. The Value corresponds to the specific value your tag has for that specific Thing. E.g. Rome. + +![Customize your tag](assets/add-tag.png "Customize your tag") + +You can add an unlimited number of tags to each Thing. + +At this point, you can go back to the Things tab and start filtering your Things according to the new tag you have just created. + +![New tag filtering](assets/new-tag-filtering.png "New tag filtering") + +## Dashboards + +With Arduino Cloud for Business, you can create an unlimited number of dashboards. Push button, Switch, Scheduler, Map, Chart… These are just a few of the many widgets you can customize to visualize all your data or to remotely control your devices. + +To start creating your dashboard, go to the **Dashboards** tab in [Arduino Cloud](https://app.arduino.cc/dashboards) and select the Thing you want to create a dashboard for. + +![Dashboard example](assets/dashboard-example.png "Dashboard example") + +***If you want to learn more on how to customize your dashboard and leverage the wide widget portfolio, check the dedicated documentation available at [this link](https://docs.arduino.cc/arduino-cloud/getting-started/dashboard-widgets).*** + +### Sharing Dashboards + +Whether it is your teammate, your customer, or your system integrator; you can freely share your dashboards with all the people you like. Just keep in mind that the interested stakeholders need to have an Arduino Account to access the dashboards. + +![Share your dashboard](assets/dashboard-sharing.png "Share your dashboard") + +***Ready to share your dashboard? Have a look at [this tutorial](https://docs.arduino.cc/arduino-cloud/features/sharing-dashboards).*** + +### Data Export + +Arduino Cloud for Business allows any user to download historical data from Arduino Cloud Things and Variables. The data are downloaded in **.csv** format to be ready for further evaluation or manipulation. + +The Arduino Cloud for Business plan includes 1-year of data retention by default; this means that your data will be available and downloadable from your Arduino Cloud account for 1 year. + +To start exporting your data locally, navigate into one of your dashboards on the [Arduino Cloud](https://app.arduino.cc/dashboards). While inside a dashboard, press the Download icon in the upper right corner. This will open a new window that will allow you to select which historical data you would like to download. + +![Download icon](assets/download-button.png "Download icon") + +From here you can select all the variables you want to download by checking the boxes as well as the time frame you are interested in. + +When you have selected the data, click on the **SELECT DATA SOURCE** button. + +![Export your data](assets/download-data.png "Exporte your data") + +At this point, click on **GET DATA** to receive your data by email. + +![Get your data](assets/get-data.png "Get your data") + +You will get an email like the one below with a link allowing you to download all your data. + +![Link to download your data](assets/email-data.png "Link to download your data") + +You are now ready to monitor and manipulate all your Cloud data. + +## Arduino Cloud API + +Use Arduino Cloud back-end to control Things and devices via Arduino rest APIs in [Javascript](https://www.npmjs.com/package/@arduino/arduino-iot-client), [Python](https://pypi.org/project/arduino-iot-client/), or [Go](https://github.com/arduino/iot-client-go). With Arduino rest APIs, you will be able to manage up to 10 requests per second, guaranteeing stable data sharing. + +Leveraging the APIs, you can interact with any element of the Cloud: data, devices, dashboards, and web properties. At the same time, APIs allow you to add power to the script, create complex scenarios or send and receive data from your custom service, 3rd party solution, or mobile application. + +To use the APIs, you need to create an API Key Token in the API Keys section of your Space. + +***We strongly recommend you add a Service Account role to your Shared Space to create/manage/maintain API Keys Tokens. The Service Account should not be linked to a personal email account so that the API Keys which will be created do not risk getting lost if that email account gets canceled.*** + +***If you want to start creating your own API Keys Token, take a look at [this tutorial](https://docs.arduino.cc/arduino-cloud/getting-started/arduino-iot-api) and [this documentation](https://www.arduino.cc/reference/en/iot/api/).*** + +## IoT Remote App + +Monitor your dashboards anywhere, anytime, and use your dashboards on the go with the free IoT Remote App. + +To start exploring it, you will need to download it from either [Google Play Store](https://play.google.com/store/apps/details?id=cc.arduino.cloudiot&hl=en&gl=US) or the [Apple App Store](https://apps.apple.com/us/app/arduino-iot-cloud-remote/id1514358431) depending on your device. + +***Do you want to get started with IoT Remote App? Read [this tutorial](https://docs.arduino.cc/arduino-cloud/tutorials/iot-remote-phone-sensors#phone-setup).*** + +## Arduino Cloud CLI + +As already mentioned, Arduino Cloud for Business fully supports the [Arduino Cloud CLI](https://github.com/arduino/arduino-cloud-cli). The Arduino Cloud CLI allows accessing all the Arduino Cloud features from your terminal window. + +Arduino Cloud CLI is the right choice when you are familiar with command-line interfaces and you would like to manage multiple devices and Things at the same time with few lines of code. + +These are the main features of Arduino Cloud CLI: + +* [Mass provisioning](https://docs.arduino.cc/arduino-cloud/getting-started/arduino-cloud-cli#device), i.e. provisioning of multiple devices at the same time. +* [Mass OTA updates](https://docs.arduino.cc/arduino-cloud/getting-started/arduino-cloud-cli#ota-over-the-air), i.e. Over-The-Air update of multiple devices at the same time. +* Advanced fleet management, including multiple devices [tagging](https://docs.arduino.cc/arduino-cloud/getting-started/arduino-cloud-cli#list-devices). +* Things monitoring and management, such as Things [tagging](https://docs.arduino.cc/arduino-cloud/getting-started/arduino-cloud-cli#tag-a-thing), [listing](https://docs.arduino.cc/arduino-cloud/getting-started/arduino-cloud-cli#list-things), [cloning](https://docs.arduino.cc/arduino-cloud/getting-started/arduino-cloud-cli#clone-things) and [template creation](https://docs.arduino.cc/arduino-cloud/getting-started/arduino-cloud-cli#extract-thing-template). +* Dashboard [creation](https://docs.arduino.cc/arduino-cloud/getting-started/arduino-cloud-cli#create-dashboard)/[cancellation](https://docs.arduino.cc/arduino-cloud/getting-started/arduino-cloud-cli#delete-dashboards), maintenance and dashboard [template extraction](https://docs.arduino.cc/arduino-cloud/getting-started/arduino-cloud-cli#extract-dashboard-template). + +***If you would like to learn more about Arduino Cloud CLI and get started with it, check the corresponding documentation available [here](https://docs.google.com/document/d/1UBh5L-GXiAJiZG4LoZ5nY7ldXd7PAXSDax3pyb5DULU/edit).*** + +## Optional Add-Ons + +Arduino Cloud for Business can be customized with optional add-ons: + +* **Portenta X8 Board Manager** +* **Machine Learning Tools Enterprise** + +These add-ons are located under **Integrations** page, found within the Shared Space sidebar. + +![Arduino Cloud Homepage with Add-ons](assets/cloud-add-on.png "Arduino Cloud Homepage with Add-ons") + +To get started with them, it is sufficient to click on the corresponding tab. + +### Portenta X8 Board Manager + +Securely maintain Portenta X8 Linux distribution with this dedicated add-on, powered by [Foundries.io](https://foundries.io/). Deploy and update all your applications packaged into containers and perform secure Over-The-Air differential updates to target Portenta X8 devices/fleets. + +***Check [Portenta X8 documentation](https://docs.arduino.cc/hardware/portenta-x8) to find out more and start working with Portenta X8 Manager.*** + +### Machine Learning Tools Enterprise + +Build and train professional-grade predictive models with just a few lines of code through this dedicated add-on, powered by [Edge Impulse®](https://www.edgeimpulse.com/). Deploy premade models out of the box to quickly develop your machine learning projects, starting from object detection, and machine vision to audio segmentation. + +***If you are interested in learning more about this add-on, have a look at [this documentation](https://cloud.arduino.cc/machine-learning-tools). Otherwise, we have plenty of tutorials already using Machine Learning Tools. Check if your device is compatible with it in the board documentation available [here](https://docs.arduino.cc/).*** + +## Additional Tutorials + +You can find more tutorials on the [Arduino Cloud documentation page](https://docs.arduino.cc/arduino-cloud/). + +## Congratulations + +You are just a few easy steps from deploying your very own IoT project. Having a project connected to the Arduino Cloud for Business opens up many possibilities, such as tracking data in real-time, triggering remote devices and building wireless systems. + +What will you create? + +[Start your Cloud journey now](https://cloud.arduino.cc/plans#business). diff --git a/content/hardware/_unlisted/boards/nano-matter/compatibility.yml b/content/hardware/_unlisted/boards/nano-matter/compatibility.yml new file mode 100644 index 0000000000..c9b1113377 --- /dev/null +++ b/content/hardware/_unlisted/boards/nano-matter/compatibility.yml @@ -0,0 +1,8 @@ +hardware: + carriers: + - nano-screw-terminal-adapter +software: + - arduino-ide + - arduino-cli + - web-editor + - iot-cloud \ No newline at end of file diff --git a/content/hardware/_unlisted/boards/nano-matter/datasheet/assets/Nano_Matter_Block_Diagram.png b/content/hardware/_unlisted/boards/nano-matter/datasheet/assets/Nano_Matter_Block_Diagram.png new file mode 100644 index 0000000000..b49533b5ad Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/datasheet/assets/Nano_Matter_Block_Diagram.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/datasheet/assets/Nano_Matter_Connectors.png b/content/hardware/_unlisted/boards/nano-matter/datasheet/assets/Nano_Matter_Connectors.png new file mode 100644 index 0000000000..e315d7268b Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/datasheet/assets/Nano_Matter_Connectors.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/datasheet/assets/Nano_Matter_Outline.png b/content/hardware/_unlisted/boards/nano-matter/datasheet/assets/Nano_Matter_Outline.png new file mode 100644 index 0000000000..ea69e92e00 Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/datasheet/assets/Nano_Matter_Outline.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/datasheet/assets/Nano_Matter_PeripheralsActuators.png b/content/hardware/_unlisted/boards/nano-matter/datasheet/assets/Nano_Matter_PeripheralsActuators.png new file mode 100644 index 0000000000..6ed76e1a2f Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/datasheet/assets/Nano_Matter_PeripheralsActuators.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/datasheet/assets/Nano_Matter_Pinout.png b/content/hardware/_unlisted/boards/nano-matter/datasheet/assets/Nano_Matter_Pinout.png new file mode 100644 index 0000000000..ad98168403 Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/datasheet/assets/Nano_Matter_Pinout.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/datasheet/assets/Nano_Matter_Power_Tree.png b/content/hardware/_unlisted/boards/nano-matter/datasheet/assets/Nano_Matter_Power_Tree.png new file mode 100644 index 0000000000..449d527026 Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/datasheet/assets/Nano_Matter_Power_Tree.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/datasheet/assets/Nano_Matter_Top_View.png b/content/hardware/_unlisted/boards/nano-matter/datasheet/assets/Nano_Matter_Top_View.png new file mode 100644 index 0000000000..c318b07efb Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/datasheet/assets/Nano_Matter_Top_View.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/datasheet/datasheet.md b/content/hardware/_unlisted/boards/nano-matter/datasheet/datasheet.md new file mode 100644 index 0000000000..b01f8127ed --- /dev/null +++ b/content/hardware/_unlisted/boards/nano-matter/datasheet/datasheet.md @@ -0,0 +1,429 @@ +--- +identifier: ABX00112 +title: Arduino® Nano Matter +type: maker +author: José Bagur +--- + +![](assets/Nano_Matter_Top_View.png) + +# Description + +

Expand your home automation and building management projects with the Arduino Nano Matter. This board integrates the high-performance MGM240S microcontroller from Silicon Labs and directly brings the advanced Matter standard for Internet of Things (IoT) connectivity to hobbyists and professionals. The Nano Matter's compact and sturdy build, measuring 18 mm x 45 mm, is perfect for projects that demand energy efficiency and diverse connectivity options, such as Bluetooth® Low Energy and OpenThread. Embrace the simplicity and versatility of the Nano Matter to effortlessly interface with any Matter® compatible devices and leverage the Arduino ecosystem's wide range of peripherals and inputs/outputs to enhance your device connectivity and project capabilities.

+ +# Target Areas + +Internet of Things, home automation, professional automation, environmental monitoring, and climate control + +# CONTENTS +## Application Examples + +The Arduino Nano Matter is not just an IoT board, it is a gateway to innovation in various sectors, from streamlining manufacturing processes to creating responsive and comfortable living and working environments. Discover more about the transformative potential of the Nano Matter in the following application examples: + +- **Smart homes**: Transform residential spaces into intelligent environments with the Nano Matter, capable of: + - **Voice-controlled smart home**: Integrate the Nano Matter with popular voice assistant platforms like Amazon Alexa or Google Assistant, enabling residents to control smart home devices, such as lights, thermostats, and switches, using simple voice commands, enhancing convenience and accessibility. + - **Smart lighting**: Automate your home lighting system with the Nano Matter to adjust the brightness based on occupancy, time of day, or ambient light levels, saving energy and ensuring optimal lighting conditions in every room. + - **Automated shades**: Connect the Nano Matter to your motorized shades to automatically adjust them according to sunlight exposure, room occupancy, or specific times of the day, creating the perfect ambiance while improving energy efficiency. + - **Home health monitoring**: Use the Nano Matter to connect with environmental sensors, monitor indoor conditions like pressure, humidity, and temperature, and maintain a healthy living environment by providing actionable insights for comfort and well-being. + +- **Building automation**: Elevate building management with the Nano Matter, enhancing comfort and efficiency through: + - **HVAC control and monitoring**: Implement the Nano Matter to connect and control HVAC systems across various building zones. Monitor environmental conditions and adjust settings for optimal indoor comfort while maximizing energy efficiency. + - **Energy management**: Use Nano Matter's connectivity to smart meters and appliances to view a building's energy consumption. Implement energy-saving measures automatically, reducing costs and environmental impact. + - **Occupancy sensing and space utilization**: With the Nano Matter and Matter-enabled sensors, gain insights into actual building occupancy and use this data to adjust lighting, heating, and cooling systems, ensuring efficient use of space and resources. + +- **Industrial automation**: Unlock the full potential of modern manufacturing with the Nano Matter. Designed for seamless integration into industrial settings, the Nano Matter streamlines operations through: + - **Machine-to-Machine interoperability**: Enhance your factory floor with the Nano Matter boards to enable dynamic supervision between machines. Should one machine begin producing defective parts due to a malfunction, adjacent machines are instantly alerted, halting their operations and notifying a human operator, thus reducing waste and downtime. + - **Machine status monitoring**: Integrate the Nano Matter into your industrial systems for real-time monitoring of critical conditions such as temperature, pressure, and humidity, ensuring timely maintenance and intervention, preventing costly breakdowns, and maintaining consistent production quality. + - **Worker safety optimization**: Elevate safety standards in your facility with the Nano Matter, which provides real-time monitoring of environmental conditions and detects personnel presence in hazardous areas, enhancing worker safety by preventing machine operation when a human is detected in dangerous zones. + +
+ +## Features +### General Specifications Overview + +

+The Arduino Nano Matter merges the well-known Arduino way of making complex technology more accessible, bringing Matter, one of the most popular IoT connectivity standards, closer to the hobbyist and professional world. The powerful MGM240S multi-protocol wireless module from Silicon Labs is the main controller of the board. + +The main features are highlighted in the table shown below. +

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FeatureDescription
Microcontroller78 MHz, 32-bit Arm® Cortex®-M33 core (MGM240SD22VNA)
Internal Memory1536 kB Flash and 256 kB RAM
Connectivity802.15.4 Thread, Bluetooth® Low Energy 5.3, and Bluetooth® Mesh
SecuritySecure Vault® from Silicon Labs
USB ConnectivityUSB-C® port for power and data
Power SupplyVarious options for easily powering the board: USB-C® port and external power supply connected through the board's Nano-styled header connector pins (IN5V, VIN)
Analog Peripherals 12-bit ADC (x19), up to 12-bit DAC (x2)
Digital PeripheralsGPIO (x22), I2C (x1), UART (x1), SPI (x1), PWM (x22)
DebuggingJTAG/SWD debug port (accessible through the board's test pads)
Dimensions18 mm x 45 mm
Weight4 g
Pinout featuresCastellated pins allow the board to be SMD soldered on a custom carrier
+
+ +
+ +### Included Accessories + +- No accessories are included + +### Related Products + +- Arduino USB Type-C® Cable 2-in-1 (SKU: TPX00094) +- Arduino Nano Screw Terminal Adapter (SKU: ASX00037-3P) + +
+ +## Ratings + +### Recommended Operating Conditions + +

+The table below provides a comprehensive guideline for the optimal use of the Nano Matter, outlining typical operating conditions and design limits. The operating conditions of the Nano Matter are largely a function based on its component's specifications. +

+ +
+ +| **Parameter** | **Symbol** | **Min** | **Typ** | **Max** | **Unit** | +|:--------------------------------:|:---------------:|:-------:|:-------:|:-------:|:--------:| +| USB Supply Input Voltage | VUSB | - | 5.0 | - | V | +| Supply Input Voltage1 | VIN | - | 5.0 | 5.5 | V | +| Operating Temperature | TOP | -40 | - | 85 | °C | + +
+ +1 Nano Matter powered through the IN5V pin (+5 VDC).
+ +### Current Consumption + +

+The table below summarizes the power consumption of the Nano Matter in different test cases. Notice that the board's operating current will depend greatly on the application. +

+ +
+ + + + + + + + + + + + + + + + + + + + + +
ParameterSymbolMinTypMaxUnit
Typical Mode Current Consumption2INM-16-mA
+
+ +2 Nano Matter powered through the IN5V pin (+5 VDC), running a Matter color lightbulb example. + +
+ +## Functional Overview + +

+The core of the Nano Matter is the MGM240SD22VNA microcontroller from Silicon Labs. The board also contains several peripherals and actuators connected to its microcontroller, such as a push button and an RGB LED available for the user. +

+ +### Pinout + +The Nano-styled header connectors pinout is shown in the figure below. + +![](assets/Nano_Matter_Pinout.png) + +
+ +### Block Diagram + +An overview of the high-level architecture of the Nano Matter is illustrated in the figure below. + +![](assets/Nano_Matter_Block_Diagram.png) + +
+ +### Power Supply + +
+ +The Nano Matter can be powered through one of the following interfaces: + +- **Onboard USB-C® port**: Provides a convenient way to power the board using standard USB-C® cables and adapters. +- **External +5 VDC power supply**: This can be connected to the IN5V pin or the VIN pin of the Nano-styled header connector. For the VIN pin, ensure the VIN jumper is shorted to enable the power supply. + +A detailed figure below illustrates the power options available on the Nano Matter and the main system power architecture. + +![](assets/Nano_Matter_Power_Tree.png) + +
+Low-Power Tip: For power efficiency, safely cut the LED jumper and connect an external +3.3 VDC power supply to the board's 3V3 pin. This configuration does not power the board's USB bridge. +
+ +
+ +
+Safety Note: Disconnect power before board modifications. Avoid short-circuiting. Refer to the full guide for more safety tips. +
+ + + + +
+ +## Device Operation + +
+ +### Getting Started - IDE + +If you want to program your Nano Matter offline, install the Arduino Desktop IDE **[1]**. To connect the Nano Matter to your computer, you will need a USB-C® cable. + +### Getting Started - Arduino Web Editor + +All Arduino devices work out of the box on the Arduino CLoud Editor **[2]** by installing a simple plugin. The Arduino Cloud Editor is hosted online. Therefore, it will always be up-to-date with all the latest features and support for all boards and devices. Follow **[3]** to start coding on the browser and upload your sketches onto your device. + +### Getting Started - Arduino Cloud + +All Arduino IoT-enabled products are supported on Arduino Cloud, which allows you to log, graph, and analyze sensor data, trigger events, and automate your home or business. Take a look at the official documentation to know more. + +### Sample Sketches + +Sample sketches for the Nano Matter can be found either in the “Examples” menu in the Arduino IDE or the “Nano Matter Documentation” section of Arduino documentation **[4]**. + +### Online Resources + +Now that you have gone through the basics of what you can do with the device, you can explore the endless possibilities it provides by checking exciting projects on Arduino Project Hub **[5]**, the Arduino Library Reference **[6]**, and the online store **[7]** where you will be able to complement your Nano Matter board with additional extensions, sensors, and actuators. +
+ +
+ +## Mechanical Information + +

+The Nano Matter is a double-sided 18 mm x 45 mm board with a USB-C® port overhanging the top edge and dual +castellated/through-hole pins around the two long edges; the onboard wireless antenna is located in the center of the bottom edge of the board. +

+ +### Board Dimensions + +The Nano Matter board outline and mounting holes dimensions are shown in the figure below; all the dimensions are in mm. + +![](assets/Nano_Matter_Outline.png) + +The Nano Matter has four 1.65 mm drilled mounting holes for mechanical fixing. + +### Board Connectors + +Connectors of the Nano Matter are placed on the top side of the board; their placement is shown in the figure below; all the dimensions are in mm. + +![](assets/Nano_Matter_Connectors.png) + +

+The Nano Matter was designed to be usable as a surface-mount module and presents a dual inline package (DIP) format with the Nano-styled header connectors on a 2.54 mm pitch grid with 1 mm holes. +

+ +### Board Peripherals and Actuators + +

+The Nano Matter has one push button and one RGB LED available for the user; both the push button and the RGB LED are placed on the top side of the board. Their placement is shown in the figure below; all the dimensions are in mm. +

+ +![](assets/Nano_Matter_PeripheralsActuators.png) + +

+The Nano Matter is designed to be usable as a surface-mount module and presents a dual inline package (DIP) format with the Nano-styled header connectors on a 2.54 mm pitch grid with 1 mm holes. +

+ +
+ +## Product Compliance + +### Product Compliance Summary + +| **Product Compliance** | +| :--------------------: | +| CE (European Union) | +| RoHS | +| REACH | +| WEEE | +| FCC (USA) | +| IC (Canada) | +| UKCA (UK) | +| Matter® | +| Bluetooth® | + +### Declaration of Conformity CE DoC (EU) + +

+We declare under our sole responsibility that the products above are in conformity with the essential requirements of the following EU Directives and therefore qualify for free movement within markets comprising the European Union (EU) and European Economic Area (EEA). +

+ +### Declaration of Conformity to EU RoHS & REACH 211 01/19/2021 + +

+Arduino boards are in compliance with RoHS 2 Directive 2011/65/EU of the European Parliament and RoHS 3 Directive 2015/863/EU of the Council of 4 June 2015 on the restriction of the use of certain hazardous substances in electrical and electronic equipment. +

+ +| **Substance** | **Maximum Limit (ppm)** | +|----------------------------------------|-------------------------| +| Lead (Pb) | 1000 | +| Cadmium (Cd) | 100 | +| Mercury (Hg) | 1000 | +| Hexavalent Chromium (Cr6+) | 1000 | +| Poly Brominated Biphenyls (PBB) | 1000 | +| Poly Brominated Diphenyl ethers (PBDE) | 1000 | +| Bis(2-Ethylhexyl) phthalate (DEHP) | 1000 | +| Benzyl butyl phthalate (BBP) | 1000 | +| Dibutyl phthalate (DBP) | 1000 | +| Diisobutyl phthalate (DIBP) | 1000 | + +
+ +Exemptions: No exemptions are claimed. + +Arduino Boards are fully compliant with the related requirements of European Union Regulation (EC) 1907 /2006 concerning the Registration, Evaluation, Authorization and Restriction of Chemicals (REACH). We declare none of the SVHCs (https://echa.europa.eu/web/guest/candidate-list-table), the Candidate List of Substances of Very High Concern for authorization currently released by ECHA, is present in all products (and also package) in quantities totaling in a concentration equal or above 0.1%. To the best of our knowledge, we also declare that our products do not contain any of the substances listed on the "Authorization List" (Annex XIV of the REACH regulations) and Substances of Very High Concern (SVHC) in any significant amounts as specified by the Annex XVII of Candidate list published by ECHA (European Chemical Agency) 1907 /2006/EC. + +### Conflict Minerals Declaration + +As a global supplier of electronic and electrical components, Arduino is aware of our obligations concerning laws and regulations regarding Conflict Minerals, specifically the Dodd-Frank Wall Street Reform and Consumer Protection Act, Section 1502. Arduino does not directly source or process conflict minerals such as Tin, Tantalum, Tungsten, or Gold. Conflict minerals are contained in our products in the form of solder, or as a component in metal alloys. As part of our reasonable due diligence, Arduino has contacted component suppliers within our supply chain to verify their continued compliance with the regulations. Based on the information received thus far we declare that our products contain Conflict Minerals sourced from conflict-free areas. + +## FCC Caution + +Any Changes or modifications not expressly approved by the party responsible for compliance could void the user’s authority to operate the equipment. + +This device complies with part 15 of the FCC Rules. Operation is subject to the following two conditions: + +1. This device may not cause harmful interference + +2. This device must accept any interference received, including interference that may cause undesired operation. + +**FCC RF Radiation Exposure Statement:** + +1. This Transmitter must not be co-located or operating in conjunction with any other antenna or transmitter + +2. This equipment complies with RF radiation exposure limits set forth for an uncontrolled environment + +3. This equipment should be installed and operated with a minimum distance of 20 cm between the radiator and your body. + +
+ +**Note:** This equipment has been tested and found to comply with the limits for a Class B digital +device, pursuant to part 15 of the FCC Rules. These limits are designed to provide +reasonable protection against harmful interference in a residential installation. This equipment +generates, uses and can radiate radio frequency energy and, if not installed and used in +accordance with the instructions, may cause harmful interference to radio communications. +However, there is no guarantee that interference will not occur in a particular installation. If +this equipment does cause harmful interference to radio or television reception, which can be +determined by turning the equipment off and on, the user is encouraged to try to correct the +interference by one or more of the following measures: +- Reorient or relocate the receiving antenna. +- Increase the separation between the equipment and receiver. +- Connect the equipment into an outlet on a circuit different from that to which the +receiver is connected. +- Consult the dealer or an experienced radio/TV technician for help. + +English: +User manuals for license-exempt radio apparatus shall contain the following or equivalent notice in a conspicuous location in the user manual or alternatively on the device or both. This device complies with Industry Canada license-exempt RSS standard(s). Operation is subject to the following two conditions: + +1. This device may not cause interference + +2. This device must accept any interference, including interference that may cause undesired operation of the device. + +French: +Le présent appareil est conforme aux CNR d’Industrie Canada applicables aux appareils radio exempts de licence. L’exploitation est autorisée aux deux conditions suivantes: + +1. L’ appareil nedoit pas produire de brouillage + +2. L’utilisateur de l’appareil doit accepter tout brouillage radioélectrique subi, même si le brouillage est susceptible d’en compromettre le fonctionnement. + +**IC SAR Warning:** + +English: +This equipment should be installed and operated with a minimum distance of 20 cm between the radiator and your body. + +French: +Lors de l’ installation et de l’ exploitation de ce dispositif, la distance entre le radiateur et le corps est d ’au moins 20 cm. + +**Important:** The operating temperature of the EUT can’t exceed 85 °C and shouldn’t be lower than -40 °C. + +Hereby, Arduino S.r.l. declares that this product is in compliance with essential requirements and other relevant provisions of Directive 2014/53/EU. This product is allowed to be used in all EU member states. + +## Company Information + +| **Company name** | **Arduino S.r.l.** | +|:----------------:|:--------------------------------------------:| +| Company address | Via Andrea Appiani, 25 - 20900 MONZA (Italy) | + +## Reference Documentation +| **Ref** | **Link** | +|:----------------------------------:|---------------------------------------------------------------------------------------------| +| Arduino IDE (Desktop) | https://www.arduino.cc/en/Main/Software | +| Arduino IDE (Cloud) | https://create.arduino.cc/editor | +| Arduino Cloud - Getting started | https://docs.arduino.cc/arduino-cloud/getting-started/iot-cloud-getting-started | +| Nano Matter Documentation | https://docs.arduino.cc/hardware/nano-matter | +| Project Hub | https://create.arduino.cc/projecthub?by=part&part_id=11332&sort=trending | +| Library Reference | https://www.arduino.cc/reference/en/ | +| Online Store | https://store.arduino.cc/ | + + +## Document Revision History + +| **Date** | **Revision** | **Changes** | +| :--------: | :----------: | :-----------------------: | +| 21/03/2024 | 1 | Community Preview Release | diff --git a/content/hardware/_unlisted/boards/nano-matter/downloads/ABX00112-datasheet.pdf b/content/hardware/_unlisted/boards/nano-matter/downloads/ABX00112-datasheet.pdf new file mode 100644 index 0000000000..17c3d9196c Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/downloads/ABX00112-datasheet.pdf differ diff --git a/content/hardware/_unlisted/boards/nano-matter/downloads/ABX00112-full-pinout.pdf b/content/hardware/_unlisted/boards/nano-matter/downloads/ABX00112-full-pinout.pdf new file mode 100644 index 0000000000..f289a30419 Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/downloads/ABX00112-full-pinout.pdf differ diff --git a/content/hardware/_unlisted/boards/nano-matter/downloads/ABX00112-schematics.pdf b/content/hardware/_unlisted/boards/nano-matter/downloads/ABX00112-schematics.pdf new file mode 100644 index 0000000000..838e203f4b Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/downloads/ABX00112-schematics.pdf differ diff --git a/content/hardware/_unlisted/boards/nano-matter/downloads/ABX00112-step.zip b/content/hardware/_unlisted/boards/nano-matter/downloads/ABX00112-step.zip new file mode 100644 index 0000000000..ac9ee9938a Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/downloads/ABX00112-step.zip differ diff --git a/content/hardware/_unlisted/boards/nano-matter/essentials.md b/content/hardware/_unlisted/boards/nano-matter/essentials.md new file mode 100644 index 0000000000..3ad61ae50e --- /dev/null +++ b/content/hardware/_unlisted/boards/nano-matter/essentials.md @@ -0,0 +1,26 @@ + + + All you need to know to get started with your new Arduino board. + + + Learn how to create your own custom hardware that is compatible with the Arduino Nano Family. + + + + + + The Silicon Labs Arduino Core enables hardware built with Silicon Labs systems to be used with the Arduino ecosystem. + + + + + + Built-in Examples are sketches included in the Arduino IDE and demonstrate all basic Arduino commands. + + + Discover interesting articles, principles and techniques related to the Arduino ecosystem. + + + Arduino programming language can be divided in three main parts: functions, values (variables and constants), and structure. + + \ No newline at end of file diff --git a/content/hardware/_unlisted/boards/nano-matter/features.md b/content/hardware/_unlisted/boards/nano-matter/features.md new file mode 100644 index 0000000000..ac175a3e76 --- /dev/null +++ b/content/hardware/_unlisted/boards/nano-matter/features.md @@ -0,0 +1,62 @@ + + + The Nano Matter uses Silicon Labs's powerful [MGM240S](https://www.silabs.com/documents/public/data-sheets/mgm240s-datasheet.pdf) chip, making the popular IoT connectivity standard, Matter®, more accessible in Maker and Professional applications. Its versatile connectivity options, including Bluetooth® Low Energy and Openthread, make it ideal for projects requiring low-power efficiency and broad connectivity. + + Thanks to the Nano Matter and its small form factor, you can easily prototype new Matter devices, expanding your home automation and professional IoT implementations to the next level. + + + + + + Create, connect, and communicate with Matter® compatible devices using Arduino as the software layer for rapid prototyping. + + + + + + + Nano Matter uses Thread for IoT mesh networking communication in a highly compact form factor. + + + + + + + The Nano Matter integrates MGM240SD22VNA, boasting a 32-bit Arm® Cortex®-M33 processor optimized for complex calculations and signal processing in power-sensitive IoT applications. + + + + + + + Leverage dual-mode connectivity, integrating both IEEE 802.15.4 (Thread) for mesh networking and Bluetooth® Low Energy for short-range communication. + + + + + + + No external debugging device is needed. Connect the board to the computer over USB and have access to a SWD interface. + + + + The Nano Matter has been designed as an ultra-low power board, being the perfect solution for IoT battery-powered applications. + + + + With a length of 45 mm and a width of 18 mm, the Nano Matter maintains a tiny footprint of the well-known Nano family, allowing easy upgrades for existing projects. + + + + Protect your project with the industry-leading suite of security features from Silicon Labs escalating Internet of Things (IoT) threats. + + + + + + +

+ + **Legal notice**: This Community Preview Product is provided "as is" and we make no express or implied warranties whatsoever with respect to its functionality, operability, or use, including, without limitation, any implied warranties of merchantability, fitness for a particular purpose, or infringement. We expressly disclaim any liability whatsoever for any direct, indirect, consequential, incidental or special damages, including, without limitation, lost revenues, lost profits, losses resulting from business interruption or loss of data, regardless of the form of action or legal theory under which the liability may be asserted, even if advised of the possibility or likelihood of such damages. + + diff --git a/content/hardware/_unlisted/boards/nano-matter/image.svg b/content/hardware/_unlisted/boards/nano-matter/image.svg new file mode 100644 index 0000000000..50c1575b1b --- /dev/null +++ b/content/hardware/_unlisted/boards/nano-matter/image.svg @@ -0,0 +1,2 @@ + + diff --git a/content/hardware/_unlisted/boards/nano-matter/interactive/ABX00112-pinout.png b/content/hardware/_unlisted/boards/nano-matter/interactive/ABX00112-pinout.png new file mode 100644 index 0000000000..2e8212710b Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/interactive/ABX00112-pinout.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/product.md b/content/hardware/_unlisted/boards/nano-matter/product.md new file mode 100644 index 0000000000..647c8ba62a --- /dev/null +++ b/content/hardware/_unlisted/boards/nano-matter/product.md @@ -0,0 +1,12 @@ +--- +title: Nano Matter +url_shop: https://arduino.to/nano-matter +primary_button_url: /tutorials/nano-matter/user-manual +primary_button_title: User Manual +sku: [ABX00112] +core: arduino:mbed_nano +--- + +**[Community Preview]** + +The Arduino Nano Matter combines Arduino's user-friendly approach with the powerful MGM240S technology from Silicon Labs. This enables Makers and Professionals to work with **[Matter®](https://csa-iot.org/all-solutions/matter/)**, the popular standard for IoT devices, taking advantage of the Nano's low-power and compact design. diff --git a/content/hardware/_unlisted/boards/nano-matter/tech-specs.md b/content/hardware/_unlisted/boards/nano-matter/tech-specs.md new file mode 100644 index 0000000000..e2029946c8 --- /dev/null +++ b/content/hardware/_unlisted/boards/nano-matter/tech-specs.md @@ -0,0 +1 @@ +Here you will find the technical specifications for the Arduino® Nano Matter. \ No newline at end of file diff --git a/content/hardware/_unlisted/boards/nano-matter/tech-specs.yml b/content/hardware/_unlisted/boards/nano-matter/tech-specs.yml new file mode 100644 index 0000000000..ac6e7f23c0 --- /dev/null +++ b/content/hardware/_unlisted/boards/nano-matter/tech-specs.yml @@ -0,0 +1,46 @@ +Board: + Name: Arduino® Nano Matter + SKU: ABX00112 +Microprocessor: MGM240SD22VNA 32-bit Arm® Cortex®-M33 with DSP instruction and FPU +Clock speed: 78 MHz +USB connector: USB-C® +Pins: + Digital I/O Pins: 14 + Analog input pins: 8 + PWM pins: 5 + UART pins: 4 + I2C pins: 2 + SPI pins: 4 +Connectivity: + Matter: Matter-ready Smart Home Connectivity + LR-WPANs: IEEE 802.15.4 w/ Thread + Bluetooth®: Bluetooth® 5.3 & Bluetooth® Mesh +Additional Compatible Protocols: OpenThread +Connectivity Band Frequency: On-board 2.4 GHz +Secure element: Secure Vault +Analog-to-digital converter (ADC): + Channels: 8 + Resolution: 16 bits +Digital-to-analog converter (DAC): + Channels: 1 + Resolution: 12 bits +Pulse Width Modulation (PWM): + Channels: 5 + Maximum simultaneously operational channel: 5 +External Interrupts: Available within all Digital pins +Communication: + UART: 1 + I2C: 1 + SPI: 1 +Power: + Circuit operating voltage: 3.3 V + Input voltage (VIN): 5 V + Source Current per I/O Pin: 40 mA + Sink Current per I/O Pin: 28 mA +Memory: + RAM: 256 kB + Flash: 1536 kB +Dimensions: + Width: 18 mm + Length: 45 mm +Environmental temperature: -40 °C to + 85 °C diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/BlinkyBLE.gif b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/BlinkyBLE.gif new file mode 100644 index 0000000000..7a7ca73616 Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/BlinkyBLE.gif differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/adc-input.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/adc-input.png new file mode 100644 index 0000000000..53d85097b8 Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/adc-input.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/add-device-2.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/add-device-2.png new file mode 100644 index 0000000000..23b78cd6b7 Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/add-device-2.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/add-device-alexa-2.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/add-device-alexa-2.png new file mode 100644 index 0000000000..6497de5067 Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/add-device-alexa-2.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/add-device-alexa.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/add-device-alexa.png new file mode 100644 index 0000000000..e8f43f99c6 Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/add-device-alexa.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/add-device-apple-2.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/add-device-apple-2.png new file mode 100644 index 0000000000..fbc5570611 Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/add-device-apple-2.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/add-device-apple-3.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/add-device-apple-3.png new file mode 100644 index 0000000000..ded95519cb Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/add-device-apple-3.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/add-device-apple.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/add-device-apple.png new file mode 100644 index 0000000000..3709b1dd55 Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/add-device-apple.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/add-device-ha-2.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/add-device-ha-2.png new file mode 100644 index 0000000000..85b3ebbe94 Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/add-device-ha-2.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/add-device-ha.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/add-device-ha.png new file mode 100644 index 0000000000..55a63c9628 Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/add-device-ha.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/add-device.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/add-device.png new file mode 100644 index 0000000000..7dabbb5f03 Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/add-device.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/api-key.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/api-key.png new file mode 100644 index 0000000000..05bce0cf34 Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/api-key.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/apple.gif b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/apple.gif new file mode 100644 index 0000000000..f6f576f551 Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/apple.gif differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/architecture.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/architecture.png new file mode 100644 index 0000000000..9d102f6fe7 Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/architecture.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/automation-create.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/automation-create.png new file mode 100644 index 0000000000..cf4aeb72db Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/automation-create.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/automation-define.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/automation-define.png new file mode 100644 index 0000000000..bfad9fb725 Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/automation-define.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/ble-setup.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/ble-setup.png new file mode 100644 index 0000000000..4fefad3090 Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/ble-setup.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/blink.gif b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/blink.gif new file mode 100644 index 0000000000..cd99d6f1c2 Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/blink.gif differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/bsp-install.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/bsp-install.png new file mode 100644 index 0000000000..a09d1a0ee4 Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/bsp-install.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/button.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/button.png new file mode 100644 index 0000000000..9c401aa7a1 Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/button.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/castellated-small.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/castellated-small.png new file mode 100644 index 0000000000..4260d4bc8d Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/castellated-small.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/cloud-add-variable.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/cloud-add-variable.png new file mode 100644 index 0000000000..3dd6c4451c Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/cloud-add-variable.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/cloud-demo.gif b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/cloud-demo.gif new file mode 100644 index 0000000000..ec18e5b2eb Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/cloud-demo.gif differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/cloud-login.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/cloud-login.png new file mode 100644 index 0000000000..706e68d171 Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/cloud-login.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/cloud-setup-variable.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/cloud-setup-variable.png new file mode 100644 index 0000000000..7cee040bd2 Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/cloud-setup-variable.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/cloud-thing.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/cloud-thing.png new file mode 100644 index 0000000000..af6b2de277 Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/cloud-thing.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/compile-blink.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/compile-blink.png new file mode 100644 index 0000000000..09d9a90c3a Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/compile-blink.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/ext-power.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/ext-power.png new file mode 100644 index 0000000000..998ad7553b Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/ext-power.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/freq-out.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/freq-out.png new file mode 100644 index 0000000000..93cf7631a3 Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/freq-out.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/gpio-wiring.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/gpio-wiring.png new file mode 100644 index 0000000000..16cf980f8a Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/gpio-wiring.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/ha-setup-2.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/ha-setup-2.png new file mode 100644 index 0000000000..2f3d9243ce Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/ha-setup-2.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/ha-setup-cloud.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/ha-setup-cloud.png new file mode 100644 index 0000000000..3f0d187216 Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/ha-setup-cloud.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/ha-setup-config.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/ha-setup-config.png new file mode 100644 index 0000000000..ee8220caf1 Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/ha-setup-config.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/ha-setup.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/ha-setup.png new file mode 100644 index 0000000000..e61c08d187 Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/ha-setup.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/ha.gif b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/ha.gif new file mode 100644 index 0000000000..af20295518 Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/ha.gif differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/home-assistant-temp.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/home-assistant-temp.png new file mode 100644 index 0000000000..79363387ec Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/home-assistant-temp.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/i2c-example.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/i2c-example.png new file mode 100644 index 0000000000..e93c46ea39 Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/i2c-example.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/id-gathering-1.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/id-gathering-1.png new file mode 100644 index 0000000000..b7385e0b04 Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/id-gathering-1.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/id-gathering-2.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/id-gathering-2.png new file mode 100644 index 0000000000..fd4e4fd392 Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/id-gathering-2.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/id-gathering-3.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/id-gathering-3.png new file mode 100644 index 0000000000..b4d14fbabc Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/id-gathering-3.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/lower-power.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/lower-power.png new file mode 100644 index 0000000000..29c3e8eb94 Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/lower-power.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/matter-alexa.gif b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/matter-alexa.gif new file mode 100644 index 0000000000..561ef54e0a Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/matter-alexa.gif differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/matter-examples.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/matter-examples.png new file mode 100644 index 0000000000..64ff44669e Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/matter-examples.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/matter-google.gif b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/matter-google.gif new file mode 100644 index 0000000000..a0ba9167ba Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/matter-google.gif differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/matter-setup.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/matter-setup.png new file mode 100644 index 0000000000..bf6558811e Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/matter-setup.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/nano-matter-banner.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/nano-matter-banner.png new file mode 100644 index 0000000000..f4dada6d2c Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/nano-matter-banner.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/pwm-out.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/pwm-out.png new file mode 100644 index 0000000000..3123fd61a0 Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/pwm-out.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/qr-code.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/qr-code.png new file mode 100644 index 0000000000..2a7845c662 Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/qr-code.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/restart-ha.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/restart-ha.png new file mode 100644 index 0000000000..1067bd63f3 Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/restart-ha.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/rgb-blink.gif b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/rgb-blink.gif new file mode 100644 index 0000000000..a55b8193b9 Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/rgb-blink.gif differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/rgb-led.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/rgb-led.png new file mode 100644 index 0000000000..0b534863fa Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/rgb-led.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/rst-button.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/rst-button.png new file mode 100644 index 0000000000..0b74829e07 Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/rst-button.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/saw-output.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/saw-output.png new file mode 100644 index 0000000000..c022a4f197 Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/saw-output.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/simple-pinout.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/simple-pinout.png new file mode 100644 index 0000000000..ad98168403 Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/simple-pinout.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/sine-output.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/sine-output.png new file mode 100644 index 0000000000..e770e94350 Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/sine-output.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/spi-example.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/spi-example.png new file mode 100644 index 0000000000..066cac320a Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/spi-example.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/uart-example.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/uart-example.png new file mode 100644 index 0000000000..43896dab64 Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/uart-example.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/upload-color.png b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/upload-color.png new file mode 100644 index 0000000000..da700d9044 Binary files /dev/null and b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/assets/upload-color.png differ diff --git a/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/content.md b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/content.md new file mode 100644 index 0000000000..81dc2023c3 --- /dev/null +++ b/content/hardware/_unlisted/boards/nano-matter/tutorials/user-manual/content.md @@ -0,0 +1,1801 @@ +--- +title: 'Nano Matter User Manual' +difficulty: beginner +compatible-products: [nano-matter] +description: 'Learn about the hardware and software features of the Arduino® Nano Matter.' +tags: + - IoT + - Matter + - BLE + - RGB +author: 'Christopher Mendez' +hardware: + - hardware/03.nano/boards/nano-matter +software: + - ide-v1 + - ide-v2 + - web-editor + - iot-cloud +--- + +## Overview + +This user manual will guide you through a practical journey covering the most interesting features of the Arduino Nano Matter. With this user manual, you will learn how to set up, configure and use this Arduino board. + +![RGB Lightbulb with Nano Matter](assets/matter-google.gif) + +## Hardware and Software Requirements +### Hardware Requirements + +- [Nano Matter](https://store.arduino.cc/products/nano-matter) (x1) +- USB-C® cable (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 Cloud Editor](https://create.arduino.cc/editor) + +## Product Overview + +The Nano Matter merges the well-known Arduino way of making complex technology more accessible with the powerful MGM240S from Silicon Labs, to bring Matter closer to the maker world, in one of the smallest form factors in the market. + +It enables 802.15.4 (Thread®) and Bluetooth® Low Energy connectivity, to interact with Matter-compatible devices with a user-friendly software layer ready for quick prototyping. + +### Board Architecture Overview + +The Nano Matter features a compact and efficient architecture powered by the MGM240S (32-bit Arm® Cortex®-M33) from Silicon Labs, a high-performance wireless module +optimized for the needs of battery and line-powered IoT devices for 2.4 GHz mesh networks. + +![Nano Matter's main components](assets/architecture.png) + +Here is an overview of the board's main components, as shown in the image above: + +- **Microcontroller**: at the heart of the Nano Matter is the MGM240S, a high-performance wireless module from Silicon Labs. The MGM240S is built around a 32-bit Arm® Cortex®-M33 processor running at 78 MHz. +- **Wireless connectivity**: the Nano Matter microcontroller also features multi-protocol connectivity to enable Matter IoT protocol and Bluetooth® Low Energy. This allows the Nano Matter to be integrated with smart home systems and communicate wirelessly with other devices. + +### Board Core and Libraries + +The **Silicon Labs** core contains the libraries and examples you need to work with the board's components, such as its Matter, Bluetooth® Low Energy, and I/Os. To install the Nano Matter core, navigate to **File > Preferences** and in the **Additional boards manager URLs**, add the following: + +`https://siliconlabs.github.io/arduino/package_arduinosilabs_index.json` + +Now 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 `Nano Matter` and install the latest `Silicon Labs` core version. + +![Installing the Silicon Labs core in the Arduino IDE](assets/bsp-install.png) + +### Pinout + +![Nano Matter Simple pinout](assets/simple-pinout.png) + +The full pinout is available and downloadable as PDF from the link below: + +- [Nano Matter pinout](https://docs.arduino.cc/resources/pinouts/ABX00112-full-pinout.pdf) + +### Datasheet + +The complete datasheet is available and downloadable as PDF from the link below: + +- [Nano Matter datasheet](https://docs.arduino.cc/resources/datasheets/ABX00112-datasheet.pdf) + +### Schematics + +The complete schematics are available and downloadable as PDF from the link below: + +- [Nano Matter schematics](https://docs.arduino.cc/resources/schematics/ABX00112-schematics.pdf) + +### STEP Files + +The complete STEP files are available and downloadable from the link below: + +- [Nano Matter STEP files](https://docs.arduino.cc/static/10c0953581f489a9a136ff00f2d2fa9d/ABX00112-step.zip) + + +### Form Factor + +The Nano Matter board features castellated pins, which are ideal for integrating the board into final solutions. + +You can easily solder the Nano Matter in your custom PCB, since the board does not present any bottom-mounted components. + +![Nano Matter castellated pins](assets/castellated-small.png) + +## First Use +### Powering the Board + +The Nano Matter can be powered by: + +- A USB-C® cable (not included). +- An external **5 V power supply** connected to `IN5V` pin (please, refer to the [board pinout section](#pinout) of the user manual). + +![Nano Matter externally powered](assets/ext-power.png) + +For low-power consumption applications, the following hacks are recommended: + +- Cut the power status LED jumper off to save energy. +- Power the board with an external **3.3 V power supply** connected to **3.3V** pin. This will not power the *USB bridge IC*, so more energy will be saved. + +![Image showing the LED jumper and external 3.3 V power](assets/lower-power.png) + +***To power the board through the VIN pin you need to close the jumper pads with solder. The maximum voltage supported is +5 VDC.*** + +### Hello World Example + +Let's program the Nano Matter with the classic `hello world` example typical of the Arduino ecosystem: the `Blink` sketch. We will use this example to verify that the board is correctly connected to the Arduino IDE and that the Silicon Labs core and the board itself are working as expected. + +Copy and paste the code below into a new sketch in the Arduino IDE. + +```arduino +// the setup function runs once when you press reset or power the board +void setup() { + // initialize digital pin LED_BUILTIN as an output. + pinMode(LED_BUILTIN, OUTPUT); +} + +// the loop function runs over and over again forever +void loop() { + digitalWrite(LED_BUILTIN, HIGH); // turn the LED on (HIGH is the voltage level) + delay(1000); // wait for a second + digitalWrite(LED_BUILTIN, LOW); // turn the LED off by making the voltage LOW + delay(1000); // wait for a second +} +``` + +In the Nano Matter, the `LED_BUILTIN` macro represents the **red LED** of the built-in RGB LED of the board. Please refer to the image below. + +To upload the code to the Nano Matter, 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 Nano Matter in the Arduino IDE](assets/compile-blink.png) + +You should now see the red LED of the built-in RGB LED turning on for one second, then off for one second, repeatedly. + +![Hello World example running in the Nano Matter](assets/blink.gif) + +If everything works as expected, you are ready to continue searching and experimenting with this mighty board. + +## Matter + +Developing Matter-compatible IoT solutions has never been easier with the Arduino ecosystem. + +![Nano Matter](assets/nano-matter-banner.png) + +The Nano Matter can communicate with Matter hubs through a Thread® network, so the hubs used must be **Thread® border routers**. + +The Silicon Labs core in the Arduino IDE comes with several Matter examples ready to be tested with the Nano Matter and works as a starting point for almost any IoT device we can imagine building. + +![Matter examples](assets/matter-examples.png) + +***The "matter_lightbulb" example is the only officially Matter-certified profile for the Nano Matter **Community Preview**. Consequently, while running any of the other available profile examples, it is expected to get an "Uncertified device" message in the different Matter-compatible apps. This does not prevent the user from prototyping a solution with different configurations.*** + +First, to start creating *Matter-enabled* solutions, we need to select the Matter protocol in **Tools > Protocol stack > Matter**: + +![Matter Protocol stack selected](assets/matter-setup.png) + +In the example below, we are going to use the Nano Matter as a *RGB Lightbulb*. For this, navigate to **File > Examples > Matter** and open the built-in sketch called **nano_matter_lightbulb_color**. + +```arduino +#include +#include + +#define LED_R LED_BUILTIN +#define LED_G LED_BUILTIN_1 +#define LED_B LED_BUILTIN_2 + +MatterColorLightbulb matter_color_bulb; + +void update_led_color(); +void led_off(); +void handle_button_press(); +volatile bool button_pressed = false; + +void setup() +{ + Serial.begin(115200); + Matter.begin(); + matter_color_bulb.begin(); + matter_color_bulb.boost_saturation(51); // Boost saturation by 20 percent + + // Set up the onboard button + pinMode(BTN_BUILTIN, INPUT_PULLUP); + attachInterrupt(BTN_BUILTIN, &handle_button_press, FALLING); + + // Turn the LED off + led_off(); + + Serial.println("Arduino Nano Matter - color lightbulb"); + + if (!Matter.isDeviceCommissioned()) { + Serial.println("Matter device is not commissioned"); + Serial.println("Commission it to your Matter hub with the manual pairing code or QR code"); + Serial.printf("Manual pairing code: %s\n", Matter.getManualPairingCode().c_str()); + Serial.printf("QR code URL: %s\n", Matter.getOnboardingQRCodeUrl().c_str()); + } + while (!Matter.isDeviceCommissioned()) { + delay(200); + } + + if (!Matter.isDeviceConnected()) { + Serial.println("Waiting for network connection..."); + } + while (!Matter.isDeviceConnected()) { + delay(200); + } + Serial.println("Device connected"); +} + +void loop() +{ + // If the physical button state changes - update the lightbulb's on/off state + if (button_pressed) { + button_pressed = false; + // Invert the on/off state of the lightbulb + bool bulb_state = matter_color_bulb.get_onoff(); + matter_color_bulb.set_onoff(!bulb_state); + } + + // Get the current on/off state of the lightbulb + static bool matter_lightbulb_last_state = false; + bool matter_lightbulb_current_state = matter_color_bulb.get_onoff(); + + // If the current state is ON and the previous was OFF - turn on the LED + if (matter_lightbulb_current_state && !matter_lightbulb_last_state) { + matter_lightbulb_last_state = matter_lightbulb_current_state; + Serial.println("Bulb ON"); + // Set the LEDs to the last received state + update_led_color(); + } + + // If the current state is OFF and the previous was ON - turn off the LED + if (!matter_lightbulb_current_state && matter_lightbulb_last_state) { + matter_lightbulb_last_state = matter_lightbulb_current_state; + Serial.println("Bulb OFF"); + led_off(); + } + + static uint8_t hue_prev = 0; + static uint8_t saturation_prev = 0; + static uint8_t brightness_prev = 0; + uint8_t hue_curr = matter_color_bulb.get_hue(); + uint8_t saturation_curr = matter_color_bulb.get_saturation_percent(); + uint8_t brightness_curr = matter_color_bulb.get_brightness_percent(); + + // If either the hue, saturation or the brightness changes - update the LED to reflect the latest change + if (hue_prev != hue_curr || saturation_prev != saturation_curr || brightness_prev != brightness_curr) { + update_led_color(); + hue_prev = hue_curr; + saturation_prev = saturation_curr; + brightness_prev = brightness_curr; + } +} + +// Updates the color of the RGB LED to match the Matter lightbulb's color +void update_led_color() +{ + if (!matter_color_bulb.get_onoff()) { + return; + } + uint8_t r, g, b; + matter_color_bulb.get_rgb(&r, &g, &b); + analogWrite(LED_R, 255 - r); + analogWrite(LED_G, 255 - g); + analogWrite(LED_B, 255 - b); + Serial.printf("Setting bulb color to > r: %u g: %u b: %u\n", r, g, b); +} + +// Turns the RGB LED off +void led_off() +{ + analogWrite(LED_R, 255); + analogWrite(LED_G, 255); + analogWrite(LED_B, 255); +} + +void handle_button_press() +{ + static uint32_t btn_last_press = 0; + if (millis() < btn_last_press + 200) { + return; + } + btn_last_press = millis(); + button_pressed = true; +} +``` + +Here is the example sketch main functions explanation: + +- In the `setup()` function, Matter is initialized with `Matter.begin()` alongside the initial configurations of the board to handle the different inputs and outputs. The device commissioning is verified with `Matter.isDeviceCommissioned()` to show the user the network pairing credentials if needed and the connection is confirmed with the `Matter.isDeviceConnected()` function. +- In the `loop()` function, the RGB LED is controlled on and off with `matter_color_bulb.set_onoff(state)`, the current state is retrieved with `matter_color_bulb.get_onoff()` and the button state is read to control the LED manually. +- In the `update_led_color()` function, the color defined in the app is retrieved using the function `matter_color_bulb.get_rgb(&r, &g, &b)` that stores the requested color code in RGB format variables. + + +To upload the code to the Nano Matter, click the **Verify** button to compile the sketch and check for errors; then click the **Upload** button to program the board with the sketch. + +![Upload the Matter RGB example](assets/upload-color.png) + +After the code is uploaded, open the Arduino IDE Serial Monitor and reset the board by clicking on the reset button. To commission a Matter device to the network you will need the credentials shown in the terminal. + +![Nano Matter Reset Button](assets/rst-button.png) + +You will find a **Manual pairing code** and a **QR code URL** as follows: + +![Commissioning credentials](assets/qr-code.png) + +***Open the QR code URL on your browser to generate the QR code.*** + +### With Google Home™ + +To create your first IoT device with the Nano Matter and the Google Home ecosystem, you first need to have a Matter-compatible hub. The Google Home products that can work as a **Matter hub** through **Thread®** are listed below: + +- Nest Hub (2nd Gen) +- Nest Hub Max +- Nest Wifi Pro (Wi-Fi 6E) +- Nest Wifi + +***Other Google devices are compatible with Matter but not Thread®.*** + +To commission your device, open the Google Home app, navigate to devices, click on **add device** and select the **matter-enabled device** option: + +![Adding a new Matter device to Google Home](assets/add-device.png) + +Then, wait for the device to be commissioned and added to the Google Home app: + +![Device added](assets/add-device-2.png) + +Finally, you will be able to control the Nano Matter built-in RGB LED as a native smart device. You can turn it on and off and control its color and brightness. + +![RGB Lightbulb with Nano Matter](assets/matter-google.gif) + +You are also able to control your device using voice commands with your personal assistant. + +If you want to commission your Nano Matter solution with another service, follow the steps in the [decommissioning](#device-decommissioning) section. + +### With Amazon Alexa + +The Amazon Alexa products that can work as a **Matter hub** through **Thread®** are listed below: + +- Echo (4th Gen) +- Echo Show 10 (3rd Gen) +- Echo Show 8 (3rd Gen) +- Echo Hub +- Echo Studio (2nd Gen) +- Echo Plus (2nd Gen) +- eero Pro 6 and 6E +- eero 6 and 6+ +- eero PoE 6 and gateway +- eero Pro +- eero Beacon +- eero Max 7 + +***Other Amazon devices are compatible with Matter but not Thread®.*** + +To commission your device, open the Amazon Alexa app, click on the upper right **+** symbol, select **device** and select the **Matter** logo option: + +![Adding a new Matter device to Amazon Alexa](assets/add-device-alexa.png) + +Read the QR code generated by the Nano Matter sketch, select the **Thread®** network available and then wait for the device to be commissioned and added to the Alexa app: + +![Device added](assets/add-device-alexa-2.png) + +Finally, you will be able to control the Nano Matter built-in RGB LED as a native smart device. You can turn it on and off and control its color and brightness. + +![RGB Lightbulb with Nano Matter](assets/matter-alexa.gif) + +You are also able to control your device using voice commands with your personal assistant. + +If you want to commission your Nano Matter solution with another service, follow the steps in the [decommissioning](#device-decommissioning) section. + +### With Apple Home + +The Apple Home products that can work as a **Matter hub** through **Thread®** are listed below: + +- Apple TV 4K (3rd generation) Wi-Fi + Ethernet +- Apple TV 4K (2nd generation) +- HomePod (2nd generation) +- HomePod mini + +To commission your device, open the Apple Home app, click on the upper right **+** symbol, select **Add Accessory** and scan the **QR code** generated by the Nano Matter in the Serial Monitor: + +![Adding a new Matter device to Apple Home](assets/add-device-apple.png) + +If this is your first Matter device, you may be asked to define the Matter hub to be used. Select its house location and give it a name: + +![Selecting the Matter hub (Bridge)](assets/add-device-apple-2.png) + +Then, follow the steps for adding and naming the Matter Light bulb: + +![Adding the Light bulb](assets/add-device-apple-3.png) + +Finally, you will be able to control the Nano Matter built-in RGB LED as a native smart device. You can turn it on and off and control its color and brightness. + +![RGB Lightbulb with Nano Matter](assets/apple.gif) + +You are also able to control your device using voice commands with your personal assistant. + +If you want to commission your Nano Matter solution with another service, follow the steps in the [decommissioning](#device-decommissioning) section. + +### With Home Assistant + +To use Matter with Home Assistant, you will need one of the *Google Home* or *Apple Home* devices that can work as a **Thread® Border Router**, as listed in the previous sections. + +To set up Home Assistant so that it can manage Matter devices, we need first to install the **Matter Server** add-on. For this, navigate to **Settings > Add-Ons > Add-On Store** and search for **Matter server**: + +![Installing the Matter Server](assets/ha-setup.png) + +When the Matter server is correctly installed, navigate to **Settings > Devices % Services > Add Integration** and search for **Matter**: + +![Installing the Matter integration](assets/ha-setup-2.png) + +A prompt will show up asking for a connection method; if you are working with custom containers running the Matter server, uncheck the box. + +In our case, we leave it checked as the Matter server is running in Home Assistant. + +You will receive a **Success** message if everything is okay. With the Home Assistant integration ready, we can start with the Nano Matter commissioning. + +To commission your device, open the Home Assistant app on your smartphone, go to **Settings > Devices & Services**, in the lower tabs bar, go to **Devices** and tap on **Add Device**. Tap on **Add Matter device** and scan the QR code generated by the Nano Matter in the Serial Monitor: + +![Adding a new Matter device to Home Assistant](assets/add-device-ha.png) + +Then, wait for the device to be commissioned and added to the Home Assistant app: + +![Device Added](assets/add-device-ha-2.png) + +Finally, you will be able to control the Nano Matter built-in RGB LED as a native smart device. You can turn it on and off and control its color and brightness. + +You can use the Home Assistant web view or mobile app to control your device. + +![RGB Lightbulb with Nano Matter](assets/ha.gif) + +If you want to commission your Nano Matter solution with another service, follow the steps in the [decommissioning](#device-decommissioning) section. + +#### Home Assistant Tips + +- Make sure you are using a **64-bit** Home Assistant OS version. +- Use the **Thread®** add-on to verify your available Thread® networks. +- You can just have a Matter device commissioned to one platform at a time. + +### Device Decommissioning + +If you have a Matter device configured and working with a _specific platform_, for example with the Google Home ecosystem, and you want to integrate it with Alexa or Apple Home instead, you need to decommission it first from the previous service. + +In simple terms, **decommissioning** refers to unpairing your device from a current service to be able to pair it with a new one. + +You can integrate this method in your solutions to leverage the Nano Matter built-in button to handle decommissioning: + +```arduino +#include + +void setup() { + // put your setup code here, to run once: + Serial.begin(115200); + + Matter.begin(); + pinMode(BTN_BUILTIN, INPUT_PULLUP); + pinMode(LEDR, OUTPUT); + digitalWrite(LEDR, HIGH); +} + +void loop() { + // put your main code here, to run repeatedly: + decommission_handler(); +} + + +void decommission_handler() { + if (digitalRead(BTN_BUILTIN) == LOW) { //Push button pressed + // measures time pressed + int startTime = millis(); + while (digitalRead(BTN_BUILTIN) == LOW) { + + int elapsedTime = (millis() - startTime) / 1000.0; + + if (elapsedTime > 10) { + Serial.printf("Decommissioning!\n"); + for (int i = 0; i < 10; i++) { + digitalWrite(LEDR, !(digitalRead(LEDR))); + delay(100); + }; + + if (!Matter.isDeviceCommissioned()) { + Serial.println("Decommission done!"); + digitalWrite(LEDR, LOW); + } else { + Serial.println("Matter device is commissioned-> Starting Decommission process"); + nvm3_eraseAll(nvm3_defaultHandle); // Decomission command + digitalWrite(LED_BUILTIN, LOW); + Serial.println("Decommission done!"); + } + break; + } + } + } +} +``` +The sketch above allows you to decommission your board manually after **pressing** the Nano Matter user button for **10 seconds**. You can monitor the status in the Arduino IDE Serial Monitor. + +## Arduino Cloud + +The Nano Matter has no built-in Wi-Fi® but can be seamlessly integrated with the Arduino Cloud using its [API](https://www.arduino.cc/reference/en/iot/api/) and Matter. + +We are going to use the [Home Assistant Matter integration](#with-home-assistant) to create automations and scripts that help us forward the Nano Matter data to the Arduino Cloud. + +In case it is the first time you are using the Arduino Cloud: + +- To use the Arduino Cloud, you need an account. If you do not have an account, create one for free [here](https://cloud.arduino.cc/). +- See the [Arduino Cloud plans](https://cloud.arduino.cc/plans/) and choose one that features **API** support. + +As a practical example, we are going to use the Nano Matter CPU temperature sensor and send the data to Arduino Cloud for monitoring. We will leverage the variety of widgets to create a professional and nice-looking user interface. + +### Nano Matter Programming + +The application sketch below is based on the `matter_temp_sensor` example that can be also found in **File > Examples > Matter**. This variation includes the [decommission](#device-decommissioning) feature to show it implemented in a real application. + +```arduino +#include +#include + +MatterTemperature matter_temp_sensor; + +unsigned long previousMillis = 0; // will store last time sensor was updated +const long interval = 2000; // interval at which to send sensor data + +void setup() { + Serial.begin(115200); + Matter.begin(); + + pinMode(BTN_BUILTIN, INPUT_PULLUP); + pinMode(LEDR, OUTPUT); + digitalWrite(LEDR, HIGH); + + matter_temp_sensor.begin(); + + Serial.println("Matter temperature sensor"); + + if (!Matter.isDeviceCommissioned()) { + Serial.println("Matter device is not commissioned"); + Serial.println("Commission it to your Matter hub with the manual pairing code or QR code"); + Serial.printf("Manual pairing code: %s\n", Matter.getManualPairingCode().c_str()); + Serial.printf("QR code URL: %s\n", Matter.getOnboardingQRCodeUrl().c_str()); + } + while (!Matter.isDeviceCommissioned()) { + delay(200); + } + + if (!Matter.isDeviceConnected()) { + Serial.println("Waiting for network connection..."); + } + while (!Matter.isDeviceConnected()) { + delay(200); + } + Serial.println("Device connected"); +} + +void loop() { + decommission_handler(); // if the user button is pressed for 10 seconds + + float current_cpu_temp = getCPUTemp(); // reads CPU temperature + + unsigned long currentMillis = millis(); + + if (currentMillis - previousMillis >= interval) { + // save the last time you updated the sensor + previousMillis = currentMillis; + + matter_temp_sensor.set_measured_value_celsius(current_cpu_temp); + Serial.printf("Current CPU temperature: %.02f C\n", current_cpu_temp); + } +} + +void decommission_handler() { + if (digitalRead(BTN_BUILTIN) == LOW) { //Push button pressed + // measures time pressed + int startTime = millis(); + while (digitalRead(BTN_BUILTIN) == LOW) { + //delay(50); + + int elapsedTime = (millis() - startTime) / 1000.0; + + if (elapsedTime > 10) { + Serial.printf("Decommissioning!\n"); + for (int i = 0; i < 10; i++) { + digitalWrite(LEDR, !(digitalRead(LEDR))); + delay(100); + }; + + if (!Matter.isDeviceCommissioned()) { + Serial.println("Decommission done!"); + digitalWrite(LEDR, LOW); + } else { + Serial.println("Matter device is commissioned-> Starting Decommission process"); + nvm3_eraseAll(nvm3_defaultHandle); // Decomission command + digitalWrite(LED_BUILTIN, LOW); + Serial.println("Decommission done!"); + } + break; + } + } + } +} +``` +The main code functions are explained below: + +- The temperature sensor object is created with the `MatterTemperature matter_temp_sensor;` statement. To initiate it, in the `setup()` function, we used `matter_temp_sensor.begin();` +- The `decommission_handler()` lets us unpair the device from a previous platform. +- The microcontroller's internal temperature is measured with the function `getCPUTemp();`. +- The temperature value is advertised using the `matter_temp_sensor.set_measured_value_celsius(current_cpu_temp);` function. + +After uploading the code to the Nano Matter, verify it is decommissioned from any other service previously used. For this, open the Serial Monitor and reset the board by clicking on the reset button. + +If it is not decommissioned you will see temperature readings printed in the Serial Monitor. To decommission it, follow these steps: + +- Press the user button for **10 seconds** until the board's built-in LED starts **blinking in red**. You will also see a message confirming the process in the Serial Monitor. + +- Finally, reset the board by clicking on the reset button and you should see the Matter commissioning credentials in the Serial Monitor. + +### Device Commissioning + +Now it is time to commission the Nano Matter with Home Assistant, for this, follow the steps explained in this [section](#with-home-assistant). + +Once you have everything set up and running you will be able to monitor the Nano Matter temperature in Home Assistant: + +![Nano Matter Temperature in Home Assistant](assets/home-assistant-temp.png) + +### Arduino Cloud Set-Up + +Let's walk through a step-by-step demonstration of how to set up the Arduino Cloud. + +Log in to your Arduino Cloud account; you should see the following: + +![Arduino Cloud Initial Page](assets/cloud-login.png) + +Navigate to **Things** in the left bar menu and click on **+ Thing** to add a Thing: + +![Creating a Thing](assets/cloud-thing.png) + +Give your Thing a name and click on **ADD** to add the temperature variable: + +![Adding a variable](assets/cloud-add-variable.png) + +Define the variable with the following settings: + +- Name: temperature +- Type: Floating Point Number +- Permission: Read & Write +- Update Policy: On change + +![Setting up the variable](assets/cloud-setup-variable.png) + +Click on the created variable and copy its **ID**, we will need it later. + +![Variable ID](assets/id-gathering-1.png) + +Navigate to your Thing metadata and copy the **Thing ID**, we will need it later. + +![Thing ID](assets/id-gathering-2.png) + +In the left bar menu, navigate to **Space Settings** and copy the **Space ID**, we will need it later. + +![Space ID](assets/id-gathering-3.png) + +***If you can't see the _Space Settings_ section is because you are using an Arduino Cloud free plan, check the [plans](https://cloud.arduino.cc/plans) with the API feature enabled.*** + +At this point you should have three IDs related to your project: + +- Variable ID +- Thing ID +- Space ID + +To properly authenticate the requests we are going to use to upload the data to the Arduino Cloud we need to create **API Keys**. + +For this, navigate to **API Keys** in the upper left corner drop-down menu and click on **Create API Key**: + +![API Keys generation](assets/api-key.png) + +You should get a **Client ID** and a **Client Secret**. Save these credentials in a safe place, you will not be able to see them again. + +### Home Assistant Set-Up + +Now, let's configure Home Assistant to set the forwarding method to Arduino Cloud. + +First, we are going to save and define our project IDs, credentials and Keys in a safe place inside the Home Assistant directory called **secrets.yaml**. Use the _File Editor_ Add-on to easily edit this file, and format the data as follows: + +``` +arduino_organization: + +token_get_payload: '{"grant_type":"client_credentials","client_id":"","client_secret":"","audience":"https://api2.arduino.cc/iot"}' + +arduino_temp_url: https://api2.arduino.cc/iot/v2/things//properties//publish +``` +This will let us use this data without exposing it later. + +![Secrets.yaml file to store credentials](assets/ha-setup-cloud.png) + +Now, let's define the services that will help us do the HTTP requests to Arduino Cloud sending the temperature value to it. Using the **File Editor** navigate to the **configuration.yaml** file and add the following blocks: + +``` +rest: + - resource: "https://api2.arduino.cc/iot/v1/clients/token" + scan_interval: 240 #4 min + timeout: 60 + method: "POST" + headers: + content_type: 'application/json,application/x-www-form-urlencoded' + payload: !secret token_get_payload + sensor: + - name: "API_Token_Bearer" + value_template: "OK" + json_attributes_path: '$..' + json_attributes: + - 'access_token' +``` +The [RESTful integration](https://www.home-assistant.io/integrations/rest/) lets us periodically gather from our Arduino Cloud account a **token** that is mandatory to authenticate our requests. This token expires every 5 minutes, this is why we generate it every 4 minutes. The token is stored in a sensor attribute called **API_Token_Bearer**. + +``` +rest_command: + send_temperature: + method: PUT + headers: + Authorization: "Bearer {{ state_attr('sensor.api_token_bearer', 'access_token') }}" + accept: "application/vnd.arduino.property+json,application/vnd.goa.error+json" + content_type: 'application/json,application/x-www-form-urlencoded' + X-Organization: !secret arduino_organization + url: !secret arduino_temp_url + payload: "{\"value\":{{states('sensor.matter_device_temperature')}}}" +``` +The [RESTful command integration](https://www.home-assistant.io/integrations/rest_command/) lets us define the HTTP request structure to be able to send the Nano Matter temperature sensor data to the Arduino Cloud. We can call this service from an automation. + +As you may noticed, the sensitive data we stored in the "secrets.yaml" file is being called here with the **!secret** prefix. + +![configuration.yaml file to define services](assets/ha-setup-config.png) + +To learn more about the Arduino Cloud API, follow this [guide](https://docs.arduino.cc/arduino-cloud/api/arduino-iot-api/). + +For the changes to take effect, navigate to **Developers Tools** and click on **Check Configuration**, if there are no errors, click on **Restart** and restart Home Assistant. + +![Restarting Home Assistant](assets/restart-ha.png) + +Finally, let's set up the automation that will call the **send_temperature** service every time the temperature sensor values change. + +For this, navigate to **Settings > Automations & scenes** and click on **Create Automation**. + +![Automation setting](assets/automation-create.png) + +In the upper right corner, click on the "three dots" menu and select **Edit in YAML**, replace the text there with the following: + +``` +alias: Nano Matter Temperature +description: "" +trigger: + - platform: state + entity_id: + - sensor.matter_device_temperature +condition: [] +action: + - service: rest_command.send_temperature + data: {} +mode: single +``` + +This automation will be triggered if the Nano Matter sensor temperature value changes and will act by calling the **rest_command.send_temperature** service. + +![Automation defining](assets/automation-define.png) + +***If you used different names for the services or devices, make sure to update them in the YAML code above.*** + +### Final Results + +With this done, Home Assistant should be forwarding the Nano Matter sensor data to Arduino Cloud where you can monitor it with different widgets and charts as follows: + +![Arduino Cloud Demo](assets/cloud-demo.gif) + +## Bluetooth® Low Energy + +To enable Bluetooth® Low Energy communication on the Nano Matter, you must enable the "BLE" protocol stack in the Arduino IDE board configurations. + +In the upper menu, navigate to **Tools > Protocol stack** and select **BLE**. + +![Enable "BLE" Protocol Stack](assets/ble-setup.png) + +For this Bluetooth® Low Energy application example, we are going to control the Nano Matter built-in LED and read the onboard button status. The example sketch to be used can be found in **File > Examples > Silicon Labs >ble_blinky**: + +```arduino +/* + BLE blinky example +*/ + +bool btn_notification_enabled = false; +bool btn_state_changed = false; +uint8_t btn_state = LOW; +static void btn_state_change_callback(); +static void send_button_state_notification(); +static void set_led_on(bool state); + +void setup() +{ + pinMode(LED_BUILTIN, OUTPUT); + set_led_on(false); + Serial.begin(115200); + Serial.println("Silicon Labs BLE blinky example"); + + // If the board has a built-in button configure it for usage + #ifdef BTN_BUILTIN + pinMode(BTN_BUILTIN, INPUT_PULLUP); + attachInterrupt(BTN_BUILTIN, btn_state_change_callback, CHANGE); + #else // BTN_BUILTIN + // Avoid warning for unused function on boards without a button + (void)btn_state_change_callback; + #endif // BTN_BUILTIN +} + +void loop() +{ + if (btn_state_changed) { + btn_state_changed = false; + send_button_state_notification(); + } +} + +static void ble_initialize_gatt_db(); +static void ble_start_advertising(); + +static const uint8_t advertised_name[] = "Blinky Example"; +static uint16_t gattdb_session_id; +static uint16_t generic_access_service_handle; +static uint16_t name_characteristic_handle; +static uint16_t blinky_service_handle; +static uint16_t led_control_characteristic_handle; +static uint16_t btn_report_characteristic_handle; + +/**************************************************************************//** + * Bluetooth stack event handler + * Called when an event happens on BLE the stack + * + * @param[in] evt Event coming from the Bluetooth stack + *****************************************************************************/ +void sl_bt_on_event(sl_bt_msg_t *evt) +{ + switch (SL_BT_MSG_ID(evt->header)) { + // ------------------------------- + // This event indicates the device has started and the radio is ready. + // Do not call any stack command before receiving this boot event! + case sl_bt_evt_system_boot_id: + { + Serial.println("BLE stack booted"); + + // Initialize the application specific GATT table + ble_initialize_gatt_db(); + + // Start advertising + ble_start_advertising(); + Serial.println("BLE advertisement started"); + } + break; + + // ------------------------------- + // This event indicates that a new connection was opened + case sl_bt_evt_connection_opened_id: + Serial.println("BLE connection opened"); + break; + + // ------------------------------- + // This event indicates that a connection was closed + case sl_bt_evt_connection_closed_id: + Serial.println("BLE connection closed"); + // Restart the advertisement + ble_start_advertising(); + Serial.println("BLE advertisement restarted"); + break; + + // ------------------------------- + // This event indicates that the value of an attribute in the local GATT + // database was changed by a remote GATT client + case sl_bt_evt_gatt_server_attribute_value_id: + // Check if the changed characteristic is the LED control + if (led_control_characteristic_handle == evt->data.evt_gatt_server_attribute_value.attribute) { + Serial.println("LED control characteristic data received"); + // Check the length of the received data + if (evt->data.evt_gatt_server_attribute_value.value.len == 0) { + break; + } + // Get the received byte + uint8_t received_data = evt->data.evt_gatt_server_attribute_value.value.data[0]; + // Turn the LED on/off according to the received data + if (received_data == 0x00) { + set_led_on(false); + Serial.println("LED off"); + } else if (received_data == 0x01) { + set_led_on(true); + Serial.println("LED on"); + } + } + break; + + // ------------------------------- + // This event is received when a GATT characteristic status changes + case sl_bt_evt_gatt_server_characteristic_status_id: + // If the 'Button report' characteristic has been changed + if (evt->data.evt_gatt_server_characteristic_status.characteristic == btn_report_characteristic_handle) { + // The client just enabled the notification - send notification of the current button state + if (evt->data.evt_gatt_server_characteristic_status.client_config_flags & sl_bt_gatt_notification) { + Serial.println("Button state change notification enabled"); + btn_notification_enabled = true; + btn_state_change_callback(); + } else { + Serial.println("Button state change notification disabled"); + btn_notification_enabled = false; + } + } + break; + + // ------------------------------- + // Default event handler + default: + break; + } +} + +/**************************************************************************//** + * Called on button state change - stores the current button state and + * sets a flag that a button state change occurred. + * If the board doesn't have a button the function does nothing. + *****************************************************************************/ +static void btn_state_change_callback() +{ + // If the board has a built-in button + #ifdef BTN_BUILTIN + // The real button state is inverted - most boards have an active low button configuration + btn_state = !digitalRead(BTN_BUILTIN); + btn_state_changed = true; + #endif // BTN_BUILTIN +} + +/**************************************************************************//** + * Sends a BLE notification the the client if notifications are enabled and + * the board has a built-in button. + *****************************************************************************/ +static void send_button_state_notification() +{ + if (!btn_notification_enabled) { + return; + } + sl_status_t sc = sl_bt_gatt_server_notify_all(btn_report_characteristic_handle, + sizeof(btn_state), + &btn_state); + if (sc == SL_STATUS_OK) { + Serial.print("Notification sent, button state: "); + Serial.println(btn_state); + } +} + +/**************************************************************************//** + * Sets the built-in LED to the desired state accounting for the inverted LED + * logic on select boards. + *****************************************************************************/ +static void set_led_on(bool state) +{ + bool state_out = state; + #if defined(ARDUINO_NANO_MATTER) || defined(ARDUINO_SILABS_WIOMG24_BLE) || defined(ARDUINO_SILABS_XG24DEVKIT) + // These boards have an inverted LED logic, state is negated to account for this + state_out = !state_out; + #endif + digitalWrite(LED_BUILTIN, state_out); +} + +/**************************************************************************//** + * Starts BLE advertisement + * Initializes advertising if it's called for the first time + *****************************************************************************/ +static void ble_start_advertising() +{ + static uint8_t advertising_set_handle = 0xff; + static bool init = true; + sl_status_t sc; + + if (init) { + // Create an advertising set + sc = sl_bt_advertiser_create_set(&advertising_set_handle); + app_assert_status(sc); + + // Set advertising interval to 100ms + sc = sl_bt_advertiser_set_timing( + advertising_set_handle, + 160, // minimum advertisement interval (milliseconds * 1.6) + 160, // maximum advertisement interval (milliseconds * 1.6) + 0, // advertisement duration + 0); // maximum number of advertisement events + app_assert_status(sc); + + init = false; + } + + // Generate data for advertising + sc = sl_bt_legacy_advertiser_generate_data(advertising_set_handle, sl_bt_advertiser_general_discoverable); + app_assert_status(sc); + + // Start advertising and enable connections + sc = sl_bt_legacy_advertiser_start(advertising_set_handle, sl_bt_advertiser_connectable_scannable); + app_assert_status(sc); +} + +/**************************************************************************//** + * Initializes the GATT database + * Creates a new GATT session and adds certain services and characteristics + *****************************************************************************/ +static void ble_initialize_gatt_db() +{ + sl_status_t sc; + // Create a new GATT database + sc = sl_bt_gattdb_new_session(&gattdb_session_id); + app_assert_status(sc); + + // Add the Generic Access service to the GATT DB + const uint8_t generic_access_service_uuid[] = { 0x00, 0x18 }; + sc = sl_bt_gattdb_add_service(gattdb_session_id, + sl_bt_gattdb_primary_service, + SL_BT_GATTDB_ADVERTISED_SERVICE, + sizeof(generic_access_service_uuid), + generic_access_service_uuid, + &generic_access_service_handle); + app_assert_status(sc); + + // Add the Device Name characteristic to the Generic Access service + // The value of the Device Name characteristic will be advertised + const sl_bt_uuid_16_t device_name_characteristic_uuid = { .data = { 0x00, 0x2A } }; + sc = sl_bt_gattdb_add_uuid16_characteristic(gattdb_session_id, + generic_access_service_handle, + SL_BT_GATTDB_CHARACTERISTIC_READ, + 0x00, + 0x00, + device_name_characteristic_uuid, + sl_bt_gattdb_fixed_length_value, + sizeof(advertised_name) - 1, + sizeof(advertised_name) - 1, + advertised_name, + &name_characteristic_handle); + app_assert_status(sc); + + // Start the Generic Access service + sc = sl_bt_gattdb_start_service(gattdb_session_id, generic_access_service_handle); + app_assert_status(sc); + + // Add the Blinky service to the GATT DB + // UUID: de8a5aac-a99b-c315-0c80-60d4cbb51224 + const uuid_128 blinky_service_uuid = { + .data = { 0x24, 0x12, 0xb5, 0xcb, 0xd4, 0x60, 0x80, 0x0c, 0x15, 0xc3, 0x9b, 0xa9, 0xac, 0x5a, 0x8a, 0xde } + }; + sc = sl_bt_gattdb_add_service(gattdb_session_id, + sl_bt_gattdb_primary_service, + SL_BT_GATTDB_ADVERTISED_SERVICE, + sizeof(blinky_service_uuid), + blinky_service_uuid.data, + &blinky_service_handle); + app_assert_status(sc); + + // Add the 'LED Control' characteristic to the Blinky service + // UUID: 5b026510-4088-c297-46d8-be6c736a087a + const uuid_128 led_control_characteristic_uuid = { + .data = { 0x7a, 0x08, 0x6a, 0x73, 0x6c, 0xbe, 0xd8, 0x46, 0x97, 0xc2, 0x88, 0x40, 0x10, 0x65, 0x02, 0x5b } + }; + uint8_t led_char_init_value = 0; + sc = sl_bt_gattdb_add_uuid128_characteristic(gattdb_session_id, + blinky_service_handle, + SL_BT_GATTDB_CHARACTERISTIC_READ | SL_BT_GATTDB_CHARACTERISTIC_WRITE, + 0x00, + 0x00, + led_control_characteristic_uuid, + sl_bt_gattdb_fixed_length_value, + 1, // max length + sizeof(led_char_init_value), // initial value length + &led_char_init_value, // initial value + &led_control_characteristic_handle); + + // Add the 'Button report' characteristic to the Blinky service + // UUID: 61a885a4-41c3-60d0-9a53-6d652a70d29c + const uuid_128 btn_report_characteristic_uuid = { + .data = { 0x9c, 0xd2, 0x70, 0x2a, 0x65, 0x6d, 0x53, 0x9a, 0xd0, 0x60, 0xc3, 0x41, 0xa4, 0x85, 0xa8, 0x61 } + }; + uint8_t btn_char_init_value = 0; + sc = sl_bt_gattdb_add_uuid128_characteristic(gattdb_session_id, + blinky_service_handle, + SL_BT_GATTDB_CHARACTERISTIC_READ | SL_BT_GATTDB_CHARACTERISTIC_NOTIFY, + 0x00, + 0x00, + btn_report_characteristic_uuid, + sl_bt_gattdb_fixed_length_value, + 1, // max length + sizeof(btn_char_init_value), // initial value length + &btn_char_init_value, // initial value + &btn_report_characteristic_handle); + + // Start the Blinky service + sc = sl_bt_gattdb_start_service(gattdb_session_id, blinky_service_handle); + app_assert_status(sc); + + // Commit the GATT DB changes + sc = sl_bt_gattdb_commit(gattdb_session_id); + app_assert_status(sc); +} + +``` +Here are the main functions explanations of the example sketch: + +The `sl_bt_on_event(sl_bt_msg_t *evt)` function is the main one of the sketch and it is responsible for: +- Initiating the Bluetooth® Low Energy radio, and start advertising the defined services alongside its characteristics. +- Handling the opening and closing of connections. +- Handling incoming and outgoing Bluetooth® Low Energy messages. + +The `ble_initialize_gatt_db()` function is responsible for: +- Adding the Generic Access service with the `1800` UUID. +- Adding the Blinky service with the `de8a5aac-a99b-c315-0c80-60d4cbb51224` UUID. +- Creating the device name characteristic so we can find the device as "Blinky Example" with the `2A00` UUID. +- Adding the LED Control characteristic to the Blinky service with the `5b026510-4088-c297-46d8-be6c736a087a` UUID. +- Adding the Button report characteristic to the Blinky service with the `61a885a4-41c3-60d0-9a53-6d652a70d29c` UUID. + +***Note that if you want to implement a different or custom Bluetooth® Low Energy service or characteristic, the UUID arrays have to start with the least significant bit (LSB) from left to right.*** + +After uploading the sketch to the Nano Matter, it is time to communicate with it through Bluetooth® Low Energy. For this, Silicon Labs has developed a **mobile app** that you can download from here: + +- [Android](https://play.google.com/store/apps/details?id=com.siliconlabs.bledemo) +- [iOS](https://itunes.apple.com/us/app/silicon-labs-blue-gecko-wstk/id1030932759) + +Open the *EFR Connect BLE Mobile APP* on your smartphone, in the lower menu, navigate to **Demo** and select **Blinky**: + +![Blinky demo controlling the Nano Matter through Bluetooth® Low Energy](assets/BlinkyBLE.gif) + +***You can also manage the LED control and button status manually from the Scan tab in the lower menu.*** + +## Onboard User Interface + +### User Button + +The Nano Matter includes an onboard **push button** that can be used as an input by the user. The button is connected to the GPIO `PA0` and can be read using the `BTN_BUILTIN` macro. + +![Nano Matter Built-in Push Button](assets/button.png) + +The button pulls the input to the ground when pressed, so is important to define the **pull-up resistor** to avoid undesired behavior by leaving the input floating. + +Here you can find a complete example code to blink the built-in RGB LED of the Nano Matter: + +```arduino +volatile bool button_pressed = false; + +void handle_button_press(); + +void setup() { + Serial.begin(115200); + + pinMode(BTN_BUILTIN, INPUT_PULLUP); + attachInterrupt(BTN_BUILTIN, &handle_button_press, FALLING); +} + +void loop() { + // If the physical button state changes - update the state + if (button_pressed) { + button_pressed = false; + Serial.println("Button Pressed!"); + } +} + +void handle_button_press() +{ + static uint32_t btn_last_press = 0; + if (millis() < btn_last_press + 200) { + return; + } + btn_last_press = millis(); + button_pressed = true; +} + +``` + +After pressing the push button, you will see a **"Button Pressed!"** message in the Serial Monitor. + +### RGB LED + +The Nano Matter features a built-in RGB LED that can be a visual feedback indicator for the user. The LED is connected through the board GPIO's; therefore, usual digital pins built-in functions can be used to operate the LED colors. + +| **LED Color Segment** | **Arduino Name** | **Microcontroller Pin** | +|:---------------------:|:----------------:|:-----------------------:| +| Red | LEDR or LED_BUILTIN | PC01 | +| Green | LEDG or LED_BUILTIN_1 | PC02 | +| Blue | LEDB or LED_BUILTIN_2 | PC03 | + +***The RGB LED colors are activated with zeros, this means that you need to set to LOW the color segment you want to turn on.*** + +![Built-in RGB LED](assets/rgb-led.png) + + +Here you can find a complete example code to blink the built-in RGB LED of the Nano Matter: + +```arduino +void setup() { + // initialize LED digital pins as outputs. + pinMode(LEDR, OUTPUT); + pinMode(LEDG, OUTPUT); + pinMode(LEDB, OUTPUT); +} + +// the loop function runs over and over again forever +void loop() { + digitalWrite(LEDR, LOW); // turn the LED on (LOW is the voltage level) + digitalWrite(LEDG, HIGH); // turn the LED off (HIGH is the voltage level) + digitalWrite(LEDB, HIGH); // turn the LED off (HIGH is the voltage level) + delay(1000); // wait for a second + digitalWrite(LEDR, HIGH); // turn the LED off by making the voltage HIGH + digitalWrite(LEDG, LOW); // turn the LED on by making the voltage LOW + digitalWrite(LEDB, HIGH); // turn the LED off by making the voltage HIGH + delay(1000); // wait for a second + digitalWrite(LEDR, HIGH); // turn the LED off by making the voltage HIGH + digitalWrite(LEDG, HIGH); // turn the LED off by making the voltage HIGH + digitalWrite(LEDB, LOW); // turn the LED on by making the voltage LOW + delay(1000); +} +``` + +![Nano Matter built-in LED blink](assets/rgb-blink.gif) + +## Pins + +### Digital Pins + +The Nano Matter has **22 digital pins**, mapped as follows: + +| **Microcontroller Pin** | **Arduino Pin Mapping** | **Pin Functionality** | +|:-----------------------:|:-----------------------:|:---------------------:| +| PB00 | A0 | GPIO/ADC/DAC | +| PB02 | A1 | GPIO/ADC | +| PB05 | A2 | GPIO/ADC | +| PC00 | A3 | GPIO/ADC | +| PA06 | A4/SDA | I2C/GPIO/ADC | +| PA07 | A5/SCL | I2C/GPIO/ADC | +| PB01 | A6 | GPIO/ADC/DAC | +| PB03 | A7 | GPIO/ADC | +| PB04 | D13 | SPI/GPIO/ADC | +| PA08 | D12 | SPI/GPIO/ADC | +| PA09 | D11 | SPI/GPIO/ADC | +| PD05 | D10 | SPI/GPIO | +| PD04 | D9 | GPIO | +| PD03 | D8 | GPIO/ADC | +| PD02 | D7 | GPIO/ADC | +| PC09 | D6 | GPIO/ADC | +| PC08 | D5 | GPIO/ADC | +| PC07 | D4 | GPIO/ADC | +| PC06 | D3 | GPIO/ADC | +| PA03 | D2 | GPIO | +| PA04 | PIN_SERIAL_TX | UART/GPIO/ADC | +| PA05 | PIN_SERIAL_RX | UART/GPIO/ADC | + + +The digital pins of the Nano Matter can be used as inputs or outputs 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()` 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()` as shown below: + +```arduino +// Read pin state, store value in a state variable +state = digitalRead(pin); +``` + +The state of a digital pin, configured as an output, can be changed using the built-in function `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 `5` to control an LED and reads the state of a button connected to digital pin `4`: + +![Digital I/O example wiring](assets/gpio-wiring.png) + +```arduino +// Define button and LED pin +int buttonPin = 4; +int ledPin = 5; + +// 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(115200); +} + +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); + Serial.println("- Button is not pressed. LED is off."); + } + + // Wait for 1000 milliseconds + delay(1000); +} +``` + +### PWM Pins + +All the digital and analog pins of the Nano Matter can be used as PWM (Pulse Width Modulation) pins. + +***You can only use 5 PWMs outputs simultaneously.*** + +This functionality can be used with the built-in function `analogWrite()` as shown below: + +```arduino +analogWrite(pin, value); +``` +By default, the output resolution is 8 bits, so the output value should be between 0 and 255. To set a greater resolution, do it using the built-in function `analogWriteResolution` as shown below: + +```arduino +analogWriteResolution(bits); +``` + +Using this function has some limitations, for example, the PWM signal frequency is fixed at 1 kHz, and this could not be ideal for every application. + +Here is an example of how to create a **1 kHz** variable duty-cycle PWM signal: + +```arduino +const int analogInPin = A0; // Analog input pin that the potentiometer is attached to +const int pwmOutPin = 13; // PWM output pin + +int sensorValue = 0; // value read from the pot +int outputValue = 0; // value output to the PWM (analog out) + +void setup() { + // initialize serial communications at 9600 bps: + Serial.begin(115200); + analogWriteResolution(12); +} + +void loop() { + // read the analog in value: + sensorValue = analogRead(analogInPin); + // map it to the range of the analog out: + outputValue = sensorValue; + // change the analog out value: + analogWrite(pwmOutPin, outputValue); + + // print the results to the Serial Monitor: + Serial.print("sensor = "); + Serial.print(sensorValue); + Serial.print("\t output = "); + Serial.println(outputValue); + + // wait 2 milliseconds before the next loop for the analog-to-digital + // converter to settle after the last reading: + delay(2); +} +``` + +![PWM output signal using the PWM at a lower level](assets/pwm-out.png) + +If you need to work with a **higher frequency** PWM signal, you can do it with the following PWM class-specific function: + +```arduino +PWM.frequency_mode(output_pin, frequency); +``` +Here is an example of how to create a **10 kHz** fixed duty-cycle PWM signal: + +```arduino +const int analogOutPin = 13; // PWM output pin to use + +void setup() { + analogWriteResolution(12); +} + +void loop() { + PWM.frequency_mode(analogOutPin, 10000); +} +``` + +![PWM output signal using the PWM at a lower level](assets/freq-out.png) + +### Analog Input Pins (ADC) + +The Nano Matter has **19 analog input pins**, mapped as follows: + +| **Microcontroller Pin** | **Arduino Pin Mapping** | **Pin Functionality** | +|:-----------------------:|:-----------------------:|:---------------------:| +| PB00 | A0 | GPIO/ADC/DAC | +| PB02 | A1 | GPIO/ADC | +| PB05 | A2 | GPIO/ADC | +| PC00 | A3 | GPIO/ADC | +| PA06 | A4/SDA | I2C/GPIO/ADC | +| PA07 | A5/SCL | I2C/GPIO/ADC | +| PB01 | A6 | GPIO/ADC/DAC | +| PB03 | A7 | GPIO/ADC | +| PB04 | D13 | SPI/GPIO/ADC | +| PA08 | D12 | SPI/GPIO/ADC | +| PA09 | D11 | SPI/GPIO/ADC | +| PD03 | D8 | GPIO/ADC | +| PD02 | D7 | GPIO/ADC | +| PC09 | D6 | GPIO/ADC | +| PC08 | D5 | GPIO/ADC | +| PC07 | D4 | GPIO/ADC | +| PC06 | D3 | GPIO/ADC | +| PA04 | PIN_SERIAL_TX | UART/GPIO/ADC | +| PA05 | PIN_SERIAL_RX | UART/GPIO/ADC | + +***Digital I/O's can also be used as analog inputs with the exception of `D10`,`D9` and `D2`.*** + +Analog input pins can be used through the built-in functions of the Arduino programming language. + +Nano Matter ADC resolution is fixed to 12 bits and cannot be changed by the user. + +The Nano Matter ADC reference voltage is 3.3 V by default, it can be configured using the function `analogReference()` with the following arguments: + + +| **Argument** | **Description** | +|:----------------:|:------------------------------:| +| AR_INTERNAL1V2 | Internal 1.2V reference | +| AR_EXTERNAL_1V25 | External 1.25V reference | +| AR_VDD | VDD (unbuffered to ground) | +| AR_08VDD | 0.8 * VDD (buffered to ground) | +| AR_MAX | Maximum value | + +To set a different analog reference from the default one, see the following example: + +```arduino +analogReference(AR_INTERNAL1V2); +``` + +The example code shown below reads the analog input value from a potentiometer connected to `A0` and displays it on the IDE Serial Monitor. To understand how to properly connect a potentiometer to the Nano Matter, take the following image as a reference: + +![ADC input example wiring](assets/adc-input.png) + +```arduino +int sensorPin = A0; // select the input pin for the potentiometer + +int sensorValue = 0; // variable to store the value coming from the sensor + +void setup() { + Serial.begin(115200); +} + +void loop() { + // read the value from the sensor: + sensorValue = analogRead(sensorPin); + + Serial.println(sensorValue); + delay(100); +} +``` + +### Analog Output Pins (DAC) + +The Nano Matter has **one DAC** with two channels, mapped as follows: + +| **Microcontroller Pin** | **Arduino Name** | **Board Pin Output** | **Peripheral** | +|:-----------------------:|:----------------:|:--------------------:|:--------------:| +| PB00 | DAC0 | A0 | DAC0_CH0 | +| PB01 | DAC1 | A6 | DAC0_CH1 | + +The digital-to-analog converters of the Nano Matter can be used as outputs through the built-in functions of the Arduino programming language. + +The DAC output resolution can be configured using the `analogWriteResolution()` function as follows: + +```arduino +analogWriteResolution(12); // enter the desired resolution in bits (8,10,12) +``` +The DAC voltage reference can be configured using the `analogReferenceDAC()` function. The available setups are listed below: + +| **Argument** | **Description** | +|:---------------------:|:------------------------:| +| DAC_VREF_1V25 | Internal 1.25V reference | +| DAC_VREF_2V5 | Internal 2.5V reference | +| DAC_VREF_AVDD | Analog VDD | +| DAC_VREF_EXTERNAL_PIN | External AREF pin | + +```arduino +analogReferenceDAC(DAC_VREF_2V5); // enter the desired reference as argument +``` +To output an analog voltage value through a DAC pin, use the `analogWrite()` function with the **DAC channel** as an argument. See the example below: + +```arduino +analogWrite(DAC0, value); // the value should be in the range of the DAC resolution (e.g. 0-4095 with a 12 bits resolution) +``` + +***If a normal GPIO is passed to the analogWrite() function, the output will be a PWM signal.*** + + +The following sketch will create a **sine** wave signal in the `A0` Nano Matter pin: + +```arduino +float sample_rate = 9600.0, freq = 60.0; //samples/second, AC waveform freq. +int npts = sample_rate / freq; + +void setup() +{ + Serial.begin(115200); + // Set the DAC resolution to 12 bits + analogWriteResolution(12); + // Select the 1.25V reference voltage (feel free to change it) + analogReferenceDAC(DAC_VREF_1V25); +} + +void loop() +{ + + for (int i = 0; i < npts; i++) { + int x = 2000 + 1000.0 * sin(2 * PI * (freq / sample_rate) * i); + analogWrite(DAC0, x); + delayMicroseconds(1.0E6 / sample_rate); //adjust constant to get correct rate + } +} +``` +The DAC output should look like the image below: + +![DAC sine wave output](assets/sine-output.png) + +The following sketch will create a **sawtooth** wave signal in the `A0` Nano Matter pin: + +```arduino +void setup() +{ + Serial.begin(115200); + // Set the DAC resolution to 8 bits + analogWriteResolution(8); + // Select the 2.5V reference voltage (feel free to change it) + analogReferenceDAC(DAC_VREF_2V5); +} + +void loop() +{ + static int value = 0; + analogWrite(DAC0, value); + Serial.println(value); + + value++; + if (value == 255) { + value = 0; + } +} +``` +The DAC output should look like the image below: + +![DAC sawtooth wave output](assets/saw-output.png) + +## Communication + +This section of the user manual covers the different communication protocols that are supported by the Nano Matter, including the Serial Peripheral Interface (SPI), Inter-Integrated Circuit (I2C) and Universal Asynchronous Receiver-Transmitter (UART). The Nano Matter features dedicated pins for each communication protocol, simplifying the connection and communication with different components, peripherals, and sensors. + +### SPI + +The Nano Matter supports SPI communication, which enables data transmission between the board and other SPI-compatible devices. The pins used in the Nano Matter for the SPI communication protocol are the following: + +| **Microcontroller Pin** | **Arduino Pin Mapping** | +|:-----------------------:|:-----------------------:| +| PD05 | SS or D10 | +| PA09 | MOSI or D11 | +| PA08 | MISO or D12 | +| PB04 | SCK or D13 | + +Please, refer to the [board pinout section](#pinout) of the user manual to localize them on the board. + +Include the `SPI` library 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 (`SS`) 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 = 0x35; + +// Replace with the value to send +byte value = 0xFA; + +// 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); +``` + +The example code above should output this: + +![SPI logic data output](assets/spi-example.png) + +### I2C + +The Nano Matter supports I2C communication, which enables data transmission between the board and other I2C-compatible devices. The pins used in the Nano Matter for the I2C communication protocol are the following: + +| **Microcontroller Pin** | **Arduino Pin Mapping** | +|:-----------------------:|:-----------------------:| +| PA06 | SDA | +| PA07 | SCL | + +Please, refer to the [board pinout section](#pinout) of the user manual to localize them on the board. + +To use I2C communication, include the `Wire` library 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 = 0x35; + +// Replace with the appropriate instruction byte +byte instruction = 0x00; + +// Replace with the value to send +byte value = 0xFA; + +// 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(); +``` + +The output data should look like the image below, where we can see the device address data frame: + +![I2C output data](assets/i2c-example.png) + + +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 pins used in the Nano Matter for the UART communication protocol are the following: + +| **Microcontroller Pin** | **Arduino Pin Mapping** | +|:-----------------------:|:-----------------------:| +| PA05 | PIN_SERIAL_RX | +| PA04 | PIN_SERIAL_TX | + +Please, refer to the [board pinout section](#pinout) of the user manual to localize them on the board. + +To begin with UART communication, you will need to configure it first. In the `setup()` function, set the baud rate (bits per second) for UART communication: + +```arduino +// Start UART communication at 115200 baud +Serial1.begin(115200); +``` + +To read incoming data, you can use a `while()` loop to continuously check for available data and read individual characters. The code shown below stores the incoming characters in a String variable and processes 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 (Serial1.available()) { + // Allow data buffering and read a single character + delay(2); + char c = Serial1.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 `write()` function: + +```arduino +// Transmit the string "Hello world! +Serial1.write("Hello world!"); +``` + +You can also use the `print` and `println()` to send a string without a newline character or followed by a newline character: + +```arduino +// Transmit the string "Hello world!" +Serial1.print("Hello world!"); + +// Transmit the string "Hello world!" followed by a newline character +Serial1.println("Hello world!"); +``` + +![Serial communication example](assets/uart-example.png) + +## Support + +If you encounter any issues or have questions while working with the Nano Matter, we provide various support resources to help you find answers and solutions. + +### Help Center + +Explore our [Help Center](https://support.arduino.cc/hc/en-us), which offers a comprehensive collection of articles and guides for the Nano Matter. The Arduino Help Center is designed to provide in-depth technical assistance and help you make the most of your device. + +- [Nano Matter Help Center page](https://support.arduino.cc/hc/en-us/sections/360004605400-Nano-Family) + +### Forum + +Join our community forum to connect with other Nano Matter 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 Nano Matter. + +- [Nano Matter category in the Arduino Forum](https://forum.arduino.cc/c/hardware/nano-family/87) + +### 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 Nano Matter. + +- [Contact us page](https://www.arduino.cc/en/contact-us/) \ No newline at end of file