Skip to content

Commit 4a94677

Browse files
maxgerhardtmaxgerhardt
authored
Update PlatformIO builder script and docs (#633)
* Update board generation, use renamed function * Update documentation with new platform integration state * Remove accidentally pushed file * Use correct update command * Use correct highlighting * Use correct language * Add section on debugging * Add docs on filesystem, minor corrections * Use -iprefix in compilation, but still expose all include paths to IDE * Add exception and RTTI support, document them * Fix typo
1 parent 3414b73 commit 4a94677

34 files changed

+243
-178
lines changed

‎docs/images/pio_debugging.png

119 KB
Loading

‎docs/images/pio_fs_upload.png

16.5 KB
Loading

‎docs/platformio.rst

Lines changed: 104 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -19,14 +19,14 @@ The PlatformIO experience:
1919

2020
Refer to the general documentation at https://docs.platformio.org/.
2121

22-
Especially useful is the `Getting started with VSCode + PlatformIO <https://docs.platformio.org/en/latest/integration/ide/vscode.html#installation), [CLI reference](https://docs.platformio.org/en/latest/core/index.html) and [platformio.ini options](https://docs.platformio.org/en/latest/projectconf/index.html)>`__ page.
22+
Especially useful is the `Getting started with VSCode + PlatformIO <https://docs.platformio.org/en/latest/integration/ide/vscode.html#installation>`_, `CLI reference <https://docs.platformio.org/en/latest/core/index.html>`_ and the `platformio.ini options <https://docs.platformio.org/en/latest/projectconf/index.html>`_ page.
2323

2424
Hereafter it is assumed that you have a basic understanding of PlatformIO in regards to project creation, project file structure and building and uploading PlatformIO projects, through reading the above pages.
2525

2626
Current state of development
2727
----------------------------
2828

29-
At the time of writing, PlatformIO integration for this core is a work-in-progress and not yet merged into mainline PlatformIO. This is subject to change soon.
29+
At the time of writing, PlatformIO integration for this core is a work-in-progress and not yet merged into mainline PlatformIO. This is subject to change once `this pull request <https://github.com/platformio/platform-raspberrypi/pull/36>`_ is merged.
3030

3131
If you want to use the PlatformIO integration right now, make sure you first create a standard Raspberry Pi Pico + Arduino project within PlatformIO.
3232
This will give you a project with the ``platformio.ini``
@@ -38,21 +38,42 @@ This will give you a project with the ``platformio.ini``
3838
board = pico
3939
framework = arduino
4040
41-
Here, you need to change the `platform` to take advantage of the features described hereunder.
42-
You *also* need to inject two PlatformIO packages, one for the compiler toolchain and one for the Arduino core package.
41+
Here, you need to change the `platform` to take advantage of the features described hereunder and switch to the new core.
4342

4443
.. code:: ini
4544
4645
[env:pico]
4746
platform = https://github.com/maxgerhardt/platform-raspberrypi.git
4847
board = pico
4948
framework = arduino
49+
board_build.core = earlephilhower
50+
51+
When the support for this core has been merged into mainline PlatformIO, this notice will be removed and a standard `platformio.ini` as shown above will work as a base.
52+
53+
Deprecation warnings
54+
---------------------
55+
56+
Previous versions of this documentation told users to inject the framework and toolchain package into the project by using
57+
58+
.. code:: ini
59+
5060
; note that download link for toolchain is specific for OS. see https://github.com/earlephilhower/pico-quick-toolchain/releases.
5161
platform_packages =
5262
maxgerhardt/framework-arduinopico@https://github.com/earlephilhower/arduino-pico.git
5363
maxgerhardt/toolchain-pico@https://github.com/earlephilhower/pico-quick-toolchain/releases/download/1.3.1-a/x86_64-w64-mingw32.arm-none-eabi-7855b0c.210706.zip
54-
55-
When the support for this core has been merged into mainline PlatformIO, this notice will be removed and a standard `platformio.ini` as shown above will work as a base.
64+
65+
This is now **deprecated** and should not be done anymore. Users should delete these ``platform_packages`` lines and update the platform integration by issuing the command
66+
67+
.. code:: bash
68+
69+
pio pkg update -g -p https://github.com/maxgerhardt/platform-raspberrypi.git
70+
71+
in the `PlatformIO CLI <https://docs.platformio.org/en/latest/integration/ide/vscode.html#platformio-core-cli>`_. The same can be achieved by using the VSCode PIO Home -> Platforms -> Updates GUI.
72+
73+
The toolchain, which was also renamed to ``toolchain-rp2040-earlephilhower`` is downloaded automatically from the registry. The same goes for the ``framework-arduinopico`` toolchain package, which points directly to the Arduino-Pico Github repository.
74+
However, users can still select a custom fork or branch of the core if desired so, as detailed in a chapter below.
75+
76+
As the pull req
5677

5778
Selecting the new core
5879
----------------------
@@ -61,8 +82,8 @@ Prerequisite for using this core is to tell PlatformIO to switch to it.
6182
There will be board definition files where the Earle-Philhower core will
6283
be the default since it's a board that only exists in this core (and not
6384
the other https://github.com/arduino/ArduinoCore-mbed). To switch boards
64-
for which this is not the default core (e.g. the standard
65-
``board = pico``), the directive
85+
for which this is not the default core (which are only
86+
``board = pico`` and ``board = nanorp2040connect``), the directive
6687

6788
.. code:: ini
6889
@@ -72,6 +93,8 @@ must be added to the ``platformio.ini``. This controls the `core
7293
switching
7394
logic <https://github.com/maxgerhardt/platform-raspberrypi/blob/77e0d3a29d1dbf00fd3ec3271104e3bf4820869c/builder/frameworks/arduino/arduino.py#L27-L32>`__.
7495

96+
When using Arduino-Pico-only boards like ``board = rpipico`` or ``board = adafruit_feather``, this is not needed.
97+
7598
Flash size
7699
----------
77100

@@ -154,6 +177,37 @@ either a sing line or a newline-separated expression.
154177
-DDEBUG_RP2040_CORE
155178
-DDEBUG_RP2040_PORT=Serial2
156179
180+
C++ Exceptions
181+
--------------
182+
183+
Exceptions are disabled by default. To enable them, use
184+
185+
.. code:: ini
186+
187+
; Enable Exceptions
188+
build_flags = -DPIO_FRAMEWORK_ARDUINO_ENABLE_EXCEPTIONS
189+
190+
Stack Protector
191+
---------------
192+
193+
To enable GCC's stack protection feature, use
194+
195+
.. code:: ini
196+
197+
; Enable Stack Protector
198+
build_flags = -fstack-protector
199+
200+
201+
RTTI
202+
----
203+
204+
RTTI (run-time type information) is disabled by default. To enable it, use
205+
206+
.. code:: ini
207+
208+
; Enable RTTI
209+
build_flags = -DPIO_FRAMEWORK_ARDUINO_ENABLE_RTTI
210+
157211
USB Stack
158212
---------
159213

@@ -188,8 +242,8 @@ directive to do so. Simply specify that the framework package
188242
Whereas the ``#master`` can also be replaced by a ``#branchname`` or a
189243
``#commithash``. If left out, it will pull the default branch, which is ``master``.
190244

191-
The ``file://`` pseudo-protocol can also be used instead of ``https://`` to point to a
192-
local copy of the core (with e.g. some modifications) on disk.
245+
The ``file://`` and ``symlink://`` pseudo-protocols can also be used instead of ``https://`` to point to a
246+
local copy of the core (with e.g. some modifications) on disk (`see documentation <https://docs.platformio.org/en/latest/core/userguide/pkg/cmd_install.html?#local-folder>_`).
193247

194248
Note that this can only be done for versions that have the PlatformIO
195249
builder script it in, so versions before 1.9.2 are not supported.
@@ -206,14 +260,50 @@ and 0.5MByte filesystem.
206260
platform = https://github.com/maxgerhardt/platform-raspberrypi.git
207261
board = pico
208262
framework = arduino
263+
; board can use both Arduino cores -- we select Arduino-Pico here
209264
board_build.core = earlephilhower
210265
board_build.filesystem_size = 0.5m
211-
; note that download link for toolchain is specific for OS. see https://github.com/earlephilhower/pico-quick-toolchain/releases.
212-
platform_packages =
213-
maxgerhardt/framework-arduinopico@https://github.com/earlephilhower/arduino-pico.git
214-
maxgerhardt/toolchain-pico@https://github.com/earlephilhower/pico-quick-toolchain/releases/download/1.3.1-a/x86_64-w64-mingw32.arm-none-eabi-7855b0c.210706.zip
215266
216267
217268
The initial project structure should be generated just creating a new
218269
project for the Pico and the Arduino framework, after which the
219270
auto-generated ``platformio.ini`` can be adapted per above.
271+
272+
Debugging
273+
---------
274+
275+
With recent updates to the toolchain and OpenOCD, debugging firmwares is also possible.
276+
277+
To specify the debugging adapter, use ``debug_tool`` (`documentation <https://docs.platformio.org/en/latest/projectconf/section_env_debug.html#debug-tool>`_). Supported values are:
278+
279+
* ``picoprobe``
280+
* ``cmsis-dap``
281+
* ``jlink``
282+
* ``raspberrypi-swd``
283+
284+
These values can also be used in ``upload_protocol`` if you want PlatformIO to upload the regular firmware through this method, which you likely want.
285+
286+
Especially the PicoProbe method is convenient when you have two Raspberry Pi Pico boards. One of them can be flashed with the PicoProbe firmware (`documentation <https://www.raspberrypi.com/documentation/microcontrollers/raspberry-pi-pico.html#debugging-using-another-raspberry-pi-pico>`_) and is then connected to the target Raspberry Pi Pico board (see `documentation <https://datasheets.raspberrypi.com/pico/getting-started-with-pico.pdf>`_ chapter "Picoprobe Wiring"). Remember that on Windows, you have to use `Zadig <https://zadig.akeo.ie/>`_ to also load "WinUSB" drivers for the "Picoprobe (Interface 2)" device so that OpenOCD can speak to it.
287+
288+
With that set up, debugging can be started via the left debugging sidebar and works nicely: Setup breakpoints, inspect the value of variables in the code, step through the code line by line. When a breakpoint is hit or execution is halted, you can even see the execution state both Cortex-M0+ cores of the RP2040.
289+
290+
.. image:: images/pio_debugging.png
291+
292+
For further information on customizing debug options, like the initial breakpoint or debugging / SWD speed, consult `the documentation <https://docs.platformio.org/en/latest/projectconf/section_env_debug.html>`_.
293+
294+
Filesystem Uploading
295+
--------------------
296+
297+
For the Arduino IDE, `a plugin <https://github.com/earlephilhower/arduino-pico#uploading-filesystem-images>`_ is available that enables a data folder to be packed as a LittleFS filesystem binary and uploaded to the Pico.
298+
299+
This functionality is also built-in in the PlatformIO integration. Open the `project tasks <https://docs.platformio.org/en/latest/integration/ide/vscode.html#project-tasks>`_ and expand the "Platform" tasks:
300+
301+
.. image:: images/pio_fs_upload.png
302+
303+
The files you want to upload should be placed in a folder called ``data`` inside the project. This can be customized `if needed <https://docs.platformio.org/en/latest/projectconf/section_platformio.html#data-dir>`_.
304+
305+
The task "Build Filesystem Image" will take all files in the data directory and create a ``littlefs.bin`` file from it using the ``mklittlefs`` tool.
306+
307+
The task "Upload Filesystem Image" will upload the filesystem image to the Pico via the specified ``upload_protocol``.
308+
309+
**Note:** Currently only the default ``picotool`` (regular direct USB upload) and the OpenOCD-based debug methods (meaning all but ``jlink``) can transport the filesystem to the Pico.

‎tools/json/adafruit_feather.json

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11,14 +11,12 @@
1111
]
1212
],
1313
"mcu": "rp2040",
14+
"variant": "adafruit_feather",
1415
"arduino": {
1516
"earlephilhower": {
16-
"variant": "adafruit_feather",
1717
"boot2_source": "boot2_w25x10cl_4_padded_checksum.S",
1818
"usb_vid": "0x239a",
19-
"usb_pid": "0x80f1",
20-
"usb_manufacturer": "Adafruit",
21-
"usb_product": "Feather RP2040"
19+
"usb_pid": "0x80f1"
2220
}
2321
}
2422
},
@@ -49,4 +47,4 @@
4947
},
5048
"url": "https://www.raspberrypi.org/products/raspberry-pi-pico/",
5149
"vendor": "Adafruit"
52-
}
50+
}

‎tools/json/adafruit_itsybitsy.json

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11,14 +11,12 @@
1111
]
1212
],
1313
"mcu": "rp2040",
14+
"variant": "adafruit_itsybitsy",
1415
"arduino": {
1516
"earlephilhower": {
16-
"variant": "adafruit_itsybitsy",
1717
"boot2_source": "boot2_w25q080_2_padded_checksum.S",
1818
"usb_vid": "0x239a",
19-
"usb_pid": "0x80fd",
20-
"usb_manufacturer": "Adafruit",
21-
"usb_product": "ItsyBitsy RP2040"
19+
"usb_pid": "0x80fd"
2220
}
2321
}
2422
},
@@ -49,4 +47,4 @@
4947
},
5048
"url": "https://www.raspberrypi.org/products/raspberry-pi-pico/",
5149
"vendor": "Adafruit"
52-
}
50+
}

‎tools/json/adafruit_kb2040.json

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11,14 +11,12 @@
1111
]
1212
],
1313
"mcu": "rp2040",
14+
"variant": "adafruit_kb2040",
1415
"arduino": {
1516
"earlephilhower": {
16-
"variant": "adafruit_kb2040",
1717
"boot2_source": "boot2_w25q080_2_padded_checksum.S",
1818
"usb_vid": "0x239a",
19-
"usb_pid": "0x8105",
20-
"usb_manufacturer": "Adafruit",
21-
"usb_product": "KB2040"
19+
"usb_pid": "0x8105"
2220
}
2321
}
2422
},
@@ -49,4 +47,4 @@
4947
},
5048
"url": "https://www.raspberrypi.org/products/raspberry-pi-pico/",
5149
"vendor": "Adafruit"
52-
}
50+
}

‎tools/json/adafruit_macropad2040.json

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11,14 +11,12 @@
1111
]
1212
],
1313
"mcu": "rp2040",
14+
"variant": "adafruit_macropad2040",
1415
"arduino": {
1516
"earlephilhower": {
16-
"variant": "adafruit_macropad2040",
1717
"boot2_source": "boot2_w25q080_2_padded_checksum.S",
1818
"usb_vid": "0x239a",
19-
"usb_pid": "0x8107",
20-
"usb_manufacturer": "Adafruit",
21-
"usb_product": "MacroPad RP2040"
19+
"usb_pid": "0x8107"
2220
}
2321
}
2422
},
@@ -49,4 +47,4 @@
4947
},
5048
"url": "https://www.raspberrypi.org/products/raspberry-pi-pico/",
5149
"vendor": "Adafruit"
52-
}
50+
}

‎tools/json/adafruit_qtpy.json

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11,14 +11,12 @@
1111
]
1212
],
1313
"mcu": "rp2040",
14+
"variant": "adafruit_qtpy",
1415
"arduino": {
1516
"earlephilhower": {
16-
"variant": "adafruit_qtpy",
1717
"boot2_source": "boot2_w25q080_2_padded_checksum.S",
1818
"usb_vid": "0x239a",
19-
"usb_pid": "0x80f7",
20-
"usb_manufacturer": "Adafruit",
21-
"usb_product": "QT Py RP2040"
19+
"usb_pid": "0x80f7"
2220
}
2321
}
2422
},
@@ -49,4 +47,4 @@
4947
},
5048
"url": "https://www.raspberrypi.org/products/raspberry-pi-pico/",
5149
"vendor": "Adafruit"
52-
}
50+
}

‎tools/json/adafruit_stemmafriend.json

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11,14 +11,12 @@
1111
]
1212
],
1313
"mcu": "rp2040",
14+
"variant": "adafruit_stemmafriend",
1415
"arduino": {
1516
"earlephilhower": {
16-
"variant": "adafruit_stemmafriend",
1717
"boot2_source": "boot2_w25q080_2_padded_checksum.S",
1818
"usb_vid": "0x239a",
19-
"usb_pid": "0x80e3",
20-
"usb_manufacturer": "Adafruit",
21-
"usb_product": "STEMMA Friend RP2040"
19+
"usb_pid": "0x80e3"
2220
}
2321
}
2422
},
@@ -49,4 +47,4 @@
4947
},
5048
"url": "https://www.raspberrypi.org/products/raspberry-pi-pico/",
5149
"vendor": "Adafruit"
52-
}
50+
}

‎tools/json/adafruit_trinkeyrp2040qt.json

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11,14 +11,12 @@
1111
]
1212
],
1313
"mcu": "rp2040",
14+
"variant": "adafruit_trinkeyrp2040qt",
1415
"arduino": {
1516
"earlephilhower": {
16-
"variant": "adafruit_trinkeyrp2040qt",
1717
"boot2_source": "boot2_w25q080_2_padded_checksum.S",
1818
"usb_vid": "0x239a",
19-
"usb_pid": "0x8109",
20-
"usb_manufacturer": "Adafruit",
21-
"usb_product": "Trinkey RP2040 QT"
19+
"usb_pid": "0x8109"
2220
}
2321
}
2422
},
@@ -49,4 +47,4 @@
4947
},
5048
"url": "https://www.raspberrypi.org/products/raspberry-pi-pico/",
5149
"vendor": "Adafruit"
52-
}
50+
}

‎tools/json/arduino_nano_connect.json

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11,14 +11,12 @@
1111
]
1212
],
1313
"mcu": "rp2040",
14+
"variant": "arduino_nano_connect",
1415
"arduino": {
1516
"earlephilhower": {
16-
"variant": "arduino_nano_connect",
1717
"boot2_source": "boot2_w25q080_2_padded_checksum.S",
1818
"usb_vid": "0x2341",
19-
"usb_pid": "0x0058",
20-
"usb_manufacturer": "Arduino",
21-
"usb_product": "Nano RP2040 Connect"
19+
"usb_pid": "0x0058"
2220
}
2321
}
2422
},
@@ -49,4 +47,4 @@
4947
},
5048
"url": "https://www.raspberrypi.org/products/raspberry-pi-pico/",
5149
"vendor": "Arduino"
52-
}
50+
}

0 commit comments

Comments
 (0)