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