.. _gateway-m-flashing-debian:

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

*OS* | *image* | *Debian*

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

Goals
-----

This guide explains how to flash (to eMMC) an **Edge IoT Gateway M** or
**Edge IoT Gateway M DIN** using the **NXP UUU utility**.

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

You will need:

* A CTHINGS.CO Debian BSP ``.zip`` package for Edge IoT Gateway M containing:

  * Bootloader binary (``flash.bin``)
  * Root filesystem image (``*.img``)
  * UUU script needed for flashing bootloader and image (``uboot.auto``)
  * (Optional) Integrity checksum (``*.sha256``)

* Flashing tool: **NXP UUU**
* USB drivers required by your host operating system


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 would like to install the ``uuu`` utility to your computer, optionally run
``sudo make install`` after compiling.

Preparing the image files
^^^^^^^^^^^^^^^^^^^^^^^^^^

Download the Debian BSP package for Edge IoT Gateway M from CTHINGS.CO and
extract the ``.zip`` file on your host computer.

The package contains the Debian image and flashing binaries. Use the binary that
matches your device model and RAM configuration.

.. list-table::
   :header-rows: 1
   :widths: 40 15 15 30

   * - Model
     - RAM size
     - Configuration
     - Flashing binary
   * - Edge IoT Gateway M
     - 1 GB
     - d1d8
     - ``m_flash.bin.d1d8``
   * - Edge IoT Gateway M
     - 2 GB
     - d2d4
     - ``m_flash.bin.d2d4``
   * - Edge IoT Gateway M
     - 4 GB
     - d2d4
     - ``m_flash.bin.d2d4``
   * - Edge IoT Gateway M
     - 8 GB
     - d1d8
     - ``m_flash.bin.d1d8``
   * - Edge IoT Gateway M DIN
     - 1 GB
     - d1d8
     - ``mdin_flash.bin.d1d8``
   * - Edge IoT Gateway M DIN
     - 2 GB
     - d2d4
     - ``mdin_flash.bin.d2d4``
   * - Edge IoT Gateway M DIN
     - 4 GB
     - d2d4
     - ``mdin_flash.bin.d2d4``
   * - Edge IoT Gateway M DIN
     - 8 GB
     - d1d8
     - ``mdin_flash.bin.d1d8``

Accessing the UUU port
^^^^^^^^^^^^^^^^^^^^^^

1. Power down the gateway.
2. Remove the SIM card cover using a pin tool.
3. Connect the micro-USB interface under the cover to your host computer. This
   is the NXP UUU interface. You may also optionally connect the serial
   interface and open a terminal emulator, but this is not required for flashing.
4. Power on the device by long-pressing the power button for 1-2 seconds.

Flashing the full eMMC image
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Run the command for your model and RAM configuration from the directory
containing the extracted BSP files.

Replace ``cthingsco-edge-gw-m-debian-bookworm-base-<date>.img`` with the image
filename provided in your package.

**Edge IoT Gateway M, 2 GB / 4 GB**

.. tab-set::

   .. tab-item:: Linux

      .. code:: console

         $ sudo uuu -b uboot.auto m_flash.bin.d2d4 cthingsco-edge-gw-m-debian-bookworm-base-<date>.img

   .. tab-item:: Windows

      .. code:: powershell

         .\uuu.exe -b uboot.auto m_flash.bin.d2d4 cthingsco-edge-gw-m-debian-bookworm-base-<date>.img

**Edge IoT Gateway M, 1 GB / 8 GB**

.. tab-set::

   .. tab-item:: Linux

      .. code:: console

         $ sudo uuu -b uboot.auto m_flash.bin.d1d8 cthingsco-edge-gw-m-debian-bookworm-base-<date>.img

   .. tab-item:: Windows

      .. code:: powershell

         .\uuu.exe -b uboot.auto m_flash.bin.d1d8 cthingsco-edge-gw-m-debian-bookworm-base-<date>.img

**Edge IoT Gateway M DIN, 2 GB / 4 GB**

.. tab-set::

   .. tab-item:: Linux

      .. code:: console

         $ sudo uuu -b uboot.auto mdin_flash.bin.d2d4 cthingsco-edge-gw-m-debian-bookworm-base-<date>.img

   .. tab-item:: Windows

      .. code:: powershell

         .\uuu.exe -b uboot.auto mdin_flash.bin.d2d4 cthingsco-edge-gw-m-debian-bookworm-base-<date>.img

**Edge IoT Gateway M DIN, 1 GB / 8 GB**

.. tab-set::

   .. tab-item:: Linux

      .. code:: console

         $ sudo uuu -b uboot.auto mdin_flash.bin.d1d8 cthingsco-edge-gw-m-debian-bookworm-base-<date>.img

   .. tab-item:: Windows

      .. code:: powershell

         .\uuu.exe -b uboot.auto mdin_flash.bin.d1d8 cthingsco-edge-gw-m-debian-bookworm-base-<date>.img

Only run the command that matches your hardware.

First boot
^^^^^^^^^^

After the flashing process completes:

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

On first boot, the Debian system resizes the filesystem and then reboots
automatically. After this automatic reboot, the device is ready to use.

Hardware configuration
----------------------

Some Edge IoT Gateway M hardware setups require a device-tree configuration
command after the device has booted into Debian. Run the command that matches
the connectivity cards installed in the device.

.. note::
   This section applies to Edge IoT Gateway M only.

.. list-table::
   :header-rows: 1
   :widths: 35 45 20

   * - Connectivity cards
     - Command to execute
     - Notes
   * - TPM2 card
     - ``sudo fw_setenv fdtfile iot-gate-imx8plus-m2tpm.dtb``
     - Can be combined with one overlay command below.
   * - EG25 + nRF52 combo card with Wi-Fi card
     - ``sudo fw_setenv fdtofile mpcie-modem-hog.dtbo``
     -
   * - EG25 + nRF52 combo card with another CTHINGS.CO M.2 card
     - ``sudo fw_setenv fdtofile modem-hog-and-pcie-no-reset-gpio.dtbo``
     -
   * - Non-combo mPCIe card with another CTHINGS.CO M.2 card
     - ``sudo fw_setenv fdtofile pcie-no-reset-gpio.dtbo``
     -
   * - Non-CTHINGS.CO modem card with Wi-Fi card
     - No command required.
     -

.. note::
   To obtain the image and firmware, please contact
   **CTHINGS.CO Support** at `support.cthings.co <https://support.cthings.co/>`_.