[board] Cleanup use of custom openocd configs

Author: salkinium

src/modm/board/black_pill_f103/module.lb

@@ -11,49 +11,19 @@
 # file, You can obtain one at http://mozilla.org/MPL/2.0/.
 # -----------------------------------------------------------------------------
 
-description = """
+def init(module):
+    module.name = ":board:black-pill-f103"
+    module.description = """
 # Black Pill
 
 STM32F103C8T6 "Black Pill" Minimum System Development Board
 
 Cheap and bread-board-friendly board for STM32 F1 series.
-Sold for less than 2 USD on well known Internet shops from China.
+Sold for less than 2 USD on Aliexpress.
 
 https://stm32-base.org/boards/STM32F103C8T6-Black-Pill.html
-
-## Programming
-
-Since the board doesn't have a programmer on-board, you need to use your
-own and *specify* which one you're using in a custom `openocd.cfg` file:
-
-```
-# Replace this with your custom programmer
-source [find interface/stlink-v2.cfg]
-
-# If you use the clone CKS32F103C8T6 chip you need to overwrite this ID
-#set CPUTAPID 0x2ba01477
-
-# To select a specific programmer you can specify its serial number
-#hla_serial "\\x53\\x3f\\x6f\\x06\\x50\\x77\\x50\\x57\\x12\\x17\\x14\\x3f"
-# You can discover the serial via `stlink --hla-serial` or `st-info --hla-serial`.
-```
-
-Then include this file in your build options like so:
-
-```xml
-<library>
-  <extends>modm:black-pill</extends>
-  <options>
-    <option name="modm:build:openocd.cfg">openocd.cfg</option>
-  </options>
-</library>
-```
 """
 
-def init(module):
-    module.name = ":board:black-pill-f103"
-    module.description = description
-
 def prepare(module, options):
     if not options[":target"].partname.startswith("stm32f103c8t"):
         return False
@@ -76,9 +46,6 @@ def build(env):
     env.copy('.')
 
     env.outbasepath = "modm/openocd/modm/board/"
-    env.copy(repopath("tools/openocd/modm/stm32f103_blue_pill.cfg"), "stm32f103_blue_pill.cfg")
-    env.collect(":build:openocd.source", "modm/board/stm32f103_blue_pill.cfg")
-
-    # Warn the user if they forgot to set a custom openocd config
-    if env.has_option(":build:openocd.cfg") and not len(env.get(":build:openocd.cfg", "")):
-        env.log.warning("You need to provide the programmer via a custom OpenOCD config!\n" + description)
+    env.template(repopath("tools/openocd/modm/stm32_swd.cfg.in"), "board.cfg",
+                 substitutions={"target": "stm32f1x"})
+    env.collect(":build:openocd.source", "modm/board/board.cfg")

src/modm/board/black_pill_f401/module.lb

@@ -12,13 +12,13 @@
 
 def init(module):
     module.name = ":board:black-pill-f401"
-    module.description = """\
+    module.description = """
 # Black Pill F401
 
 STM32F401CCU "Mini-F401" Minimum System Development Board
 
 Cheap and bread-board-friendly board for STM32F401 series.
-Sold for less than 4 USD on well known Internet shops from China.
+Sold for less than 4 USD on Aliexpress.
 Attention: There are two variants: Mini-F411 and the cheaper Mini-F401.
 
 https://stm32-base.org/boards/STM32F401CEU6-WeAct-Black-Pill-V3.0
@@ -32,25 +32,6 @@ A DFU command is integrated into the `modm:build:scons` tool and can be called a
 ```
 scons program-dfu
 ```
-
-Alternatively you can go for an external programmer
-and *specify* which one you're using in a custom `openocd.cfg` file:
-
-```
-# Replace this with your custom programmer
-source [find interface/stlink-v2.cfg]
-```
-
-Then include this file in your build options like so:
-
-```xml
-<library>
-  <extends>modm:black-pill-f401</extends>
-  <options>
-    <option name="modm:build:openocd.cfg">openocd.cfg</option>
-  </options>
-</library>
-```
 """
 
 def prepare(module, options):
@@ -75,5 +56,6 @@ def build(env):
     env.copy('../black_pill_f411/board.hpp', 'board.hpp')
 
     env.outbasepath = "modm/openocd/modm/board/"
-    env.copy(repopath("tools/openocd/modm/stm32f4x1_mini_f4x1.cfg"), "stm32f4x1_mini_f4x1.cfg")
-    env.collect(":build:openocd.source", "modm/board/stm32f4x1_mini_f4x1.cfg")
+    env.template(repopath("tools/openocd/modm/stm32_swd.cfg.in"), "board.cfg",
+                 substitutions={"target": "stm32f4x"})
+    env.collect(":build:openocd.source", "modm/board/board.cfg")

src/modm/board/black_pill_f411/module.lb

@@ -12,13 +12,13 @@
 
 def init(module):
     module.name = ":board:black-pill-f411"
-    module.description = """\
+    module.description = """
 # Black Pill F411
 
 STM32F411CEU "Mini-F411" Minimum System Development Board
 
 Cheap and bread-board-friendly board for STM32F411 series.
-Sold for less than 5 USD on well known Internet shops from China.
+Sold for less than 5 USD on Aliexpress.
 Attention: There are two variants: Mini-F411 and the cheaper Mini-F401.
 
 https://stm32-base.org/boards/STM32F401CEU6-WeAct-Black-Pill-V3.0
@@ -32,25 +32,6 @@ A DFU command is integrated into the `modm:build:scons` tool and can be called a
 ```
 scons program-dfu
 ```
-
-Alternatively you can go for an external programmer
-and *specify* which one you're using in a custom `openocd.cfg` file:
-
-```
-# Replace this with your custom programmer
-source [find interface/stlink-v2.cfg]
-```
-
-Then include this file in your build options like so:
-
-```xml
-<library>
-  <extends>modm:black-pill-f411</extends>
-  <options>
-    <option name="modm:build:openocd.cfg">openocd.cfg</option>
-  </options>
-</library>
-```
 """
 
 def prepare(module, options):
@@ -75,5 +56,6 @@ def build(env):
     env.copy('.')
 
     env.outbasepath = "modm/openocd/modm/board/"
-    env.copy(repopath("tools/openocd/modm/stm32f4x1_mini_f4x1.cfg"), "stm32f4x1_mini_f4x1.cfg")
-    env.collect(":build:openocd.source", "modm/board/stm32f4x1_mini_f4x1.cfg")
+    env.template(repopath("tools/openocd/modm/stm32_swd.cfg.in"), "board.cfg",
+                 substitutions={"target": "stm32f4x"})
+    env.collect(":build:openocd.source", "modm/board/board.cfg")

src/modm/board/blue_pill_f103/module.lb

@@ -11,49 +11,19 @@
 # file, You can obtain one at http://mozilla.org/MPL/2.0/.
 # -----------------------------------------------------------------------------
 
-description = """
+def init(module):
+    module.name = ":board:blue-pill-f103"
+    module.description = """
 # Blue Pill
 
 STM32F103C8T6 "Blue Pill" Minimum System Development Board
 
 Cheap and bread-board-friendly board for STM32 F1 series.
-Sold for less than 2 USD on well known Internet shops from China.
+Sold for less than 2 USD on Aliexpress.
 
 https://stm32-base.org/boards/STM32F103C8T6-Blue-Pill.html
-
-## Programming
-
-Since the board doesn't have a programmer on-board, you need to use your
-own and *specify* which one you're using in a custom `openocd.cfg` file:
-
-```
-# Replace this with your custom programmer
-source [find interface/stlink-v2.cfg]
-
-# If you use the clone CKS32F103C8T6 chip you need to overwrite this ID
-#set CPUTAPID 0x2ba01477
-
-# To select a specific programmer you can specify its serial number
-#hla_serial "\\x53\\x3f\\x6f\\x06\\x50\\x77\\x50\\x57\\x12\\x17\\x13\\x3f"
-# You can discover the serial via `stlink --hla-serial` or `st-info --hla-serial`.
-```
-
-Then include this file in your build options like so:
-
-```xml
-<library>
-  <extends>modm:blue-pill-f103</extends>
-  <options>
-    <option name="modm:build:openocd.cfg">openocd.cfg</option>
-  </options>
-</library>
-```
 """
 
-def init(module):
-    module.name = ":board:blue-pill-f103"
-    module.description = description
-
 def prepare(module, options):
     if not options[":target"].partname.startswith("stm32f103c8t"):
         return False
@@ -76,9 +46,6 @@ def build(env):
     env.copy('.')
 
     env.outbasepath = "modm/openocd/modm/board/"
-    env.copy(repopath("tools/openocd/modm/stm32f103_blue_pill.cfg"), "stm32f103_blue_pill.cfg")
-    env.collect(":build:openocd.source", "modm/board/stm32f103_blue_pill.cfg")
-
-    # Warn the user if they forgot to set a custom openocd config
-    if env.has_option(":build:openocd.cfg") and not len(env.get(":build:openocd.cfg", "")):
-        env.log.warning("You need to provide the programmer via a custom OpenOCD config!\n" + description)
+    env.template(repopath("tools/openocd/modm/stm32_swd.cfg.in"), "board.cfg",
+                 substitutions={"target": "stm32f1x"})
+    env.collect(":build:openocd.source", "modm/board/board.cfg")

src/modm/board/devebox_stm32f4xx/module.lb

@@ -40,5 +40,6 @@ def build(env):
     env.copy('.')
 
     env.outbasepath = "modm/openocd/modm/board/"
-    env.copy(repopath("tools/openocd/modm/stm32f4x1_mini_f4x1.cfg"), "stm32f4x1_mini_f4x1.cfg")
-    env.collect(":build:openocd.source", "modm/board/stm32f4x1_mini_f4x1.cfg")
+    env.template(repopath("tools/openocd/modm/stm32_swd.cfg.in"), "board.cfg",
+                 substitutions={"target": "stm32f4x"})
+    env.collect(":build:openocd.source", "modm/board/board.cfg")

src/modm/board/devebox_stm32h750vb/module.lb

@@ -10,7 +10,9 @@
 # file, You can obtain one at http://mozilla.org/MPL/2.0/.
 # -----------------------------------------------------------------------------
 
-description = """
+def init(module):
+    module.name = ":board:devebox-stm32h750vb"
+    module.description = """
 # STM32F750VB mcudev DevEBox
 
 [STM32F750VB mcudev DevEBox H7xx](https://github.com/mcauser/MCUDEV_DEVEBOX_H7XX_M)
@@ -32,40 +34,8 @@ target option in your `project.xml`:
   </options>
 </library>
 ```
-
-## Programming
-
-Since the board doesn't have a programmer on-board, you need to use your
-own and *specify* which one you're using in a custom `openocd.cfg` file:
-
-```
-# Replace this with your custom programmer
-source [find interface/stlink.cfg]
-
-# If you use the clone CKS32F103C8T6 chip you need to overwrite this ID
-#set CPUTAPID 0x2ba01477
-
-# To select a specific programmer you can specify its serial number
-#hla_serial "\\x53\\x3f\\x6f\\x06\\x50\\x77\\x50\\x57\\x12\\x17\\x13\\x3f"
-# You can discover the serial via `stlink --hla-serial` or `st-info --hla-serial`.
-```
-
-Then include this file in your build options like so:
-
-```xml
-<library>
-  <extends>modm:devebox-stm32h750vb</extends>
-  <options>
-    <option name="modm:build:openocd.cfg">openocd.cfg</option>
-  </options>
-</library>
-```
 """
 
-def init(module):
-    module.name = ":board:devebox-stm32h750vb"
-    module.description = description
-
 def prepare(module, options):
     if not options[":target"].partname.startswith("stm32h750vbt"):
         return False
@@ -90,9 +60,6 @@ def build(env):
     env.copy('.')
 
     env.outbasepath = "modm/openocd/modm/board/"
-    env.copy(repopath("tools/openocd/modm/stm32h7xx_devebox.cfg"), "stm32h7xx_devebox.cfg")
-    env.collect(":build:openocd.source", "modm/board/stm32h7xx_devebox.cfg")
-
-    # Warn the user if they forgot to set a custom openocd config
-    if env.has_option(":build:openocd.cfg") and not len(env.get(":build:openocd.cfg", "")):
-        env.log.warning("You need to provide the programmer via a custom OpenOCD config!\n" + description)
+    env.template(repopath("tools/openocd/modm/stm32_swd.cfg.in"), "board.cfg",
+                 substitutions={"target": "stm32h7x"})
+    env.collect(":build:openocd.source", "modm/board/board.cfg")

src/modm/board/feather_m0/module.lb

@@ -47,7 +47,3 @@ def build(env):
     }
     env.template("../board.cpp.in", "board.cpp")
     env.copy('.')
-
-    # env.outbasepath = "modm/openocd/modm/board/"
-    # env.copy(repopath("tools/openocd/modm/stm32f103_blue_pill.cfg"), "stm32f103_blue_pill.cfg")
-    # env.collect(":build:openocd.source", "modm/board/stm32f103_blue_pill.cfg");

src/modm/board/feather_rp2040/module.lb

@@ -43,7 +43,4 @@ def build(env):
     }
     env.template("../board.cpp.in", "board.cpp")
     env.copy('.')
-
-    env.outbasepath = "modm/openocd/modm/board/"
-    env.copy(repopath("tools/openocd/modm/rp2040_picoprobe.cfg"), "rp2040_picoprobe.cfg")
-    env.collect(":build:openocd.source", "modm/board/rp2040_picoprobe.cfg")
+    env.collect(":build:openocd.source", "interface/picoprobe.cfg", "target/rp2040.cfg")

src/modm/board/module.md

@@ -66,6 +66,45 @@ int main()
 	same functions resulting in naming conflicts.
 
 
+## Programming
+
+Most development boards have a programmer on-board and the BSPs are configured
+to use them automatically.
+
+However, for development boards without a programmer on-board, you need to use
+your own and *specify* which one you're using. For simple configuration, adding
+a collector is enough:
+
+```xml
+<library>
+  <collectors>
+    <collect name="modm:build:openocd.source">interface/stlink.cfg</collect>
+  </collectors>
+</library>
+```
+
+For more complex configuration, add a custom `openocd.cfg` file:
+
+```tcl
+# Replace this with your custom programmer
+source [find interface/stlink.cfg]
+
+# To select a specific programmer you can specify its serial number
+hla_serial "\\x53\\x3f\\x6f\\x06\\x50\\x77\\x50\\x57\\x12\\x17\\x14\\x3f"
+# You can discover the serial via `lsusb -v`.
+```
+
+Then include this file in your build options like so:
+
+```xml
+<library>
+  <options>
+    <option name="modm:build:openocd.cfg">openocd.cfg</option>
+  </options>
+</library>
+```
+
+
 ## Customization
 
 The BSPs contain an opinionated set of pre-defined functionality and settings.

src/modm/board/nucleo_c031c6/module.lb

@@ -39,5 +39,6 @@ def build(env):
     env.copy("../nucleo64_arduino_c0.hpp", "nucleo64_arduino.hpp")
 
     env.outbasepath = "modm/openocd/modm/board/"
-    env.copy(repopath("tools/openocd/modm/st_nucleo_c0.cfg"), "st_nucleo_c0.cfg")
-    env.collect(":build:openocd.source", "modm/board/st_nucleo_c0.cfg")
+    env.template(repopath("tools/openocd/modm/st_nucleo_swd.cfg.in"), "board.cfg",
+                 substitutions={"target": "stm32c0x"})
+    env.collect(":build:openocd.source", "modm/board/board.cfg")

src/modm/board/nucleo_g070rb/module.lb

@@ -35,7 +35,4 @@ def build(env):
     }
     env.template("../board.cpp.in", "board.cpp")
     env.copy("../nucleo_g071rb/board.hpp", "board.hpp")
-
-    env.outbasepath = "modm/openocd/modm/board/"
-    env.copy(repopath("tools/openocd/modm/st_nucleo_g0.cfg"), "st_nucleo_g0.cfg")
-    env.collect(":build:openocd.source", "modm/board/st_nucleo_g0.cfg")
+    env.collect(":build:openocd.source", "board/st_nucleo_g0.cfg")