Draft:GSE Open GPS Protocol

From Wikipedia, the free encyclopedia
Jump to navigation Jump to search

GSE Open GPS Protocol is an open standard for GPS, M2M, or SCADA device manufacturers to utilize for ease of implementation and flexibility by using a common standard. This standard is open to additional message types as suggested by the community of manufactures of telematics devices and sensor manufactures. The protocol is designed to include multiple blocks of data in a single transmission, and can be broken into multiple transmissions as seen fit based on message size limitations of satellite, GSM, UDP, or the protocol of your choosing.

This protocol format is a collaboration of multiple vendors to utilize a common protocol or messaging structure for low bandwidth, messaging style applications, where there is often a custom protocol definition for every hardware vendor in the IoT market. As there is a common dataset transmitted by most telematics and tracking devices, this open format and collaboration between any hardware vendor looking to utilize a common standard, will speed the integration time of hardware and platforms.

Hardware vendors benefit from immediately available data in any telematics or IoT platform that already supports this format

Platform vendors benefit from easy integration and testing of new hardware or additional capabilities from hardware vendors.

There is large blocks of datasets left open for definitions and expansions as new technologies come to market. Continually adding additional dataset definitions to this protocol will expand as the group of vendors continue to innovate these markets. Feel free to reach out to any of the group of vendors contributing to this protocol for comments, questions, reviews, and or additions.

Open License[edit]

Copyright (c) 2017 Global Satellite Engineering, Inc. Permission is hereby granted, free of charge, to any person to deal in the message format without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the message format, to send and receive messages formatted according to the message format, and to permit persons to whom the message format is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies of documentation describing the message format. THE MESSAGE FORMAT IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE MESSAGE FORMAT OR THE USE OR OTHER DEALINGS IN THE MESSAGE FORMAT.


Mobile Originated and Mobile Terminated Packet Definitions[edit]

All data blocks are big-endian (MSB) unless otherwise specified.

Mobile Originated Packet[edit]

Offsets Octet 0
Octet Bit  7  6  5  4  3  2  1  0
0 0 Message Block Type
(0) GPS Format Reserved 10 Byte
(1) Text Message
(2) Settings Update
(3) Interface Version Response
(4) 10 Byte GPS Location
(5) 18 Byte GPS Location
(6) MAC Address (BLE or WiFi)
(7) Sensor
(8) Device ID/IMEI
(9) Ping/Pong
(10-19) GPS Formats Reservation
(20-39) LoRA and RFID Reservation
(40-199) Do not use, future definitions
(200-249) User Defined (Open for manufacturer specific development)
(250) Payload Version
(254) ACK Request/Response
(255) Encrypted Message
1 - X 8 - X Block Data
X X Additional Message Block Type...
X - X X - X Block Data...

Mobile Terminated Packet[edit]

Offsets Octet 0
Octet Bit  7  6  5  4  3  2  1  0
0 0 - 7 Packet Version
1 8 - 15 Message Block Type
(0) Command
(1) Text Message
(2) Setting(s) Update
(3) Settings Request
(4) Settings Interface Version
(5) Request Data
(9) Ping/Pong
(10-199) Do not use, future definitions
(200-249) User Defined (Open for manufacturer specific development)
(254) ACK Request/Response
(255) Encrypted Message
2 - X 8 - X Block Data
X X Additional Message Block Type...
X - X X - X Block Data...
X - (X + 10) X - (X + 80) HMAC-SHA256-80
Format Definitions
HMAC-SHA256-80 HMAC-SHA256-80(<password>,<payload>)

HMAC-SHA256 is computed over the (header byte not included) using a password/key shared by

the device and server, and is truncated to the first 10 bytes (80-bits)

Packet Version 0x00 (Future versions may be defined)

Mobile Originated Block Data Definitions[edit]

Mobile Originated Block Data 1: Text Message[edit]

Offsets Octet 0
Octet Bit  7  6  5  4  3  2  1  0
0 0 Recipient Length
1 - X 8 - X Recipient String
X - X X - X Text String (NULL terminated)
Format Definitions
Recipient String ASCII text
Text String ASCII text - NULL (0x00) terminated


Mobile Originated Block Data 2: Settings Message[edit]

Offsets Octet 0
Octet Bit  7  6  5  4  3  2  1  0
0 0 Manufacturer ID
1 8 Settings Version
2-(X + 4) 16 - X 32 bit value, manufacturer specific
Manufacturer 0x03 (GSatMicro)
2-5 16-47 Default Version
6-9 48-79 GPS HDOP
10-13 80-111 GPS Timeout
14-17 112-143 Iridium Tx Timeout
18-21 144-175 Iridium Signal Timeout
22-25 176-207 Iridium Tx Retries
26-29 208-239 Sleep Interval
30-33 240-271 SOS Sleep Interval
34-37 272-303 Sleep When Powered
38-41 304-335 LED Mask
42-45 336-367 Keep Radio Awake
46-49 368-399 Include Altitude
50-53 400-431 GPS Settle
54-65 432-527 Reserved
66-69 528-559 Low Batt Off
70-73 560-591 GPS Hibernate Sleep
74-77 592-623 Cache Reports
78-81 624-655 Moving Sleep Interval
82-85 656-687 Moving Threshold Speed
86-89 688-719 Require Encrypted MT
90-93 720-751 GPS On Always
94-97 752-783 Sleep With Battery
98-101 784-815 Include Seconds
102-105 816-847 Report Format
Format Definitions
GPS HDOP X/10, 10-500
GPS Timeout Seconds, 1-(2^31-1)


Mobile Originated Block Data 4: 10 Byte GPS Location[edit]

Offsets Octet 0
Octet Bit  7  6  5  4  3  2  1  0
0 0 Magic Number Longitude
1 8 Longitude
2 16 Longitude
3 24 Longitude Heading
4 32 Time
5 40 Time Latitude
6 48 Latitude
7 56 Latitude
8 64 Speed Altitude
9 72 Altitude
Format Definitions
Magic Number 0x0
Longitude X/23301-180 degrees

Invalid Position = 0xFF for all bytes of Latitude AND Longitude

Heading X * 5 degrees
Time (X*2)/24/60 minutes since midnight
(2 minute resolution)
(no date, only time)
Latitude X/23301-90

Invalid Position = 0xFF for all bytes of Latitude AND Longitude

Speed X meters per second
Altitude X * 5 meters

Invalid Altitude = 0xFF for all bytes Integer values only (no negative/below sea level altitude support)


Mobile Originated Block Data 5: 18 Byte GPS Location[edit]

Offsets Octet 0
Octet Bit  7  6  5  4  3  2  1  0
0 0 Magic Number Longitude
1 8 Longitude
2 16 Longitude
3 24 Longitude External Pwr Distress Intrusion/Checkin
4 32 Time
5 40 Time
6 48 Time
7 56 Time GPS Satellites
8 64 Latitude
9 72 Latitude
10 80 Latitude
11 88 Latitude Heading GPS HDOP
12 96 GPS HDOP Climb Rate
13 104 Climb Rate
14 112 Battery Percent Speed
15 120 Speed
16 128 Altitude
17 136 Altitude
Format Definitions
Magic Number 0x0
Longitude X/186413-180 degrees

Invalid Position = 0xFF for all bytes of Latitude AND Longitude

Time '2015/1/1' + X seconds
Latitude X/186413-90

Invalid Position = 0xFF for all bytes of Latitude AND Longitude

Heading X*5 degrees
GPS HDOP X meters
Climb Rate (X-(2^(10)))/20 meters per second

Invalid Climb Rate = 0xFF for all bytes

Battery X*3 percent
Speed X kph
Altitude X meters

Invalid Altitude = 0xFF for all bytes Integer values only (no negative/below sea level altitude support)

Mobile Originated Block Data 7: Sensor[edit]

Offsets Octet 0
Octet Bit  7  6  5  4  3  2  1  0
0 0 - 7 Sensor Type
1 - X 8 - X Sensor Data
Format Definitions
Sensor Types 0 = Temperature, 1 = Heart Rate

Mobile Originated Block Data 8: Device ID/IMEI[edit]

Offsets Octet 0
Octet Bit  7  6  5  4  3  2  1  0
0 0 - 7 ID Type ID Length
1 - x 8 - X Data: ASCII, Big Endian Integer, or Little Endian Integer bytes....
Format Definitions
Device ID/IMEI ID Type 00 = ASCII, 01 = Big Endian Integer, 10 = Little Endian Integer, 11 = Reserved
Device ID Ascii Example ID Type 0 = ASCII, ID Len = 10, Data = '1A2B3C4D5F'
Device ID Integer Example ID Type 1 = Big Endian Integer, ID Len = 7, Data = 0x01 3A 64 A4 1D 4B 87 = 345678901234567

Mobile Originated OR Mobile Terminated Block Data 9: Ping/Pong[edit]

Offsets Octet 0
Octet Bit  7  6  5  4  3  2  1  0
0 0 - 7 Ping/Pong Unique ID
Format Definitions
Ping/Pong Ping = 0x0, Pong = 0x1

Upon receiving a Ping, client and server should reply with Pong

Unique ID Unique ID should be randomly generated for Ping.

Pong reply MUST copy Unique ID in reply

Mobile Originated Block Data 250: Payload Version[edit]

Offsets Octet 0
Octet Bit  7  6  5  4  3  2  1  0
0 0 - 7 0x00 = Current Version
Future versions to be defined

Mobile Originated OR Mobile Terminated Block Data 254: ACK Request/Reply[edit]

Offsets Octet 0
Octet Bit  7  6  5  4  3  2  1  0
0 0 - 7 ACK Request/Reply Respond Directly Reserved Unique ID
Format Definitions
ACK Request/Reply ACK Request = 0x1, ACK Reply = 0x0

Upon receiving an ACK Request, reply with an ACK Reply with the same Message ID field

Respond Directly Respond Directly = 0x1, Respond Normally = 0x0

A normal response would be to reply to the unit via the normal behavior, IE, queue the message to a satellite gateway or hybrid unit message queue.
A direct response would force the reply, acknowledgment, or other message responses, to be sent directly back to the incoming data connection and override the normal behavior.

Unique ID Unique ID should be an indexed number for ACK Request.

ACK Reply reply MUST copy Unique ID in reply

Mobile Terminated Block Data Definitions[edit]

Mobile terminated block definitions always include a message or block size in the message to help simple parsers (micro controllers) to decode and process blocks with simple loop and integer indexing.


Mobile Terminated Block Data 0: Command Message[edit]

Offsets Octet 0
Octet Bit  7  6  5  4  3  2  1  0
0 0 - 7 Command Message Length
1 - X 8 - X Command Message


Mobile Terminated Block Data 1: Text Message[edit]

Offsets Octet 0
Octet Bit  7  6  5  4  3  2  1  0
0 0 - 7 Text Message Length
1 - X 8 - X Text Message
Format Definitions
Text Message ASCII text


Mobile Terminated Block Data 2: Update Setting[edit]

Offsets Octet 0
Octet Bit  7  6  5  4  3  2  1  0
0 0 - 7 Block Size (Fixed at 0x06)
1 - 2 8 - 15 Setting Number
2 - 3 16 - 23 Setting Number
3 - 4 24 - 31 Setting Value
4 - 5 32 - 39 Setting Value
5 - 6 40 - 47 Setting Value
6 - 7 48 - 55 Setting Value
Format Definitions
Setting Number 16 bit unsigned integer
Setting Value 32 bit signed integer


Mobile Terminated Block Data 3: Request Settings[edit]

Offsets Octet 0
Octet Bit  7  6  5  4  3  2  1  0
0 0 - 7 Block Length 0x00


Mobile Terminated Block Data 4: Request Version[edit]

Offsets Octet 0
Octet Bit  7  6  5  4  3  2  1  0
0 0 - 7 Block Length 0x00

Mobile Terminated Block Data 5: Request Data[edit]

Offsets Octet 0
Octet Bit  7  6  5  4  3  2  1  0
0 0 - 7 Block Length 0x01
1 8 - 15 Request Data Type
(0) GPS Position
(1) IMEI
(2) Sensor
(3) MAC Address
(4) Accelerometer (future)
(5) Canned Address Book Version (future)
(6) Canned Messages Version (future)
(7) Drivers (future)
(8) Geofence Hash/Version (future)
(9) Terminal Diagnostics (future)
(200-249) User Defined (Open for manufacturer specific development)
(255) Encrypted Message

Mobile Terminated Block Data 9: Ping/Pong[edit]

See Mobile Originated Block Data 9: Ping/Pong





Definitions to be released[edit]

Advanced text message with status acknowledgement

message is a reply to a specific message

message has been viewed

message has been deleted

message has been replied

message has been delivered

message is being sent to a phone number (must start with a + sign and follow E.164 numbering standard)

message is being sent to an email, must contain an @ sign

message is being forwarded to another unit/user, must be a number

message is being sent to the portal operator, destination field is set to "0"

Multi-packet block

Sequence field

message # x of y

mobile terminated 9601/2/3 = (270 bytes - 4 byte header) * 256 = 68096 byte packet maximum

mobile originated 9601/2/3 = (340 bytes - 4 byte header) * 256 = 86016 byte packet maximum

mobile terminated 9522/3 = (1890 bytes - 4 byte header) * 256 = 482816 byte packet maximum

mobile originated 9601/2/3 = (1960 bytes - 4 byte header) * 256 = 500736 byte packet maximum

Configuration Update block

...to complete from GSE documentation...

References[edit]

External links[edit]