Arduino

Pigweed AI summary: This section provides information about building Pigweed on Arduino cores. It mentions that currently only Teensy 4.x and 3.x boards are supported. It also explains how to install Arduino cores and set up the build options. Additionally, it provides instructions on running unit tests and using the test server. There is also a section on flashing known issues, specifically for Teensy boards. Finally, it includes an example GN target for building an Arduino application.

This target supports building Pigweed on a few Arduino cores.

See also

There are a few caveats when running Pigweed on top of the Arduino API. See pw_arduino_build for details.

Supported Boards

Pigweed AI summary: Teensy 4.x and 3.x boards are currently the only ones supported. A table lists the supported boards and their compatibility with compiling, flashing, and test running. Other boards listed include Arduino Zero, Arduino Due, Adafruit Feather M0, Adafruit SAMD51 Boards, and stm32duino, but they are not currently supported.

Currently only Teensy 4.x and 3.x boards are supported.

Core	Board Name	Compiling	Flashing	Test Runner
teensy	Teensy 4.1	✓	✓	✓
teensy	Teensy 4.0	✓	✓	✓
teensy	Teensy 3.6	✓	✓	✓
teensy	Teensy 3.5	✓	✓	✓
teensy	Teensy 3.2	✓	✓	✓
arduino-samd	Arduino Zero
arduino-sam	Arduino Due
adafruit-samd	Adafruit Feather M0
adafruit-samd	Adafruit SAMD51 Boards
stm32duino

Setup

Pigweed AI summary: To use Pigweed, an Arduino core must be installed or the location of existing cores must be specified using the "pw_arduino_build_CORE_PATH" build argument. The "arduino_builder" utility can automatically install Arduino cores, with the recommended installation location being "third_party/arduino/cores/". The provided code snippet shows how to install the Teensy core using Pigweed.

You must first install an Arduino core or let Pigweed know where you have cores installed using the pw_arduino_build_CORE_PATH build arg.

Installing Arduino Cores

Pigweed AI summary: The arduino_builder utility can automatically install Arduino cores, and it is suggested to install them into third_party/arduino/cores/. To install an arduino core, only teensy is supported and the pigweed environment must be set up first.

The arduino_builder utility can install Arduino cores automatically. It’s recommended to install them to into third_party/arduino/cores/.

# Setup pigweed environment.
. ./activate.sh
# Install an arduino core, only teensy is supported
pw package install teensy

Building

Pigweed AI summary: This section provides instructions on how to build for the Pigweed target using the top-level "arduino" Ninja target. Users can set Arduino build options using "gn args out" or by running "gn gen out" on a Windows machine. The article also provides information on how to see supported boards and Arduino menu options for a given core, and how to set different Arduino build options in "pw_arduino_build_MENU_OPTIONS". The "arduino_builder" command can be used to see all menu options that

To build for this Pigweed target, simply build the top-level “arduino” Ninja target. You can set Arduino build options using gn args out or by running:

gn gen out --args='
  pw_arduino_build_CORE_PATH = "//environment/packages"
  pw_arduino_build_CORE_NAME = "teensy"
  pw_arduino_build_PACKAGE_NAME = "avr/1.58.1"
  pw_arduino_build_BOARD = "teensy40"
  pw_arduino_build_MENU_OPTIONS=["menu.usb.serial", "menu.keys.en-us"]'

On a Windows machine it’s easier to run:

gn args out

That will open a text file where you can paste the args in:

pw_arduino_build_CORE_PATH = "//environment/packages"
pw_arduino_build_CORE_NAME = "teensy"
pw_arduino_build_PACKAGE_NAME = "avr/1.58.1"
pw_arduino_build_BOARD = "teensy40"
pw_arduino_build_MENU_OPTIONS = ["menu.usb.serial", "menu.keys.en-us"]

Save the file and close the text editor.

Then build with:

ninja -C out arduino

To see supported boards and Arduino menu options for a given core:

arduino_builder --arduino-package-path ./environment/packages/teensy \
                --arduino-package-name avr/1.58.1 \
                list-boards

Board Name  Description
teensy41    Teensy 4.1
teensy40    Teensy 4.0
teensy36    Teensy 3.6
teensy35    Teensy 3.5
teensy31    Teensy 3.2 / 3.1

You may wish to set different arduino build options in pw_arduino_build_MENU_OPTIONS. Run this to see what’s available for your core:

arduino_builder --arduino-package-path ./environment/packages/teensy \
                --arduino-package-name avr/1.58.1 \
                list-menu-options \
                --board teensy40

That will show all menu options that can be added to gn args out.

All Options
----------------------------------------------------------------
menu.usb.serial             Serial
menu.usb.serial2            Dual Serial
menu.usb.serial3            Triple Serial
menu.usb.keyboard           Keyboard
menu.usb.touch              Keyboard + Touch Screen
menu.usb.hidtouch           Keyboard + Mouse + Touch Screen
menu.usb.hid                Keyboard + Mouse + Joystick
menu.usb.serialhid          Serial + Keyboard + Mouse + Joystick
menu.usb.midi               MIDI
...

Default Options
--------------------------------------
menu.usb.serial             Serial
menu.speed.600              600 MHz
menu.opt.o2std              Faster
menu.keys.en-us             US English

Testing

Pigweed AI summary: This document provides instructions for building and running unit tests for Pigweed modules using the arduino_unit_test_runner tool. The tests can be run on-device using the out build directory and can also be run using the pw_arduino_use_test_server GN arg. The document also highlights known issues with flashing Teensy boards using the Teensy Loader Application.

When working in upstream Pigweed, building this target will build all Pigweed modules’ unit tests. These tests can be run on-device in a few different ways.

Run a unit test

Pigweed AI summary: This section provides instructions on how to run a unit test using the arduino_unit_test_runner tool. The tests are located in the out/arduino_debug/obj/[module name]/[test_name].elf directory if using "out" as a build directory. A bash script is provided to run all tests on a Linux machine, which involves generating the build directory using gn, compiling the code using ninja, and running the tests using the arduino_unit_test_runner tool.

If using out as a build directory, tests will be located in out/arduino_debug/obj/[module name]/[test_name].elf.

Tests can be flashed and run using the arduino_unit_test_runner tool. Here is a sample bash script to run all tests on a Linux machine.

#!/bin/bash
gn gen out --export-compile-commands \
    --args='pw_arduino_build_CORE_PATH="environment/packages"
            pw_arduino_build_CORE_NAME="teensy"
            pw_arduino_build_PACKAGE_NAME="avr/1.58.1"
            pw_arduino_build_BOARD="teensy40"
            pw_arduino_build_MENU_OPTIONS=["menu.usb.serial", "menu.keys.en-us"]' && \
  ninja -C out arduino

for f in $(find out/arduino_debug/obj/ -iname "*.elf"); do
    arduino_unit_test_runner --verbose \
        --config-file ./out/arduino_debug/gen/arduino_builder_config.json \
        --upload-tool teensyloader \
        $f
done

Using the test server

Pigweed AI summary: This section explains how to use the test server to run tests using the GN arg "pw_arduino_use_test_server = true". The server requires an "arduino_builder" config file to locate the correct Arduino core, compiler path, and board used. The code block shows the command to run the test server with the config file. The section is marked as incomplete and needs further elaboration.

Tests may also be run using the pw_arduino_use_test_server = true GN arg. The server must be run with an arduino_builder config file so it can locate the correct Arduino core, compiler path, and Arduino board used.

arduino_test_server --verbose \
    --config-file ./out/arduino_debug/gen/arduino_builder_config.json

Flashing Known Issues

Pigweed AI summary: Teensyduino uses the Teensy Loader Application by default, which has limitations such as requiring a GUI and only being able to flash one board at a time.

Teensy Boards

Pigweed AI summary: Teensyduino uses the Teensy Loader Application by default, which has limitations such as requiring a GUI and only being able to flash one board at a time.

By default Teensyduino uses the Teensy Loader Application which has a couple limitations:

• Requires a GUI (or X11 on Linux).

• Can only flash one board at a time.

GN Target Example

Pigweed AI summary: This is an example of a GN rule for a pw_executable that includes some Teensyduino libraries. The rule imports some GNI files and sets some library arguments. It then defines the sources and dependencies for the executable, including some Arduino API functions. Finally, it removes some configurations and adds the arduino_core_sources as a dependency.

Here is an example pw_executable gn rule that includes some Teensyduino libraries.

import("//build_overrides/pigweed.gni")
import("$dir_pw_arduino_build/arduino.gni")
import("$dir_pw_build/target_types.gni")

_library_args = [
  "--library-path",
  rebase_path(arduino_core_library_path, root_build_dir),
  "--library-names",
  "Time",
  "Wire",
]

pw_executable("my_app") {
  # All Library Sources
  _library_c_files = exec_script(
          arduino_builder_script,
          arduino_show_command_args + _library_args + [
            "--library-c-files"
          ],
          "list lines")
  _library_cpp_files = exec_script(
          arduino_builder_script,
          arduino_show_command_args + _library_args + [
            "--library-cpp-files"
          ],
          "list lines")

  sources = [ "main.cc" ] + _library_c_files + _library_cpp_files

  deps = [
    "$dir_pw_hex_dump",
    "$dir_pw_log",
    "$dir_pw_string",
  ]

  include_dirs = exec_script(arduino_builder_script,
                             arduino_show_command_args + _library_args +
                                 [ "--library-include-dirs" ],
                             "list lines")

  # Required for using Arduino.h and any Arduino API functions
  remove_configs = [ "$dir_pw_build:strict_warnings" ]
  deps += [ "$dir_pw_third_party/arduino:arduino_core_sources" ]
}