1.. _target-arduino: 2 3------- 4Arduino 5------- 6 7This target supports building Pigweed on a few Arduino cores. 8 9.. seealso:: 10 There are a few caveats when running Pigweed on top of the Arduino API. See 11 :ref:`module-pw_arduino_build` for details. 12 13Supported Boards 14================ 15 16Currently only Teensy 4.x and 3.x boards are supported. 17 18+------------------------------------------------------------------+-------------------------------------------------------------------+-----------+----------+-------------+ 19| Core | Board Name | Compiling | Flashing | Test Runner | 20+==================================================================+===================================================================+===========+==========+=============+ 21| `teensy <https://www.pjrc.com/teensy/td_download.html>`_ | `Teensy 4.1 <https://www.pjrc.com/store/teensy41.html>`_ | ✓ | ✓ | ✓ | 22+------------------------------------------------------------------+-------------------------------------------------------------------+-----------+----------+-------------+ 23| `teensy <https://www.pjrc.com/teensy/td_download.html>`_ | `Teensy 4.0 <https://www.pjrc.com/store/teensy40.html>`_ | ✓ | ✓ | ✓ | 24+------------------------------------------------------------------+-------------------------------------------------------------------+-----------+----------+-------------+ 25| `teensy <https://www.pjrc.com/teensy/td_download.html>`_ | `Teensy 3.6 <https://www.pjrc.com/store/teensy36.html>`_ | ✓ | ✓ | ✓ | 26+------------------------------------------------------------------+-------------------------------------------------------------------+-----------+----------+-------------+ 27| `teensy <https://www.pjrc.com/teensy/td_download.html>`_ | `Teensy 3.5 <https://www.pjrc.com/store/teensy35.html>`_ | ✓ | ✓ | ✓ | 28+------------------------------------------------------------------+-------------------------------------------------------------------+-----------+----------+-------------+ 29| `teensy <https://www.pjrc.com/teensy/td_download.html>`_ | `Teensy 3.2 <https://www.pjrc.com/store/teensy32.html>`_ | ✓ | ✓ | ✓ | 30+------------------------------------------------------------------+-------------------------------------------------------------------+-----------+----------+-------------+ 31| `arduino-samd <https://github.com/arduino/ArduinoCore-samd>`_ | `Arduino Zero <https://store.arduino.cc/usa/arduino-zero>`_ | | | | 32+------------------------------------------------------------------+-------------------------------------------------------------------+-----------+----------+-------------+ 33| `arduino-sam <https://github.com/arduino/ArduinoCore-sam>`_ | `Arduino Due <https://store.arduino.cc/usa/due>`_ | | | | 34+------------------------------------------------------------------+-------------------------------------------------------------------+-----------+----------+-------------+ 35| `adafruit-samd <https://github.com/adafruit/ArduinoCore-samd>`_ | `Adafruit Feather M0 <https://www.adafruit.com/?q=feather+m0>`_ | | | | 36+------------------------------------------------------------------+-------------------------------------------------------------------+-----------+----------+-------------+ 37| `adafruit-samd <https://github.com/adafruit/ArduinoCore-samd>`_ | `Adafruit SAMD51 Boards <https://www.adafruit.com/category/952>`_ | | | | 38+------------------------------------------------------------------+-------------------------------------------------------------------+-----------+----------+-------------+ 39| `stm32duino <https://github.com/stm32duino/Arduino_Core_STM32>`_ | | | | | 40+------------------------------------------------------------------+-------------------------------------------------------------------+-----------+----------+-------------+ 41 42Setup 43===== 44 45You must first install an Arduino core or let Pigweed know where you have cores 46installed using the ``pw_arduino_build_CORE_PATH`` build arg. 47 48Installing Arduino Cores 49------------------------ 50 51The ``arduino_builder`` utility can install Arduino cores automatically. It's 52recommended to install them to into ``third_party/arduino/cores/``. 53 54.. code-block:: console 55 56 # Setup pigweed environment. 57 $ . ./activate.sh 58 # Install an arduino core, only teensy is supported 59 $ pw package install teensy 60 61Building 62======== 63To build for this Pigweed target, simply build the top-level "arduino" Ninja 64target. You can set Arduino build options using ``gn args out`` or by running: 65 66.. code-block:: console 67 68 $ gn gen out --args=" 69 pw_arduino_build_CORE_PATH = \"//environment/packages\" 70 pw_arduino_build_CORE_NAME = \"teensy\" 71 pw_arduino_build_PACKAGE_NAME = \"avr/1.58.1\" 72 pw_arduino_build_BOARD = \"teensy40\" 73 pw_arduino_build_MENU_OPTIONS=[\"menu.usb.serial\", \"menu.keys.en-us\"] 74 " 75 76On a Windows machine it's easier to run: 77 78.. code-block:: console 79 80 $ gn args out 81 82That will open a text file where you can paste the args in: 83 84.. code-block:: text 85 86 pw_arduino_build_CORE_PATH = "//environment/packages" 87 pw_arduino_build_CORE_NAME = "teensy" 88 pw_arduino_build_PACKAGE_NAME = "avr/1.58.1" 89 pw_arduino_build_BOARD = "teensy40" 90 pw_arduino_build_MENU_OPTIONS = ["menu.usb.serial", "menu.keys.en-us"] 91 92Save the file and close the text editor. 93 94Then build with: 95 96.. code-block:: console 97 98 $ ninja -C out arduino 99 100To see supported boards and Arduino menu options for a given core: 101 102.. code-block:: console 103 104 $ arduino_builder --arduino-package-path ./environment/packages/teensy \ 105 > --arduino-package-name avr/1.58.1 \ 106 > list-boards 107 108.. code-block:: text 109 110 Board Name Description 111 teensy41 Teensy 4.1 112 teensy40 Teensy 4.0 113 teensy36 Teensy 3.6 114 teensy35 Teensy 3.5 115 teensy31 Teensy 3.2 / 3.1 116 117You may wish to set different arduino build options in 118``pw_arduino_build_MENU_OPTIONS``. Run this to see what's available for your core: 119 120.. code-block:: console 121 122 $ arduino_builder --arduino-package-path ./environment/packages/teensy \ 123 > --arduino-package-name avr/1.58.1 \ 124 > list-menu-options \ 125 > --board teensy40 126 127That will show all menu options that can be added to ``gn args out``. 128 129.. code-block:: text 130 131 All Options 132 ---------------------------------------------------------------- 133 menu.usb.serial Serial 134 menu.usb.serial2 Dual Serial 135 menu.usb.serial3 Triple Serial 136 menu.usb.keyboard Keyboard 137 menu.usb.touch Keyboard + Touch Screen 138 menu.usb.hidtouch Keyboard + Mouse + Touch Screen 139 menu.usb.hid Keyboard + Mouse + Joystick 140 menu.usb.serialhid Serial + Keyboard + Mouse + Joystick 141 menu.usb.midi MIDI 142 ... 143 144 Default Options 145 -------------------------------------- 146 menu.usb.serial Serial 147 menu.speed.600 600 MHz 148 menu.opt.o2std Faster 149 menu.keys.en-us US English 150 151Testing 152======= 153When working in upstream Pigweed, building this target will build all Pigweed 154modules' unit tests. These tests can be run on-device in a few different ways. 155 156Run a unit test 157--------------- 158If using ``out`` as a build directory, tests will be located in 159``out/arduino_debug/obj/[module name]/[test_name].elf``. 160 161Tests can be flashed and run using the `arduino_unit_test_runner` tool. Here is 162a sample bash script to run all tests on a Linux machine. 163 164.. code-block:: shell 165 166 #!/bin/bash 167 gn gen out --export-compile-commands \ 168 --args='pw_arduino_build_CORE_PATH="environment/packages" 169 pw_arduino_build_CORE_NAME="teensy" 170 pw_arduino_build_PACKAGE_NAME="avr/1.58.1" 171 pw_arduino_build_BOARD="teensy40" 172 pw_arduino_build_MENU_OPTIONS=["menu.usb.serial", "menu.keys.en-us"]' && \ 173 ninja -C out arduino 174 175 for f in $(find out/arduino_debug/obj/ -iname "*.elf"); do 176 arduino_unit_test_runner --verbose \ 177 --config-file ./out/arduino_debug/gen/arduino_builder_config.json \ 178 --upload-tool teensyloader \ 179 $f 180 done 181 182Using the test server 183--------------------- 184 185Tests may also be run using the `pw_arduino_use_test_server = true` GN arg. 186The server must be run with an `arduino_builder` config file so it can locate 187the correct Arduino core, compiler path, and Arduino board used. 188 189.. code-block:: console 190 191 $ arduino_test_server --verbose \ 192 > --config-file ./out/arduino_debug/gen/arduino_builder_config.json 193 194.. TODO(tonymd): Flesh out this section similar to the stm32f429i target docs. 195 196Flashing Known Issues 197--------------------- 198 199Teensy Boards 200^^^^^^^^^^^^^ 201 202By default Teensyduino uses the `Teensy Loader Application 203<https://www.pjrc.com/teensy/loader.html>`_ which has a couple limitations: 204 205- Requires a GUI (or X11 on Linux). 206- Can only flash one board at a time. 207 208GN Target Example 209================= 210 211Here is an example `pw_executable` gn rule that includes some Teensyduino 212libraries. 213 214.. code-block:: text 215 216 import("//build_overrides/pigweed.gni") 217 import("$dir_pw_arduino_build/arduino.gni") 218 import("$dir_pw_build/target_types.gni") 219 220 _library_args = [ 221 "--library-path", 222 rebase_path(arduino_core_library_path, root_build_dir), 223 "--library-names", 224 "Time", 225 "Wire", 226 ] 227 228 pw_executable("my_app") { 229 # All Library Sources 230 _library_c_files = exec_script( 231 arduino_builder_script, 232 arduino_show_command_args + _library_args + [ 233 "--library-c-files" 234 ], 235 "list lines") 236 _library_cpp_files = exec_script( 237 arduino_builder_script, 238 arduino_show_command_args + _library_args + [ 239 "--library-cpp-files" 240 ], 241 "list lines") 242 243 sources = [ "main.cc" ] + _library_c_files + _library_cpp_files 244 245 deps = [ 246 "$dir_pw_hex_dump", 247 "$dir_pw_log", 248 "$dir_pw_string", 249 ] 250 251 include_dirs = exec_script(arduino_builder_script, 252 arduino_show_command_args + _library_args + 253 [ "--library-include-dirs" ], 254 "list lines") 255 256 # Required for using Arduino.h and any Arduino API functions 257 remove_configs = [ "$dir_pw_build:strict_warnings" ] 258 deps += [ "$dir_pw_third_party/arduino:arduino_core_sources" ] 259 } 260