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:: sh 55 56 # Setup pigweed environment. 57 source activate.sh 58 # Install an arduino core 59 arduino_builder install-core --prefix ./third_party/arduino/cores/ --core-name 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:: sh 67 68 gn gen out --args=' 69 pw_arduino_build_CORE_PATH="//third_party/arduino/cores" 70 pw_arduino_build_CORE_NAME="teensy" 71 pw_arduino_build_PACKAGE_NAME="teensy/avr" 72 pw_arduino_build_BOARD="teensy40" 73 pw_arduino_build_MENU_OPTIONS=["menu.usb.serial", "menu.keys.en-us"]' 74 75On a Windows machine it's easier to run: 76 77.. code:: sh 78 79 gn args out 80 81That will open a text file where you can paste the args in: 82 83.. code:: text 84 85 pw_arduino_build_CORE_PATH = "//third_party/arduino/cores" 86 pw_arduino_build_CORE_NAME = "teensy" 87 pw_arduino_build_PACKAGE_NAME="teensy/avr" 88 pw_arduino_build_BOARD = "teensy40" 89 pw_arduino_build_MENU_OPTIONS = ["menu.usb.serial", "menu.keys.en-us"] 90 91Save the file and close the text editor. 92 93Then build with: 94 95.. code:: sh 96 97 ninja -C out arduino 98 99To see supported boards and Arduino menu options for a given core: 100 101.. code:: sh 102 103 arduino_builder --arduino-package-path ./third_party/arduino/cores/teensy \ 104 --arduino-package-name teensy/avr \ 105 list-boards 106 107.. code:: text 108 109 Board Name Description 110 teensy41 Teensy 4.1 111 teensy40 Teensy 4.0 112 teensy36 Teensy 3.6 113 teensy35 Teensy 3.5 114 teensy31 Teensy 3.2 / 3.1 115 116You may wish to set different arduino build options in 117``pw_arduino_build_MENU_OPTIONS``. Run this to see what's available for your core: 118 119.. code:: sh 120 121 arduino_builder --arduino-package-path ./third_party/arduino/cores/teensy \ 122 --arduino-package-name teensy/avr \ 123 list-menu-options --board teensy40 124 125That will show all menu options that can be added to ``gn args out``. 126 127.. code:: text 128 129 All Options 130 ---------------------------------------------------------------- 131 menu.usb.serial Serial 132 menu.usb.serial2 Dual Serial 133 menu.usb.serial3 Triple Serial 134 menu.usb.keyboard Keyboard 135 menu.usb.touch Keyboard + Touch Screen 136 menu.usb.hidtouch Keyboard + Mouse + Touch Screen 137 menu.usb.hid Keyboard + Mouse + Joystick 138 menu.usb.serialhid Serial + Keyboard + Mouse + Joystick 139 menu.usb.midi MIDI 140 ... 141 142 Default Options 143 -------------------------------------- 144 menu.usb.serial Serial 145 menu.speed.600 600 MHz 146 menu.opt.o2std Faster 147 menu.keys.en-us US English 148 149Testing 150======= 151When working in upstream Pigweed, building this target will build all Pigweed 152modules' unit tests. These tests can be run on-device in a few different ways. 153 154Run a unit test 155--------------- 156If using ``out`` as a build directory, tests will be located in 157``out/arduino_debug/obj/[module name]/[test_name].elf``. 158 159Tests can be flashed and run using the `arduino_unit_test_runner` tool. Here is 160a sample bash script to run all tests on a Linux machine. 161 162.. code:: sh 163 164 #!/bin/bash 165 gn gen out --export-compile-commands \ 166 --args='pw_arduino_build_CORE_PATH="//third_party/arduino/cores" 167 pw_arduino_build_CORE_NAME="teensy" 168 pw_arduino_build_PACKAGE_NAME="teensy/avr" 169 pw_arduino_build_BOARD="teensy40" 170 pw_arduino_build_MENU_OPTIONS=["menu.usb.serial", "menu.keys.en-us"]' && \ 171 ninja -C out arduino 172 173 for f in $(find out/arduino_debug/obj/ -iname "*.elf"); do 174 arduino_unit_test_runner --verbose \ 175 --config-file ./out/arduino_debug/gen/arduino_builder_config.json \ 176 --upload-tool teensyloader \ 177 out/arduino_debug/obj/pw_string/test/format_test.elf 178 done 179 180Using the test server 181--------------------- 182 183Tests may also be run using the `pw_arduino_use_test_server = true` GN arg. 184The server must be run with an `arduino_builder` config file so it can locate 185the correct Arduino core, compiler path, and Arduino board used. 186 187.. code:: sh 188 189 arduino_test_server --verbose \ 190 --config-file ./out/arduino_debug/gen/arduino_builder_config.json 191 192.. TODO(tonymd): Flesh out this section similar to the stm32f429i target docs. 193 194Flashing Known Issues 195--------------------- 196 197Teensy Boards 198^^^^^^^^^^^^^ 199 200By default Teensyduino uses the `Teensy Loader Application 201<https://www.pjrc.com/teensy/loader.html>`_ which has a couple limitations: 202 203- Requires a GUI (or X11 on Linux). 204- Can only flash one board at a time. 205 206GN Target Example 207================= 208 209Here is an example `pw_executable` gn rule that includes some Teensyduino 210libraries. 211 212.. code:: text 213 214 import("//build_overrides/pigweed.gni") 215 import("$dir_pw_arduino_build/arduino.gni") 216 import("$dir_pw_build/target_types.gni") 217 218 _library_args = [ 219 "--library-path", 220 rebase_path(arduino_core_library_path, root_build_dir), 221 "--library-names", 222 "Time", 223 "Wire", 224 ] 225 226 pw_executable("my_app") { 227 # All Library Sources 228 _library_c_files = exec_script( 229 arduino_builder_script, 230 arduino_show_command_args + _library_args + [ 231 "--library-c-files" 232 ], 233 "list lines") 234 _library_cpp_files = exec_script( 235 arduino_builder_script, 236 arduino_show_command_args + _library_args + [ 237 "--library-cpp-files" 238 ], 239 "list lines") 240 241 sources = [ "main.cc" ] + _library_c_files + _library_cpp_files 242 243 deps = [ 244 "$dir_pw_hex_dump", 245 "$dir_pw_log", 246 "$dir_pw_string", 247 ] 248 249 include_dirs = exec_script(arduino_builder_script, 250 arduino_show_command_args + _library_args + 251 [ "--library-include-dirs" ], 252 "list lines") 253 254 # Required for using Arduino.h and any Arduino API functions 255 remove_configs = [ "$dir_pw_build:strict_warnings" ] 256 deps += [ "$dir_pw_third_party/arduino:arduino_core_sources" ] 257 } 258 259