.. _gateway-xs-os-flashing:

Flashing Debian
==================

**For assistance:** contact **CTHINGS.CO Support** at `support.cthings.co <https://support.cthings.co/>`_.

Goals
-----

This guide explains how to flash the **Edge IoT Gateway (XS)** using the **NXP UUU utility**.

Prerequisites
---------------

You will need:

* A valid Debian OS image containing:
  
  * Bootloader (``*.bin``)
  * Root filesystem (``*.img``)
  * (Optional) Integrity checksum (``*.sha256``)

* Flashing tool: **NXP UUU**

.. image:: images/gw-xs-uuu.png
    :width: 75%
    :alt: Location of UUU programming port
    :align: center

Steps
---------

Installing NXP UUU
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Follow the instructions here (it is recommended to use a Linux-based host computer):
`https://github.com/nxp-imx/mfgtools <https://github.com/nxp-imx/mfgtools>`_

If you’d like you install the ``uuu`` utility to your computer, optionally run ``sudo make install``  after compiling.

Flashing the Bootloader
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Acquire the bootloader
""""""""""""""""""""""""""""""

Obtain the correct ``.bin`` bootloader file for your **Edge IoT Gateway XS** hardware revision.

Accessing the UUU port
""""""""""""""""""""""""""""""

1. Power off the gateway.  
2. Connect the micro-USB interface to your host computer (this is the NXP UUU interface).

Entering flashing mode
""""""""""""""""""""""""""""""

Power on the device by long-pressing the **ON** button for approximately 1–2 seconds.  
The gateway should be detected automatically by the **UUU** tool.


Flashing the bootloader
"""""""""""""""""""""""""

Run one of the following commands, depending on your host OS:

.. tab-set::

   .. tab-item:: Windows

      .. code:: powershell

         .\uuu.exe -b emmc flash.bin

   .. tab-item:: Linux

      .. code:: console

         $ sudo uuu -b emmc flash.bin

Replace ``flash.bin`` with the correct bootloader filename for your model.


Resetting after bootloader flashing
""""""""""""""""""""""""""""""""""""""""

1. Power off the device (either by pressing and holding the power button or unplugging the device).
2. Disconnect the micro-USB cable from the NXP UUU interface port. Connect a cable between the console port and your computer and establish a serial connection. 
3. Power on the device. Interrupt the boot in order to enter the U-Boot shell.


Resetting and saving U-Boot environment
""""""""""""""""""""""""""""""""""""""""

At the U-Boot prompt, execute:

.. code:: bash

   env default -a
   saveenv
   reset


Flashing a Complete OS Image
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Prepare
""""""""""

1. Power down the gateway (simple shutdown will suffice; no need to unplug power).
2. Connect the micro-USB interface to your host computer (this is the NXP UUU interface).
3. Power on the device by long-pressing (1-2 seconds) the power button.


Acquire and verify the image
""""""""""""""""""""""""""""""

Acquire the image and verify checksums (if available). 

.. code:: console

   $ sha256sum cthingsco-xs-debian-xxxxxxxx.img
   d41fbc4d2a5e7d8c...  cthingsco-xs-debian-xxxxxxxx.img


Flashing the full eMMC image
""""""""""""""""""""""""""""""

Use the ``emmc_all`` target to flash the complete image:

.. code:: console

   $ sudo uuu -b emmc_all cthingsco-xs-debian-xxxxxxxx.img

Replace the filename with your actual ``.img`` provided by CTHINGS.CO.


First reboot
""""""""""""""""""""

After the flashing process completes:

1. Disconnect power.  
2. Wait 1–2 seconds.  
3. Power on the gateway.  

The Debian system will boot automatically and expand the filesystem if supported by the image.

.. note::
   To obtain the correct image and firmware for your hardware revision, please contact  
   **CTHINGS.CO Support** at `support@cthings.co <mailto:support@cthings.co>`_.