英文写作

 

 

 

GPS Vehicle Tracker Communication Protocol 

 

 

Table of Contents

Preface. 5

Terminologies. 5

Protocol Overview.. 5

General Constrains. 5

Rules for IP Resolving. 6

Communication Flow.. 6

Packet Format. 6

Header 7

Protocol 7

Length. 7

Sequence. 7

Packet Body. 7

Login Packet (0x01) 8

GPS Packet (0x02) 9

Heartbeat Packet (0x03) 11

Alarm Packet (0x04) 12

ACC Packet (0x05) 13

SMS Uplink Command Packet (0x06) 14

Downlink Command Packet (0x80) 15

Common Downlink Message Packet (0x81) 15

BS Packet (0x91) 16

Extended Heartbeat Packet (0x07) 18

Time Calibration Packet (0x08) 20

Downlink Command List. 20

 

Preface

This document specifies the protocol used for the communication between vehicle trackers and our vehicle-tracking platform using GPS.

Terminologies

Abbreviations	Terms
CMPP	China Mobile Peer to Peer
GPS	Global Positioning System
GSM	Global System for Mobile Communication
GPRS	General Packet Radio Service
TCP	Transport Control Protocol
LBS	Location Based Services
IMEI	International Mobile Equipment Identity
MCC	Mobile Country Code
MNC	Mobile Network Code
LAC	Location Area Code
Cell ID	Cell Tower ID
RSSI	Received Signal Strength Indicator
UDP	User Datagram Protocol
SOS	Save Our Ship/Save Our Souls
CRC	Cyclic Redundancy Check
NITZ	Network Identity and Time Zone,
GIS	Geographic Information System

Protocol Overview

General Constrains

1.       Byte Order

With field values that occupy more than one bytes in the protocol, they should be in network byte order, also known as Big Endian. You may visit the Wikipedia page on Big Endian for more information.

2.       Any time value in packet body should be in UTC.

You may visit the Wikipedia page on UTC for more information.

3.       The size of a data packet should be less than 1024 bytes.

Rules for IP Resolving

Trackers should implement the mechanism to cache IP for a specified domain, and generally use this cached IP to try to connect to the server without asking DNS server to resolve the domain. If connecting to the server fails for three times using a cached IP, then this is the time when asking DNS server for the new IP of the domain is needed.

The benefits of the IP cache strategy are as follows:

ž  Asking DNS to resolve for a domain is time consuming, and using IP cache is faster.

ž  To reduce the overload of DNS server and avoid domain resolving failures.

ž  To insure connectivity to our platform in case of DNS server downtime.

Notice that there is some consideration about the limit on the number of times trying to connect using a cached IP with failures. Consider that if the sever IP has changed, then the cached IP is outdated, and trying to establish connection with the cached IP will fail. Plus, it takes about 20 to 60 seconds each time to try to establish connection. Therefore, if the times limit is too big, then the total amount of time wasted to establish connection with an outdated IP with failures should be tremendous. Given this consideration, and for the overall outcome of connectivity, we recommend that you set the times limit to be 3, that is, if a tracker tries to connect with a cached IP fails for 3 times, then it should request DNS server to resolve the domain for the correct IP.

Communication Flow

The communication flow between trackers and our vehicle-tracking platform is as follows:

ž  Start a tracker and connect to our vehicle-tracking platform, then send a login packet to login the platform. Trackers should send a login packet as the first one packet after connection.

ž  After login, the tracker may send GPS data to our server regularly if it has new data to transmit.

ž  To ensure connectivity, the tracker should send Heartbeat packets to our server at regular time, and the server will send response packets back to the tracker to confirm connectivity.

ž  If the Protocol Number and Message Sequence Number of a packet sent from a tracker are the same as that of a responded packet from our server respectively, then the two packets are matched.

Packet Format

Fields	Header	Protocol	Length	Sequence	Body
Bytes	2	1	2	2	N

The total size of a packet is 7+N bytes.

This format applies to both uplink and downlink packets.

Header

Header field occupies 2 bytes, and its value fixes to 0x67 0x67.

Protocol

Protocol field occupies 1 byte and defines the type of a packet. The table below lists all the protocols with descriptions.

Protocols	Descriptions	Response Required
0x01	Login Packet	Yes
0x02	GPS Packet	No
0x03	Heartbeat Packet	Yes
0x04	Alarm Packet	Yes
0x05	ACC Packet	Yes
0x06	SMS Uplink Command Packet	Yes
0x80	Downlink Command Packet	Yes
0x81	Common Downlink Message Packet	No
0x91	BS Packet	No
0x07	Extended Heartbeat Packet	Yes
0x08	Time Calibration Packet	Yes

Length

Length field occupies 2 bytes. The value of Length field is calculated by adding the size of Sequence field and the size of Body field.

Sequence

Sequence field occupies 2 bytes.

After a tracker has been booted, the Sequence value of the first packet sent from the tracker is marked with ‘1’. For subsequent packets, Sequence value should be increased by 1 for each packet. When the value reaches 65535, it should be reset to 1 again.

Packet Body

In the following paragraphs, we will describe each type of packet by their Body fileds in detail.

Login Packet (0x01)

Format	Body
	Tracker ID	Language
Bytes	8	1

Before transmitting other packets, a tracker should send a Login packet to our vehicle platform for the authentication of the connection.

1.       Tracker ID (8 bytes)

The value of Tracker ID field is an IMEI (which is a number with 12 or 15 decimal digitals) specified in hexadecimal notation.

e.g.

IMEI: 123456789012345

Tracker ID: 0x01 0x23 0x45 0x67 0x89 0x01 0x23 0x45

2.       Language (1 byte)

Code	Language
0x00	简体中文
0x01	English

    

This field specifies the language of information transmitting between a tracker and the server.

In cases where trackers need the server to response with literal information, then the Language field specifies the language of the information that the server should response.

e.g.

In case of SOS alarm, when the Language filed is specified as Chinese, then the message returned by the server may be:

SOS报警：广东省.深圳市.宝安区留仙一路.G4.离高新奇科技股份有限公司约86米.离高新奇工业区约88米

And when you specify the language to be English, then the message returned by the server may be:

SOS! http://maps.google.com/?q=22.577308,113.916685<DateTime:2013-01-22 19:40:00>

 

3.       Packet Example

The packet a tracker send to the server may be as follows:

0x67 0x67	0x01	0x00 0x0B	0x00 0x01	0x010x23 0x45 0x67 0x89 0x01 0x23 0x45	0x00
Header	Protocol	Length	Sequence	Tracker ID	Language

The decimal result of the value of the Tracker ID field above is 123456789012345.

The packet the server response to the tracker will be as follows:

0x67 0x67	0x01	0x00 0x02	0x00 0x01
Header	Protocol	Length	Sequence

Notice that the value of the Protocol field of the response packet is the same as that of the first packet sent from the tracker.

GPS Packet (0x02)

Format	Body
	Time	Latitude	Longitude	Speed	Course	BS	Status
Bytes	4	4	4	1	2	9	1

1.       Time

Time field occupies 4 bytes. The value is in UTC format and round to seconds.

2.       Latitude

Latitude field occupies 4 bytes, and represents the latitude of the position of a tracker. Its value ranges from -162000000 to 162000000 in decimal notation; in sexagesimal notation, that is from -90 degrees (southward latitudes) to 90 degrees (northward latitudes). For transmission, the value of Latitude field should be specified in hexadecimal notation, and its unit is 1/500 seconds. The representation in sexagesimal notation using degrees and minutes can be converted to the representation using the unit 1/500 seconds as follows:

Firstly, convert the output latitude (expressed in degrees and minutes) of GPS module to a decimal fraction in unit minutes.

Secondly, multiply the result of the first step and 30000, and then convert the new result to its hexadecimal notation.

e.g.

North latitude 22°32.7658′should be converted to (22×60 + 32.7658)*30000=40582974, then to hexadecimal notation as x02 0x6B 0x3F 0x3E.

South latitude -22°32.7658′should be converted to (-22×60 + ( -32.7658))*30000=-40582974, and then to hexadecimal notation as 0xFD 0x94 0xC0 0xC2.

3.       Longitude

Longitude field occupies 4 bytes, and represents the longitude of the position of a tracker. Its value ranges from -324000000 to 324000000 in decimal notation; in sexagesimal notation, that is from -180 degrees (westward longitudes) to 180 degrees (eastward longitudes). For transmission, the value of Longitude field should be specified in hexadecimal notation, and its unit is 1/500 seconds. The representation in sexagesimal notation using degrees and minutes can be converted to the representation using the unit 1/500 seconds. The way of conversion is the same as that of the Latitude field described above.

4.       Speed

Speed field occupies 1 byte, and represent the velocity of a tracker measured using GPS. The value range of Speed field is 0x00～0xFF, corresponding to 0～255 miles/hour.

5.       Course

Course field occupies 2 bytes, and represent the heading of a tracker measured using GPS. The value of Course field ranges from 0 to 360, and its unit is degree. The value is 0 for true north, and increases clockwise.

6.       BS

Format	MCC	MNC	LAC	CI
Bytes	2	2	2	3

The abbreviation BS stands for Base Station, and occupies 9 bytes.

e.g. (One of the base stations in China)

0x01 0xCC	0x00 0x01	0x27 0x49	0x00 0x0C 0xEE
MCC	MNC	LAC	CI

7.       Status

High							Low
7	6	5	4	3	2	1	0

Status field occupies 1 byte, and represents the positioning state of a tracker. Notice that 1 byte consists of 8 bits, and we number the lowest bit as position 0, and the highest bit as position 7. At the time of transmission, higher position bits should be sent prior to lower position bits. The specification of each bit is as follows:

Position 0	0: GPS not positioned 1: GPS positioned
Position 1	Reserve
Position 2	Reserve
Position 3	Reserve
Position 4	Reserve
Position 5	Reserve
Position 6	Reserve
Position 7	Reserve

8.       Server Response

The server does not need to response to GPS packets sent from trackers.

9.       Note

Trackers generally do not need to send old data to the server if there is no new GPS positioning results, but except for some otherwise purposes, in circumstances such as alarming, etc.

Heartbeat Packet (0x03)

Format	Body
	Status
Bytes	2

A tracker should send Heartbeat packets at a fixed-frequency to confirm connectivity between the tracker and the server.

1.       Status

High							Low
15	14	…	…	…	…	1	0

Status field occupies 2 bytes, and represents the positioning state of a tracker. Notice that 1 byte consists of 8 bits, and we number the lowest bit as position 0, and the highest bit as position 7. As for the second byte, you should continue numbering the lowest bit of this byte as position 8, and so on. At the time of transmission, higher position bits should be sent prior to lower position bits. The specification of each bit is as follows:

Position 0	0: GPS not positioned 1: GPS positioned
Position 1,2	10: ACC off 11: ACC on 00: State undefined
Position 3,4	10: Defense unset 11: Defense set up 00: State undefined
Position 5,6	10: Oil and electricity off 11: Oil and electricity on 00: State undefined
Position 7,8	10: Battery charger unplugged 11: Battery charger plugged 00: State undefined
Position 9	Reserve
…	…
Position 14	Reserve
Position 15	Reserve

e.g.

With 0x00BB, that is 1011 1011 in binary notation, the status of the tracker should be “GPS positioned, ACC off, Defense set up, Oil and electricity off and Battery charger unplugged”.

2.       Packet Example

The Heartbeat packet sent from a tracker to the server:

0x67 0x67	0x03	0x00 0x04	0x00 0x1A	0x00 0x01
Header	Protocol	Length	Sequence	Status

The response packet by the server:

0x67 0x67	0x03	0x00 0x02	0x00 0x1A
Header	Protocol	Length	Sequence

Notice that the value of the Protocol field of the response packet is the same as that of the Heartbeat packet sent from the tracker.

Alarm Packet (0x04)

Format	Body
	Time	Latitude	Longitude	Speed	Course	BS	Status	Alarm Type
Bytes	4	4	4	1	2	9	1	1

When something triggers some kind of alarm, a tracker sends Alarm packets to the server.

For the specification of Time, Latitude, Longitude, Speed, BS and Status, please refer to GPS Packet section for more information.

1.   Alarm Type

Value	Alarm Type
0x01	Power off
0x02	SOS
0x03	Low battery
0x04	Vibration
0x05	Displacement
0x06	Into dead zone
0x07	Out of dead zone
0x08	GPS antenna open circuit
0x09	GPS antenna short circuit
0x0a	Light sensation
0x0b	Magnetic sensation
0x0c	Anti-dismantle
0x0d	Over speed
0x0e	Signal shielding

2.   Server Response

Format	Body
	Alarm SMS
Bytes	N

   

When the server receives an Alarm packet from a tracker, it will then send a response packet with an alarm text back to the tracker; And after receiving the response packet, the tracker may then send a SMS with the alarm text to a phone using the center phone number or SOS number specified in the tracker. Notice that, in some cases the alarm text from the server might be an empty string, where a tracker should have a check and not send the text to the user.

Alarm texts from the server are in UTF-8 Encoding.

e.g.

The alarm text may be “SOS! http://maps.google.com/?q=22.577308,113.916685<DateTime:2013-01-22 19:40:00>”.

ACC Packet (0x05)

Format	Body
	Time	Latitude	Longitude	Speed	Course	BS	Status	ACC Type	ACC Time
Bytes	4	4	4	1	2	9	1	1	N

ACC Packet is an extension for GPS Packet, used for collecting the ACC state of a tracker. Whenever ACC state has changed, a tracker should send this packet to the server.

For the specification of Time, Latitude, Longitude, Speed, BS and Status, please refer to GPS Packet section for more information.

1.       ACC Type

ACC Type	ACC Time	Description
0x01	From Tracker(4 bytes，UTC, round to seconds)	ACC on
0x02	From Tracker(4 bytes，UTC, round to seconds)	ACC off

2.       Server Response

Format	Body
	(Empty)
Bytes	0

3.   Note

Tracker side should take the responsibility to synchronize its local time with that from GPS.

SMS Uplink Command Packet (0x06)

Format	Body
	Time	Latitude	Longitude	Speed	Course	BS	Status	Phone	SMS Command
Bytes	4	4	4	1	2	9	1	21	N

User may use a mobile phone to send SMS text as a command to a tracker (through the sim card installed in the tracker). After receiving a command from a phone, a tracker may execute it locally or pass it to the server to execute (see the rules below for more detail).

For the specification of Time, Latitude, Longitude, Speed, BS and Status, please refer to GPS Packet section for more information.

1.       Phone

The value of Phone field is in ASCII encoding, and represents the number of a phone that sends a SMS text command to a tracker. If the length of a phone number expressed in hexadecimal notation is less than 21 bytes, then add copies of 0x00 to the right of the value to fulfill the length criteria.

2.       SMS Command

SMS Command text is in UTF-8 encoding, it may be processed on the tracker side or on the server.

Rules that decide where to execute a command:

ž  Command text that is in the command list defined in a tracker, such as “STATUS#”, will run on the tracker side.

ž  Command text that does not include Chinese characters, and with a length bigger than 2 chars and less than 30 chars, should be passed to the server to process. Such as “position#” or “123” (User may send one of these two texts to get the location of a tracker).

3.       Server Response

     

Format	Body
	Phone	Response
Bytes	21	N

    

Response text from the server is in UTF-8 encoding. After receiving the response packet from the server, a tracker may pass the response text to the user by the phone number in that packet. If the response text is empty (0 bytes), a tracker may not need to pass anything to the phone specified.

Downlink Command Packet (0x80)

Format	Body
	Flag	Server Flag	Content
Bytes	1	4	N

Users may login our web site (www.cootrack.net) and use command-sending features on the site to control their trackers.

1.       Flag

Flag	Description
0x01	Command
0x02	Reserve

2.       Server Flag

Tracker side does need to process this field, but put it right in the response packet to send back to the server.

3.       Content

The command text to send to a tracker, using UTF-8 encoding. See Downlink Command List section for the definition of each command.

4.       Tracker Response

Format	Body
	Flag	Server Flag	Response
Bytes	1	4	N

Response text from tracker side to the server is in UTF-8 encoding.

Common Downlink Message Packet (0x81)

Format	Body
	Flag	Content
Bytes	1	N

Users may login our web site (www.cootrack.net) and use corresponding features on the site to tell the server to send text to a tracker. The tracker may then display the text on a screen or pass it to a mobile phone according to the type flag in the packet.

5.       Flag

Flag	Type	Description
0x01	Relay	Pass the text to a mobile phone

ž  Relay (0x01)

Format	Phone	Text
Bytes	21	N

Note: If the value of Phone field is 21 copies of 0x00, that means the tracker should pass the text to a phone by the Center Number or SOS number specified in the tracker.

BS Packet (0x91)

Format	Body
	Time	TA	MCC	MNC	BS Count	BS 1	BS 2	BS 3	BS 4	BS 5	Status
Bytes	4	1	2	1	1	6	6	6	6	6	1

1.       Time

Time field occupies 4 bytes. The value is in UTC format and round to seconds. Noticed that it should be transmitted in big-endian order (also referred to as network byte order).

2.       TA (Timing Advance)

The TA value is normally between 0 and 63. TA values can only be captured during phone call or SMS sending phases, otherwise you may get a TA value of 255, and that is an invalid value. Multiply the TA value and 550 meters to get the distance between a tracker and a primary cell. You may refer to the Wikipedia page on Timing Advance for more information.

3.   MCC

A mobile country code (MCC) is used in combination with a mobile network code (MNC) (also known as a "MCC / MNC tuple") to uniquely identify a mobile network operator (carrier). The value of MCC is between 0x0000 and 0x03E7 expressed in hexadecimal notation. You may refer to the Wikipedia page on MCC and MNC for more information.

4.       MNC

Please refer to the Wikipedia page on MCC and MNC for more information.

5.       BS Count

BS Count represents the number of base stations, of which the location data is included in the packet. So for example, if the BS Count value is 3, then there should be exactly 3 BS data fields following the BS Count field. The max value of this field is 5, and if a tracker can get location data from more than 5 base stations, it should report only the data from the 5 base stations which have stronger signals. The order of base stations in the packet depends on their signal strengths; that is the station with the strongest signal comes first during transmission.

Notice that the number of the following BS fields should be the same as the value specified in the BS Count filed. Therefore, if the BS Count value is 5, and you have got data from only 3 base stations, then you should fill the last 2 BS fields with value 0 specifically.

6.       BS

LAC	CI	RSSI
2	3	1

The BS field consists of LAC, CI and RSSI.

ž  LAC is the abbreviation of Location Area Code. The value of LAC occupies 2 bytes and is in hexadecimal notation, ranges from 0x0001 to 0xFFFE (notice that 0x0000 and 0xFFFF are not included). A location area may contain one or more cells.

ž  CI is the abbreviation of Cell ID, and represents the ID of a primary cell tower available. The value of CI ranges from 0x000000 to 0xFFFFFF.

ž  RSSI is the abbreviation of Received Signal Strength Indicator, and represents the signal strength of the primary cell. The value of RSSI ranges from 0x00 to 0xFF. The sign of original value is negative, but the data sent should be an absolute value.

7.       Status

High							Low
7	6	5	4	3	2	1	0

Status field occupies 1 byte, and represents the positioning state of a tracker. Notice that 1 byte consists of 8 bits, and we number the lowest bit as position 0, and the highest bit as position 7. At the time of transmission, higher position bits should be sent prior to lower position bits. The specification of each bit is as follows:

Position 0	0: GPS not positioned 1: GPS positioned
Position 1	0: Automatic Packet 1: Triggered by SMS
Position 2	Reserve
Position 3	Reserve
Position 4	Reserve
Position 5	Reserve
Position 6	Reserve
Position 7	Reserve

8.   Server Response

The server does not need to response to BS packets.

9.       Note

Base station positioning is far less accurate than GPS positioning, so it is a consideration only when GPS positioning is not available.

Because of the rough precision of 100 meters to 10,000 meters of base station positioning, when a tracker receives a SMS request for positioning, it should try to collect Timing Advance data to assist the positioning, plus, the value of position 1 of the Status field should be 1 for SMS triggered positioning.

Moreover, because of the rough precision, trackers do not need to send base station positioning data every 10 seconds. The sending condition may be this: it is beyond 20 seconds since the last sending, and the positioning data of the three stations which have stronger signals has changed.

Extended Heartbeat Packet (0x07)

Format	Body
	Status	GSM Signal Level	Quantity of Electricity
Bytes	2	1	1

5.3 

5.4 

5.5 

5.6 

5.7 

5.8 

5.9 

Trackers send Heartbeat packets at a fixed-frequency to confirm the connectivity between tracker side and the server.

1.       Status

High							Low
15	14	…	…	…	…	1	0

Status field occupies 2 bytes, and represents the positioning state of a tracker. Notice that 1 byte consists of 8 bits, and we number the lowest bit as position 0, and the highest bit as position 7. As for the second byte, you should continue numbering the lowest bit of this byte as position 8, and so on. At the time of transmission, higher position bits should be sent prior to lower position bits. The specification of each bit is as follows:

Position 0	0: GPS not positioned 1: GPS positioned
Position 1,2	10: ACC off 11: ACC on 00: State undefined
Position 3,4	10: Defense unset 11: Defense set up 00: State undefined
Position 5,6	10: Oil and electricity off 11: Oil and electricity on 00: State undefined
Position 7,8	10: Battery charger unplugged 11: Battery charger plugged 00: State undefined
Position 9	Reserve
…	…
Position 14	Reserve
Position 15	Reserve

e.g.

With 0x00BB, that is 1011 1011 in binary notation, the status of the tracker should be “GPS positioned, ACC off, Defense set up, Oil and electricity off and Battery charger unplugged”.

2.       GSM Signal Level

The field GSM Signal Level occupies 1 byte. There are 5 signal levels:

Value	Description
0x00	No signal
0x01	Extremely week
0x02	A little week
0x03	Good
0x04	Strong

3.       Quantity of Electricity

The field Quantity of Electricity occupies 1 byte. The value of this field is a percentage number, expressed in hexadecimal notation, and ranges from 0x0000 to 0x0064.

e.g.

With 0x005D, that is 93 in decimal notation, so the quantity of electricity of the tracker is 93%.

4.   Packet Example

A packet sent from tracker side to the sever may be as follows:

0x67 0x67	0x03	0x00 0x04	0x00 0x1A	0x00 0x01
Header	Protocol	Length	Sequence	Status

The packet responded from the server to the tracker may be as follows:

0x67 0x67	0x03	0x00 0x02	0x00 0x1A
Header	Protocol	Length	Sequence

Notice that the Sequence value of the response packet is the same as that of the packet sent from the tracker.

Time Calibration Packet (0x08)

There is no Body field in Time Calibration packets sent from trackers.

1.       Server Response

5.3 

5.4 

5.5 

5.6 

5.7 

5.8 

5.9 

5.10 

5.11 

Format	Body
	UTC
Bytes	4

The UTC value in the Body field of the response packet occupies 4 bytes, and is the time from GPS data.

2.       Packet Example

A Time Calibration packet sent from a tracker to the server may be as follows:

0x67 0x67	0x08	0x00 0x02	0x00 0x1A
Header	Protocol	Length	Sequence

The response packet from the server for the Time Calibration packet may be as follows

0x67 0x67	0x08	0x00 0x06	0x00 0x1A	0x57 0x30 0x06 0x90
Header	Protocol	Length	Sequence	UTC Time

Notice that the Sequence value of the response packet is the same as that of the packet sent from the tracker.