Wyatt Hepler | f9fb90f | 2020-09-30 18:59:33 -0700 | [diff] [blame] | 1 | .. _target-arduino: |
Anthony DiGirolamo | 9147aa0 | 2020-09-22 10:41:05 -0700 | [diff] [blame] | 2 | |
Anthony DiGirolamo | eea0d77 | 2020-08-06 12:00:36 -0700 | [diff] [blame] | 3 | ------- |
| 4 | Arduino |
| 5 | ------- |
| 6 | |
| 7 | This target supports building Pigweed on a few Arduino cores. |
| 8 | |
Anthony DiGirolamo | 9147aa0 | 2020-09-22 10:41:05 -0700 | [diff] [blame] | 9 | .. seealso:: |
| 10 | There are a few caveats when running Pigweed on top of the Arduino API. See |
Wyatt Hepler | f9fb90f | 2020-09-30 18:59:33 -0700 | [diff] [blame] | 11 | :ref:`module-pw_arduino_build` for details. |
Anthony DiGirolamo | 9147aa0 | 2020-09-22 10:41:05 -0700 | [diff] [blame] | 12 | |
Anthony DiGirolamo | eea0d77 | 2020-08-06 12:00:36 -0700 | [diff] [blame] | 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 | +==================================================================+===================================================================+===========+==========+=============+ |
Anthony DiGirolamo | 62de81b | 2020-10-20 17:31:36 -0700 | [diff] [blame] | 21 | | `teensy <https://www.pjrc.com/teensy/td_download.html>`_ | `Teensy 4.1 <https://www.pjrc.com/store/teensy41.html>`_ | ✓ | ✓ | ✓ | |
Anthony DiGirolamo | eea0d77 | 2020-08-06 12:00:36 -0700 | [diff] [blame] | 22 | +------------------------------------------------------------------+-------------------------------------------------------------------+-----------+----------+-------------+ |
Anthony DiGirolamo | 62de81b | 2020-10-20 17:31:36 -0700 | [diff] [blame] | 23 | | `teensy <https://www.pjrc.com/teensy/td_download.html>`_ | `Teensy 4.0 <https://www.pjrc.com/store/teensy40.html>`_ | ✓ | ✓ | ✓ | |
Anthony DiGirolamo | eea0d77 | 2020-08-06 12:00:36 -0700 | [diff] [blame] | 24 | +------------------------------------------------------------------+-------------------------------------------------------------------+-----------+----------+-------------+ |
Anthony DiGirolamo | 62de81b | 2020-10-20 17:31:36 -0700 | [diff] [blame] | 25 | | `teensy <https://www.pjrc.com/teensy/td_download.html>`_ | `Teensy 3.6 <https://www.pjrc.com/store/teensy36.html>`_ | ✓ | ✓ | ✓ | |
Anthony DiGirolamo | eea0d77 | 2020-08-06 12:00:36 -0700 | [diff] [blame] | 26 | +------------------------------------------------------------------+-------------------------------------------------------------------+-----------+----------+-------------+ |
Anthony DiGirolamo | 62de81b | 2020-10-20 17:31:36 -0700 | [diff] [blame] | 27 | | `teensy <https://www.pjrc.com/teensy/td_download.html>`_ | `Teensy 3.5 <https://www.pjrc.com/store/teensy35.html>`_ | ✓ | ✓ | ✓ | |
Anthony DiGirolamo | eea0d77 | 2020-08-06 12:00:36 -0700 | [diff] [blame] | 28 | +------------------------------------------------------------------+-------------------------------------------------------------------+-----------+----------+-------------+ |
Anthony DiGirolamo | 62de81b | 2020-10-20 17:31:36 -0700 | [diff] [blame] | 29 | | `teensy <https://www.pjrc.com/teensy/td_download.html>`_ | `Teensy 3.2 <https://www.pjrc.com/store/teensy32.html>`_ | ✓ | ✓ | ✓ | |
Anthony DiGirolamo | eea0d77 | 2020-08-06 12:00:36 -0700 | [diff] [blame] | 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 |
Anthony DiGirolamo | 383be05 | 2020-11-26 12:06:41 -0800 | [diff] [blame] | 46 | installed using the ``pw_arduino_build_CORE_PATH`` build arg. |
Anthony DiGirolamo | eea0d77 | 2020-08-06 12:00:36 -0700 | [diff] [blame] | 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. |
Anthony DiGirolamo | 62de81b | 2020-10-20 17:31:36 -0700 | [diff] [blame] | 57 | source activate.sh |
Anthony DiGirolamo | eea0d77 | 2020-08-06 12:00:36 -0700 | [diff] [blame] | 58 | # Install an arduino core |
Anthony DiGirolamo | 62de81b | 2020-10-20 17:31:36 -0700 | [diff] [blame] | 59 | arduino_builder install-core --prefix ./third_party/arduino/cores/ --core-name teensy |
Anthony DiGirolamo | eea0d77 | 2020-08-06 12:00:36 -0700 | [diff] [blame] | 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 | |
Anthony DiGirolamo | 383be05 | 2020-11-26 12:06:41 -0800 | [diff] [blame] | 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"]' |
Anthony DiGirolamo | 62de81b | 2020-10-20 17:31:36 -0700 | [diff] [blame] | 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 | |
Anthony DiGirolamo | 383be05 | 2020-11-26 12:06:41 -0800 | [diff] [blame] | 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"] |
Anthony DiGirolamo | 62de81b | 2020-10-20 17:31:36 -0700 | [diff] [blame] | 90 | |
| 91 | Save the file and close the text editor. |
Anthony DiGirolamo | eea0d77 | 2020-08-06 12:00:36 -0700 | [diff] [blame] | 92 | |
| 93 | Then build with: |
| 94 | |
| 95 | .. code:: sh |
| 96 | |
Anthony DiGirolamo | 62de81b | 2020-10-20 17:31:36 -0700 | [diff] [blame] | 97 | ninja -C out arduino |
Anthony DiGirolamo | eea0d77 | 2020-08-06 12:00:36 -0700 | [diff] [blame] | 98 | |
| 99 | To see supported boards and Arduino menu options for a given core: |
| 100 | |
| 101 | .. code:: sh |
| 102 | |
Anthony DiGirolamo | 62de81b | 2020-10-20 17:31:36 -0700 | [diff] [blame] | 103 | arduino_builder --arduino-package-path ./third_party/arduino/cores/teensy \ |
| 104 | --arduino-package-name teensy/avr \ |
| 105 | list-boards |
Anthony DiGirolamo | eea0d77 | 2020-08-06 12:00:36 -0700 | [diff] [blame] | 106 | |
Anthony DiGirolamo | 62de81b | 2020-10-20 17:31:36 -0700 | [diff] [blame] | 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 |
Anthony DiGirolamo | 383be05 | 2020-11-26 12:06:41 -0800 | [diff] [blame] | 117 | ``pw_arduino_build_MENU_OPTIONS``. Run this to see what's available for your core: |
Anthony DiGirolamo | 62de81b | 2020-10-20 17:31:36 -0700 | [diff] [blame] | 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 |
Anthony DiGirolamo | eea0d77 | 2020-08-06 12:00:36 -0700 | [diff] [blame] | 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 | |
Anthony DiGirolamo | c36af65 | 2020-09-29 14:34:27 -0700 | [diff] [blame] | 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. |
Anthony DiGirolamo | eea0d77 | 2020-08-06 12:00:36 -0700 | [diff] [blame] | 161 | |
| 162 | .. code:: sh |
| 163 | |
| 164 | #!/bin/bash |
| 165 | gn gen out --export-compile-commands \ |
Anthony DiGirolamo | 383be05 | 2020-11-26 12:06:41 -0800 | [diff] [blame] | 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"]' && \ |
Anthony DiGirolamo | eea0d77 | 2020-08-06 12:00:36 -0700 | [diff] [blame] | 171 | ninja -C out arduino |
| 172 | |
Anthony DiGirolamo | eea0d77 | 2020-08-06 12:00:36 -0700 | [diff] [blame] | 173 | for f in $(find out/arduino_debug/obj/ -iname "*.elf"); do |
Anthony DiGirolamo | c36af65 | 2020-09-29 14:34:27 -0700 | [diff] [blame] | 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 |
Anthony DiGirolamo | eea0d77 | 2020-08-06 12:00:36 -0700 | [diff] [blame] | 178 | done |
Anthony DiGirolamo | c36af65 | 2020-09-29 14:34:27 -0700 | [diff] [blame] | 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 | |
Anthony DiGirolamo | 62de81b | 2020-10-20 17:31:36 -0700 | [diff] [blame] | 189 | arduino_test_server --verbose \ |
| 190 | --config-file ./out/arduino_debug/gen/arduino_builder_config.json |
Anthony DiGirolamo | c36af65 | 2020-09-29 14:34:27 -0700 | [diff] [blame] | 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. |
Anthony DiGirolamo | 00e773e | 2020-11-04 11:57:27 -0800 | [diff] [blame] | 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", |
Michael Spang | c8b9390 | 2021-05-30 15:53:56 -0400 | [diff] [blame] | 220 | rebase_path(arduino_core_library_path, root_build_dir), |
Anthony DiGirolamo | 00e773e | 2020-11-04 11:57:27 -0800 | [diff] [blame] | 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 | |
Anthony DiGirolamo | 383be05 | 2020-11-26 12:06:41 -0800 | [diff] [blame] | 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" ] |
Anthony DiGirolamo | 00e773e | 2020-11-04 11:57:27 -0800 | [diff] [blame] | 257 | } |
| 258 | |