Using Kuiper Images

After obtaining your Kuiper image (built or downloaded), you’ll need to write it to an SD card or storage device and boot your target hardware. This section guides you through that process.

Extracting the Image

The build process produces a zip file in the kuiper-volume/ directory. Extract it using:

Listing 1 Extract the image
~/kuiper-volume$

unzip image_YYYY-MM-DD-ADI-Kuiper-Linux-[arch].zip

Writing the Image to an SD Card

Using Balena Etcher

Balena Etcher provides a simple, graphical interface for writing images to SD cards and is the recommended method:

  1. Download and install Balena Etcher.

  2. Launch Etcher and click “Flash from file”.

  3. Select the image file you extracted from the zip.

  4. Select your SD card as the target.

  5. Click “Flash” and wait for the process to complete.

Using Command Line on Linux

For users who prefer command line tools:

  1. Insert your SD card into your computer.

  2. Identify the device name of your SD card:

    ~$

    lsblk

    NAME   MAJ:MIN RM  SIZE RO TYPE MOUNTPOINT
sda      8:0    0 465.8G  0 disk
├─sda1   8:1    0   512M  0 part /boot/efi
└─sda2   8:2    0 465.3G  0 part /
sdb           8:16   1  29.7G  0 disk
├─sdb1        8:17   1     2G  0 part /media/user/BOOT
├─sdb2        8:18   1  27.7G  0 part /media/user/rootfs
└─sdb3        8:19   1     8M  0 part

    Look for a device like /dev/sdX or /dev/mmcblkX (where X is a letter or number) that matches your SD card’s size. In this example, /dev/sdb is a 32GB SD card.

  3. Unmount any auto-mounted partitions:

    ~$

    sudo umount /dev/sdX*

    Replace /dev/sdX with your actual device path.

    Warning

    Double-check the device name. Writing to the wrong device will destroy data on that device.

  4. Write the image to the SD card:

    ~$

    sudo dd if=image_YYYY-MM-DD-ADI-Kuiper-Linux-[arch].img of=/dev/sdX bs=4M status=progress conv=fsync

    Replace /dev/sdX with your actual device path, and update the image filename accordingly.

    This process may take several minutes depending on image size and SD card speed.

  5. Eject the SD card:

    ~$

    sudo eject /dev/sdX

Alternative Image Writing Tools

While Balena Etcher is recommended for its simplicity and cross-platform support, you can also use these alternatives:

Linux alternatives

  • GNOME Disks (pre-installed on most GNOME-based distributions)

  • Ubuntu Disk Image Writer

  • Popsicle

Windows alternatives

  • Win32 Disk Imager

  • Rufus

All platforms

  • Raspberry Pi Imager (works with any .img file, not just Pi images)

Before You Boot: Platform-Specific Requirements

Important

The next steps depend on your hardware platform. Read this section carefully to avoid boot failures.

ADI Evaluation Boards

ADI evaluation boards (ZedBoard, ZC706, ADRV9009-ZU11EG, etc.) require configuration before your system will boot successfully.

Configuration specifies which evaluation board and carrier combination you’re using, allowing the system to load the correct boot files.

If you configured during the build process:

You set ADI_EVAL_BOARD and CARRIER parameters in your configuration file before building.

If you did NOT configure during the build process:

Your image is not yet configured for any specific hardware.

  • STOP HERE - Do not boot yet

  • See ADI Evaluation Boards Configuration to configure your image for your specific evaluation board and carrier

  • Return here after configuration is complete

Raspberry Pi

Raspberry Pi images work out-of-box with no configuration required.

Booting Your Device

After writing the image to your SD card and completing any required configuration:

  1. Insert the SD card into your target device.

  2. Connect required peripherals:

    • Power supply

    • Display (HDMI or other video output) if using console access

    • Keyboard and mouse if using console access

    • Ethernet cable if using wired network access

  3. Power on the device.

  4. Wait for first boot to complete:

    The first boot takes longer than subsequent boots (typically 1-3 minutes) as the system automatically resizes the root partition to use the full SD card capacity.

    Successful boot indicators:

    • Console displays login prompt

    • SSH becomes accessible (if network connected)

    • System responds to keyboard input

    If the system doesn’t boot:

    • For ADI evaluation boards: Verify you completed configuration (see ADI Evaluation Boards)

    • Check SD card is properly inserted

    • Verify power supply provides adequate current

    • Check display connection if using console access

Login Information

Username: analog

Password: analog

Root access is available using the same password with sudo or by logging in directly as root.

Accessing Your Kuiper System

Console Access

Connect directly with a keyboard and display if your hardware supports it. This is the most reliable access method for initial setup.

SSH Access

If your device is connected to a network, you can access it via SSH.

First, find your device’s IP address. If you have console access:

~$

ip addr show

1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN
    inet 127.0.0.1/8 scope host lo
2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state UP
    inet 192.168.1.100/24 brd 192.168.1.255 scope global eth0

In this example, the device IP address is 192.168.1.100.

Then connect from another computer:

~$

ssh analog@192.168.1.100

The authenticity of host '192.168.1.100 (192.168.1.100)' can't be established.
ECDSA key fingerprint is SHA256:...
Are you sure you want to continue connecting (yes/no)? yes
analog@192.168.1.100's password:

Enter the password analog when prompted.

VNC Access

If you built your image with CONFIG_DESKTOP=y, you can access the graphical environment via VNC:

  1. Connect to your device using a VNC client (like RealVNC, TigerVNC, or Remmina).

  2. Use the device’s IP address and port 5900, for example:

    192.168.1.100:5900

  3. Enter the password analog when prompted.

Verifying Your Installation

To verify that your Kuiper image is working correctly:

Check system information:

~$

uname -a

Linux analog 6.6.63-v8-16k+ #1 SMP PREEMPT Wed Aug 13 10:31:20 UTC 2025 aarch64 GNU/Linux

Verify ADI tools (if you included them in your build):

~$

iio_info --version

iio_info version: 0.26 (git tag:ba74e6c5)
Libiio version: 0.26 (git tag: ba74e6c) backends: local xml ip usb serial

~$

iio_info -n 192.168.1.100 | head

iio_info version: 0.26 (git tag:ba74e6c5)
Libiio version: 0.26 (git tag: ba74e6c) backends: local xml ip usb serial
IIO context created with network backend.
Backend version: 0.26 (git tag: ba74e6c)
Backend description string: 192.168.1.100 Linux analog 6.6.63-v8-16k+ #1 SMP PREEMPT Wed Aug 13 10:31:20 UTC 2025 aarch64
IIO context has 5 attributes:
  hw_carrier: Raspberry Pi 5 Model B Rev 1.0
  dtoverlay: vc4-fkms-v3d,dwc2
  local,kernel: 6.6.63-v8-16k+
  uri: ip:192.168.1.100

This command lists IIO devices accessible on the network. If you have ADI evaluation hardware properly configured and connected, you should see device information.

Note

The exact output will vary depending on your build configuration, hardware platform, and installed packages. The examples above show typical successful outputs.