.. _netboot: 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 :ref:`devkit_elxr_conversion` 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. .. include:: ../blocks/elxr_conversion_note.rst .. dropdown:: Step 1. Physical Setup :animate: fade-in :color: secondary :open: .. 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 :ref:`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: .. code-block:: console 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 :ref:`here `. .. dropdown:: Step 2. Start the TFTP Netboot Server on the Host :animate: fade-in :color: secondary :open: **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 ```` with the target SDK version (for example ``2.0.0``), ```` with ``modalix`` or ``mlsoc``, and ```` with ``yocto`` or ``elxr``. **On macOS:** .. code-block:: console sima-user@sima-user-machine:~$ sima-cli bootimg --boardtype --fwtype -v --netboot **On Linux:** .. warning:: The TFTP server binds to port 69, which is privileged, so ``sudo`` is required: .. code-block:: console sima-user@sima-user-machine:~$ sudo ~/.sima-cli/.venv/bin/sima-cli bootimg --boardtype --fwtype -v --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.). .. dropdown:: Step 3. Configure the DevKit to Netboot :animate: fade-in :color: secondary :open: 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: .. code-block:: console ... ... ... 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: .. code-block:: console sima:~$ setenv boot_targets net; saveenv; boot For Modalix **eLxr** targets, also set the cpio image name before booting: .. code-block:: console 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: .. code-block:: console sima:~$ setenv serverip 10.0.0.10; setenv ipaddr 10.0.0.1; saveenv; boot .. dropdown:: Step 4. Flash the eMMC :animate: fade-in :color: secondary :open: 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: .. code-block:: console netboot> f You should see logs similar to: .. code-block:: text 🔍 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: .. code-block:: text ↦ 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: .. code-block:: console sima-user@sima-user-machine:~$ ping Then pass the new IP explicitly to ``f``: .. code-block:: console netboot> f .. dropdown:: Troubleshooting :animate: fade-in :color: secondary :open: - 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: .. code-block:: console 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.