Arduino Core API

Introduction

The Arduino-Core-Zephyr module started as a Google Summer of Code 2022 project [5] to provide Arduino-style APIs for Zephyr RTOS applications. This module acts as an abstraction layer, allowing developers familiar with Arduino programming to leverage Zephyr’s capabilities without having to learn entirely new APIs and libraries.

Understanding the Components

This module consists of two key components that work together:

1. ArduinoCore-API (Common Arduino API Definition)

The ArduinoCore-API is Arduino’s official hardware abstraction layer that defines the common Arduino API. It contains the abstract API definitions and implementations for hardware-independent functionality.

Key characteristics:

  • Contains both API definitions (headers) and hardware-agnostic implementations

  • Provides classes like String, Print, Stream, IPAddress with full implementations

  • Defines interfaces for hardware-specific classes (e.g., HardwareSerial, HardwareSPI)

  • Shared across all modern Arduino platforms for consistency

  • See the ArduinoCore-API README for implementation details

  • It is Licensed as GNU LESSER GENERAL PUBLIC LICENSE Version 2.1

2. ArduinoCore-Zephyr (Zephyr-Specific Implementation)

The Arduino-Core-Zephyr module provides the Zephyr-specific implementation of the Arduino API. This is where hardware-dependent Arduino functions are implemented using Zephyr’s native APIs and drivers.

Key characteristics:

  • Contains the cores/arduino directory with Zephyr implementations (zephyrCommon.cpp, zephyrSerial.cpp, etc.)

  • Provides board-specific variants with pin mappings and Device Tree overlays

  • Includes Zephyr build system integration (CMake, Kconfig, west.yml)

  • Links to ArduinoCore-API to inherit the common implementations

  • See the project documentation for implementation details

  • It is Licensed under Apache-2.0

Features Provided

Together, these components provide:

  • Standard Arduino API functions like pinMode(), digitalWrite(), analogRead(), etc.

  • Support for Arduino-style setup() and loop() functions

  • Pin mapping between Arduino pin numbers and Zephyr’s GPIO definitions

  • Support for common Arduino communication protocols (Serial, I2C, SPI)

  • Compatibility with existing Arduino libraries

  • Board variant support for various hardware platforms already present in Zephyr

By bringing Arduino-style programming to Zephyr, this module provides a gentler learning curve for those transitioning from Arduino to Zephyr while still benefiting from Zephyr’s advanced features, scalability, and broad hardware support.

Usage with Zephyr

Adding the Arduino Core API to a Zephyr Project

  1. To pull in the Arduino Core for Zephyr as a Zephyr module, either add it as a West project in the west.yml file or pull it in by adding a submanifest (e.g. zephyr/submanifests/arduinocore.yaml) file with the following content:

    # Arduino API repository
- name: ArduinoCore-zephyr
  path: modules/lib/arduinocore-zephyr
  revision: main
  url: https://github.com/zephyrproject-rtos/ArduinoCore-zephyr

  2. Run the following command to update your project:

    west update

  3. For Linux users, there’s an install.sh script in the module that will automatically link the ArduinoCore-API. If you can’t use this script, follow the manual steps below.

    Note

    Skip the next step if the install.sh script succeeded. The next step is for Linux users who may have a difference in where the module is installed or have some custom Zephyr setup with custom paths.

  4. Complete the core setup by linking the API folder from the ArduinoCore-API repository into the arduinocore-zephyr folder:

    west blobs fetch

    The cores folder is located inside <zephyr-project-path>/modules/lib/arduinocore-zephyr/cores.

Using Arduino Core API in Your Application

  1. In your application’s prj.conf file, enable the Arduino API configs similar to how it’s being done in the blinky_arduino sample [7].

  2. Create your application using Arduino-style code:

    #include <Arduino.h>

void setup() {
  pinMode(LED_BUILTIN, OUTPUT);
}

void loop() {
  digitalWrite(LED_BUILTIN, HIGH);
  delay(1000);
  digitalWrite(LED_BUILTIN, LOW);
  delay(1000);
}

  3. Build your application with the target board:

    west build -b <board_name> path/to/your/app

Adding Custom Board Support

Supported boards reside in the variants/ directory in the arduinocore-zephyr. To add support for a custom board:

  1. Create a new folder in the variants/ directory with your board’s name

  2. Add an overlay file and a pinmap header file that match the board name

  3. Add your new header file to an #ifdef statement in the variant.h file

For detailed instructions on adding board variants, refer to the board variants documentation [1].

Using External Arduino Libraries

To use external Arduino libraries with your Zephyr project:

  1. Add your library’s source files (e.g., MyLibrary.h and MyLibrary.cpp) to your project’s src folder

  2. Update your application’s CMakeLists.txt to include these files:

    target_sources(app PRIVATE src/MyLibrary.cpp)

  3. Include the library in your source code:

    #include "MyLibrary.h"

For more details on using external libraries, see the Arduino libraries documentation [2].

References

  1. Arduino-Core-Zephyr GitHub Repository [3]

  2. ArduinoCore-API Repository [4]

  3. Golioth Article: Zephyr + Arduino: a Google Summer of Code story [6]