.. _headlabel-refx-manage-upd: Firmware Over The Air ===================== This section describes how to use the `AT@UPD` command to upgrade the terminal firmware over the air. .. _refx-manage-upd-process: Update Process -------------- The firmware update process includes four steps: start the update, check security, download the update package and perform the update. Here is a flowchart of successful update: .. figure:: ../_static/pictures/air/manage/air-manage-1.png :align: center Flowchart of Successful Update Please see below for more detailed information for each update step. - **Start the Update** The backend server sends the AT\@UPD (sub-command 0) command to the terminal to initiate the update process. Along with this command, necessary information is sent to the terminal to start the update process. Backend server decides when and how to initiate the firmware update process of all the terminals it controls. As the response message receiver and the controller, the backend server has all the information (including the current firmware version of the terminal, the version of the latest available firmware and the location of the proper update packages) it needs to start an update process. - **Check Security** After receiving the valid AT\@UPD (sub-command 0) command, the terminal will first check the security of the system, such as whether the battery is sufficient and whether the vehicle is parking (just for example). If the terminal is not currently in a secure environment, it will send a **F1H** report (code 04H) to inform the backend server that the update process is to be aborted. If the current terminal is in a state that allows the update, the terminal will connect to the file server. If the connection successful, the terminal will send a F1H report (code 01H) to the backend server and then start to download the update package. - **Download the Update Package** If the terminal downloading the update package failed, it will retry until it succeeds or times out. If the downloading is successful, the terminal will check the downloaded file, after confirming that the file is right, the terminal will send a **F1H** report (code 02H) to the backend server and the update process proceeds to the next step. Before the "Perform the Update" step, if the terminal receives AT\@UPD (sub-command 1) to cancel current update process, then the terminal will terminate the update process. In addition, if the terminal is in the process of downloading the file package when receiving the cancel command, then the terminal may send the **F1H** report (code 05H) to the backend server after the download process is completed (before "Perform the Update"). - **Perform the Update** After downloading the package successfully, the terminal will check the system security again. If the terminal is not currently in a secure environment, the terminal will send a **F1H** report (code 08H) to inform the backend server that the update process is to be aborted. Otherwise, the terminal will start updating. After the update, whether successful or not, the terminal will reboot automatically. After that, it will send a F1H report (if successful, the code is 03H) with update information to the backend server and work as usual. The AT\@UPD command and F1H report are described in detail below. .. _refx-manage-upd-cmd: UPD (Upgrade Firmware) ---------------------- The `AT@UPD` command is used to update the firmware of terminal via network. .. note:: Download files from the specified URL. After the terminal fails to connect to the file server (which specified by 'Download URL'), a gradual delay retry strategy will be adopted. .. code-block:: none Example: AT@UPD=gl601###,0,1,,,10,http://218.17.46.11:979/GL601/deltabin/GL601_R00A01V02.enc,,,,,1234$ +ACK:UPD,123456789012345,C031,10,0,0,1234,20210407101530,1234$ +NACK:UPD,123456789012345,C031,10,0,0,0,1234,20210407101530,1234$ AT@UPD=gl601###,1,,,,,,,,,,0125$ +ACK:UPD,123456789012345,C031,10,0,1,0125,20210407101530,1234$ +NACK:UPD,123456789012345,C031,10,0,1,2,0125,20210407101530,1234$ .. table:: :width: 100% :widths: 7 27 16 36 14 +-------+----------------------------------+---------------+---------------------------------------+---------------------+ | Parts | Fields | Length (Byte) | Range/Format | Default | +=======+==================================+===============+=======================================+=====================+ | Head | Header | 3 | AT@ | AT@ | + +----------------------------------+---------------+---------------------------------------+---------------------+ | | Command Word | 3 | UPD | UPD | + +----------------------------------+---------------+---------------------------------------+---------------------+ | | Leading Symbol | 1 | = | = | + +----------------------------------+---------------+---------------------------------------+---------------------+ | | Password | 8-16 | | gl601### | +-------+----------------------------------+---------------+---------------------------------------+---------------------+ | Body | `Sub Command` | 1 | 0-1 | | + +----------------------------------+---------------+---------------------------------------+---------------------+ | | `Update Type` | <=2 | Please see below. | | + +----------------------------------+---------------+---------------------------------------+---------------------+ | | Reserved | 0 | | | + +----------------------------------+---------------+---------------------------------------+---------------------+ | | Reserved | 0 | | | + +----------------------------------+---------------+---------------------------------------+---------------------+ | | `Download Timeout` | <=2 | 10 - 60 (minutes) | 10 | + +----------------------------------+---------------+---------------------------------------+---------------------+ | | `Download URL` | <=150 | A valid URL. | | + +----------------------------------+---------------+---------------------------------------+---------------------+ | | `Authentication Username` | <=6 | '0'-'9', 'a'-'z', 'A'-'Z' | | + +----------------------------------+---------------+---------------------------------------+---------------------+ | | `Authentication Password` | <=6 | '0'-'9', 'a'-'z', 'A'-'Z' | | + +----------------------------------+---------------+---------------------------------------+---------------------+ | | Reserved | 0 | | | + +----------------------------------+---------------+---------------------------------------+---------------------+ | | Reserved | 0 | | | +-------+----------------------------------+---------------+---------------------------------------+---------------------+ | Tail | Sequence Number | 4 | 0000-FFFF ('0'-'9', 'A'-'F') | | + +----------------------------------+---------------+---------------------------------------+---------------------+ | | Tail | 1 | $ | $ | +-------+----------------------------------+---------------+---------------------------------------+---------------------+ - `Sub Command` A numeral to indicate the sub command to be executed. - **0** - Start the firmware update. - **1** - Stop the firmware update. .. note:: If this field is 1, the other fields below can be empty. - `Update Type` The type of the firmware to be updated. - **1** - Tracker firmware. - **2** - Bluetooth firmware. - **6** - Modem firmware. - **8** - GNSS firmware. - `Download Timeout` If downloading is not finished within this time, it will be regarded that the downloading failed. - `Download URL` It specifies the URL to download the package. For GL601, the following URL types are supported: - **HTTP URL** - `Authentication Username` If the server (that corresponding to URL) uses authentication, the username is specified here. - `Authentication Password` If the server (that corresponding to URL) uses authentication, the password is specified here. .. _refx-manage-upd-f1: F1H (UPD Status) ---------------- During the firmware update process, the device reports its status including the update confirmation information, package downloading information and firmware update information to the backend server via this message (a report that only carries Record F1H) at different phases. .. code-block:: none For example (Total 41 bytes): 2B 00 00 29 00 01 23 45 67 89 01 23 45 C0 31 00 0A 00 00 12 66 8E 47 F7 00 00 F1 00 65 07 01 00 01 00 00 00 00 01 23 32 24 For example (Total 41 bytes): 2B 00 00 29 00 01 23 45 67 89 01 23 45 C0 31 00 0A 00 00 12 66 8E 47 F7 00 00 F1 00 65 07 02 00 01 00 00 00 00 01 23 DC 24 For example (Total 41 bytes): 2B 00 00 29 00 01 23 45 67 89 01 23 45 C0 31 00 0A 00 00 12 66 8E 47 F7 00 00 F1 00 65 07 03 00 01 00 00 00 00 01 23 69 24 .. table:: :width: 100% :widths: 11 13 15 16 35 10 +----------+--------------------+------------------+---------------+-----------------------------+---------------+ | Parts | Fields | Length (Byte) | Range/Format | Default | +==========+====================+==================+===============+=============================+===============+ | Head | | 18 or 20 | | | +----------+--------------------+------------------+---------------+-----------------------------+---------------+ | Reserved | | 1 or 1+N | | | +----------+--------------------+------------------+---------------+-----------------------------+---------------+ | Records | Record Length | 1 or 2 | 00H-7FH or 8080H-FFFFH | | + +--------------------+------------------+---------------+-----------------------------+---------------+ | | Generated Time | 4 | | | + +--------------------+------------------+---------------+-----------------------------+---------------+ | | `Record ID` | 1 | **F1H** | **F1H** | + +--------------------+------------------+---------------+-----------------------------+---------------+ | | `Event Code` | 1 | 00H | 00H | + +--------------------+------------------+---------------+-----------------------------+---------------+ | | `Data of Record` | Data ID | 1 or 2 | 00H-7FH or 8080H-FFFFH | | + + +------------------+---------------+-----------------------------+---------------+ | | | Data Length | 1 or 2 | 00H-7FH or 8080H-FFFFH | | + + +------------------+---------------+-----------------------------+---------------+ | | | Data Content | N | | | + + +------------------+---------------+-----------------------------+---------------+ | | | ... | | | | + +--------------------+------------------+---------------+-----------------------------+---------------+ | | ... | | | | +----------+--------------------+------------------+---------------+-----------------------------+---------------+ | Tail | | 4 | | | +----------+--------------------+------------------+---------------+-----------------------------+---------------+ The definitions of parts 'Head', 'Reserved', and 'Tail' are :ref:`here `. - `Event Code` The default is **00H**. - `Data of Record` Fixedly, this record contains only the following :ref:`Data ID units `: - :ref:`Data 101 ` - Upgrade Information.