How to flash .UF2 devices on an unattended Linux machine (CI)

[Josverl]

In order to get automatic runs on preview builds in , I created a few scripts to be used in the CI workflow (Actions) on a local runner with some boards attached.

1. ID board
2. Download recent preview image
3. Flash firmware to the board
4. start the rest of the tests / processing

This works for esp* and for (some) of the stm32 boards , but for the .uf2 ports (samd / rp2) i cant get this to work yet. If possibly id like to avoid needing to depend on tools such as picotool - Also I'm not sure if there is an equivalent samdtool

On windows this is rather trivial , but the same approach does not work (well) on Linux , at least not without a human keeping the desktop unlocked 24/7.

Flash .UF2 devices via bootloader and filecopy (windows)
- mpremote bootloader
- Wait for the device to mount as a drive (up to 5s)
- detect new drive with INFO_UF2.TXT
- copy the firmware file to the drive
- wait for the device to restart (5s)

On Ubuntu 22.04 the 'flash drive' is not auto-mounted unless the desktop is unlocked.
there is a workaround to manually mount via pmount, that appears to work , just not sure how robust that is over time.

I hope someone has already solved this problem, and can share the solution / approach.

[xyzzy42]

Use udiskctl. This lets you query, mount, and detect storage devices from user accounts. I used this api to handle automatic detection and mounting of USB devices in embedded Linux products that have no "desktop".

[ned-pcs]

The UF2 partitions should appear under /dev/disk/by-id like: /dev/disk/by-id/usb-RPI_RP2_E0C9125B0D9B-0:0-part1.
You can use udisksctl to get associated information:

% udisksctl info -b /dev/disk/by-id/usb-RPI_RP2_E0C9125B0D9B-0:0-part1
/org/freedesktop/UDisks2/block_devices/sda1:
  org.freedesktop.UDisks2.Block:
    Configuration:              []
    CryptoBackingDevice:        '/'
    Device:                     /dev/sda1
    DeviceNumber:               2049
    Drive:                      '/org/freedesktop/UDisks2/drives/RPI_RP2_E0C9125B0D9B'
    HintAuto:                   true
    HintIconName:               
    HintIgnore:                 false
    HintName:                   
    HintPartitionable:          true
    HintSymbolicIconName:       
    HintSystem:                 false
    Id:                         by-uuid-000A-A023
    IdLabel:                    RPI-RP2
    IdType:                     vfat
    IdUUID:                     000A-A023
    IdUsage:                    filesystem
    IdVersion:                  FAT16
    MDRaid:                     '/'
    MDRaidMember:               '/'
    PreferredDevice:            /dev/sda1
    ReadOnly:                   false
    Size:                       134217216
    Symlinks:                   /dev/disk/by-id/usb-RPI_RP2_E0C9125B0D9B-0:0-part1
                                /dev/disk/by-label/RPI-RP2
                                /dev/disk/by-partuuid/000aa023-01
                                /dev/disk/by-path/pci-0000:00:14.0-usb-0:3.2:1.0-scsi-0:0:0:0-part1
                                /dev/disk/by-uuid/000A-A023
    UserspaceMountOptions:      
  org.freedesktop.UDisks2.Filesystem:
    MountPoints:        
    Size:               0
  org.freedesktop.UDisks2.Partition:
    Flags:              0
    IsContained:        false
    IsContainer:        false
    Name:               
    Number:             1
    Offset:             512
    Size:               134217216
    Table:              '/org/freedesktop/UDisks2/block_devices/sda'
    Type:               0x0e
    UUID:               000aa023-01

and you can also mount it:

udisksctl mount --no-user-interaction -b /dev/disk/by-id/usb-RPI_RP2_E0C9125B0D9B-0:0-part1 
Mounted /dev/sda1 at /media/ned/RPI-RP2

[xyzzy42]

/dev/disk/by-label/RPI-RP2 looks like a good way to find a RP2 filesystem vs all the other storage devices that might get connected. Better, IMHO, that waiting for any device to show up with an unknown drive letter and then needing to poke around in the files it might have to guess what device it is.

[ned-pcs]

Yes, but if you have more than one RP2 devices in bootloader mode you'd probably want to use the /dev/disk/by-id/usb-RPI_RP2_*-part1 instead.

[Josverl]

looking in /dev/disk/by-id looks promising:
State : One RP2040 and one SAMD51 in bootloader

lrwxrwxrwx 1 root root 10 feb 18 14:57 ata-KINGSTON_SA400S37240G_50026B77832FE821-part4 -> ../../sda4
lrwxrwxrwx 1 root root  9 feb 21 12:49 usb-RPI_RP2_E0C9125B0D9B-0:0 -> ../../sdb
lrwxrwxrwx 1 root root 10 feb 21 12:49 usb-RPI_RP2_E0C9125B0D9B-0:0-part1 -> ../../sdb1
lrwxrwxrwx 1 root root  9 feb 20 16:59 usb-Wio_Term_inal_7A674ABB5336464E4E202020FF130722-0:0 -> ../../sdc
lrwxrwxrwx 1 root root  9 feb 18 14:57 wwn-0x50026b77832fe821 -> ../../sda
lrwxrwxrwx 1 root root 10 feb 18 14:57 wwn-0x50026b77832fe821-part1 -> ../../sda1

Please note that while both devices show up, that they are exposed / expose themselves differently :

• rp2: disk + partition - fat16
• samd15 : disk
  so some additional processing is needed

`$ udisksctl info -b /dev/disk/by-id/usb-Wio_Term_inal_7A674ABB5336464E4E202020FF130722-0:0`

/org/freedesktop/UDisks2/block_devices/sdc:
  org.freedesktop.UDisks2.Block:
    Configuration:              []
    CryptoBackingDevice:        '/'
    Device:                     /dev/sdc
    DeviceNumber:               2080
    Drive:                      '/org/freedesktop/UDisks2/drives/Wio_Term_inal_7A674ABB5336464E4E202020FF130722'
    HintAuto:                   true
    HintIconName:               
    HintIgnore:                 false
    HintName:                   
    HintPartitionable:          true
    HintSymbolicIconName:       
    HintSystem:                 false
    Id:                         by-uuid-0042-0042
    IdLabel:                    Arduino
    IdType:                     vfat
    IdUUID:                     0042-0042
    IdUsage:                    filesystem
    IdVersion:                  FAT16
    MDRaid:                     '/'
    MDRaidMember:               '/'
    PreferredDevice:            /dev/sdc
    ReadOnly:                   false
    Size:                       8192000
    Symlinks:                   /dev/disk/by-id/usb-Wio_Term_inal_7A674ABB5336464E4E202020FF130722-0:0
                                /dev/disk/by-label/Arduino
                                /dev/disk/by-path/pci-0000:00:14.0-usb-0:2:1.2-scsi-0:0:0:0
                                /dev/disk/by-uuid/0042-0042
    UserspaceMountOptions:      
  org.freedesktop.UDisks2.Filesystem:
    MountPoints:        
    Size:               0

So to find the filesystems with FAT16 (somewhat of an assumption for now)

$ lsblk --list --fs  | grep FAT16
sdb1   vfat     FAT16 RPI-RP2                                                     
sdc    vfat     FAT16 Arduino 0042-0042  

or in python

from blkinfo import BlkDiskInfo
myblkd = BlkDiskInfo()
filters = {
   'tran': 'usb',
}
blkinfo = myblkd.get_disks(filters)

for bi in blkinfo:
    if bi["fstype"] == "vfat":
        # unpartioned usb disk or partition (e.g. /dev/sdb )
        # SEEED WIO Terminal is unpartioned
        name = bi["name"]
    elif bi["type"] == "disk":
        if bi.get("children")[0]["type"] == "part":
            name = bi.get("children")[0]["name"]

    print(name)

gets me :
sdb1 and sdc

... waiting for any device to show up with an unknown drive letter and then needing to poke around in the files it might have to guess what device it is.

Opinions respected, but that is not guessing; its part of the UF2 specification. (It is also not any different than waiting for a device to show up in /dev/disk )

• https://github.com/microsoft/uf2?tab=readme-ov-file#files-exposed-by-bootloaders

Read https://makecode.com/blog/one-chip-to-flash-them-all for some more background.
so after finding a filesystem and mounting it,
then the last check is to see if INFO_UF2.TXT indeed exists. ( and bail-out / dismount if it does not )