ikluft/piflash

Write ("flash") a Raspberry Pi boot image to an SD card, with features for power users (auto-unwrap archive files) or newbies (safety checks to avoid erasing wrong device)

Name

piflash - Raspberry Pi SD-flashing script with safety checks to avoid erasing the wrong device

Synopsis

piflash [--verbose] [--resize] [--config conf-file] input-file output-device

piflash [--verbose] --sdsearch

piflash --version

Featured article

"Getting started with PiFlash: Booting your Raspberry Pi on Linux"
by Ian Kluft at OpenSource.com
March 15, 2019

Description

PiFlash writes (or "flashes") an SD card for a Raspberry Pi. It includes safety checks so that it can only erase and write to an SD card, not another device on the system. The safety checks are probably of most use to beginners. For more advanced users (like the author) it also has the convenience of flashing directly from the file formats downloadable from raspberrypi.org without extracting a .img file from a zip/gz/xz file.

User documentation

• PiFlash program usage and installation
• Online resources for PiFlash
  • Where to download Raspberry Pi bootable images
  • Presentations and Articles
• PiFlash release on CPAN
• PiFlash source code on GitHub

PiFlash documentation is available as Unix man-pages and as Perl POD (Plain Old Documentation). Once installed, you can run man or perldoc from a shell to read the documentation:

% man piflash

or

% perldoc piflash

Developer documentation

• PiFlash - Raspberry Pi SD-flashing script with safety checks to avoid erasing the wrong device
• PiFlash::Command - process/command running utilities for piflash
• PiFlash::Hook - named dispatch/hook library for PiFlash
• PiFlash::Inspector - PiFlash functions to inspect Linux system devices to flash an SD card for Raspberry Pi
• PiFlash::MediaWriter - write to Raspberry Pi SD card installation with scriptable customization
• PiFlash::Object - object functions for PiFlash classes
• PiFlash::Plugin - plugin extension interface for PiFlash
• PiFlash::State - PiFlash::State class to store configuration, device info and program state

Participation in PiFlash

See the Contributing to PiFlash docs.

• Code of Conduct
• Submitting an issue
• Submitting a Pull Request

When reporting a bug, please include the full output using the --verbose option. That will include all of the program's state information, which will help understand the bigger picture what was happening on your system. Feel free to remove information you don't want to post in a publicly-visible bug report - though it's helpful to add "[redacted]" where you removed something so it's clear what happened.

For any SD card reader hardware which piflash fails to recognize (and therefore refuses to write to), please describe the hardware as best you can including name, product number, bus (USB, PCI, etc), any known controller chips.

piflash's Issues

Feature request: Fetch images automatically

I'm the author of RPi::WiringPi, WiringPi::API amongst others, and am wondering if you'd be interested in hacking into your distribution the ability to grab the "latest" version of the images from the Raspberry Pi download site automatically.

You've named this distribution "Pi" related, so it makes sense to keep it in that scope.

This isn't a 'bug' or an 'issue' per-se, it's a request to understand if the above fits your roadmap or not. If so, could you provide guidance as to how that could/might be built-in?

.img or .img.xz files

Thanks Ian for those whose Linux machine somehow won't install the Etcher version. So Piflash installed fine, but when given a burn command with an .img or .img.xz file it just offers advice about usage. Format used by FreedomBox project.

blkid fails to get fs type

I installed PiFlash v.0.4.3 via cpan inside my home folder on my Ubuntu 18.04 system. When I try to flash an zipped image to a blank SD Card, blkid fails to get the fs type, like that:

$ piflash ./2019-09-26-raspbian-buster-lite.zip /dev/sdg
requested to flash ./2019-09-26-raspbian-buster-lite.zip to /dev/sdg
output device /dev/sdg will be erased
input file is a Zip archive data, at least v2.0 to extract
error: use blkid to get fs type for /dev/sdg command exited with value 2 at /home/[redacted]/perl5/lib/perl5/PiFlash/Command.pm line 193.

What did I get wrong? As far as I debugged it myself, the problem might be the following command:

$ /usr/bin/sudo /sbin/blkid --probe --output=value --match-tag=TYPE /dev/sdg; echo $?
2

I don't know, what the return code 2 means. However, below is my verbose output:

fork_exec running: unzip - list contents /usr/bin/unzip -l 2019-09-26-raspbian-buster-lite.zip
PiFlash::Hook dispatch: no such hook cli_options - ignored
requested to flash 2019-09-26-raspbian-buster-lite.zip to /dev/sdg
output device /dev/sdg will be erased
input file is a Zip archive data, at least v2.0 to extract
fork_exec running: lsblk lookup of MOUNTPOINT /bin/lsblk --bytes --nodeps --noheadings --output MOUNTPOINT /dev/sdg
fork_exec running: lsblk lookup of FSTYPE /bin/lsblk --bytes --nodeps --noheadings --output FSTYPE /dev/sdg
fork_exec running: lsblk lookup of SIZE /bin/lsblk --bytes --nodeps --noheadings --output SIZE /dev/sdg
fork_exec running: lsblk lookup of SUBSYSTEMS /bin/lsblk --bytes --nodeps --noheadings --output SUBSYSTEMS /dev/sdg
fork_exec running: lsblk lookup of TYPE /bin/lsblk --bytes --nodeps --noheadings --output TYPE /dev/sdg
fork_exec running: lsblk lookup of MODEL /bin/lsblk --bytes --nodeps --noheadings --output MODEL /dev/sdg
fork_exec running: lsblk lookup of RO /bin/lsblk --bytes --nodeps --noheadings --output RO /dev/sdg
fork_exec running: lsblk lookup of RM /bin/lsblk --bytes --nodeps --noheadings --output RM /dev/sdg
fork_exec running: lsblk lookup of HOTPLUG /bin/lsblk --bytes --nodeps --noheadings --output HOTPLUG /dev/sdg
fork_exec running: lsblk lookup of PHY-SEC /bin/lsblk --bytes --nodeps --noheadings --output PHY-SEC /dev/sdg
fork_exec running: use lsblk to get fs type for /dev/sdg /usr/bin/sudo /bin/lsblk --nodeps --noheadings --output FSTYPE /dev/sdg
fork_exec running: use blkid to get fs type for /dev/sdg /usr/bin/sudo /sbin/blkid --probe --output=value --match-tag=TYPE /dev/sdg
error: use blkid to get fs type for /dev/sdg command exited with value 2
Program state dump...
cli_opt:
    verbose: 1
config:
hook:
input:
    imgfile: 2019-09-26-raspbian-buster-lite.img
    info:
        description: Zip archive data, at least v2.0 to extract
        encoding: binary
        mime_type: application/zip
        mime_with_encoding: application/zip; charset=binary
    parse:
        name: 2019-09-26-raspbian-buster-lite
        path: ./
        suffix: .zip
    path: 2019-09-26-raspbian-buster-lite.zip
    size: 2248146944
    type: zip
log:
    cmd:
            cmdline:
                /usr/bin/unzip
                -l
                2019-09-26-raspbian-buster-lite.zip
            cmdname: unzip - list contents
            err: undef
            out: Archive:  2019-09-26-raspbian-buster-lite.zip
  Length      Date    Time    Name
---------  ---------- -----   ----
2248146944  2019-09-26 02:24   2019-09-26-raspbian-buster-lite.img
---------                     -------
2248146944                     1 file

            returncode: 0
            cmdline:
                /bin/lsblk
                --bytes
                --nodeps
                --noheadings
                --output
                MOUNTPOINT
                /dev/sdg
            cmdname: lsblk lookup of MOUNTPOINT
            err: undef
            out: 

            returncode: 0
            cmdline:
                /bin/lsblk
                --bytes
                --nodeps
                --noheadings
                --output
                FSTYPE
                /dev/sdg
            cmdname: lsblk lookup of FSTYPE
            err: undef
            out: 

            returncode: 0
            cmdline:
                /bin/lsblk
                --bytes
                --nodeps
                --noheadings
                --output
                SIZE
                /dev/sdg
            cmdname: lsblk lookup of SIZE
            err: undef
            out: 3965190144

            returncode: 0
            cmdline:
                /bin/lsblk
                --bytes
                --nodeps
                --noheadings
                --output
                SUBSYSTEMS
                /dev/sdg
            cmdname: lsblk lookup of SUBSYSTEMS
            err: undef
            out: block:scsi:usb:pci

            returncode: 0
            cmdline:
                /bin/lsblk
                --bytes
                --nodeps
                --noheadings
                --output
                TYPE
                /dev/sdg
            cmdname: lsblk lookup of TYPE
            err: undef
            out: disk

            returncode: 0
            cmdline:
                /bin/lsblk
                --bytes
                --nodeps
                --noheadings
                --output
                MODEL
                /dev/sdg
            cmdname: lsblk lookup of MODEL
            err: undef
            out: WorkflowSR2     

            returncode: 0
            cmdline:
                /bin/lsblk
                --bytes
                --nodeps
                --noheadings
                --output
                RO
                /dev/sdg
            cmdname: lsblk lookup of RO
            err: undef
            out:  0

            returncode: 0
            cmdline:
                /bin/lsblk
                --bytes
                --nodeps
                --noheadings
                --output
                RM
                /dev/sdg
            cmdname: lsblk lookup of RM
            err: undef
            out:  1

            returncode: 0
            cmdline:
                /bin/lsblk
                --bytes
                --nodeps
                --noheadings
                --output
                HOTPLUG
                /dev/sdg
            cmdname: lsblk lookup of HOTPLUG
            err: undef
            out:       1

            returncode: 0
            cmdline:
                /bin/lsblk
                --bytes
                --nodeps
                --noheadings
                --output
                PHY-SEC
                /dev/sdg
            cmdname: lsblk lookup of PHY-SEC
            err: undef
            out:     512

            returncode: 0
            cmdline:
                /usr/bin/sudo
                /bin/lsblk
                --nodeps
                --noheadings
                --output
                FSTYPE
                /dev/sdg
            cmdname: use lsblk to get fs type for /dev/sdg
            err: undef
            out: 

            returncode: 0
            cmdline:
                /usr/bin/sudo
                /sbin/blkid
                --probe
                --output=value
                --match-tag=TYPE
                /dev/sdg
            cmdname: use blkid to get fs type for /dev/sdg
            err: undef
            out: undef
            returncode: 2
output:
    fstype: 
    hotplug: 1
    model: WorkflowSR2
    mountpoint: 
    path: /dev/sdg
    phy-sec: 512
    rm: 1
    ro: 0
    size: 3965190144
    subsystems: block:scsi:usb:pci
    type: disk
plugin:
system:
    filesystems:
        vfat
        ext4
        ext3
        ext2
        squashfs
        fuseblk
    machine: x86_64
    media_dir: /media
    nodename: [redacted]
    PATH: /sbin:/usr/sbin:/bin:/usr/bin
    primary_fs: vfat
    prog:
        blkid: /sbin/blkid
        lsblk: /bin/lsblk
        sudo: /usr/bin/sudo
        unzip: /usr/bin/unzip
    release: 5.0.0-32-generic
    sysname: Linux
    version: #34~18.04.2-Ubuntu SMP Thu Oct 10 10:36:02 UTC 2019
 at /home/[redacted]/perl5/lib/perl5/PiFlash/Command.pm line 193.

I'm looking forward to get this mystery solved :-)