Sparkfun Thing Plus SAMD51 needs newer bossac for uploading to work

[smarpug]

Initially, I was going to post this issue as a question, but I will be creating a pull request for this instead, since I think I have discovered a solution. I want to post this as an issue, though, so I can explain the change more fully.

Problem:

The problem is that I could not get sketches to upload to my Sparkfun Thing Plus SAMD51 in PlatformIO (PlatformIO IDE v2.2.1, VSCode v1.52.1, Arduino for VSCode v0.3.4, run on Windows Version 10.0.19041 Build 19041). I used the Blink.ino example. The board would reset, but nothing would seem to upload after that, and the board would not even show back up on the Device Manager. When I used the Arduino for VS Code without PlatformIO IDE, or the Arduino IDE, both successfully upload to the Thing Plus (although only after putting the device in bootloader mode... a problem for another day, I just need to be able to upload in PlatformIO).

Analyzing the build and upload output, I found that the Arduino IDE is using a command line parameter "--offset=0x4000" when calling the bossac uploader, while the PlatformIO output does not:

Output excerpt from PlatformIO

Building .pio\build\sparkfun_samd51_thing_plus\firmware.bin
Checking size .pio\build\sparkfun_samd51_thing_plus\firmware.elf
Advanced Memory Usage is available via "PlatformIO Home > Project Inspect"
RAM:   [          ]   1.1% (used 2228 bytes from 196608 bytes)
Flash: [          ]   2.1% (used 10756 bytes from 507904 bytes)
Configuring upload protocol...
AVAILABLE: atmel-ice, jlink, sam-ba
CURRENT: upload_protocol = sam-ba
Looking for upload port...
Auto-detected: COM15
Forcing reset using 1200bps open/close on port COM15
Waiting for the new upload port...
Port: COM6
Port: COM6
Port: COM15
Found new port: COM15
Uploading bossac --port "COM15" --write --verify --reset -i -d --erase -U true .pio\build\sparkfun_samd51_thing_plus\firmware.bin

Output excerpt from Arduino IDE

Sketch uses 10776 bytes (2%) of program storage space. Maximum is 507904 bytes.
Forcing reset using 1200bps open/close on port COM14
PORTS {COM6, COM14, } / {COM6, COM14, } => {}
PORTS {COM6, COM14, } / {COM6, COM14, } => {}
PORTS {COM6, COM14, } / {COM6, COM14, } => {}
PORTS {COM6, COM14, } / {COM6, COM14, } => {}
PORTS {COM6, COM14, } / {COM6, COM14, } => {}
PORTS {COM6, COM14, } / {COM6, COM14, } => {}
PORTS {COM6, COM14, } / {COM6, COM14, } => {}
PORTS {COM6, COM14, } / {COM6, COM14, } => {}
PORTS {COM6, COM14, } / {COM6, COM14, } => {}
PORTS {COM6, COM14, } / {COM6, COM14, } => {}
PORTS {COM6, COM14, } / {COM6, COM14, } => {}
PORTS {COM6, COM14, } / {COM6, COM14, } => {}
PORTS {COM6, COM14, } / {COM6, COM14, } => {}
PORTS {COM6, COM14, } / {COM6, COM14, } => {}
PORTS {COM6, COM14, } / {COM6, COM14, } => {}
PORTS {COM6, COM14, } / {COM6, COM14, } => {}
PORTS {COM6, COM14, } / {COM6, COM14, } => {}
PORTS {COM6, COM14, } / {COM6, COM14, } => {}
PORTS {COM6, COM14, } / {COM6, COM14, } => {}
PORTS {COM6, COM14, } / {COM6, COM14, } => {}
Uploading using selected port: COM14
C:\Users\jb_user\AppData\Local\Arduino15\packages\arduino\tools\bossac\1.8.0-48-gb176eee/bossac -i -d --port=COM14 -U -i --offset=0x4000 -w -v C:\Users\jb_user\AppData\Local\Temp\arduino_build_512716/Blink.ino.bin -R 

Solution

I found that simply adding the command-line parameter to the bossac call did not work, since it just gave me this error:

Uploading bossac --port "COM14" --write --verify --reset -i -d -U --offset 0x4000 .pio\build\sparkfun_samd51_thing_plus\firmware.bin
bossac: extra arguments found
Try 'bossac -h' or 'bossac --help' for more information
*** [upload] Error 1

Digging deeper, I found that PlatformIO uses a newer bossac version for most SAMD51 boards, and that the older bossac version does not support the "--offset" parameter. The newer version of bossac is set to be used only for Adafruit and Seeed Studio SAMD51 boards in platform.py lines 82-85:

        if (board.get("build.core", "") in ("adafruit", "seeed")
                and "tool-bossac" in self.packages
                and board.get("build.mcu", "").startswith("samd51")):
            self.packages["tool-bossac"]['version'] = "~1.10900.0"

The offset values to be used are likewise added in builder/main.py (lines 219-231)

    if board.get("build.core") in ("adafruit", "seeed") and board.get(
            "build.mcu").startswith("samd51"):
        # special flags for the latest bossac tool
        env.Append(
            UPLOADERFLAGS=[
            "-U", "--offset", board.get("upload.offset_address")])

    else:
        env.Append(UPLOADERFLAGS=[
            "--erase",
            "-U", "true"
            if env.BoardConfig().get("upload.native_usb", False) else "false"
        ])

What is missing is adding Sparkfun branded boards along with Adafruit and Seeed. The corrected snippets: (platform.py lines 82-85)

        if (board.get("build.core", "") in ("adafruit", "seeed", "sparkfun")
                and "tool-bossac" in self.packages
                and board.get("build.mcu", "").startswith("samd51")):
            self.packages["tool-bossac"]['version'] = "~1.10900.0"

(builder/main.py lines 219-231)

    if board.get("build.core") in ("adafruit", "seeed", "sparkfun") and board.get(
            "build.mcu").startswith("samd51"):
        # special flags for the latest bossac tool
        env.Append(
            UPLOADERFLAGS=[
            "-U", "--offset", board.get("upload.offset_address")])

    else:
        env.Append(UPLOADERFLAGS=[
            "--erase",
            "-U", "true"
            if env.BoardConfig().get("upload.native_usb", False) else "false"
        ])