.. _upgrading-quectel-firmware:

Upgrading Quectel Cellular Modem Firmware
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. warning::

    * **These instructions are for Quectel modules only.** Incorrect firmware can brick the device.
    * Maintain a secondary connection during the upgrade.
    * This example uses the RM500Q 5G modem. Adapt as needed.

Steps
""""""""""

1. Ensure that you are currently logged in as the root user:

   .. code:: console

       $ sudo su

2. Create and enter a new temporary directory:

   .. code:: console

       $ mkdir ~/upgrade_fw && cd ~/upgrade_fw

3. Download the latest version of the firmware flash tool (contact us for the latest version of the utility):

   .. code:: console

       $ wget https://content.cthings.co/static/iveos/QFirehose_Linux_Android_V1.4.9.zip

4. Unzip the flash tool:

   .. code:: console

       $ unzip QFirehose_Linux_Android_V1.4.9.zip

5. Create and enter a directory for the firmware file:

   .. code:: console

       $ mkdir ~/upgrade_fw/fw && cd ~/upgrade_fw/fw

6. Contact us for the hyperlink for the correct firmware file for your modem. Download it:

   .. code:: console

       $ wget https://content.cthings.co/static/iveos/FIRMWARE.zip

7. Unzip the firmware file:

   .. code:: console

       $ unzip FIRMWARE.zip

8. Change directory to the firmware flash tool:

   .. code:: console

       $ cd ~/upgrade_fw/QFirehose_Linux_Android_V1.4.9

9. Compile and link the tool:

   .. code:: console

       $ make

10. Identify the correct integer identifier for the modem that you are trying to upgrade. In the following example, the identifier is ``0``:

    .. code:: console

       $ mmcli -L   
       /org/freedesktop/ModemManager1/Modem/0 [Quectel] RM500Q-GL

11. Query the modem information using the integer identifier found in the previous step. Identify the USB hardware identifier of the modem. In this example, the value is ``4-1.4``:

    .. code:: console

       $ mmcli -m 0
       -----------------------------
       General  |         dbus path: /org/freedesktop/ModemManager1/Modem/0
                |         device id: a15de9fa88f041206c0a1b88a9c0cb6be4dc8c9b
       -----------------------------
       Hardware |      manufacturer: Quectel
                |             model: RM500Q-GL
                | firmware revision: RM500QGLABR11A05M4G
                |    carrier config: default
                |      h/w revision: 20000
                |         supported: gsm-umts, lte, 5gnr
                |           current: gsm-umts, lte, 5gnr
                |      equipment id: 863305040348640
       -----------------------------
       System   |            device: /sys/<omitted>/xhci-hcd.2.auto/usb4/4-1/4-1.4
                |           drivers: option1, qmi_wwan
                |            plugin: quectel
                |      primary port: cdc-wdm0
                |             ports: cdc-wdm0 (qmi), ttyUSB0 (qcdm), ttyUSB1 (gps),
                                     wwan0 (net)

12. Start the firmware upgrade. Please do not interrupt the upgrade process, as this may result in the device being permanently and irrecoverably bricked. Ensure the success message is shown:

    .. code:: console

       $ ./QFirehose -f ~/upgrade_fw/fw -s /sys/bus/usb/devices/4-1.4
       ...<truncated>
       [064.987]: THE TOTAL DOWNLOAD TIME IS 60.370 s
       [064.987]: Upgrade module successfully.


13. The upgrade process is complete. Clean up by deleting the downloaded files:

    .. code:: console

       $ cd ~ && rm -rf ~/upgrade_fw