The CuBox-i is a series of compact, fanless computers, by SolidRun, that feature a cube-shaped enclosure.

Installing Debian Linux on CuBox-i series computers, such as the CuBox-i1, CuBox-i2, CuBox-i2eX, or a CuBox-i4Pro, requires specific bootloader preparation.

After spending four hours troubleshooting multiple failed installations, I found the reliable solution documented here. This article details a deployment strategy using the Debian hd-media offline installation method over a serial console connection, avoiding the network-based installer and HDMI issues. After booting the installed Debian system, the network and other hardware work as expected.

Requirements

Computers:

• A Linux computer used to prepare the storage media and access the CuBox serial console.
• A CuBox-i series computer (CuBox-i1, CuBox-i2, CuBox-i2eX, or a CuBox-i4Pro).

Accessories:

• Micro-USB Data Cable: A standard Micro-USB to USB-A cable capable of data transfer (not a charge-only cable). This connects the host computer to the CuBox micro-USB service port to access the serial console, enabling terminal access during boot and installation.
• USB Flash Drive: A drive used to store the Debian ISO for offline installation, such as "debian-12.x.x-armhf-netinst.iso".
• MicroSD Card: Required to boot the Debian installer and will serve as the storage medium where Debian will be installed. A minimum of 4 GB is recommended.

Packages:

• screen: Install the screen, to connect to "/dev/ttyUSB0", using: apt-get install screen
• dosfstools: Install the mkfs.vfat command-line tool using apt-get install dosfstools

Known Debian installer issues on the CuBox-i computers

Before beginning, it is important to understand why the Debian network-based installation method can fail on this hardware:

• Network installer issues: Some Debian installer versions have had problems detecting or configuring the CuBox-i Ethernet interface.
• HDMI display issues: The Debian installer can fail to provide a usable HDMI display on some CuBox-i models. Using the serial console avoids depending on HDMI output during installation.

The solution is to perform an offline installation using the hd-media method while operating the system through a serial console over USB.

Preparing the MicroSD card

Requirement: A MicroSD card. This card is required to boot the Debian installer and will serve as the storage medium where Debian will be installed. A minimum of 4 GB is recommended.

The CuBox-i requires a device-specific U-Boot bootloader to initialize the hardware.

Download the following files:

• firmware.MX6_Cubox-i.img.gz
  http://deb.debian.org/debian/dists/stable/main/installer-armhf/current/images/netboot/SD-card-images/firmware.MX6_Cubox-i.img.gz
• partition.img.gz
  http://deb.debian.org/debian/dists/stable/main/installer-armhf/current/images/netboot/SD-card-images/partition.img.gz

Note: The links above download both files from the Debian stable (/stable/) version.

Then run the following commands as root to write the firmware and partition images directly to the SD card:

zcat firmware.MX6_Cubox-i.img.gz partition.img.gz > /dev/sdX

Warning: This command will erase all data on /dev/sdX. Verify that /dev/sdX is the correct SD card device before running it.

Note: Replace /dev/sdX with the exact target device identifier. (The SD card identifier will typically appear as /dev/sdX for USB adapters or /dev/mmcblkX for native readers.)

Finally, flush file system buffers to ensure all data is written to the device:

sync

This creates the Debian installer image from the device-specific U-Boot portion and the installer partition image.

Preparing the offline installation media (USB Flash Drive)

Requirements:

• A USB flash drive. A drive used to store the Debian ISO for offline installation, such as "debian-12.x.x-armhf-netinst.iso".
• A Linux computer used to prepare the storage media.

The hd-media installer can use a Debian ISO image stored on a separate USB drive.

Step 1: Download the netinst ISO image: https://cdimage.debian.org/debian-cd/current/armhf/iso-cd/

(For example, debian-x.x.x-armhf-netinst.iso, where x.x.x represents the current version number from the official image repository.)

Step 2: Copy the ISO as a normal file onto the USB filesystem. (Do not use block-level writing tools like dd for this step.) Run the following as root:

# Format the first partition of the USB drive to FAT32
mkfs.fat -F 32 /dev/sdX1

# Mount the newly formatted partition to a temporary directory
mkdir -p /mnt/debian-usb
mount /dev/sdX1 /mnt/debian-usb

# Copy the Debian netinst ISO file as a standard file into the FAT32 partition
cp debian-x.x.x-armhf-netinst.iso /mnt/debian-usb/

# Safely unmount the USB drive
umount /mnt/debian-usb

# Flush buffers to prevent data corruption on large file transfers
sync

The Debian installer can then locate and mount the ISO from the USB drive.

Note: The Debian hd-media installer kernel on the MicroSD card must be the same release version as the kernel inside the .iso file. Mixing daily installer builds with stable ISO images will result in a kernel mismatch error. As a rule of thumb, if a stable Debian (current) ISO is downloaded, the hd-media kernel should also be downloaded from the corresponding stable Debian release rather than from the daily installer builds.

Reboot and start installing Debian

With both storage media prepared:

• Insert the prepared MicroSD card into the MicroSD card slot on the CuBox-i.
• Insert the FAT32 USB flash drive containing the Debian .iso file into one of the on the CuBox-i USB ports.
• Ensure the micro-USB data cable connects the CuBox-i service port to the host Linux machine.
• Unplug and plug the power adapter into the CuBox-i.

Accessing the serial console

Requirement: A Micro-USB data cable. A standard Micro-USB to USB-A cable capable of data transfer. This connects the host computer to the CuBox micro-USB service port to access the serial console.

Early boot graphics can fail to provide usable HDMI output on some CuBox-i configurations. Instead, use the built-in serial interface via the micro-USB port to access the terminal output.

Run the following on the Linux host connected to the CuBox-i through a Micro-USB cable to access the CuBox serial interface:

screen /dev/ttyUSB0 115200

(To exit the screen session safely: press Ctrl+A, release, press uppercase K, press Y)

The serial console provides direct, text-based access to early kernel panic messages and hardware initialization logs. The interface is strictly command-line.

Note: Disconnecting the HDMI cable is recommended during setup. HDMI cables carry a 5V line that can backfeed into the CuBox power regulator, causing an "error enabling vbus supply" warning and halting the boot sequence.

The Debian Installer: Navigating the installation steps

• Locale and keyboard: Select the preferred language, country, and keyboard layout.
• Missing firmware prompt: If the installer reports missing firmware, select No. The installer can then continue with the offline installation and search local storage for the Debian .iso file.
• Network setup: If prompted to configure the network, select the option to configure the network later or proceed without a network connection. (Some Debian installer versions have had problems detecting or configuring the CuBox-i Ethernet interface. The hd-media method avoids depending on network access during installation by providing the Debian ISO locally. The Debian installer can locate the ISO on a separate USB storage device and use it to obtain the installation files. This allows the installation to proceed without relying on the CuBox-i Ethernet interface during the installer stage. Network connectivity after installation depends on the installed kernel, drivers, firmware, and configuration.)
• Partition disks: At the partitioning screen, choose "Guided - use entire disk" and select the MicroSD card. (The Debian installer runs from system memory after startup and that existing partitions on the installation card can be deleted or replaced.)
• Software selection: Select standard system utilities.

When the installer reaches the "Installation complete" screen:

• Remove the USB flash drive from the CuBox-i.
• Select Continue to reboot the CuBox-i.

The CuBox-i will reboot and load the Debian operating system from the MicroSD card.