1. Manuals
  2. Brands
  3. BOX Telematics Manuals
  4. GPS
  5. BOX tracker
  6. Communication protocol manual

BOX Telematics BOX tracker Communication Protocol Manual

Hide thumbs
Table of Contents

Advertisement

Quick Links

Download this manual
Communication Protocol v1.5

Advertisement

Table of Contents
loading
Need help?

Need help?

Do you have a question about the BOX tracker and is the answer not in the manual?

Questions and answers

Summary of Contents for BOX Telematics BOX tracker

  • Page 1 Communication Protocol v1.5...
  • Page 2 © Copyright 2001–2009 BOX telematics ltd. BOX telematics makes no warranty of any kind with regard to this material, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. BOX telematics shall not be liable for errors contained herein or for incidental or consequential damages in connection with the furnishing, performance, or use of this material.
  • Page 3 tracker Preface This document describes the server communication and configuration protocols used by BOX-tracker. It provides technical information to allow developers to integrate its functionality into a server application for vehicle tracking or asset management. The protocol is based on a TCP connection over the Internet via GSM GPRS and supports both connect and drop or a permanent server connection.

  • Page 4: Table Of Contents

    tracker Contents Document History............................5 Communication Methods ........................... 6 2.1 GPRS (TCP) Connection ........................6 2.2 Commands ............................7 Commands sent by BOX-tracker ........................8 3.1 Header Command (H) ........................8 Log Command (L) ..........................10 3.1.1 Data Items ......................... 11 Firmware Update Protocol ........................
  • Page 5 tracker  6.20 IMMOB ............................ 22  6.21 IN ............................. 23  6.22 IDLEALMT ..........................23  6.23 IGN_OFF_CHG ........................23  6.24 JDISTALM ..........................23  6.25 JTIMEALM ..........................24  6.26 LOG ............................24  6.27 ODOMETER ..........................24 ...

  • Page 6: Document History

    tracker 1 Document History Date Section Description 1.00 1/11/2008 Preliminary release 1.01 2/2/2009 Various update prior to formal release 1.03 16/4/2009 3.2.1 Event codes 35 & 36 added Battery logging details added FWS_TIME now defaults to 3600seconds 5.26 PERM_CON (permanent connection) added 5.32 SERVER2_ADDR added 5.33...

  • Page 7: Communication Methods

    tracker 2 Communication Methods Commands can be sent to and from BOX-tracker via several methods depending on setup:  Remote connection over GPRS (TCP)  Local RS232 connection  Local USB connection  Remote connection over GSM (CSD) To configure via its serial port requires a VT100 terminal emulation program such as HyperTerminal, configured to 115200 baud, 8 data bits, no parity, 1 Stop bit, no flow control.

  • Page 8: Commands

    tracker The following shows a typical communication session:  H,BT,358281002435893,081028142432,F5813D19,6D6E6DC2  L,081028142429,G,52.51084,-1.70849,0,170,0,1,0  L,081028142432,G,52.51081,-1.70849,0,203,0,16,0   Commands All communication is 7bit ASCII based. A command consists of an initial word, often abbreviated to a single character, followed by one or more optional parameters.

  • Page 9: Commands Sent By Box-Tracker

    tracker 3 Commands sent by BOX-tracker The following are the primary commands used during a GPRS connection to pass logged information from the tracker to the server. Header Command (H)  H, DeviceType,SerialNum,DateTime,SecurityToken,FirmwareVer[,SimNumber] When a TCP connection is first made BOX-tracker will send the header command. The header command is never sent via SMS, instead a simple password is included.
  • Page 10 tracker Date Time The current date and time of the trackers real-time clock. Whilst BOX-tracker normally synchronises its time from the GPS receiver this value can be used by the server to verify the time is correct and send a command to correct it. However Its main purpose is to provide a constantly changing security token.

  • Page 11: Log Command (L)

    tracker If required the SIM number can be configured (via the  SIM_SN_ALWAYS command) to always be present. This allows the SIM number to be used to identify the tracker instead of the serial number. Log Command (L)  L, <DataTime>,<DataItem>,<Values>[;<DataItem>,<Values>][;<DataItem>,<Values>] The Log command is used to pass historical (or real-time) log entries recorded by BOX-tracker.

  • Page 12: Data Items

    tracker 3.1.1 Data Items  G, Latitiude, Logitude, Speed, bearing, Distance, EventCode, Status The main Data Item is G, which is used to pass all GPS location data. Seven values are passed after the G Data Item name each separated by a comma: Latitude Latitude is a signed floating point number representing degrees and fractions of a degree between -90.0 and +90.0.
  • Page 13 tracker GPS Tamper. Occurs when the GPS antenna is removed or a fault occurs. Journey Distance Exceeded. This event is logged when the distance of the current journey exceeds a configurable value. Journey Time Exceeded This event is logged when the length of the current journey exceeds a configurable time. Speeding The speed of the vehicle has exceeded a configurable value.
  • Page 14 tracker Status This defines the status of the vehicle at the time the log was made. The value is passed as a hexadecimal number each bit within this number has a specific meaning as described below. Value = 0 Value = 1 Ignition is off Ignition is on.
  • Page 15 tracker  GF#, value Returns a value which indicates if a Geofence was entered or exited Defines the geofence number affected. A decimal number (1 to 64) Value 1 = Entry, 0 = Exit L,090617113820,G,52.51045,-1.70872,2,22,0.13,24,3;GF2,1 Geofence 2 entered. L,090617123820,G,52.54045,-1.72872,2,22,0.13,25,3;GF2,0 Geofence 2 exited ...

  • Page 16: Firmware Update Protocol

    At no time should the server start sending the firmware without having received a request from BOX-tracker to do so. If preferred, firmware updates may be collected from the servers hosted at BOX telematics by setting the FWS_TIME parameter (See section 6.9).

  • Page 17: Configuration Update Protocol

    tracker StartPosition The start position requested by BOX-tracker in the F command or zero if a file different to that being requested is being sent. This is formatted as a decimal number. Length The length of the firmware data (from the first byte to the last). This is formatted as a decimal number.

  • Page 18: Configuration Commands

    tracker 6 Configuration Commands The following commands may be sent to the tracker to configure it to behave in different ways or to requests a specific action.  ACCESS This commands allows the password access requirement to be turned on or off for specific communication methods.

  • Page 19: Anc

    tracker  ANC Enabling or disabling logging of analogue channels 0 to 3 and the externally battery supply. Each parameter may be set to a 0 (disable logging) or 1 (enable logging) Parameter 1 = Analogue Channel 0 Parameter 2 = Analogue Channel 1 Parameter 3 = Analogue Channel 2 Parameter 4 = Analogue Channel 3 Parameter 5 = External battery...

  • Page 20: Default

    If the firmware update protocol (section 4) is not being implemented on your system then firmware updates can be obtained from the servers at BOX Telematics. This parameter defines how often the tracker checks these servers for updates. If this is set to 0 then no checks will be made and any firmware will need to be updated in accordance with the update protocol in section 4.

  • Page 21: Geof

    tracker  GEOF# 6.10 Defines the size and location of Geofence zones that when breached generate logged events 24 & 25 GEOF<index>,1,alarm_entry>,<alarm_exit>,<lat>,<long>,<rad> <index> 64 geofences can be created this value index can between 1 and 64 <alarm_entry> (1 Enabled, 0 disabled) If enabled then event is recorded when tracker enters geofence <alarm_exit>...

  • Page 22: Gpshc

    tracker  GPSHC 6.14 This causes a log to be made each time the vehicles direction changes by more than the specified number of degrees. If this is set to zero then no log is made on a heading change. To configure the tracker to log an entry when the direction changes by 45 degrees or over GPSHC,45 Default value:...

  • Page 23: Gpsli_Ioff

    tracker  GPSLI_IOFF 6.18 Defines the interval (in seconds) between successive vehicle location logs whilst the ignition is off. This only defines the interval between logs and not the frequency the data is sent to the server. Eg: Log locations every hour whilst the ignition is off GPSLI_IOFF,3600 Default value: 86400 seconds (24 hours)

  • Page 24: Idlealmt

    tracker  IN 6.21 Requests the current status of all inputs, it is mainly used for diagnostic support.  IN  Digitals: 0 0  Analogs: 0027 0027 0025 0027 0945  Analogs: 0.105V 0.105V 0.1V 0.105V 22.942V  Ignition: 1 ...

  • Page 25: Jtimealm

    tracker  JTIMEALM 6.25 After the ignition has been turned on for the specified the time event code 21 is logged. Set to zero to disable To log an event when journeys exceed 2 hours JTIMEALM,7200 Default value: Range: 0 to 4,294,967 seconds (49.7 days) ...

  • Page 26: Odometer_Trip

    tracker  ODOMETER_TRIP 6.28 Each log entry contains the distance travelled since the start of the journey. If this is set to 1 then the distance is reset to zero at the end of each journey and the distance acts as a trip meter. If it is set to zero the distance is not reset and the distance acts as an odometer reading.

  • Page 27: Password

    tracker  PASSWORD 6.32 This defines the password which is used to calculate the security token that needs to be entered when using: RS232 command line USB command line GSM Command line Sending an SMS message to be processed by the tracker The password is used to calculate a security token and it is this security token which should be used to gain access via one of these communication channels, not the password.

  • Page 28: Server1_Addr

    tracker  SERVER1_ADDR 6.36 The TCP/IP address used for all primary communication over GPRS. The address may be specified as an IP address or as domain name URL. If set to an empty string then no connection is made over GPRS. E.g.

  • Page 29: Server2_Pass

    tracker  SERVER2_PASS 6.40 This password used to calculate the security token contained within the Header Command sent by the tracker when first connecting to the server. This password is case sensitive. (See SEVER2_ADDR) E.g. SERVER2_PASS,MyPassword Default value: password Range: 0 to 20 characters ...

  • Page 30: Sync

    tracker  SYNC 6.44 Requests the tracker to make a connection with the server over GPRS. This command is particularly useful when sent via SMS. It has no parameters.  TIME 6.45 Sets the trackers real-time clock. The time is automatically set when a GPS fix is achieved but this command may also be used.

  • Page 31: Uploadd

    tracker  UPLOADD 6.49 On Vehicle trackers this defines distance in km between each upload event. The accrued distance travelled is reset each time any upload event occurs. If this parameter is set to zero then upload is not initiated on distance travelled. E.g.

  • Page 32: Ver

    tracker E.g. To define a 24 volt supply VBAT12,0 Default value: 1 (12 Volt) Range: 0 or 1  VER 6.53 Returns version and firmware information on the tracker   1.12   VER 1  $URL: file:///C:/SvnRepos/Tracker/Tags/1.12/version.c $: Aug 1 2008 12:58:41 ...

  • Page 33: Appendix

    tracker 7 Appendix CRC Check Sum Algorithm The following code may be used to calculate CRC Security Token to include in the Header command (3.1) and to access the tracker via GSM, USB or SMS. This routine can return either a 16 or 32 BIT CRC. BOX-tracker uses a 32 Bit CRC.

  • Page 34: Example Communication Sessions

    tracker else { if (reflectOut) checksum >>= 1; else checksum <<= 1; if (reflectIn) maskIn <<= 1; else maskIn >>= 1; if (xorOut) checksum = ~checksum; checksum &= outMask; return checksum; Example Communication Sessions 7.2.1 Disconnected Session Sequence  H,BT,358281000146500,080401153209,9F84265E,12F4A98D ...

  • Page 35: Firmware Download

    tracker  L,080528113835,G,52.4,-1.3,101.6,94,23.89,1,03  L,080528113935,G,52.4,-1.3,101.6,94,23.89,1,03    L,080528115135,G,52.4,-1.3,101.6,94,23.89,1,03  L,080528115235,G,52.4,-1.3,101.6,94,23.89,1,03  L,080528115335,G,52.4,-1.3,101.6,94,23.89,1,03  L,080528115435,G,52.4,-1.3,101.6,94,23.89,1,03  L,080528115535,G,52.4,-1.3,101.6,94,23.89,1,03    L,080528115635,G,52.4,-1.3,101.6,94,23.89,1,03  L,080528115735,G,52.4,-1.3,101.6,94,23.89,1,03  L,080528115835,G,52.4,-1.3,101.6,94,23.89,1,03  L,080528115935,G,52.4,-1.3,101.6,94,23.89,1,03  L,080528125135,G,52.4,-1.3,101.6,94,23.89,1,03   7.2.3 Firmware Download  H,BT,358281000146500,080401153209,9F84265E,12F4A98D   L,080528112501,AI1,145.56  L,080528112630,DI3,1 ...

  • Page 36: Configuration Update

    tracker  PANIC_BTN,1  VBAT12,1  ANC,0,0,0,0,1   7.2.5 Configuration update  H,BT,358281000146500,080401153209,9F84265E,12F4A98D   L,080528112501,AI1,145.56  L,080528112630,DI3,1  L,080528112835,G,52.4,-1.3,101.6,94,23.89,1,03;DI3,1  L,080528152501,AI1,145.56  L,080528152601,AI1,145.56  L,080528152701,AI1,145.56  L,080528152701500,AI1,145.56     JDISTALM,200  JTIMEALM,7200  UPLOADI,60   Communication Protocol v1.5 35 of 36...

  • Page 37: Road Map

    tracker Road Map Harsh braking, harsh acceleration detection. Driver ID not presented within time limit log Event 14. More status information is to be passed with each GPS position. Configuring analogue inputs as digital inputs (to give maximum of 6 Digital inputs). Digital status passed back as a HEX value with a GPS position with each packet (configurable).

Table of Contents