Repository navigation
Expand file tree
/
Copy pathuf2conv.py
More file actions
861 lines (708 loc) · 27 KB
/
Copy pathuf2conv.py
File metadata and controls
861 lines (708 loc) · 27 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
#!/usr/bin/env python3
r"""Convert firmware images between Intel HEX, raw BIN, and Raspberry Pi UF2.
This is the course's single canonical copy of the converter. Every week that
patches a binary refers to the copy at the repository root:
python ../uf2conv.py build/image-h.bin --base 0x10000000 \\
--family 0xe48bff59 --output build/hacked.uf2
It descends from the upstream Raspberry Pi ``uf2conv.py``, with the following
changes made for this course:
* Full type annotations and Google-style docstrings on every public callable.
* ``pathlib`` instead of ``os.path``, and explicit ``except`` clauses.
* Latent crash bugs in the upstream error paths fixed (see
:func:`convert_from_uf2`).
* Module globals replaced with an explicit :class:`ConverterContext`, so the
base address and family ID are threaded through rather than mutated behind
the caller's back.
UF2 format, for reference
-------------------------
A UF2 file is a flat sequence of 512-byte blocks. Each block is::
offset size field
0x00 4 magicStart0 = 0x0A324655 ("UF2\\n")
0x04 4 magicStart1 = 0x9E5D5157 (arbitrary constant)
0x08 4 flags
0x0C 4 targetAddr
0x10 4 payloadSize (max 476)
0x14 4 blockNo
0x18 4 numBlocks
0x1C 4 familyID
0x20 476 data
0x1FC 4 magicEnd = 0x0AB16F30
Flags that matter here:
* ``0x00000001`` -- "do not flash"; this block is a no-flash marker.
* ``0x00002000`` -- "family ID present"; ``familyID`` is meaningful.
For the RP2350 the family ID is ``0xe48bff59``, and it is what tells the
boot ROM that this UF2 targets RP2350 hardware rather than, say, an RP2040 or
a Pico W.
See Also:
--------
* ``uf2families.json`` -- the family-name to family-ID table, loaded from the
directory containing this file.
* ``flash.sh`` / ``flash.ps1`` -- program a raw ``.bin`` over SWD instead.
"""
from __future__ import annotations
import argparse
import json
import os
import re
import struct
import subprocess
import sys
from dataclasses import dataclass
from pathlib import Path
from time import sleep
# ---------------------------------------------------------------------------
# UF2 format constants
# ---------------------------------------------------------------------------
#: First magic word, ``"UF2\n"`` read as a little-endian uint32.
UF2_MAGIC_START0 = 0x0A324655
#: Second magic word. The value is arbitrary but must be constant.
UF2_MAGIC_START1 = 0x9E5D5157
#: Trailing magic word closing every 512-byte block.
UF2_MAGIC_END = 0x0AB16F30
#: Size of one UF2 block in bytes.
UF2_BLOCK_SIZE = 512
#: Offset of the 32-byte block header within a block.
UF2_HEADER_SIZE = 32
#: Largest payload a single block may carry (476 = 512 - 32 header - 4 magic).
UF2_MAX_PAYLOAD = UF2_BLOCK_SIZE - UF2_HEADER_SIZE - 4
#: Flag bit marking a block the bootloader must NOT program.
UF2_FLAG_NOFLASH = 0x00000001
#: Flag bit announcing that ``familyID`` carries a meaningful value.
UF2_FLAG_FAMILY_ID = 0x00002000
#: Name of the marker file the boot ROM exposes on its flash-drive volume.
INFO_FILE = "INFO_UF2.TXT"
#: Struct format for the 32-byte UF2 block header.
_HEADER_STRUCT = struct.Struct("<IIIIIIII")
#: The default family ID assumed when the caller does not pass ``--family``.
DEFAULT_FAMILY_ID = 0x0
#: The default base address assumed when the caller does not pass ``--base``.
#: Matches the upstream default; RP2350 firmware always overrides this.
DEFAULT_BASE_ADDRESS = 0x2000
class Uf2Error(Exception):
"""Raised when an input file is malformed or internally inconsistent."""
@dataclass
class ConverterContext:
"""Mutable conversion state shared across a single CLI invocation.
Attributes:
appstartaddr: Base address that payload offsets are relative to. Set
from ``--base``; ``0`` means "derive it from the input".
familyid: Family ID written into every UF2 block. ``0`` means "no
family flag", which is the correct behaviour for a plain BIN->UF2
conversion of RP2040-era images, and the wrong behaviour for
RP2350, which is why the course always passes ``--family``.
"""
appstartaddr: int | None = DEFAULT_BASE_ADDRESS
familyid: int = DEFAULT_FAMILY_ID
# ---------------------------------------------------------------------------
# Format detection
# ---------------------------------------------------------------------------
def is_uf2(buf: bytes) -> bool:
"""Report whether a buffer begins with the UF2 start magic.
Args:
buf: Raw file contents.
Returns:
``True`` if the first two uint32 words are the UF2 start magic.
"""
if len(buf) < 8:
return False
word0, word1 = _HEADER_STRUCT.unpack_from(buf, 0)[:2]
return word0 == UF2_MAGIC_START0 and word1 == UF2_MAGIC_START1
def is_hex(buf: bytes) -> bool:
"""Report whether a buffer looks like an Intel HEX file.
A file qualifies when it decodes as UTF-8, begins with a record marker
``:``, and contains only characters legal in Intel HEX records.
Args:
buf: Raw file contents.
Returns:
``True`` if the buffer should be treated as Intel HEX.
"""
try:
text = buf[:30].decode("utf-8")
except UnicodeDecodeError:
return False
if not text.startswith(":"):
return False
return re.match(rb"^[:0-9a-fA-F\r\n]+$", buf) is not None
# ---------------------------------------------------------------------------
# UF2 -> BIN
# ---------------------------------------------------------------------------
def convert_from_uf2(buf: bytes, ctx: ConverterContext) -> bytes:
"""Decode a UF2 file back into a flat binary image.
Blocks are visited in file order. Gaps between consecutive block addresses
are filled with zero words, and any trailing gap is dropped so that the
result ends at the last byte actually programmed.
A UF2 file may legitimately interleave blocks from several families (this
is how a multicore image ships both cores in one download). When more than
one family is present and the caller did not constrain the family with
``--family``, the conversion is ambiguous, so the payload is emptied and
``appstartaddr`` reset to ``0``.
Args:
buf: Complete UF2 file contents.
ctx: Conversion state; updated in place with the discovered base
address.
Returns:
The decoded payload.
Raises:
Uf2Error: If a block declares an oversized payload, the blocks are out
of order, or the implied padding exceeds 10 MiB.
Note:
The upstream Raspberry Pi version of this function crashes on its own
error paths: it builds the message with ``"..." + ptr`` where ``ptr``
is an ``int``, which raises :class:`TypeError` and masks the real
problem. The messages here use f-strings so the diagnostic survives.
"""
numblocks = len(buf) // UF2_BLOCK_SIZE
curraddr: int | None = None
currfamilyid: int | None = None
families_found: dict[int, int] = {}
prev_flag: int | None = None
all_flags_same = True
outp: list[bytes] = []
for blockno in range(numblocks):
ptr = blockno * UF2_BLOCK_SIZE
block = buf[ptr : ptr + UF2_BLOCK_SIZE]
(
magic0,
magic1,
flags,
target_addr,
datalen,
_blockno,
_numblocks,
block_family,
) = _HEADER_STRUCT.unpack_from(block, 0)
if magic0 != UF2_MAGIC_START0 or magic1 != UF2_MAGIC_START1:
print(f"Skipping block at {ptr:#x}; bad magic")
continue
if flags & UF2_FLAG_NOFLASH:
continue
if datalen > UF2_MAX_PAYLOAD:
msg = f"Invalid UF2 data size at {ptr:#x}: {datalen}"
raise Uf2Error(msg)
if flags & UF2_FLAG_FAMILY_ID and currfamilyid is None:
currfamilyid = block_family
# A new contiguous run starts when the address jumps or the family
# changes. appstartaddr tracks the start of the current run, which is
# what makes the reported start address the image's true base rather
# than the address of its last block.
if curraddr is None or (
flags & UF2_FLAG_FAMILY_ID and block_family != currfamilyid
):
currfamilyid = block_family
curraddr = target_addr
if ctx.familyid == DEFAULT_FAMILY_ID or ctx.familyid == block_family:
ctx.appstartaddr = target_addr
padding = target_addr - curraddr
if padding < 0:
msg = f"Block out of order at {ptr:#x}: {target_addr:#x} < {curraddr:#x}"
raise Uf2Error(msg)
if padding > 10 * 1024 * 1024:
msg = f"More than 10M of padding needed at {ptr:#x}"
raise Uf2Error(msg)
if padding % 4 != 0:
msg = f"Non-word padding size at {ptr:#x}: {padding}"
raise Uf2Error(msg)
while padding > 0:
padding -= 4
outp.append(b"\x00\x00\x00\x00")
if ctx.familyid == DEFAULT_FAMILY_ID or (
flags & UF2_FLAG_FAMILY_ID and ctx.familyid == block_family
):
outp.append(
block[UF2_HEADER_SIZE : UF2_HEADER_SIZE + datalen],
)
curraddr = target_addr + datalen
if flags & UF2_FLAG_FAMILY_ID:
existing = families_found.get(block_family)
if existing is None or existing > target_addr:
families_found[block_family] = target_addr
if prev_flag is None:
prev_flag = flags
elif prev_flag != flags:
all_flags_same = False
if blockno == numblocks - 1:
_print_uf2_header_info(families_found, all_flags_same, flags)
if len(families_found) > 1 and ctx.familyid == DEFAULT_FAMILY_ID:
outp = []
ctx.appstartaddr = 0x0
return b"".join(outp)
def _print_uf2_header_info(
families_found: dict[int, int],
all_flags_same: bool,
flags: int,
) -> None:
"""Print the family summary block that follows a UF2->BIN conversion.
Args:
families_found: Mapping of family ID to the lowest target address seen
for that family.
all_flags_same: Whether every block carried an identical flag word.
flags: The flag word from the final block, used for display.
"""
print("--- UF2 File Header Info ---")
families = load_families()
name_by_id = {value: key for key, value in families.items()}
for family_hex, address in families_found.items():
short_name = name_by_id.get(family_hex, "")
print(f"Family ID is {short_name}, hex value is {family_hex:#010x}")
print(f"Target Address is {address:#010x}")
if all_flags_same:
print(f"All block flag values consistent, {flags:#06x}")
else:
print("Flags were not all the same")
print("----------------------------")
# ---------------------------------------------------------------------------
# BIN -> UF2
# ---------------------------------------------------------------------------
def convert_to_uf2(file_content: bytes, ctx: ConverterContext) -> bytes:
"""Wrap a raw binary in UF2 blocks.
The binary is split into 256-byte payloads; the final block is zero-padded.
Each block's ``targetAddr`` is the byte offset within the image plus
:attr:`ConverterContext.appstartaddr`, so for RP2350 firmware built at
``0x10000000`` the caller passes ``--base 0x10000000``.
Args:
file_content: The raw image.
ctx: Conversion state supplying the base address and family ID.
Returns:
The UF2 file contents, always a whole number of 512-byte blocks.
"""
datapadding = bytes(UF2_BLOCK_SIZE - 256 - UF2_HEADER_SIZE - 4)
numblocks = (len(file_content) + 255) // 256
flags = UF2_FLAG_FAMILY_ID if ctx.familyid else 0x0
base = ctx.appstartaddr or 0
blocks: list[bytes] = []
for blockno in range(numblocks):
ptr = 256 * blockno
chunk = file_content[ptr : ptr + 256]
header = _HEADER_STRUCT.pack(
UF2_MAGIC_START0,
UF2_MAGIC_START1,
flags,
ptr + base,
256,
blockno,
numblocks,
ctx.familyid,
)
payload = chunk + bytes(256 - len(chunk))
block = header + payload + datapadding + struct.pack("<I", UF2_MAGIC_END)
blocks.append(block)
return b"".join(blocks)
def convert_to_carray(file_content: bytes) -> bytes:
"""Render a binary as a C array initialiser for embedding in firmware.
Args:
file_content: The raw image.
Returns:
UTF-8 bytes of a C translation unit fragment.
"""
parts = [
f"const unsigned long bindata_len = {len(file_content)};\n",
"const unsigned char bindata[] __attribute__((aligned(16))) = {",
]
for index, value in enumerate(file_content):
if index % 16 == 0:
parts.append("\n")
parts.append(f"{value:#04x}, ")
parts.append("\n};\n")
return "".join(parts).encode()
# ---------------------------------------------------------------------------
# Intel HEX -> UF2
# ---------------------------------------------------------------------------
@dataclass
class Block:
"""A single 256-byte-aligned region of an image under construction.
Attributes:
addr: Base address of the block, always 256-byte aligned.
data: The block's bytes, initialised to ``default_data``.
"""
addr: int
data: bytearray
def __init__(self, addr: int, default_data: int = 0xFF) -> None:
"""Initialise an erased 256-byte block.
Args:
addr: 256-byte-aligned base address of the block.
default_data: Fill byte; ``0xFF`` matches erased flash.
"""
self.addr = addr
self.data = bytearray([default_data] * 256)
def encode(self, blockno: int, numblocks: int, ctx: ConverterContext) -> bytes:
"""Serialise this block into a 512-byte UF2 block.
Args:
blockno: Index of this block within the file.
numblocks: Total number of blocks in the file.
ctx: Conversion state supplying the family ID.
Returns:
Exactly 512 bytes.
"""
flags = UF2_FLAG_FAMILY_ID if ctx.familyid else 0x0
out = _HEADER_STRUCT.pack(
UF2_MAGIC_START0,
UF2_MAGIC_START1,
flags,
self.addr,
256,
blockno,
numblocks,
ctx.familyid,
)
out += self.data[0:256]
out += bytes(UF2_BLOCK_SIZE - 4 - len(out))
out += struct.pack("<I", UF2_MAGIC_END)
return out
def convert_from_hex_to_uf2(text: str, ctx: ConverterContext) -> bytes:
"""Assemble Intel HEX records into a UF2 file.
Only record types 0x00 (data), 0x01 (EOF), 0x02 (extended segment address)
and 0x04 (extended linear address) are handled; any other type is ignored,
matching the upstream behaviour.
Args:
text: Decoded Intel HEX file contents.
ctx: Conversion state; ``appstartaddr`` is set to the first data
address seen.
Returns:
The UF2 file contents.
"""
ctx.appstartaddr = None
upper = 0
currblock: Block | None = None
blocks: list[Block] = []
for line in text.split("\n"):
if not line.startswith(":"):
continue
record = [int(line[i : i + 2], 16) for i in range(1, len(line) - 1, 2)]
rec_type = record[3]
if rec_type == 4:
upper = ((record[4] << 8) | record[5]) << 16
elif rec_type == 2:
upper = ((record[4] << 8) | record[5]) << 4
elif rec_type == 1:
break
elif rec_type == 0:
addr = upper + ((record[1] << 8) | record[2])
if ctx.appstartaddr is None:
ctx.appstartaddr = addr
index = 4
while index < len(record) - 1:
if currblock is None or currblock.addr & ~0xFF != addr & ~0xFF:
currblock = Block(addr & ~0xFF)
blocks.append(currblock)
currblock.data[addr & 0xFF] = record[index]
addr += 1
index += 1
numblocks = len(blocks)
return b"".join(blocks[i].encode(i, numblocks, ctx) for i in range(numblocks))
# ---------------------------------------------------------------------------
# Drive discovery
# ---------------------------------------------------------------------------
def _iter_candidate_dirs() -> list[Path]:
"""Return the directories that may contain mounted removable volumes."""
if sys.platform == "win32":
return []
searchpaths = [Path("/mnt"), Path("/media")]
if sys.platform == "darwin":
searchpaths = [Path("/Volumes")]
elif sys.platform == "linux":
user = environ_user()
if user:
searchpaths += [Path("/media") / user, Path("/run/media") / user]
sudo_user = os.environ.get("SUDO_USER")
if sudo_user:
searchpaths += [
Path("/media") / sudo_user,
Path("/run/media") / sudo_user,
]
return searchpaths
def environ_user() -> str | None:
"""Return the current user name from the environment.
Tried under several variable names so the search works on macOS, Linux and
Windows shells alike.
Returns:
The user name, or ``None`` if it cannot be determined.
"""
for var in ("USER", "USERNAME", "LOGNAME"):
value = os.environ.get(var)
if value:
return value
return None
def get_drives() -> list[Path]:
"""Find mounted Pico boot drives.
A drive qualifies when it contains the ``INFO_UF2.TXT`` marker the boot ROM
writes when it presents the flash as a USB mass-storage device.
Returns:
Every qualifying mount point.
"""
drives: list[Path] = []
if sys.platform == "win32":
command = (
"(Get-Volume | Where-Object { $_.FileSystemLabel -match 'RP2350|RPI-RP2' })"
".DriveLetter"
)
try:
raw = subprocess.check_output(
["powershell", "-Command", command],
text=True,
)
except (subprocess.CalledProcessError, FileNotFoundError, OSError):
return []
for letter in raw.split():
if len(letter) == 1 and letter.isalpha():
drives.append(Path(f"{letter.upper()}:\\"))
return drives
for rootpath in _iter_candidate_dirs():
if not rootpath.is_dir():
continue
try:
entries = list(rootpath.iterdir())
except OSError:
continue
for entry in entries:
if not entry.is_dir():
continue
if (entry / INFO_FILE).is_file():
drives.append(entry)
return drives
def board_id(path: Path) -> str:
"""Read the ``Board-ID`` field from a boot drive's info file.
Args:
path: Mount point of the boot drive.
Returns:
The board ID string, for example ``RP2350``.
Raises:
Uf2Error: If the info file is missing or has no ``Board-ID`` field.
"""
info = path / INFO_FILE
if not info.is_file():
msg = f"Not a Pico boot drive: {path} has no {INFO_FILE}"
raise Uf2Error(msg)
match = re.search(r"Board-ID: ([^\r\n]*)", info.read_text())
if match is None:
msg = f"No Board-ID field in {info}"
raise Uf2Error(msg)
return match.group(1)
def list_drives() -> None:
"""Print every connected Pico boot drive and its board ID."""
for drive in get_drives():
try:
print(drive, board_id(drive))
except Uf2Error as exc:
print(f"{drive} <unreadable: {exc}>")
def write_file(name: Path | str, buf: bytes) -> None:
"""Write a buffer to disk and report the size written.
Args:
name: Destination path.
buf: Bytes to write.
"""
path = Path(name)
path.parent.mkdir(parents=True, exist_ok=True)
path.write_bytes(buf)
print(f"Wrote {len(buf)} bytes to {path}")
def load_families() -> dict[str, int]:
"""Load the family-name to family-ID table.
``uf2families.json`` is read from the directory containing this script, so
the converter works regardless of the caller's working directory.
Returns:
Mapping of upper-case short name to family ID.
Raises:
Uf2Error: If the JSON file is missing or malformed.
"""
pathname = Path(__file__).resolve().parent / "uf2families.json"
try:
raw_families = json.loads(pathname.read_text())
except FileNotFoundError as exc:
msg = f"Required family table not found: {pathname}"
raise Uf2Error(msg) from exc
except json.JSONDecodeError as exc:
msg = f"Malformed family table {pathname}: {exc}"
raise Uf2Error(msg) from exc
return {fam["short_name"]: int(fam["id"], 0) for fam in raw_families}
# ---------------------------------------------------------------------------
# CLI
# ---------------------------------------------------------------------------
def _build_parser() -> argparse.ArgumentParser:
"""Construct the command-line argument parser.
Returns:
A configured :class:`argparse.ArgumentParser`.
"""
parser = argparse.ArgumentParser(
prog="uf2conv.py",
description="Convert firmware between Intel HEX, raw BIN and UF2.",
epilog=(
"Course example (RP2350 raw image built for XIP flash):\n"
" python ../uf2conv.py build/image-h.bin "
"--base 0x10000000 \\\n"
" --family 0xe48bff59 --output build/hacked.uf2\n"
),
formatter_class=argparse.RawDescriptionHelpFormatter,
)
parser.add_argument(
"input",
metavar="INPUT",
nargs="?",
help="input file (HEX, BIN or UF2); omit when using --list",
)
parser.add_argument(
"-b",
"--base",
default=hex(DEFAULT_BASE_ADDRESS),
help=(
"base address of the application for BIN input "
f"(default: {hex(DEFAULT_BASE_ADDRESS)}; use 0x10000000 for RP2350 XIP)"
),
)
parser.add_argument(
"-f",
"--family",
default=hex(DEFAULT_FAMILY_ID),
help=(
"family ID as a number or a name from uf2families.json "
f"(default: {hex(DEFAULT_FAMILY_ID)}; RP2350 is 0xe48bff59)"
),
)
parser.add_argument(
"-o",
"--output",
metavar="FILE",
help='write output to FILE; defaults to "flash.uf2" or "flash.bin"',
)
parser.add_argument(
"-d",
"--device",
dest="device_path",
help="select a specific device path to flash (reserved; unused)",
)
parser.add_argument(
"-l",
"--list",
action="store_true",
help="list connected Pico boot drives and exit",
)
parser.add_argument(
"-c",
"--convert",
action="store_true",
help="convert only; do not deploy to a mounted boot drive",
)
parser.add_argument(
"-D",
"--deploy",
action="store_true",
help="deploy the input file unchanged; do not convert",
)
parser.add_argument(
"-w",
"--wait",
action="store_true",
help="poll for a boot drive to appear instead of failing immediately",
)
parser.add_argument(
"-C",
"--carray",
action="store_true",
help="emit a C array initialiser instead of a UF2 file",
)
parser.add_argument(
"-i",
"--info",
action="store_true",
help="print UF2 header information and exit without converting",
)
return parser
def _resolve_family(spec: str) -> int:
"""Resolve a ``--family`` value to a numeric family ID.
Args:
spec: Either a family short name (case-insensitive) or an integer
literal such as ``0xe48bff59``.
Returns:
The numeric family ID.
Raises:
Uf2Error: If the value is neither a known name nor a valid integer.
"""
families = load_families()
if spec.upper() in families:
return families[spec.upper()]
try:
return int(spec, 0)
except ValueError as exc:
msg = "Family ID needs to be a number or one of: " + ", ".join(families)
raise Uf2Error(msg) from exc
def _wait_for_drive() -> Path | None:
"""Poll for a boot drive to be mounted.
Returns:
The first drive found, or ``None`` if the wait was interrupted.
"""
print("Waiting for drive to deploy...")
while True:
drives = get_drives()
if drives:
return drives[0]
sleep(0.1)
def main(argv: list[str] | None = None) -> int:
"""Run the command-line converter.
Args:
argv: Argument list, defaulting to :data:`sys.argv` ``[1:]``.
Returns:
``0`` on success, ``1`` on a user or input error.
"""
parser = _build_parser()
args = parser.parse_args(argv)
ctx = ConverterContext()
try:
ctx.familyid = _resolve_family(args.family)
ctx.appstartaddr = int(args.base, 0)
except (Uf2Error, ValueError) as exc:
print(exc, file=sys.stderr)
return 1
if args.list:
list_drives()
return 0
if not args.input:
print("Need an input file (or use --list)", file=sys.stderr)
return 1
source = Path(args.input)
if not source.is_file():
print(f"error: file not found: {source}", file=sys.stderr)
return 1
inpbuf = source.read_bytes()
from_uf2 = is_uf2(inpbuf)
ext = "uf2"
try:
if args.deploy:
outbuf = inpbuf
elif from_uf2 and not args.info:
outbuf = convert_from_uf2(inpbuf, ctx)
ext = "bin"
elif from_uf2 and args.info:
outbuf = b""
convert_from_uf2(inpbuf, ctx)
elif is_hex(inpbuf):
outbuf = convert_from_hex_to_uf2(inpbuf.decode("utf-8"), ctx)
elif args.carray:
outbuf = convert_to_carray(inpbuf)
ext = "h"
else:
outbuf = convert_to_uf2(inpbuf, ctx)
except Uf2Error as exc:
print(f"error: {exc}", file=sys.stderr)
return 1
if not args.deploy and not args.info:
print(
f"Converted to {ext}, output size: {len(outbuf)}, "
f"start address: {ctx.appstartaddr or 0:#x}",
)
if (args.convert or ext != "uf2") and args.output is None:
args.output = f"flash.{ext}"
if args.output:
write_file(args.output, outbuf)
if ext == "uf2" and not args.convert and not args.info:
drives = get_drives()
if not drives:
if args.wait:
found = _wait_for_drive()
drives = [found] if found else []
elif not args.output:
print("error: no drive to deploy", file=sys.stderr)
return 1
for drive in drives:
print(f"Flashing {drive} ({board_id(drive)})")
write_file(drive / "NEW.UF2", outbuf)
return 0
if __name__ == "__main__":
sys.exit(main())