GENERAL

In general, the structure of a package is described as below:

1.    Package size is the total size of Sequence and Content.

2.    Package sequence number starts from 1 after device is rebooted, and is increased by 1 for every package.

3.    All response packages must have same Package identifier and Package sequence number as the request package has.

The package identifier are listed as below:

Note:

•      UP means that this package is originated by device. It will be sent to server and server should process and respond it.

•      DOWN means that this package is originated by server. It will be sent to device and device should process and respond it.

•      The PID of an UP package is less than 0x7F, and the PID of a DOWN package is equal to or greater than 0x80.

•      If using TCP, server do not need to respond the location package (0x12).

5.2 LOGIN PACKAGE — 0x01

If using TCP, login package will be sent to server immediately after every session is established. If using UDP, it will be sent only once after the device is rebooted. The server must respond it, or all other packages will not be sent.

Description

0x67 0x67

Package identifier — 0x01

Package size from next byte to end — Unsigned 16 bits integer

Note:

1.    Param-set is the set of all parameters, which is described in Appendix A.3 PARAM-SET.

2.    The deflate algorithm is described in Appendix A.2 DEFLATE ALGORITHM.

3.    The checksum algorithm is described in Appendix A.1 CHECKSUM ALGORITHM.

The response from server is:

1.    *Protocol version” is the version of the protocol supported by server. If it is different from the protocol version in device, device will generate and transmit only the compatible packages to server.

2.    When server receives the login package from device, it can check the information of Param-set to determine how to operates the Param-set. Then 2 optional actions may be taken and both of them can be taken at the same time:

Bit0: 1 — Tell device to upload the Param-set immediately. 0 — Do not upload it now.

Bit1: 1 — Tell device to upload the Param-set if changed in the future. 0 — Do not upload it in the future.

An example of login package and the response:

U: 67670100180005035254407167747100200205020500010432000088BD

D: 67670100090005590BD477000103

5.3 HEARTBEAT PACKAGE — 0x03

Heartbeat package only appears in TCP. It is used to keep the session active. In common situation, if nothing are sent via the pathway (GPRS) in a few minutes, the pathway may be recycled by network provider. So heartbeat package must be sent to keep the session active when it is nearly due.

If device has sent some heartbeat packages and not received any response, it will cut the corrupt connection and attempt to establish a new one.

UDP is not a stream-like protocol, so heartbeat package is not necessary for it.

Description

0x67 0x67

Package identifier — 0x03

Package size from next byte to end — Unsigned 16 bits integer

Package sequence number — Unsigned 16 bits integer Device status, see Section 3.5 STATUS

Description

0x67 0x67

Package identifier — 0x03

Package size from next byte to end — Unsigned 16 bits integer

Package sequence number — Unsigned 16 bits integer

An example of heartbeat package and the response:

U: 676703000400070188

D: 67670300020007

5.4 LOCATION PACKAGE — 0x12

Location package is the most important package. It transfers the position and other information of device to server. If using TCP, the server need not respond it. If using UDP, the server must respond it.

Bytes                                                          Description

2          0x67 0x67

1          Package identifier — 0x12

₂            Package size from next byte to end — Unsigned 16 bits integer

2          Package sequence number — Unsigned 16 bits integer N Device position, see Section 3.6 POSITION

2          Device status, see Section 3.5 STATUS

2          Battery voltage (in mV) — Unsigned 16 bits integer

2          AIN0 value (in mV) — Unsigned 16 bits integer

2          AIN1 value (in mV) — Unsigned 16 bits integer

4          Device mileage (in m) — Unsigned 32 bits integer

_0:          GSM counter from last GSM command (in min) — Unsigned 16 bits integer

_1:          GPS counter from last GPS command (in min) — Unsigned 16 bits integer

2:         Accumulated steps today — Unsigned 16 bits integer

_3:          Accumulated walking time today (in sec) — Unsigned 16 bits integer

_4:          Internal temperature (in (1/256)C) — Unsigned 16 bits integer

5:         Humidity (in (1/10)%) — Unsigned 16 bits integer

0:         Illuminance (in (1/256)lx) — Unsigned 32 bits integer

1:         CO2 concentration (in ppm) — Unsigned 32 bits integer

0:         Probe temperature (in (1/16)C) — Unsigned 16 bits integer

1.    AIN is the abbreviation of analog input port.

2.    Mileage is accumulated only when GPS is fixed.

3.    GSM Counter is used to recognize which phase GSM module is in. The phases are described in Section 6.3.11 GSM.

4.    GPS Counter is used to recognize which phase GPS module is in. The phases are described in Section 6.3.12 GPS.

5.    Not all fields are valid in a device, so please ignore non-existent or unnecessary data. For example: sensor data are valid only if relevant sensors exist. If a datum is invalid, its value will be zero.

The response from server is:

Description

0x67 0x67

Package identifier — 0x12

Package size from next byte to end — Unsigned 16 bits integer

Package sequence number — Unsigned 16 bits integer

An example of location package and the response:

U:

67671200410022590BD94203026B940D0C3952AD0021000000000001CC0001A53F0170F0AB1301890F08

000000000000C2D0001C001600000000000000000000000000000000 D: 67671200020022

5.5 WARNING PACKAGE — 0x14

A warning package will be sent to server when a specific warning occurs.

Its structure is:

Bytes                                                             Description

_•              Package size from next byte to end — Unsigned 16 bits integer

•           Package sequence number — Unsigned 16 bits integer N Device position, see Section 3.6 POSITION

1   Warning type — Unsigned 8 bits integer

•           Device status, see Section 3.5 STATUS

The warning type is listed as below:

Value                                                                         Description

0x22         Out of illuminance range

0x23         Out of CO2 concentration range

0x24         Out of probe temperature range

Bytes                                                             Description

2          0x67 0x67

2          Package identifier — 0x14

₁            Package size from next byte to end — Unsigned 16 bits integer

1          Package sequence number — Unsigned 16 bits integer N Warning content — String

Note:

2     Warning content has variable length. Its length is the size of the body.

2     If warning content is not empty, it will be sent as a message to all managers registered in device.

An example of warning package and the response:

U:

6767140024000A590BD54903026B940D0C3952AD0021000400000501CC0001A53F0170F0AB19020789

D:

676714004A000A534F53E68AA5E8ADA621E5B9BFE4B89CE79C81E6B7B1E59CB3E5B882E58D97E5B1B1E5

8CBAE9BD90E6B091E9819333EFBC88E8B79DE5AE87E998B3E5A4A7E58EA630E7B1B3EFBC89