Add USB Flashing Format (UF2) support

Uses code originally from microsoft/uf2 on GitHub.
microsoft/uf2#42

.pylintrc

@@ -0,0 +1,2 @@
+[MESSAGES CONTROL]
+disable=too-few-public-methods

README.md

@@ -2,7 +2,7 @@
     =====================================
     generator=datazen
     version=3.1.2
-    hash=6f0dde62ff0b6f57cc4c8520ac87412c
+    hash=48ddeeed1a075ecca577bad65f289187
     =====================================
 -->
 
@@ -130,20 +130,21 @@ following a specific convention), put your configuration data here.
 ```
 $ ./venv3.11/bin/mbs -h
 
-usage: mbs [-h] [--version] [-v] [-C DIR] {gen,noop} ...
+usage: mbs [-h] [--version] [-v] [-C DIR] {gen,uf2conv,noop} ...
 
 Yet another meta build-system.
 
 options:
-  -h, --help         show this help message and exit
-  --version          show program's version number and exit
-  -v, --verbose      set to increase logging verbosity
-  -C DIR, --dir DIR  execute from a specific directory
+  -h, --help          show this help message and exit
+  --version           show program's version number and exit
+  -v, --verbose       set to increase logging verbosity
+  -C DIR, --dir DIR   execute from a specific directory
 
 commands:
-  {gen,noop}         set of available commands
-    gen              poll the source tree and generate any new build files
-    noop             command stub (does nothing)
+  {gen,uf2conv,noop}  set of available commands
+    gen               poll the source tree and generate any new build files
+    uf2conv           Convert to UF2 or flash directly.
+    noop              command stub (does nothing)
 
 ```
 
@@ -167,6 +168,38 @@ options:
 
 ```
 
+### `uf2conv`
+
+```
+$ ./venv3.11/bin/mbs uf2conv -h
+
+usage: mbs uf2conv [-h] [-b BASE] [-f FAMILY] [-o FILE] [-d DEVICE_PATH] [-l]
+                   [-c] [-D] [-w] [-C] [-i]
+                   [INPUT]
+
+positional arguments:
+  INPUT                 input file (HEX, BIN or UF2)
+
+options:
+  -h, --help            show this help message and exit
+  -b BASE, --base BASE  set base address of application for BIN format
+                        (default: 0x2000)
+  -f FAMILY, --family FAMILY
+                        specify familyID - number or name (default: 0x0)
+  -o FILE, --output FILE
+                        write output to named file; defaults to "flash.uf2" or
+                        "flash.bin" where sensible
+  -d DEVICE_PATH, --device DEVICE_PATH
+                        select a device path to flash
+  -l, --list            list connected devices
+  -c, --convert         do not flash, just convert
+  -D, --deploy          just flash, do not convert
+  -w, --wait            wait for device to flash
+  -C, --carray          convert binary file to a C array, not UF2
+  -i, --info            display header information from UF2, do not convert
+
+```
+
 # Internal Dependency Graph
 
 A coarse view of the internal structure and scale of

local/configs/package.yaml

@@ -14,3 +14,5 @@ dev_requirements:
 commands:
   - name: gen
     description: poll the source tree and generate any new build files
+  - name: uf2conv
+    description: Convert to UF2 or flash directly.

local/includes/sub_commands.yaml

@@ -3,7 +3,7 @@
 default_dirs: false
 
 commands:
-{% for command in ["gen"] %}
+{% for command in ["gen", "uf2conv"] %}
   - name: help-{{command}}
     command: "./venv{{python_version}}/bin/{{entry}}"
     force: true

manifest.yaml

@@ -31,6 +31,7 @@ renders:
       - renders-python_readme_dep_graph.md
       - commands-help
       - commands-help-gen
+      - commands-help-uf2conv
 
   - name: app.py
     output_dir: "{{project}}"

tests/commands/test_uf2conv.py

@@ -0,0 +1,65 @@
+"""
+Test the 'commands.uf2conv' module.
+"""
+
+# third-party
+from vcorelib.paths.context import tempfile
+
+# internal
+from tests.resources import resource
+
+# module under test
+from yambs import PKG_NAME
+from yambs.entry import main as yambs_main
+
+
+def test_uf2conv_basic():
+    """Test the 'uf2conv' command."""
+
+    base = [PKG_NAME, "uf2conv", "-c"]
+
+    assert yambs_main(base) != 0
+
+    assert yambs_main(base + ["-l"]) == 0
+
+    with tempfile() as tmp:
+        for kind in ["bin", "hex"]:
+            output = ["-o", str(tmp)]
+            args = output + [str(resource(f"test1.{kind}"))]
+            assert yambs_main(base + args) == 0
+            assert yambs_main(base + ["--carray"] + args) == 0
+            assert yambs_main(base + ["--info"] + args) == 0
+            assert yambs_main(base + ["-f", "0x16573617"] + args) == 0
+            assert yambs_main(base + ["-f", "SAML21"] + args) == 0
+            assert yambs_main(base + ["-f", "bad"] + args) != 0
+
+        assert (
+            yambs_main(
+                base + output + [str(resource("pi_pico_circuitpython.uf2"))]
+            )
+            == 0
+        )
+        assert (
+            yambs_main(
+                base
+                + output
+                + ["--carray", str(resource("pi_pico_circuitpython.uf2"))]
+            )
+            == 0
+        )
+        assert (
+            yambs_main(
+                base
+                + output
+                + ["--info", str(resource("pi_pico_circuitpython.uf2"))]
+            )
+            == 0
+        )
+        assert (
+            yambs_main(
+                base
+                + output
+                + ["--info", str(resource("pi_pico_circuitpython.uf2"))]
+            )
+            == 0
+        )

tests/data/valid/INFO_UF2.TXT

@@ -0,0 +1,3 @@
+UF2 Bootloader v1.23.1-adafruit.1-88-g797305f SFHWRO
+Model: Grand Central M4 Express
+Board-ID: SAMD51P20A-GrandCentral-v0

tests/data/valid/test1.hex

@@ -0,0 +1,36 @@
+:020000040800F2
+:100000000000012041000008F7010008F501000888
+:10001000F5010008F5010008F501000800000000E6
+:10002000000000000000000000000000F7010008D0
+:10003000F701000800000000F7010008F7010008C0
+:1000400008B54FF0E022D2F8883D43F47003C2F8BF
+:10005000883DBFF34F8FBFF36F8F0024E1EE104A4E
+:10006000094A0A490A4800F086F82146094A0A481E
+:1000700000F08FF8094800F0BFF800F093F821462F
+:10008000204600F01BF8FEE7000000001002000808
+:1000900000000020080000000000002000000020F8
+:1000A00080B483B000AF786039607A683B681344ED
+:1000B00018460C37BD465DF8047B704780B582B0AA
+:1000C00000AF02210120FFF7EBFF00F03BF800F04A
+:1000D00020F84FF000037B6000233B6010E0D7ED79
+:1000E000017A77EEA77AC7ED017A97ED017AF0EE03
+:1000F000006AC7EE267AC7ED017A3B6801333B60A0
+:100100003B68B3F57A7FEADB002318460837BD4623
+:1001100080BD80B483B000AF00237B6000233B60D0
+:1001200005E07B689B007B603B6801333B603B687C
+:10013000B3F5FA6FF5DB00BF00BF0C37BD465DF8C5
+:10014000047B704780B483B000AF00237B60002342
+:100150003B6005E07B685B007B603B6801333B6094
+:100160003B68B3F57A7FF5DB00BF00BF0C37BD46B7
+:100170005DF8047B70470A44914200F1FF3300D1DF
+:10018000704710B511F8014B03F8014F9142F9D1B6
+:1001900010BD02440346934200D1704703F8011B8F
+:1001A000F9E7000070B50E4D0E4C641BA41000263C
+:1001B000A6420BD10C4B0BB1AFF300800B4D0C4C96
+:1001C000641BA4100026A64205D170BD55F8043B5F
+:1001D00098470136ECE755F8043B98470136F2E7BB
+:1001E00010020008100200080000000010020008C1
+:1001F00010020008FEE77047024BC01A024B18605D
+:10020000704700BF08000000000000200000000050
+:0400000508000041AE
+:00000001FF

tests/uf2/test_uf2.py

@@ -0,0 +1,17 @@
+"""
+Test the 'uf2' module.
+"""
+
+# internal
+from tests.resources import resource
+
+# module under test
+from yambs.uf2 import board_id, to_str
+
+
+def test_board_id():
+    """Test the 'board_id' method."""
+
+    assert board_id(str(resource("."))) is not None
+    assert board_id(str(resource(".")), info_file="/test.txt") is None
+    assert to_str(b"hello") == "hello"

yambs/commands/all.py

@@ -1,7 +1,7 @@
 # =====================================
 # generator=datazen
 # version=3.1.2
-# hash=cb9e0150c875bbd5c9a734e5c037a6bd
+# hash=2d9ea45d9d92893a74af1c97e577bc7f
 # =====================================
 
 """
@@ -17,6 +17,7 @@
 
 # internal
 from yambs.commands.gen import add_gen_cmd
+from yambs.commands.uf2conv import add_uf2conv_cmd
 
 
 def commands() -> _List[_Tuple[str, str, _CommandRegister]]:
@@ -28,5 +29,10 @@ def commands() -> _List[_Tuple[str, str, _CommandRegister]]:
             "poll the source tree and generate any new build files",
             add_gen_cmd,
         ),
+        (
+            "uf2conv",
+            "Convert to UF2 or flash directly.",
+            add_uf2conv_cmd,
+        ),
         ("noop", "command stub (does nothing)", lambda _: lambda _: 0),
     ]