.. _devkit_elxr_conversion:

Convert to eLxr
===============

This guide explains how to convert an existing SiMa.ai **Yocto-based DevKit** to the new **eLxr** runtime environment, and how to revert back to Yocto when needed.

.. note::

   The eLxr platform is available starting from SDK **2.0.0** and later on the **Modalix DevKit**.

   Converting to eLxr requires a tRoot update and eMMC reflash facilitated by :ref:`netboot`.

The **eLxr** platform replaces the legacy Yocto environment as the new default runtime for SiMa.ai DevKits.  
It offers significant benefits for developers:

* **Simplified updates** — unified root file system layout with larger root file system.  
* **Standard package manager** — Debian-based foundation with persistent package management.  

To confirm your current environment before migrating, follow the quick check below.

To determine which firmware the DevKit is currently running, connect via serial or SSH and run:

.. code-block:: bash

   cat /etc/buildinfo | grep DISTRO

You should see either:

.. code-block:: text

   DISTRO = poky

or

.. code-block:: text

   DISTRO = eLxr

If you see ``poky``, follow the steps below to migrate.


.. dropdown:: Step 1. Physical Setup
   :animate: fade-in
   :color: secondary
   :open:

   .. note::

      This procedure is supported on **macOS** and **Ubuntu Linux** platforms.

      If you have not installed ``sima-cli`` on your host machine, follow the
      instructions :ref:`here <sima_cli>` to install it.

      This procedure requires two terminal sessions:

      1. A serial console session connected to the Modalix DevKit, used to modify U-Boot environment variables so the DevKit can boot over the network.
      2. A host shell session used to update the tRoot, configure NetBoot, and initiate the DevKit eMMC flashing process.

   .. figure:: media/conversion-diagram.png
      :width: 800px
      :align: center

      **Connection Diagram**

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

   2. Connect the **UART port** of the DevKit to the host for console access.  
      Ensure your host has the latest ``sima-cli`` installed. Then run:
   
      .. include:: blocks/host-cli.rst
      .. code-block:: bash

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

      to open a serial terminal and connect to the DevKit.

   3. On the DevKit, configure the network interface to the default static IP
      address (**192.168.1.20**) by following the instructions
      :ref:`here <setup_standalone_network_cfg>`.

.. dropdown:: Step 2. Update to the Latest tRoot
   :animate: fade-in
   :color: secondary
   :open:

   Before proceeding with the eLxr conversion, update the DevKit to the
   latest **tRoot** image.

   This update is required to ensure that the tRoot (trusted root) is
   compatible with eLxr. 
   
   .. include:: blocks/host-cli.rst
   .. code-block:: bash

      sima-user@sima-user-machine:~$ sima-cli update --ip 192.168.1.20 2.0.0 --troot_only

   After the update completes successfully, **power cycle the DevKit**
   to apply the changes.


.. dropdown:: Step 3. Prepare Netboot Environment
    :animate: fade-in
    :color: secondary
    :open:

   

    To boot the DevKit into eLxr and prepare for eMMC flashing, prepare a TFTP-based netboot environment.

    **On macOS:**

    .. include:: blocks/host-cli.rst
    .. code-block:: bash

       sima-user@sima-user-machine:~$ sima-cli bootimg --boardtype modalix --fwtype elxr -v 2.0.0 --netboot

    **On Linux:**

    .. warning:: 
      
         The TFTP server requires binding to port 69, which is a privileged port. Therefore, ``sudo`` is required:

    .. include:: blocks/host-cli.rst
    .. code-block:: bash

       sima-user@sima-user-machine:~$ sudo ~/.sima-cli/.venv/bin/sima-cli bootimg --boardtype modalix --fwtype elxr -v 2.0.0 --netboot

    This command automatically:

    - Downloads the appropriate eLxr netboot image  
    - Starts a temporary TFTP server  
    - Prepares all files needed for eMMC flashing

.. dropdown:: Step 4. Configure DevKit for Netboot
    :animate: fade-in
    :color: secondary
    :open:

    Power cycle the Modalix DevKit while connected to host through serial console. From the DevKit **serial console**, interrupt the boot process to enter the **u-boot** shell.  

    .. code-block:: bash

      ... ... ... 

      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:

    .. include:: blocks/devkit-cli.rst
    .. code-block:: bash

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

    This tells the DevKit to boot from the host’s TFTP server prepared in the previous step.

.. dropdown:: Step 5. Flash the eMMC
    :animate: fade-in
    :color: secondary
    :open:

    Wait for the DevKit to finish booting. This process may take several minutes.

    Once the login prompt is shown on the serial console connecting to the DevKit, the board is ready.

    Switch back to the host terminal and press **Enter** until you see the ``netboot>`` prompt, then type:

    .. include:: blocks/host-cli.rst
    .. code-block:: bash

      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 [...]

    This is a 1.6GB image file, transferring to the board can take 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 completed and power cycled, the DevKit is running **eLxr** natively from eMMC.

.. dropdown:: Step 6. Optional: Install 2.0 eLxr Out-of-the-box Demo
    :animate: fade-in
    :color: secondary
    :open:

      Your DevKit running version 1.7 may be preloaded with a 1.7-compatible
      OOB (out-of-the-box) demo. After converting the DevKit to version 2.0
      with eLxr, you can upgrade the OOB demo by following the instructions
      below.

      To proceed, connect your DevKit to the Internet and access it using
      either an SSH session or the serial console.

      .. figure:: media/conversion-devkit-standalone.png
         :width: 800px
         :align: center

         **Standalone DevKit**

      .. include:: blocks/devkit-cli.rst
      .. code-block:: bash

         modalix:~$ cd /tmp && curl -O https://tools.modalix.info/setup-oob.sh && bash setup-oob.sh

      During the setup process, you will be prompted to confirm whether you
      want to upgrade the OOB demo. Select ``Yes`` to continue.


.. dropdown:: Revert to Yocto (Optional)
    :animate: fade-in
    :color: secondary
    :open:

    To switch back to Yocto, the procedure is identical to converting to eLxr, just use ``fwtype=yocto`` instead when running the sima-cli bootimg command with --netboot.

    **On macOS:**

    .. include:: blocks/host-cli.rst
    .. code-block:: bash

       sima-user@sima-user-machine:~$ sima-cli bootimg --boardtype modalix --fwtype yocto -v 2.0.0 --netboot

    **On Linux:**

    .. code-block:: bash

       sima-user@sima-user-machine:~$ sudo ~/.sima-cli/.venv/bin/sima-cli bootimg --boardtype modalix --fwtype yocto -v 2.0.0 --netboot

    Then, in the u-boot console:

    .. include:: blocks/devkit-cli.rst
    .. code-block:: bash

       sima$ setenv boot_targets net
       sima$ saveenv
       sima$ boot

    Once the DevKit netboots, type:

    .. include:: blocks/host-cli.rst
    .. code-block:: bash

       netboot > f

    to flash the Yocto root file system to eMMC.

    .. note::

       There is **no minimum version requirement** when converting back to Yocto.

.. 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 Modalix Early Access board, make sure to use ethernet port 0 port only.
    * On Linux, ensure your firewall allows UDP port **69 (TFTP)**.  
    * You can verify connectivity from the DevKit by running:

      .. code-block:: bash

         ping 192.168.1.10

    * If ``f`` fails to find the image, rerun the netboot setup command to refresh paths:

      .. code-block:: bash

         sima-user@sima-user-machine:~$ sima-cli bootimg --boardtype modalix --fwtype elxr -v 2.0.0 --netboot

    * If NFS-related error messages appear on the serial console after the DevKit has been converted to eLxr, they can be safely ignored.

Summary
-------

1. Update to the latest **tRoot** image (≥ 2.0.0).  
2. Prepare the **eLxr netboot** image using ``sima-cli``.  
3. Set **u-boot** to netboot from the host.  
4. Boot the device and type ``f`` to flash eMMC.