.. _headlabel-refx-frames-configuration: Configuration Command and Acknowledgement ========================================= As mentioned :ref:`earlier `, `Configuration Command`, `ACK` and `NACK` frames are often used together. .. _refx-frames-configuration-command: Configuration Command --------------------- The configuration command is used to set the working parameters of the terminal device. All configuration commands are encoded using printable `ASCII` characters, and the character ',' is used to separate the neighboring parameter characters, as follows: .. code-block:: none Example: AT@APN=gl601###,,cmnet,,,0,,012F$ AT@TMA=gl601###,0,+32,0,,time.windows.com,123,0387$ AT@AGPS=gl601###,1,1,,,1101$ .. table:: :width: 100% :widths: 7 27 16 34 16 +-------+----------------+---------------+---------------------------------------------------+--------------+ | Parts | Fields | Length (Byte) | Range/Format | Default | +=======+================+===============+===================================================+==============+ | Head | Header | 3 | AT@ | AT@ | + +----------------+---------------+---------------------------------------------------+--------------+ | | Command Word | <=10 | 'A'-'Z', '0'-'9' | | + +----------------+---------------+---------------------------------------------------+--------------+ | | Leading Symbol | 1 | = | = | + +----------------+---------------+---------------------------------------------------+--------------+ | | Password | 8-16 | '0'-'9', 'a'-'z', 'A'-'Z', '-', '_', '#' | gl601### | +-------+----------------+---------------+---------------------------------------------------+--------------+ | Body | Parameters | N | Refer to the detailed definition of each command. | | +-------+----------------+---------------+---------------------------------------------------+--------------+ | Tail | Sequence Number| 4 | 0000-FFFF ('0'-'9', 'A'-'F') | | + +----------------+---------------+---------------------------------------------------+--------------+ | | Tail | 1 | $ | $ | +-------+----------------+---------------+---------------------------------------------------+--------------+ - `Command Word` Used to indicate which command to configure. Please refer to :ref:`Commands ` for the command words supported by the terminal device and the definition of 'Parameters' it carries. - `Password` The password of the terminal device, the default is "gl601###", which can be changed by the :ref:`AT@CFG ` command. - `Parameters` Corresponding to 'Command Word', that means the content, length and meaning are all determined by 'Command Word'. Parameters usually contains multiple fields separated by commas. And a field of length 0 is called an `empty field`, which means: - It may just represent a 'Reserved' field, without clear meaning and function. - Unless otherwise stated, an empty field means that the contents of this field are not changed, that is, the last configured value is left unchanged. - `Sequence Number` The sequence number of the command. It will be included in the `ACK` or `NACK` frame (see below) of the terminal device responding to the command. .. note:: 'Header', 'Leading Symbol', and 'Tail' are continuous between the fields adjacent to them, not separated by commas. **THIS NOTE WILL NOT BE REPEATED ELSEWHERE**. ACK and NACK ------------ When the terminal device receives a configuration command (or real-time operation command), it will always respond with an ACK or NACK frame, where ACK indicates that the configuration command is legitimate (supported), and NACK indicates that it is illegal (unsupported). ACK and NACK are also encoded using printable `ASCII` characters, and the character ',' is used to separate the neighboring parameter characters. .. _refx-frames-configuration-ack: ACK Format ~~~~~~~~~~ The frame format of ACK is as follows: .. code-block:: none Example: +ACK:APN,123456789012345,C031,10,0,,012F,20210407101530,1234$ +ACK:TMA,123456789012345,C031,10,0,,0378,20210407101540,1235$ +ACK:RTO,123456789012345,C031,10,0,1,028A,20210407101550,1236$ +ACK:QRC,123456789012345,C031,10,0,03,A052,20210407101554,1237$ .. table:: :width: 100% :widths: 7 27 16 34 16 +-------+--------------------+---------------+--------------------------------+-------------+ | Parts | Fields | Length (Byte) | Range/Format | Default | +=======+====================+===============+================================+=============+ | Head | Header | 4 | +ACK | +ACK | + +--------------------+---------------+--------------------------------+-------------+ | | Leading Symbol | 1 | : | : | + +--------------------+---------------+--------------------------------+-------------+ | | Command Word | <=10 | 'A'-'Z', '0'-'9' | | + +--------------------+---------------+--------------------------------+-------------+ | | IMEI | 15 | | | + +--------------------+---------------+--------------------------------+-------------+ | | Device Type | 4 | 0000-FFFF ('0'-'9', 'A'-'F') | C031 | + +--------------------+---------------+--------------------------------+-------------+ | | Protocol Version | 1-5 | 1-65535 | 10 | + +--------------------+---------------+--------------------------------+-------------+ | | Custom Version | 1-3 | 0-255 | 0 | +-------+--------------------+---------------+--------------------------------+-------------+ | Body | Flexible Field | N | Please see below. | | +-------+--------------------+---------------+--------------------------------+-------------+ | Tail | Sequence Number | 4 | 0000-FFFF ('0'-'9', 'A'-'F') | | + +--------------------+---------------+--------------------------------+-------------+ | | Generated Time | 14 | YYYYMMDDHHMMSS | | + +--------------------+---------------+--------------------------------+-------------+ | | Count Number | 4 | 0000-FFFF ('0'-'9', 'A'-'F') | | + +--------------------+---------------+--------------------------------+-------------+ | | Tail | 1 | $ | $ | +-------+--------------------+---------------+--------------------------------+-------------+ - `Command Word` Corresponding to the 'Command Word' in the configuration command. - `IMEI` The International Mobile Equipment Identity of the terminal device. - `Device Type` The type of terminal device. For GL601, it is **"C031"**. - `Protocol Version` The version number of this @Track protocol. For example, "1" means V1, "12" means V12, and "123" means V123. - `Custom Version` This version number is reserved for user customization. For example, "1" means V1, "12" means V12, and "123" means V123. If the custom version number has not been set, it defaults to "0". - `Flexible Field` This field is prepared for some special commands that need to carry additional necessary information, and the meaning is also determined by these commands. In fact, this field is only meaningful in the following commands, and it is an empty field (length is 0) in all other commands: +---------------------------------------------------+---------------------+ | Command | Parameter | +===================================================+=====================+ | :ref:`AT@RTO ` | `Sub Command` | +---------------------------------------------------+---------------------+ | :ref:`AT@UPD ` | `Sub Command` | +---------------------------------------------------+---------------------+ | :ref:`AT@QRC ` | `Record ID` | +---------------------------------------------------+---------------------+ | :ref:`AT@BTBCN ` | `Group ID` | +---------------------------------------------------+---------------------+ | :ref:`AT@ETH ` | `Alarm ID` | +---------------------------------------------------+---------------------+ | :ref:`AT@GEO ` | `GEO ID` | +---------------------------------------------------+---------------------+ | :ref:`AT@PROFILE ` | `Profile ID` | +---------------------------------------------------+---------------------+ | :ref:`AT@WIFIGEO ` | `GEO ID` | +---------------------------------------------------+---------------------+ Some examples are given below: - :ref:`AT@RTO ` When responding to the AT\@RTO command, this field corresponds to the **'Sub Command'** field in the command to indicate which subcommand to respond to. For example, *+ACK:RTO,123456789012345,C031,10,0,1,028A,20210407101550,1236$* responds to subcommand 1 (Request the terminal to report its current position). - :ref:`AT@UPD ` When responding to the AT\@UPD command, this field corresponds to the **'Sub Command'** field in the command to indicate which subcommand to respond to. For example, *+ACK:UPD,123456789012345,C031,10,0,0,028A,20210407101550,1236$* responds to subcommand 0 (Start the firmware update). - :ref:`AT@QRC ` When responding to the AT\@QRC command, this field corresponds to the **'Record ID'** field in the command to indicate which record to respond to. For example, *+ACK:QRC,123456789012345,C031,10,0,03,A052,20210407101554,1237$* responds to Record 03H (Connection Starts). - :ref:`AT@PROFILE ` When responding to the AT\@PROFILE command, this field corresponds to the **'Profile ID'** field in the command to indicate which profile ID to respond to. For example, *+ACK:PROFILE,123456789012345,C031,10,0,0,012F,20210407101530,1234$* responds to profile 0 (Default). For example, *+ACK:PROFILE,123456789012345,C031,10,0,0|63,012F,20210407101530,1234$* responds to profile 0 (Default) and profile 63 (Emergency). For example, *+ACK:PROFILE,123456789012345,C031,10,0,,012F,20210407101530,1234$* responds to all profiles. - :ref:`AT@GEO ` When responding to the AT\@GEO command, this field corresponds to the **'GEO ID'** field in the command to indicate which GEO ID to respond to. For example, *+ACK:GEO,123456789012345,C031,10,0,1,012F,20210407101530,1234$* responds to GEO ID 1. - `Sequence Number` Corresponding to the sequence number in the configuration command. - `Generated Time` The UTC time when the frame was generated, in 'YYYYMMDDHHMMSS' format. For example, "20230907105030" indicates the UTC time *September 7,2023,10:50:30*. - `Count Number` A self-increasing count number in each acknowledgement message. It begins from "0000" and increases by 1 for each acknowledgement message. And it rolls back after "FFFF". .. note:: The ACK frame only indicates that the terminal device has received the command, but does not mean that the command has been successfully executed; the terminal device will send a report to inform the backend server of the execution result of the command when necessary. .. _refx-frames-configuration-nack: NACK Format ~~~~~~~~~~~ The frame format of NACK is as follows: .. code-block:: none Example: +NACK:APN,123456789012345,C031,10,0,,0,012F,20210407101530,1234$ +NACK:TMA,123456789012345,C031,10,0,,1,0378,20210407101540,1235$ +NACK:RTO,123456789012345,C031,10,0,1,2,028A,20210407101550,1236$ +NACK:QRC,123456789012345,C031,10,0,03,1,A052,20210407101554,1237$ .. table:: :width: 100% :widths: 7 27 16 34 16 +-------+---------------------+---------------+--------------------------------+-------------+ | Parts | Fields | Length (Byte) | Range/Format | Default | +=======+=====================+===============+================================+=============+ | Head | Header | 5 | +NACK | +NACK | + +---------------------+---------------+--------------------------------+-------------+ | | Leading Symbol | 1 | : | : | + +---------------------+---------------+--------------------------------+-------------+ | | Command Word | <=10 | 'A'-'Z', '0'-'9' | | + +---------------------+---------------+--------------------------------+-------------+ | | IMEI | 15 | | | + +---------------------+---------------+--------------------------------+-------------+ | | Device Type | 4 | 0000-FFFF ('0'-'9', 'A'-'F') | C031 | + +---------------------+---------------+--------------------------------+-------------+ | | Protocol Version | 1-5 | 1-65535 | 10 | + +---------------------+---------------+--------------------------------+-------------+ | | Custom Version | 1-3 | 0-255 | 0 | +-------+---------------------+---------------+--------------------------------+-------------+ | Body | Flexible Field | N | | | + +---------------------+---------------+--------------------------------+-------------+ | | Cause | 1-2 | 0-99 | | +-------+---------------------+---------------+--------------------------------+-------------+ | Tail | Sequence Number | 4 | 0000-FFFF ('0'-'9', 'A'-'F') | | + +---------------------+---------------+--------------------------------+-------------+ | | Generated Time | 14 | YYYYMMDDHHMMSS | | + +---------------------+---------------+--------------------------------+-------------+ | | Count Number | 4 | 0000-FFFF ('0'-'9', 'A'-'F') | | + +---------------------+---------------+--------------------------------+-------------+ | | Tail | 1 | $ | $ | +-------+---------------------+---------------+--------------------------------+-------------+ - `Cause` It is used to indicate the specific reason for the NACK to be triggered. - **0** - The password or parameter is incorrect. - **1** - The terminal device does not support this command. - **2** - The terminal device is not allowed to execute this command now, probably for security reasons. NACK has one more 'Cause' field than ACK frame, and the meaning of other fields is the same. .. note:: In order to avoid network attacks, the terminal device will not send a NACK to the backend server after continuously sending **5** NACKs until it receives a legitimate (supported) command, or after one hour.