Flashing SD Card Images

This guide covers how to flash an Infix SD card image to a microSD card or eMMC module.

Prerequisites

You will need:

• An SD card reader (USB or built-in)
• A microSD card or eMMC module (minimum 2 GB recommended)
• An Infix SD card image from the latest-boot builds

Linux

Using dd

The traditional dd command works on any Linux system without additional software:

$ sudo dd if=infix-aarch64-bpi-r3.img of=/dev/sdX bs=1M status=progress oflag=direct conv=fsync

Replace /dev/sdX with your actual SD card device. You can find the correct device using lsblk to list all block devices.

Make sure to unmount any partitions on the SD card before flashing. The device should be /dev/sdX (the whole disk), not /dev/sdX1 (a partition).

Using Balena Etcher

Balena Etcher provides a graphical interface and works on Linux, Windows, and macOS. It includes built-in verification.

1. Download and install Etcher from the official website
2. Launch Etcher
3. Click “Flash from file” and select your image file
4. Click “Select target” and choose your SD card
5. Click “Flash!” and wait for the process to complete

Etcher will automatically unmount the SD card and verify the written data.

Using bmaptool

The bmaptool utility is the fastest option for flashing images, as it only writes data to blocks that actually contain data, skipping empty regions.

Install bmaptool on Debian-based systems:

$ sudo apt install bmap-tools

Since Infix does not yet publish .bmap files, you need to generate one first:

$ bmaptool create infix-aarch64-bpi-r3.img > infix-aarch64-bpi-r3.bmap

Flash the image:

$ sudo bmaptool copy infix-aarch64-bpi-r3.img /dev/sdX

The tool will automatically find and use the .bmap file if it exists in the same directory as the image.

Windows

Balena Etcher is recommended for Windows:

1. Download and install Etcher from the official website
2. Insert your SD card
3. Launch Etcher
4. Click “Flash from file” and select your image file
5. Click “Select target” and choose your SD card
6. Click “Flash!” and wait for the process to complete

An alternative is Win32 Disk Imager, which provides similar functionality.

Verifying the Flash

After flashing, safely eject the SD card from your computer and insert it into your target device. The system should boot and be accessible via serial console or SSH to the hostname advertised over mDNS.

The default credentials and network configuration are described in the getting started guide.

Troubleshooting

If the device does not boot:

• Verify you wrote to the correct device (not a partition)
• Check that the SD card is properly seated in the slot
• Try a different SD card (some cards are incompatible with certain devices)
• Verify the image is for the correct board
• Check the serial console output for error messages

For additional help, consult the documentation or ask on the community Discord.

Shell Script Example

For regular flashing tasks on Linux, a shell script with safety checks can be helpful:

#!/bin/sh
# flash.sh - Write image file to SD card with safety checks

yorn=
file=
dev=

fatal()
{
    printf "Error: %s\n" "$*" >&2
    exit 1
}

note()
{
    printf "%s\n" "$*"
}

yorn()
{
    [ -n "$yorn" ] && return 0
    printf "%s, are you sure (y/N)? " "$1"
    read -r answer
    [ "$answer" = "y" ] || [ "$answer" = "Y" ]
}

# Parse arguments
while getopts "y" opt; do
    case "$opt" in
        y) yorn=y ;;
        *) echo "Usage: flash [-y] DEV FILE" >&2; exit 1 ;;
    esac
done
shift $((OPTIND-1))

# Get device and file
if [ $# -eq 2 ]; then
    dev=$1
    file=$2
elif [ $# -eq 1 ]; then
    file=$1
    # Try to guess SD card device
    guess_dev=$(lsblk -ndo NAME,RM,MOUNTPOINT | awk '$2=="1" && $3=="" { print $1 }')
    count=$(printf "%s\n" "$guess_dev" | wc -l)
    if [ "$count" -eq 1 ]; then
        dev="/dev/$guess_dev"
        note "Guessed SD card device: $dev"
    else
        fatal "Unable to safely guess SD card device."
    fi
else
    echo "Usage: flash [-y] DEV FILE" >&2
    exit 1
fi

[ -b "$dev" ]  || fatal "$dev is not a block device."
[ -f "$file" ] || fatal "$file does not exist."

# Safety check for system drives
case "$dev" in
    /dev/sda* | /dev/nvme0n1* | /dev/vda*)
        printf "WARNING: %s looks like a system drive!\n" "$dev" >&2
        yorn "Flash to $dev" || exit 1
        ;;
esac

# Check if mounted
if mountpoint -q "$dev" 2>/dev/null; then
    fatal "$dev is mounted. Unmount before proceeding."
fi

yorn "Write $file to $dev" || exit 0

note "Writing $file to $dev..."
if ! dd if="$file" of="$dev" bs=1M status=progress oflag=direct conv=fsync; then
    fatal "dd failed to write image."
fi

note "Done."

Save this as flash.sh, make it executable with chmod +x flash.sh, and use:

$ ./flash.sh /dev/sdX infix-aarch64-bpi-r3.img

The script includes automatic device detection if you omit the device argument, and safety checks to prevent accidentally overwriting system drives.