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