mobile Devices Ingenierie
Protocol header
2007-04-24
Mobile Devices Ingénierie – 12 rue Roger Salengro 94270 Le Kremlin Bicêtre Tél. : +33 142 119 325 – Fax : +33 142 118 717 – http://www.mobile-devices.fr This document is the property of Mobile Devices; it can not be reproduced or copied without authorization.
Table of contents 1 2
3 4 5
6
Introduction ........................................................................................................................ 3 How activate protocol header............................................................................................. 3 2.1 On MD501-T3............................................................................................................ 3 2.1.1 USE_FRAME_CONFIG.................................................................................... 3 2.1.2 FRAME_CONFIG ............................................................................................. 3 2.1.3 FRAME_DBVALUES....................................................................................... 3 2.1.4 NO_TRAME_IDV ............................................................................................. 3 2.2 On MD501-C4............................................................................................................ 3 Header format..................................................................................................................... 4 Encoding into base 64 ........................................................................................................ 5 Frame parameters ............................................................................................................... 5 5.1 Protocol header version 1.0 ........................................................................................ 6 5.2 Protocol header version 1.1 ........................................................................................ 9 Data .................................................................................................................................. 11 6.1 Tracking data format ................................................................................................ 11 6.2 Mask inputs .............................................................................................................. 11 6.3 RMC frame............................................................................................................... 11 6.4 Available events on MD501-T3 in version 1.0 ........................................................ 12
Mobile Devices Ingénierie – 12 rue Roger Salengro 94270 Le Kremlin Bicêtre Tél. : +33 142 119 325 – Fax : +33 142 118 717 – http://www.mobile-devices.fr This document is the property of Mobile Devices; it can not be reproduced or copied without authorization.
1 INTRODUCTION This protocol is used to describe data sent by “Mobile Devices” devices as MD501-T3 or MD501-C4. For each connection, a header is sent to the server and it describes the frames. MD501-T3
MD501-C4
Protocol Header is not compatible with FTP
FTP TCP
OK
OK
UDP
UDP protocol not available
OK
Header and protocol
2 HOW ACTIVATE PROTOCOL HEADER 2.1 ON MD501-T3 2.1.1 USE_FRAME_CONFIG If this option is set to ‘1’, the header is added when MD501-T3 sends data to the remote server. 2.1.2 FRAME_CONFIG Add the field ‘config:FRAME_CONFIG’ in the header if this parameter is set. FRAME_CONFIG is replaced by its value in the configuration file. 2.1.3 FRAME_DBVALUES Add the field ‘dbValues:FRAME_DBVALUES’ in the header if this parameter is set to 1. FRAME_DBVALUES is replaced by the values of the DB parameter. 2.1.4 DATAFORMATTER Only for firmware revision > 1.4r24?? STANDARD for Protocol Header version 1.0 (default) EXTENDED for Protocol Header version 1.1 2.1.5 NO_TRAME_IDV If this parameter is set to ‘1’, suppress the device ID on the beginning of each frame. It is recommended for MD501-T3, which used protocol header.
2.2 ON MD501-C4 The protocol Header is automatically activated on MD501-C4
Mobile Devices Ingénierie – 12 rue Roger Salengro 94270 Le Kremlin Bicêtre Tél. : +33 142 119 325 – Fax : +33 142 118 717 – http://www.mobile-devices.fr This document is the property of Mobile Devices; it can not be reproduced or copied without authorization.
3 HEADER FORMAT MDIXY\r\n modid: xxxxxxxxx \r\n config: xxxxxxxxx \r\n frame:xxxxxxxxx.\r\n dbValues:xxxxxxxxx,xxxxxxxxxxxx\r\n board:xxxxxxxxx \r\n xxxxxxxxx\r\n \r\n $GPRMC,085153.00,A,4848.8722,N,00221.7265,E,0.004,5.42,130406,,,A*6C\r\n $GPRMC,085214.00,A,4848.8717,N,00221.7276,E,0.003,188.54,130406,,,A*67\r\n $GPRMC,085234.00,A,4848.8712,N,00221.7277,E,0.012,1.87,130406,,,A*62\r\n $GPRMC,085255.00,A,4848.8700,N,00221.7274,E,0.014,352.02,130406,,,A*60\r\n $GPRMC,085315.00,A,4848.8698,N,00221.7270,E,0.015,354.43,130406,,,A*68\r\n $GPRMC,085336.00,A,4848.8695,N,00221.7265,E,0.005,193.18,130406,,,A*66 Type Parameter MDIXY String
modid
config frame
dbValues board
Information Example Beginning of the header; if X equals to ‘0’ = protocol MDI00 = Protocol Header, text; Y is used to give information about version text mode, version 1.0 MDI01 = Protocol Header, text mode, version 1.0 MDI20 = Another protocol String Device ID. 355000111222333444 • On MD501-T3, it is the parameter CNFMODID. TRUCK0001 Customers must configure this parameter ; • On MD501-C4, by default, it is the modem IMEI (automatically, on 15 digits) String Optional field; It is the name of the configuration. MD501-T3L MD501-C4R String in base- Identify data that are sent or not. A bit to ‘1’ means f/wAAAAAA 64 that the information is present on the frame, a bit to ///eTwAAD2 ‘0’ means that the information is not present on the frame. On version 1.0, this field has only 9 digits. On version >1.0, this field can be change (more or least than 9 digits) String Optional field for MD501-T3 NB : DB values are not computed on the field frame String Optional field; Board information, as firmware Logiciel-T3B-1.4r2333 revision
NB: The field “frame” is only valid for $GPRMC frames. For event frames (as $MENU for MD501-T3, see above for more information) NB: Some information in the header can be added; the header finishes with the string “\r\n”
Mobile Devices Ingénierie – 12 rue Roger Salengro 94270 Le Kremlin Bicêtre Tél. : +33 142 119 325 – Fax : +33 142 118 717 – http://www.mobile-devices.fr This document is the property of Mobile Devices; it can not be reproduced or copied without authorization.
4 ENCODING INTO BASE 64 Value Encoding Value Encoding Value Encoding Value Encoding 0 (0x00) A 16 (0x10) Q 32 (0x20) g 48 (0x30) w 1 (0x01) B 17 (0x11) R 33 (0x21) h 49 (0x31) x 2 (0x02) C 18 (0x12) S 34 (0x22) i 50 (0x32) y 3 (0x03) D 19 (0x13) T 35 (0x23) j 51 (0x33) z 4 (0x04) E 20 (0x14) U 36 (0x24) k 52 (0x34) 0 5 (0x05) F 21 (0x15) V 37 (0x25) l 53 (0x35) 1 6 (0x06) G 22 (0x16) W 38 (0x26) m 54 (0x36) 2 7 (0x07) H 23 (0x17) X 39 (0x27) n 55 (0x37) 3 8 (0x08) I 24 (0x18) Y 40 (0x28) o 56 (0x38) 4 9 (0x09) J 25 (0x19) Z 41 (0x29) p 57 (0x39) 5 10 (0x0A) K 26 (0x1A) a 42 (0x2A) q 58 (0x3A) 6 11 (0x0B) L 27 (0x1B) b 43 (0x2B) r 59 (0x3B) 7 12 (0x0C) M 28 (0x1C) c 44 (0x2C) s 60 (0x3C) 8 13 (0x0D) N 29 (0x1D) d 45 (0x2D) t 61 (0x3D) 9 14 (0x0E) O 30 (0x1E) e 46 (0x2E) u 62 (0x3E) + 15 (0x0F) P 31 (0x1F) f 47 (0x2F) v 63 (0x3F) /
5 FRAME PARAMETERS The parameter “frame” describes data sent by the device; when it has been decoded, server knows the structure of each frame. Each character has been encoded into base 64 (encoding in 6 bytes). Each byte is corresponding to one frame information. A byte to ‘0’ means that the information is not present in the frame. A byte to ‘1’ means that the information is present in the frame. Example 1: Only the GPRMC frame is recorded and sent to the server. $GPRMC,075432.00,A,4847.7995,N,00221.5050,E,000.0,000.0,240804,03.8,W,A*1F Server receives "frame:f/wAAAAAA" in 1.0 Char f / w A A A A A A Byte 0x1F 0x3F 0x30 0x00 0x00 0x00 0x00 0x00 0x00 Binary 011111 111111 110000 000000 000000 000000 000000 000000 000000 Example 2: GPRMC frame with tachymeter information with ID iButton and 4 sensors $GPRMC,013009.00,V,,,,,,,010100,,,N*53,R,S,0.0,0,0,0000000000000000,27,27,27,27 Server receives "frame:f/weXwAAA" in 1.0 Char f / w e X w A A A Byte 0x1F 0x3F 0x30 0x1E 0x17 0x30 0x00 0x00 0x00 Binary 011111 111111 110000 011110 010111 110000 000000 000000 000000 Below, command configuration for MD501-T3 or MD401-C4 to add information in frames. Mobile Devices Ingénierie – 12 rue Roger Salengro 94270 Le Kremlin Bicêtre Tél. : +33 142 119 325 – Fax : +33 142 118 717 – http://www.mobile-devices.fr This document is the property of Mobile Devices; it can not be reproduced or copied without authorization.
5.1 PROTOCOL HEADER VERSION 1.0 Byte Bit
1
2
3
Information
MD501-T3
MD501-C4
Following commands add information frame; to suppress information, inverse the value (0 => 1 and 1 => 0)
X = -1 means “data not recorded” X = 0 means “record on event” X > 0 means “record every X seconds)
6 5 4
ID Device NMEA / $GPRMC NMEA / UTC time
3
NMEA / Status
dataRecorder.fieldPeriod[3]=X
2 1
NMEA / Latitude NMEA / N/S
dataRecorder.fieldPeriod[4]=X dataRecorder.fieldPeriod[5]=X
6 5
NMEA / Longitude NMEA / E/W
4 3 2
NMEA / Speed NMEA / Course NMEA / Date
1 6
NMEA / Magnetic variation value NMEA / MV E/W NMEA / MV E/W*Checksum NMEA / Mode*Checksum Unused Ignition State
5 4
NO_TRAME_IDV=0
OBLIGATORY FIELDS
dataRecorder.fieldPeriod[0]=X dataRecorder.fieldPeriod[1]=X dataRecorder.fieldPeriod[2]=X
dataRecorder.fieldPeriod[6]=X dataRecorder.fieldPeriod[7]=X dataRecorder.fieldPeriod[8]=X dataRecorder.fieldPeriod[9]=X dataRecorder.fieldPeriod[10]=X dataRecorder.fieldPeriod[11]=X dataRecorder.fieldPeriod[12]=X dataRecorder.fieldPeriod[13]=X
NO_TRAME_APC=0
dataRecorder.fieldPeriod[14]=X
Mobile Devices Ingénierie – 12 rue Roger Salengro 94270 Le Kremlin Bicêtre Tél. : +33 142 119 325 – Fax : +33 142 118 717 – http://www.mobile-devices.fr This document is the property of Mobile Devices; it can not be reproduced or copied without authorization.
Commentary / Format String String String HHMMSS.ss Character [A|V] A = valid frame, V = invalid frame Float Character [N|S] N = North, S = South Float Character [E|W] E = East, W = West Float Integer Integer DDMMYY Integer NMEA version (depends GPS firmware) NMEA Simple NMEA Extended Boolean 1 = Ignition is turned on, 0 otherwise
3
Power supply State
NO_BAT_LVL=0
dataRecorder.fieldPeriod[15]=X
2
GPRS state
NO_TRAME_GPRS_LVL=0
dataRecorder.fieldPeriod[16]=X
1 6
GSM level State button
NO_TRAME_GSM_LVL=0 PUSHB_USE=1
dataRecorder.fieldPeriod[17]=X Not available
5
Tachymeter selector or GPS odometer simulator Tachymeter driving or GPS odometer simulator
CHRONOTACHY_EVENT=1 or CHRONOTACHY_EVENT=0 TRAME_GPSODO=1 GPSODO_CHRONO_TRAME=1 CHRONOTACHY_EVENT=1 CNFCHRONO,XXX
Not available
4 4
5
3
Tachymeter partial kilometre
2
Tachymeter total kilometre
1
GPS odometer partial kilometre
6
GPS odometer total kilometre
Not available Not available Not available
CHRONOTACHY_EVENT=0 TRAME_GPSODO=1 GPSODO_CHRONO_TRAME=0 or CHRONOTACHY_EVENT=0 TRAME_GPSODO=1 GPSODO_CHRONO_TRAME=1
dataRecorder.fieldPeriod[23]=X
Positive integer 1 = Battery is good, 0 = Internal battery low, 2 = Internal battery critic Positive integer • 0 = Gprs Off • 1 = GPRS On • 2 = Gprs Off and Roaming • 3 = Gprs On and Roaming Positive integer : [0-99] Boolean 1 = Button is pushed, 0 otherwise Character [T|R|A] T = Work, R = Rest, A = Wait Character [D|S] D = Driver, S = Stop Positive float (in kilometre) Positive float (in kilometre) Positive float (in kilometre)
dataRecorder.fieldPeriod[24]=X
Mobile Devices Ingénierie – 12 rue Roger Salengro 94270 Le Kremlin Bicêtre Tél. : +33 142 119 325 – Fax : +33 142 118 717 – http://www.mobile-devices.fr This document is the property of Mobile Devices; it can not be reproduced or copied without authorization.
Positive float (in kilometre)
5
6
Tachymeter driving time or GPS odometer simulator
CHRONOTACHY_EVENT=1 or CHRONOTACHY_EVENT=0 TRAME_GPSODO=1 GPSODO_CHRONO_TRAME=1 ALARM_USE=1
Not available
dataRecorder.fieldPeriod[27]=X dataRecorder.fieldPeriod[28]=X dataRecorder.fieldPeriod[29]=X dataRecorder.fieldPeriod[30]=X dataRecorder.fieldPeriod[31]=X dataRecorder.fieldPeriod[32]=X dataRecorder.fieldPeriod[33]=X dataRecorder.fieldPeriod[34]=X dataRecorder.fieldPeriod[35]=X dataRecorder.fieldPeriod[36]=X dataRecorder.fieldPeriod[37]=X dataRecorder.fieldPeriod[38]=X Not available
4
Alarm state
3
iButton ID
2 1 6 5 4 3 2 1 6 5 4
Sensor 1 Sensor 2 Sensor 3 Sensor 4 Sensor 5 Sensor 6 Sensor 7 Sensor 8 Sensor 9 Sensor 10 Inputs state
NO_TRAME_OW=0 OWUSE,1 HS_USE=-1 or 1 to 10 / OWUSE=1 HS_USE=2 to 10 / OWUSE=1 HS_USE=3 to 10 / OWUSE=1 HS_USE=4 to 10 / OWUSE=1 HS_USE=5 to 10 / OWUSE=1 HS_USE=6 to 10 / OWUSE=1 HS_USE=7 to 10 / OWUSE=1 HS_USE=8 to 10 / OWUSE=1 HS_USE=9 to 10 / OWUSE=1 HS_USE=10 / OWUSE=1 NO_TRAME_TOR=0
3 2 1 6 5 4 3 2 1
Box counting Mode 1
BCUSE=1
Positive integer (in second)
dataRecorder.fieldPeriod[26]=X
7
8
Boolean 1 = Alarm On, 0 otherwise Hexadecimal ID on 16 bytes. Default value: 0000000000000000
Float
Hexadecimal mask (no fix length) The first input is the LSB See documentation about box counting. Currently, box counting modes are only available on MD501-T3
Box counting Mode 2
BCUSE=2
Not available
Mobile Devices Ingénierie – 12 rue Roger Salengro 94270 Le Kremlin Bicêtre Tél. : +33 142 119 325 – Fax : +33 142 118 717 – http://www.mobile-devices.fr This document is the property of Mobile Devices; it can not be reproduced or copied without authorization.
9
6 5 4 3 2
Tachymeter driver ID
1
Current Geofencing sector
CHRONOTACHYEVENT=1 NO_CHRONO_ID=0 NO_TRAME_GEOFENCING=0
Not available Not available
Hexadecimal ID (variable size) No value if no driver card Integer
5.2 PROTOCOL HEADER VERSION 1.1 Byte Bit
Information
6
Tachymeter timestamp
5 4
Satellites viewed Movement state
3 2
Boot reason Shutdown reason
1 6
Internal battery level (in mA) Kb sent by GPRS since last counter reset Kb received by GPRS since last counter reset
10
11
5 4
MD501-T3
MD501-C4
Following commands add information frame; to suppress information, inverse the value (0 => 1 and 1 => 0)
X = -1 means “data not recorded” X = 0 means “record on event” X > 0 means “record every X seconds)
CHRONOTACHYEVENT=1 NO_CHRONO_TIME=0 NO_TRAME_SAT_NUMBER=0 GPSODO_USE=1 USE_GPS_MOVE=1 NO_TRAME_GPS_MOVE=0 NO_TRAME_BOOT_REASON=0 NO_TRAME_SHUTDOWN_REA SON=0 Not available Not available Not available
Not available dataRecorder.fieldPeriod[55]=X dataRecorder.fieldPeriod[56]=X
dataRecorder.fieldPeriod[57]=X dataRecorder.fieldPeriod[58]=X dataRecorder.fieldPeriod[59]=X dataRecorder.fieldPeriod[60]=X dataRecorder.fieldPeriod[61]=X
Not implemented 1
the number of seconds since January 1 1970 00:00:00 GMT; timestamp depends of tachymeter time and its settings Mobile Devices Ingénierie – 12 rue Roger Salengro 94270 Le Kremlin Bicêtre Tél. : +33 142 119 325 – Fax : +33 142 118 717 – http://www.mobile-devices.fr This document is the property of Mobile Devices; it can not be reproduced or copied without authorization.
Commentary / Format Positive integer Unix timestamp in local time1 Positive integer Boolean 0 = STOP / 1 = START String See documentation about device for more information Positive integer Positive integer Positive integer
3 2 1
Not implemented Not implemented Not implemented
Some information can be added in the future, i.e. byte 11 (or more) can appear.
Mobile Devices Ingénierie – 12 rue Roger Salengro 94270 Le Kremlin Bicêtre Tél. : +33 142 119 325 – Fax : +33 142 118 717 – http://www.mobile-devices.fr This document is the property of Mobile Devices; it can not be reproduced or copied without authorization.
6 DATA 6.1 TRACKING DATA FORMAT … Tracking file does not finish by the characters .
6.2 MASK INPUTS The inputs are summed up in a hexadecimal value: Input number Input 1 Input 2 Input 3 Input 4
Value (hexa) 1 2 4 8
Input number Input 5 Input 6 Input 7 Input 8
Value (hexa) 10 20 40 80
Input 1 is the LSB (less significant bit). For example, if entries 1, 3, 4, 5 and 8 are activated, the following value is obtained (caution: calculation is made in hexadecimal): Input number Input 1 Input 3 Input 4 Input 5 Input 7 Input 8 Synthesis
Value (hexa) 1 4 8 10 40 80 DD
“DD” is obtained in the value. For more information about hexadecimal system: http://en.wikipedia.org/wiki/Hexadecimal For MD501 devices, mask inputs size is not fixed.
6.3 RMC FRAME $GPRMC,225446,A,4916.45,N,12311.12,W,000.5,054.7,191194,020.3,W,E*68 225446 = Time of position fix : 22:54:46 UTC A = Status: (V = Navigation receiver warning, A = Data Valid) 4916.45,N = Latitude 49 deg. 16.45 min North (N = North, S = South) 12311.12,W = Longitude 123 deg. 11.12 min West (E = East, W = West) 000.5 = Speed over ground, Knots 054.7 = Course over ground, degrees 191194 = Current date 19 November 1994 020.3,W = Magnetic variation 20.3 deg West (E = East, W = West) E*68 = checksum Mobile Devices Ingénierie – 12 rue Roger Salengro 94270 Le Kremlin Bicêtre Tél. : +33 142 119 325 – Fax : +33 142 118 717 – http://www.mobile-devices.fr This document is the property of Mobile Devices; it can not be reproduced or copied without authorization.
6.4 AVAILABLE EVENTS ON MD501-T3 IN VERSION 1.0 These specials frames have only available on MD501-T3, version 1.0 The header of the NMEA frame, “GPRMC”, can be modified to indicate events. The following list shows the different available headers: Commentary The frame is generated when MD501 starts or stops. Data are added at the end of the standard frame and indicates shutdown and boot reasons. The data added can be modified by Mobile Devices. $GPRMC Standard frame with the standard header. $IBUTT A frame is recorded when an iButton key is inserted in a reader. $MENU This frame is generated by screen devices. The data are added at the end of the frame. The character ‘;’ is used to separated standard data and menu data. The format depends of the client application. $MSTART This frame is generated by the odometer GPS module, when the vehicle starts or stops a movement ($MSTOP = vehicle stops moving, $MSTART = vehicle starts to move). $MSTOP $START The frame is generated when ignition changes its state ($START = ignition ON, $STOP = ignition OFF). $STOP $USER The frame is generated by the client application and its format depends of the client. Event $EVENT
Mobile Devices Ingénierie – 12 rue Roger Salengro 94270 Le Kremlin Bicêtre Tél. : +33 142 119 325 – Fax : +33 142 118 717 – http://www.mobile-devices.fr This document is the property of Mobile Devices; it can not be reproduced or copied without authorization.
