Repository files navigation

This repository contains the official implementation ofArduino Core for Zephyr RTOS based board.

Zephyr RTOS is an open-source, real-time operating system designed for low-power, resource-constrained devices. It's modular, scalable, and supports multiple architectures.

Install the core and its toolchains via Board Manager:

• Download and install the latestArduino IDE (only versions2.x.x are supported).
• Open the'Settings / Preferences' window.
• Open the'Boards Manager' from the side menu and search for'Zephyr'.
  • If it doesn’t appear, add the following URL to the'Additional Boards Manager URLs' field:https://downloads.arduino.cc/packages/package_zephyr_index.json (if you have multiple URLs, separate them with a comma).
• Install theArduino Zephyr Boards platform.

Alternatively, to install the core using the command line, run the following command with the Arduino CLI:

arduino-cli core install arduino:zephyr --additional-urls https://downloads.arduino.cc/packages/package_zephyr_index.json

To get started with your board:

• Put the board in bootloader mode by double-clicking the RESET button.
• Run theBurn Bootloader option from the IDE/CLI.
  • Note that due to limitations in the Arduino IDE, you may need to select any programmer from theProgrammers menu.
• Once the bootloader is installed, you can load your first sketch by placing the board into bootloader mode again.

A: Connect a USB-to-UART adapter to the default UART (eg. TX0/RX0 on Giga, TX/RX on Nano) and read the error message (with the sketch compiled inDefault mode). If you don't own a USB-to-UART adapter, compile the sketch inDebug mode; this will force the shell to wait until you open the Serial Monitor. Then, runsketch command andprobably you'll be able to read the error (if generated byllext). For OS crashes, the USB-to-UART adapter is the only way to collect the crash.

A: This means you are trying to use a Zephyr function which has not yet been exported. Openllext_exports.c, add the function you need and recompile/upload the loader.

A: Open the.conf file for your board, add the requiredCONFIG_, recompile/upload the loader.

A: This is usually due to a buffer overflow or coding error in the user's own code. However, since the project is still in beta 🧪, agood bug report could help identify any issues in our code.

A: Since collecting bug reports is very important at this time, we are keeping Zephyr's shell enabled to allow loading a full sketch (which requires a large stack). Adjust your board's.conf file to reduce the stack size if your platform doesn't have enough RAM.

• ArduinoBLE: This library is enabled only for the Arduino Nano 33 BLE. Please usethis branch to test it.

Unlike traditional Arduino implementations, where the final output is a standalone binary loaded by a bootloader, this core generates a freestandingelf file. This file is dynamically loaded by a precompiled Zephyr firmware, referred to as theloader.

Theloader is responsible for managing the interaction between your sketches and the underlying Zephyr system. After the initial bootloader installation, theloader takes over the sketch loading process automatically.

To ensure flexibility, theloader project is designed to be generic. Any necessary modifications for specific boards should be made in the corresponding "DTS overlay" or a special "fixup" file, using appropriate guards to maintain compatibility.

The behavior of theloader can be adjusted through theMode menu of the IDE:

• Standard: The sketch is loaded automatically.
• Debug: The user must typesketch in Zephyr's shell, which is accessible via the default Serial.

The most important components of this project are:

• Zephyr based loader
• LLEXT
• Actual core withvariants and the usualplatform andboards files
• ArduinoCore-API
• zephyr-sketch-tool

In this section, we’ll guide you through setting up your environment to work on and update the Zephyr core.

Shell scripts are available to simplify the installation process (Windows is not supported at the moment 😔).

mkdir my_new_zephyr_folder&&cd my_new_zephyr_foldergit clone https://github.com/arduino/ArduinoCore-zephyr

Before running the installation script, ensure that Python,pip andvenv are installed on your system. The script will automatically installwest and manage the necessary dependencies.

On Ubuntu or similarapt-based distros, make sure to run the following command:

sudo apt install python3-pip python3-setuptools python3-venv build-essential git cmake ninja-build zstd jq

cd ArduinoCore-zephyr./extra/bootstrap.sh

This will take care of installingwest, the Zephyr build tool. It will thendownload all packages required for a Zephyr build in addition to the toolchainsin the Zephyr SDK.

The loader is compiled for each board by running the./extra/build.sh script.The target can be specified either with the Arduino board name (as defined inboards.txt), or with the Zephyr board name and any additional arguments thatmay be required by the Zephyr build system.

For example, to build for the Arduino Portenta H7, you can use either theArduino name:

./extra/build.sh portentah7

or the Zephyr board target:

./extra/build.sh arduino_portenta_h7//m7

The firmwares will be copied to thefirmware folder, and theassociated variant will be updated.

If the board is fully supported by Zephyr, you can flash the firmware directly onto the board using the following command:

west flash

This can also be performed via the "Burn bootloader" action in the IDE if the core is properly installed, as detailed below.

After running thebootstrap.sh script, you can symlink the core to$sketchbook/hardware/arduino-git/zephyr. Once linked, it will appear in the IDE/CLI, and the board's Fully Qualified Board Name (FQBN) will be formatted asarduino-git:zephyr:name_from_boards_txt.

. venv/bin/activatewest config -d manifest.project-filterwest sdk install --version 0.17.0west update

To add a new board that is already supported by mainline Zephyr with the target$your_board, follow these steps:

• Get the variant name from your board by runningextra/get_variant_name.sh $your_board.

• Create a folder in thevariants/ directory with the same name as the variant for your new board.

• Create the DTS<variant>.overlay and Kconfig<variant>.conf files in that directory.

  The overlay must include:

  • A flash partition calleduser_sketch, typically located near the end of the flash.
  • Azephyr,user section containing the description for GPIOs, Analog, UART, SPI and I2C devices. Feel free to leave some fields empty in case Zephyr support is missing. This will result in some APIs not being available at runtime (eg.analogWrite if PWM section is empty).

  The Kconfig file must include any board-specific options required by this target.

• Build the Loader: run./extra/build.sh $your_board (with any additional arguments as required) and start debugging the errors. 😁

• Update theboards.txt: add an entry for your board, manually filling the required fields.

  Make sure to set:

  • build.zephyr_target andbuild.zephyr_args to the arguments used in thebuild.sh call;
  • build.zephyr_hals to the (space-separated list of) HAL modules required by the board;
  • build.variant to the variant name identified above.

• Implement touch support: if your board supports the "1200bps touch" method, implement_on_1200_bps in a file located inside the variant folder of your board.

To report a bug, open theissues and follow the instructions. Any issue opened without the needed information will be discarded.

Contributions are always welcome. The preferred way to receive code contribution is by submitting aPull request.

• Remove binaries from this repo history (#102,⚠️ will require a clean clone)
• Network: support UDP and TLS
• USB: switch toUSB_DEVICE_STACK_NEXT to support PluggableUSB
• Relocate RODATA in flash to accommodate sketches with large assets
• Provide better error reporting for failed llext operations
• Replacellext_exports.c with proper symbols generation (via includes)
• Fix corner cases withstd:: includes (like<iterator>)
• Get rid of all warnings

This effort would have been very hard without theGSoC project and the Zephyr community.