Update with Net Boot

In some development or recovery scenarios, it may be preferable — or even necessary — to boot the DevKit over the network instead of using a removable device like an SD card. This is particularly useful when:

  • You need to downgrade the DevKit to an older SDK release.

  • You need to install a build that is not the latest release (for example, a pre-release develop build or an internal engineering image).

  • You need to recover a board with a corrupted bootloader or filesystem and there’s no SD card available.

  • You’re bringing up a new board and want to avoid wear on internal storage devices.

  • You’re converting a Modalix DevKit from Yocto Linux to eLxr, or from eLxr back to Yocto Linux. See Convert to eLxr for the conversion-specific prerequisites.

In these situations, use the --netboot option with sima-cli bootimg. It downloads the appropriate boot image for the target board, then serves it over a built-in TFTP server on the host machine. The DevKit is then configured in U-Boot to boot from that TFTP server, and the new image is flashed to eMMC from the host.

Warning

Upgrading a Modalix DevKit from SDK 1.7 to 2.0 requires additional steps. Refer to the Convert to eLxr guide for the conversion procedure.

Step 1. Physical Setup

Note

This procedure is supported on macOS and Ubuntu Linux hosts.

If you have not installed sima-cli on your host machine, follow the instructions here to install it.

Two terminal sessions are required:

  1. A serial console session connected to the DevKit, used to modify U-Boot environment variables so the DevKit boots over the network.

  2. A host shell session used to start the TFTP server and initiate the eMMC flash.

  1. Connect the DevKit’s Ethernet port directly to the host PC and set the host’s network interface to static IP 192.168.1.10. On the Modalix Early Access board, use Ethernet port 0.

  2. Connect the UART port of the DevKit to the host for console access. With sima-cli installed on the host, open a serial terminal:

    sima-user@sima-user-machine:~$ sima-cli serial

  3. On the DevKit, configure the network interface to the default static IP 192.168.1.20 by following the instructions here.

Step 2. Start the TFTP Netboot Server on the Host

Requirements

  • The host and DevKit must be on the same physical network or direct Ethernet link.

  • The Ethernet connection must be a Gigabit interface or faster (link greater than 1000 Mbps).

  • The host needs an Internet connection to download the firmware image.

  • UDP port 69 (TFTP) must not be blocked by the host firewall.

Replace <version> with the target SDK version (for example 2.0.0), <boardtype> with modalix or mlsoc, and <fwtype> with yocto or elxr.

On macOS:

sima-user@sima-user-machine:~$ sima-cli bootimg --boardtype <boardtype> --fwtype <fwtype> -v <version> --netboot

On Linux:

Warning

The TFTP server binds to port 69, which is privileged, so sudo is required:

sima-user@sima-user-machine:~$ sudo ~/.sima-cli/.venv/bin/sima-cli bootimg --boardtype <boardtype> --fwtype <fwtype> -v <version> --netboot

This command performs the following steps:

  1. Downloads the bootable image for the requested SDK version and board type.

  2. Extracts the files to a temporary working directory.

  3. Starts a local TFTP server and serves the extracted boot files (Image, boot.scr, .dtb files, etc.).

Step 3. Configure the DevKit to Netboot

Power-cycle the DevKit while it is connected to the host via the serial console. If the serial console disconnects during the power cycle, reconnect it. There is a brief delay of a few seconds before boot messages appear — wait until you see the message Hit any key to stop autoboot, then press any key to drop into the U-Boot shell:

... ... ...

Address in DT is          ff:ff:ff:ff:ff:ff
Address in environment is 68:e1:54:00:05:c6
eth0: ethernet@a800000 [PRIME]
Hit any key to stop autoboot:  0
sima$

Then run the following commands in the U-Boot shell:

sima:~$ setenv boot_targets net; saveenv; boot

For Modalix eLxr targets, also set the cpio image name before booting:

sima:~$ setenv cpio_name simaai-image-palette-modalix.cpio.gz; setenv boot_targets net; saveenv; boot

This tells the DevKit to boot from the host’s TFTP server prepared in Step 2.

Note

By default, the DevKit U-Boot is configured with:

  • ipaddr=192.168.1.20 (DevKit’s Ethernet interface, first port on multi-port boards).

  • serverip=192.168.1.10 (host machine running the TFTP server).

To use a different network, update serverip and ipaddr in U-Boot to match your environment, ensuring the DevKit can reach the host at the chosen IPs:

sima:~$ setenv serverip 10.0.0.10; setenv ipaddr 10.0.0.1; saveenv; boot
Step 4. Flash the eMMC

The --netboot shell on the host supports two commands:

  • c — Show all connected clients and the firmware version currently running on them.

  • f — Flash the selected client’s eMMC.

Wait for the DevKit to finish netbooting — this may take several minutes. Once the login prompt is shown on the serial console, the board is ready. We recommend keeping the serial console connected throughout to observe the full boot sequence.

Switch back to the host terminal and press Enter until you see the netboot> prompt. Optionally type c to confirm the DevKit is connected and show its current firmware version, then type f to flash:

netboot> f

You should see logs similar to:

🔍 Checking SSH availability for 192.168.1.20...
✅ Board is online!
✅ SSH is available on 192.168.1.20
netboot> f
🔧 Initiating eMMC flash [...]

The image is roughly 1.6 GB and the transfer takes a few minutes. Example progress:

↦ 520093696 bytes (520 MB, 496 MiB) copied, 1 s, 515 MB/s
↦ 5368709120 bytes (5.4 GB, 5.0 GiB) copied, 163.331 s, 32.9 MB/s

Once flashing completes, power-cycle the DevKit. It will now boot the target version from eMMC.

Note

If the DevKit’s IP changed during netboot (for example, because DHCP assigned a different address than the default 192.168.1.20), f on its own will fail to reach the board. Find the new IP on the DevKit serial console — it is printed in the boot log and shown by ip addr at the netbooted shell — and make sure the host can reach it:

sima-user@sima-user-machine:~$ ping <new-ip>

Then pass the new IP explicitly to f:

netboot> f <new-ip>
Troubleshooting

  • If the DevKit fails to netboot, verify both host and device are on the same subnet (192.168.1.x).

  • On the Modalix Early Access board, only Ethernet port 0 is supported for netboot.

  • On Linux, ensure the host firewall allows UDP port 69 (TFTP).

  • Verify connectivity from the DevKit:

    modalix:~$ ping 192.168.1.10

  • If f fails to find the image, rerun the sima-cli bootimg --netboot command from Step 2 to refresh the TFTP paths.

  • If NFS-related error messages appear on the serial console after converting a Modalix DevKit to eLxr, they can be safely ignored.