third_party/pigweed/repo/targets/arduino/target_docs.rst

   1 .. _target-arduino:
   2
   3 -------
   4 Arduino
   5 -------
   6
   7 This 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
  13 Supported Boards
  14 ================
  15
  16 Currently 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
  42 Setup
  43 =====
  44
  45 You must first install an Arduino core or let Pigweed know where you have cores
  46 installed using the ``pw_arduino_build_CORE_PATH`` build arg.
  47
  48 Installing Arduino Cores
  49 ------------------------
  50
  51 The ``arduino_builder`` utility can install Arduino cores automatically. It's
  52 recommended 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
  61 Building
  62 ========
  63 To build for this Pigweed target, simply build the top-level "arduino" Ninja
  64 target. 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
  75 On a Windows machine it's easier to run:
  76
  77 .. code:: sh
  78
  79   gn args out
  80
  81 That 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
  91 Save the file and close the text editor.
  92
  93 Then build with:
  94
  95 .. code:: sh
  96
  97   ninja -C out arduino
  98
  99 To 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
 116 You 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
 125 That 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
 149 Testing
 150 =======
 151 When working in upstream Pigweed, building this target will build all Pigweed
 152 modules' unit tests.  These tests can be run on-device in a few different ways.
 153
 154 Run a unit test
 155 ---------------
 156 If using ``out`` as a build directory, tests will be located in
 157 ``out/arduino_debug/obj/[module name]/[test_name].elf``.
 158
 159 Tests can be flashed and run using the `arduino_unit_test_runner` tool. Here is
 160 a 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
 180 Using the test server
 181 ---------------------
 182
 183 Tests may also be run using the `pw_arduino_use_test_server = true` GN arg.
 184 The server must be run with an `arduino_builder` config file so it can locate
 185 the 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
 194 Flashing Known Issues
 195 ---------------------
 196
 197 Teensy Boards
 198 ^^^^^^^^^^^^^
 199
 200 By 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
 206 GN Target Example
 207 =================
 208
 209 Here is an example `pw_executable` gn rule that includes some Teensyduino
 210 libraries.
 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),
 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