.. _debian-linux:

Debian Linux
-------------

Your gateway comes pre-installed with the latest Debian operating system image and its userland ecosystem.  Various drivers and tools for important hardware elements (such as Wi-Fi, Bluetooth, cellular, Wirepas, etc.) are pre-installed. It is also possible to run other root filesystems with our provided kernel.  Contact us with your requirements if you would like to use a custom operating system.


Connecting over serial console
----------------------------------

Please refer to the quick start guide explaining :ref:`connection over serial console <subsection_iot_gateway_light_2022_quick_start_connect_over_serial_console>`.


Connecting using a monitor/keyboard
-------------------------------------------

Please refer to the quick start guide explaining :ref:`connection using a monitor/keyboard <subsection_iot_gateway_light_2022_quick_start_connect_with_monitor_keyboard>`.


Connecting over SSH
---------------------

Please refer to the quick start guide explaining :ref:`connection over SSH <subsection_iot_gateway_light_2022_quick_start_connect_over_ssh>`.


Flashing a new image
--------------------------

**Prerequisites**

* Source image file relevant to your device, acquired from `CTHINGS.CO <http://cthings.co>`_
* USB flash drive with a capacity of 8GB or larger
* Host PC/Mac (Windows/Linux/macOS) to connect from and flash the USB drive
* USB Type-A (or Type-C, depending on the host computer) to USB Type-B micro cable
* Terminal emulator application (we recommend ``PuTTY`` on Windows; ``picocom`` on macOS; or ``picocom`` on Linux)

.. warning:: Flashing a new image will fully erase the gateway's memory. Ensure you have a full backup of any required files before proceeding.

**Steps**

1. Download and install `Etcher <https://www.balena.io/etcher/>`_ (a multi-platform tool for easy flashing) on your PC or Mac.
2. Connect the USB flash drive to your PC or Mac.
3. Open Etcher. Select the acquired image and the MicroSD card.  If multiple external drives are connected, ensure you select the correct device.
4. Proceed with flashing. Etcher will automatically format, write, and verify the image.
5. Power off and unplug the gateway. If running, gracefully shut it down using ``sudo shutdown now`` (administrative rights required).
6. Connect the flash drive to a USB port on the gateway (USB 3.0 recommended).
7. Set up a serial console connection (see :ref:`Connecting over serial console <subsection_iot_gateway_light_2022_quick_start_connect_over_serial_console>`).
8. Reconnect the gateway to power. After a few seconds, the GNU GRUB boot selection screen will appear. Select *Install Linux* and press *Enter*.
9. The installation will proceed automatically. **Do not** tamper with or unplug the device. If this happens, reboot and start over.  Once successful, the wizard will ask you to "Remove installation media & Press Enter".
10. Disconnect the USB flash drive. Press *Enter* to reboot. The gateway will reboot into the newly flashed image.

.. note:: Advanced users may prefer other flashing applications. We recommend ``Win32DiskImager`` for Windows and ``dd`` for Linux and Mac.

    The recommended ``dd`` command is:

    .. code:: console

        $ unzip -p ~/path/to/image.zip | sudo dd of=/dev/sdX bs=1M status=progress conv=fsync