Update PlatformIO builder script and docs

docs/platformio.rst

@@ -19,14 +19,14 @@ The PlatformIO experience:
 
 Refer to the general documentation at https://docs.platformio.org/.
 
-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.
+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.
 
 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.
 
 Current state of development
 ----------------------------
 
-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.
+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.
 
 If you want to use the PlatformIO integration right now, make sure you first create a standard Raspberry Pi Pico + Arduino project within PlatformIO. 
 This will give you a project with the ``platformio.ini`` 
@@ -38,21 +38,42 @@ This will give you a project with the ``platformio.ini``
     board = pico
     framework = arduino
 
-Here, you need to change the `platform` to take advantage of the features described hereunder. 
-You *also* need to inject two PlatformIO packages, one for the compiler toolchain and one for the Arduino core package.
+Here, you need to change the `platform` to take advantage of the features described hereunder and switch to the new core.
 
 .. code:: ini
 
     [env:pico]
     platform = https://github.com/maxgerhardt/platform-raspberrypi.git
     board = pico
     framework = arduino
+    board_build.core = earlephilhower
+
+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.
+
+Deprecation warnings
+---------------------
+
+Previous versions of this documentation told users to inject the framework and toolchain package into the project by using
+
+.. code:: ini
+
     ; note that download link for toolchain is specific for OS. see https://github.com/earlephilhower/pico-quick-toolchain/releases.
     platform_packages = 
         maxgerhardt/framework-arduinopico@https://github.com/earlephilhower/arduino-pico.git
         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
-
-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.
+
+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
+
+.. code:: bash
+
+    pio pkg update -g -p https://github.com/maxgerhardt/platform-raspberrypi.git
+
+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.
+
+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.
+However, users can still select a custom fork or branch of the core if desired so, as detailed in a chapter below.
+
+As the pull req
 
 Selecting the new core
 ----------------------
@@ -61,8 +82,8 @@ Prerequisite for using this core is to tell PlatformIO to switch to it.
 There will be board definition files where the Earle-Philhower core will
 be the default since it's a board that only exists in this core (and not
 the other https://github.com/arduino/ArduinoCore-mbed). To switch boards
-for which this is not the default core (e.g. the standard
-``board = pico``), the directive
+for which this is not the default core (which are only
+``board = pico`` and ``board = nanorp2040connect``), the directive
 
 .. code:: ini
 
@@ -72,6 +93,8 @@ must be added to the ``platformio.ini``. This controls the `core
 switching
 logic <https://github.com/maxgerhardt/platform-raspberrypi/blob/77e0d3a29d1dbf00fd3ec3271104e3bf4820869c/builder/frameworks/arduino/arduino.py#L27-L32>`__.
 
+When using Arduino-Pico-only boards like ``board = rpipico`` or ``board = adafruit_feather``, this is not needed.
+
 Flash size
 ----------
 
@@ -154,6 +177,37 @@ either a sing line or a newline-separated expression.
        -DDEBUG_RP2040_CORE
        -DDEBUG_RP2040_PORT=Serial2
 
+C++ Exceptions
+--------------
+
+Exceptions are disabled by default. To enable them, use
+
+.. code:: ini
+
+    ; Enable Exceptions
+    build_flags = -DPIO_FRAMEWORK_ARDUINO_ENABLE_EXCEPTIONS
+
+Stack Protector
+---------------
+
+To enable GCC's stack protection feature, use
+
+.. code:: ini
+
+    ; Enable Stack Protector
+    build_flags = -fstack-protector
+
+
+RTTI
+----
+
+RTTI (run-time type information) is disabled by default. To enable it, use
+
+.. code:: ini
+
+    ; Enable RTTI
+    build_flags = -DPIO_FRAMEWORK_ARDUINO_ENABLE_RTTI
+
 USB Stack
 ---------
 
@@ -188,8 +242,8 @@ directive to do so. Simply specify that the framework package
 Whereas the ``#master`` can also be replaced by a ``#branchname`` or a
 ``#commithash``. If left out, it will pull the default branch, which is ``master``.
 
-The ``file://`` pseudo-protocol can also be used instead of ``https://`` to point to a
-local copy of the core (with e.g. some modifications) on disk.
+The ``file://`` and ``symlink://`` pseudo-protocols can also be used instead of ``https://`` to point to a
+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>_`).
 
 Note that this can only be done for versions that have the PlatformIO
 builder script it in, so versions before 1.9.2 are not supported.
@@ -206,14 +260,50 @@ and 0.5MByte filesystem.
     platform = https://github.com/maxgerhardt/platform-raspberrypi.git
     board = pico
     framework = arduino
+    ; board can use both Arduino cores -- we select Arduino-Pico here
     board_build.core = earlephilhower
     board_build.filesystem_size = 0.5m
-    ; note that download link for toolchain is specific for OS. see https://github.com/earlephilhower/pico-quick-toolchain/releases.
-    platform_packages = 
-        maxgerhardt/framework-arduinopico@https://github.com/earlephilhower/arduino-pico.git
-        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
 
 
 The initial project structure should be generated just creating a new
 project for the Pico and the Arduino framework, after which the
 auto-generated ``platformio.ini`` can be adapted per above.
+
+Debugging
+---------
+
+With recent updates to the toolchain and OpenOCD, debugging firmwares is also possible.
+
+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:
+
+* ``picoprobe``
+* ``cmsis-dap``
+* ``jlink``
+* ``raspberrypi-swd``
+
+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.
+
+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.
+
+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.
+
+.. image:: images/pio_debugging.png
+
+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>`_.
+
+Filesystem Uploading
+--------------------
+
+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.
+
+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: 
+
+.. image:: images/pio_fs_upload.png
+
+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>`_.
+
+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.
+
+The task "Upload Filesystem Image" will upload the filesystem image to the Pico via the specified ``upload_protocol``. 
+
+**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

@@ -11,14 +11,12 @@
       ]
     ],
     "mcu": "rp2040",
+    "variant": "adafruit_feather",
     "arduino": {
       "earlephilhower": {
-        "variant": "adafruit_feather",
         "boot2_source": "boot2_w25x10cl_4_padded_checksum.S",
         "usb_vid": "0x239a",
-        "usb_pid": "0x80f1",
-        "usb_manufacturer": "Adafruit",
-        "usb_product": "Feather RP2040"
+        "usb_pid": "0x80f1"
       }
     }
   },
@@ -49,4 +47,4 @@
   },
   "url": "https://www.raspberrypi.org/products/raspberry-pi-pico/",
   "vendor": "Adafruit"
-}
+}

tools/json/adafruit_itsybitsy.json

@@ -11,14 +11,12 @@
       ]
     ],
     "mcu": "rp2040",
+    "variant": "adafruit_itsybitsy",
     "arduino": {
       "earlephilhower": {
-        "variant": "adafruit_itsybitsy",
         "boot2_source": "boot2_w25q080_2_padded_checksum.S",
         "usb_vid": "0x239a",
-        "usb_pid": "0x80fd",
-        "usb_manufacturer": "Adafruit",
-        "usb_product": "ItsyBitsy RP2040"
+        "usb_pid": "0x80fd"
       }
     }
   },
@@ -49,4 +47,4 @@
   },
   "url": "https://www.raspberrypi.org/products/raspberry-pi-pico/",
   "vendor": "Adafruit"
-}
+}

tools/json/adafruit_kb2040.json

@@ -11,14 +11,12 @@
       ]
     ],
     "mcu": "rp2040",
+    "variant": "adafruit_kb2040",
     "arduino": {
       "earlephilhower": {
-        "variant": "adafruit_kb2040",
         "boot2_source": "boot2_w25q080_2_padded_checksum.S",
         "usb_vid": "0x239a",
-        "usb_pid": "0x8105",
-        "usb_manufacturer": "Adafruit",
-        "usb_product": "KB2040"
+        "usb_pid": "0x8105"
       }
     }
   },
@@ -49,4 +47,4 @@
   },
   "url": "https://www.raspberrypi.org/products/raspberry-pi-pico/",
   "vendor": "Adafruit"
-}
+}

tools/json/adafruit_macropad2040.json

@@ -11,14 +11,12 @@
       ]
     ],
     "mcu": "rp2040",
+    "variant": "adafruit_macropad2040",
     "arduino": {
       "earlephilhower": {
-        "variant": "adafruit_macropad2040",
         "boot2_source": "boot2_w25q080_2_padded_checksum.S",
         "usb_vid": "0x239a",
-        "usb_pid": "0x8107",
-        "usb_manufacturer": "Adafruit",
-        "usb_product": "MacroPad RP2040"
+        "usb_pid": "0x8107"
       }
     }
   },
@@ -49,4 +47,4 @@
   },
   "url": "https://www.raspberrypi.org/products/raspberry-pi-pico/",
   "vendor": "Adafruit"
-}
+}

tools/json/adafruit_qtpy.json

@@ -11,14 +11,12 @@
       ]
     ],
     "mcu": "rp2040",
+    "variant": "adafruit_qtpy",
     "arduino": {
       "earlephilhower": {
-        "variant": "adafruit_qtpy",
         "boot2_source": "boot2_w25q080_2_padded_checksum.S",
         "usb_vid": "0x239a",
-        "usb_pid": "0x80f7",
-        "usb_manufacturer": "Adafruit",
-        "usb_product": "QT Py RP2040"
+        "usb_pid": "0x80f7"
       }
     }
   },
@@ -49,4 +47,4 @@
   },
   "url": "https://www.raspberrypi.org/products/raspberry-pi-pico/",
   "vendor": "Adafruit"
-}
+}

tools/json/adafruit_stemmafriend.json

@@ -11,14 +11,12 @@
       ]
     ],
     "mcu": "rp2040",
+    "variant": "adafruit_stemmafriend",
     "arduino": {
       "earlephilhower": {
-        "variant": "adafruit_stemmafriend",
         "boot2_source": "boot2_w25q080_2_padded_checksum.S",
         "usb_vid": "0x239a",
-        "usb_pid": "0x80e3",
-        "usb_manufacturer": "Adafruit",
-        "usb_product": "STEMMA Friend RP2040"
+        "usb_pid": "0x80e3"
       }
     }
   },
@@ -49,4 +47,4 @@
   },
   "url": "https://www.raspberrypi.org/products/raspberry-pi-pico/",
   "vendor": "Adafruit"
-}
+}

tools/json/adafruit_trinkeyrp2040qt.json

@@ -11,14 +11,12 @@
       ]
     ],
     "mcu": "rp2040",
+    "variant": "adafruit_trinkeyrp2040qt",
     "arduino": {
       "earlephilhower": {
-        "variant": "adafruit_trinkeyrp2040qt",
         "boot2_source": "boot2_w25q080_2_padded_checksum.S",
         "usb_vid": "0x239a",
-        "usb_pid": "0x8109",
-        "usb_manufacturer": "Adafruit",
-        "usb_product": "Trinkey RP2040 QT"
+        "usb_pid": "0x8109"
       }
     }
   },
@@ -49,4 +47,4 @@
   },
   "url": "https://www.raspberrypi.org/products/raspberry-pi-pico/",
   "vendor": "Adafruit"
-}
+}

tools/json/arduino_nano_connect.json

@@ -11,14 +11,12 @@
       ]
     ],
     "mcu": "rp2040",
+    "variant": "arduino_nano_connect",
     "arduino": {
       "earlephilhower": {
-        "variant": "arduino_nano_connect",
         "boot2_source": "boot2_w25q080_2_padded_checksum.S",
         "usb_vid": "0x2341",
-        "usb_pid": "0x0058",
-        "usb_manufacturer": "Arduino",
-        "usb_product": "Nano RP2040 Connect"
+        "usb_pid": "0x0058"
       }
     }
   },
@@ -49,4 +47,4 @@
   },
   "url": "https://www.raspberrypi.org/products/raspberry-pi-pico/",
   "vendor": "Arduino"
-}
+}