Enable BlackMagicProbe for PlatformIO (#1378)

maxgerhardt · web-flow · commit 4f643d27d94c · 2023-04-15T12:35:45.000-07:00
diff --git a/docs/platformio.rst b/docs/platformio.rst
@@ -341,17 +341,26 @@ To specify the debugging adapter, use ``debug_tool`` (`documentation <https://do
 * ``cmsis-dap``
 * ``jlink``
 * ``raspberrypi-swd``
+* ``blackmagic``
 
 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.
+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.
+
+.. note::
+    Newer PicoProbe firmware versions have dropped the proprietary "PicoProbe" USB communication protocol and emulate a **CMSIS-DAP** instead. Meaning, you have to use ``debug_tool = cmsis-dap`` for these newer firmwares, such as those obtained from `raspberrypi/picoprobe <https://github.com/raspberrypi/picoprobe/releases>`__
 
 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>`_.
 
+.. note:: 
+    For the BlackMagicProbe debugging probe (as can be e.g., created by simply flashing a STM32F103C8 "Bluepill" board), you currently have to use the branch ``fix/rp2040-flash-reliability`` (or at least commit ``1d001bc``) **and** use the `official ARM provided toolchain <https://github.com/blackmagic-debug/blackmagic/issues/1364#issuecomment-1503393266>`_.
+
+    You can obtain precompiled binaries from `here <https://github.com/blackmagic-debug/blackmagic/issues/1364#issuecomment-1503372723>`__. A flashing guide is available `here <https://primalcortex.wordpress.com/2017/06/13/building-a-black-magic-debug-probe/>`__. You then have to configure the target serial port ("GDB port") in your project per `documentation <https://docs.platformio.org/en/latest/plus/debug-tools/blackmagic.html#debugging-tool-blackmagic>`__.
+
 Filesystem Uploading
 --------------------
 
diff --git a/tools/json/0xcb_helios.json b/tools/json/0xcb_helios.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/adafruit_feather.json b/tools/json/adafruit_feather.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/adafruit_feather_dvi.json b/tools/json/adafruit_feather_dvi.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/adafruit_feather_rfm.json b/tools/json/adafruit_feather_rfm.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/adafruit_feather_scorpio.json b/tools/json/adafruit_feather_scorpio.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/adafruit_feather_thinkink.json b/tools/json/adafruit_feather_thinkink.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/adafruit_feather_usb_host.json b/tools/json/adafruit_feather_usb_host.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/adafruit_itsybitsy.json b/tools/json/adafruit_itsybitsy.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/adafruit_kb2040.json b/tools/json/adafruit_kb2040.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/adafruit_macropad2040.json b/tools/json/adafruit_macropad2040.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/adafruit_qtpy.json b/tools/json/adafruit_qtpy.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/adafruit_stemmafriend.json b/tools/json/adafruit_stemmafriend.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/adafruit_trinkeyrp2040qt.json b/tools/json/adafruit_trinkeyrp2040qt.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/arduino_nano_connect.json b/tools/json/arduino_nano_connect.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/bridgetek_idm2040-7a.json b/tools/json/bridgetek_idm2040-7a.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/challenger_2040_lora.json b/tools/json/challenger_2040_lora.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/challenger_2040_lte.json b/tools/json/challenger_2040_lte.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/challenger_2040_nfc.json b/tools/json/challenger_2040_nfc.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/challenger_2040_sdrtc.json b/tools/json/challenger_2040_sdrtc.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/challenger_2040_subghz.json b/tools/json/challenger_2040_subghz.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/challenger_2040_uwb.json b/tools/json/challenger_2040_uwb.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/challenger_2040_wifi.json b/tools/json/challenger_2040_wifi.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/challenger_2040_wifi_ble.json b/tools/json/challenger_2040_wifi_ble.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/challenger_nb_2040_wifi.json b/tools/json/challenger_nb_2040_wifi.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/cytron_maker_nano_rp2040.json b/tools/json/cytron_maker_nano_rp2040.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/cytron_maker_pi_rp2040.json b/tools/json/cytron_maker_pi_rp2040.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/datanoisetv_picoadk.json b/tools/json/datanoisetv_picoadk.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/dfrobot_beetle_rp2040.json b/tools/json/dfrobot_beetle_rp2040.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/electroniccats_huntercat_nfc.json b/tools/json/electroniccats_huntercat_nfc.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/extelec_rc2040.json b/tools/json/extelec_rc2040.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/flyboard2040_core.json b/tools/json/flyboard2040_core.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/generic.json b/tools/json/generic.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/ilabs_rpico32.json b/tools/json/ilabs_rpico32.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/melopero_cookie_rp2040.json b/tools/json/melopero_cookie_rp2040.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/melopero_shake_rp2040.json b/tools/json/melopero_shake_rp2040.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/nekosystems_bl2040_mini.json b/tools/json/nekosystems_bl2040_mini.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/nullbits_bit_c_pro.json b/tools/json/nullbits_bit_c_pro.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/pimoroni_pga2040.json b/tools/json/pimoroni_pga2040.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/rpipico.json b/tools/json/rpipico.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/rpipicow.json b/tools/json/rpipicow.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/seeed_xiao_rp2040.json b/tools/json/seeed_xiao_rp2040.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/solderparty_rp2040_stamp.json b/tools/json/solderparty_rp2040_stamp.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/sparkfun_promicrorp2040.json b/tools/json/sparkfun_promicrorp2040.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/sparkfun_thingplusrp2040.json b/tools/json/sparkfun_thingplusrp2040.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/upesy_rp2040_devkit.json b/tools/json/upesy_rp2040_devkit.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/vccgnd_yd_rp2040.json b/tools/json/vccgnd_yd_rp2040.json
@@ -42,6 +42,7 @@
     "wait_for_upload_port": false,
     "protocol": "picotool",
     "protocols": [
+      "blackmagic",
       "cmsis-dap",
       "jlink",
       "raspberrypi-swd",
diff --git a/tools/json/viyalab_mizu.json b/tools/json/viyalab_mizu.json
diff --git a/tools/json/waveshare_rp2040_lcd_0_96.json b/tools/json/waveshare_rp2040_lcd_0_96.json
diff --git a/tools/json/waveshare_rp2040_lcd_1_28.json b/tools/json/waveshare_rp2040_lcd_1_28.json
diff --git a/tools/json/waveshare_rp2040_one.json b/tools/json/waveshare_rp2040_one.json
diff --git a/tools/json/waveshare_rp2040_plus_16mb.json b/tools/json/waveshare_rp2040_plus_16mb.json
diff --git a/tools/json/waveshare_rp2040_plus_4mb.json b/tools/json/waveshare_rp2040_plus_4mb.json
diff --git a/tools/json/waveshare_rp2040_zero.json b/tools/json/waveshare_rp2040_zero.json
diff --git a/tools/json/wiznet_5100s_evb_pico.json b/tools/json/wiznet_5100s_evb_pico.json
diff --git a/tools/json/wiznet_5500_evb_pico.json b/tools/json/wiznet_5500_evb_pico.json
diff --git a/tools/json/wiznet_wizfi360_evb_pico.json b/tools/json/wiznet_wizfi360_evb_pico.json
diff --git a/tools/makeboards.py b/tools/makeboards.py
