BOX Telematics BOX tracker, Communication Protocol Manual

Page 1: ...Communication Protocol v1 5 ...

Page 2: ...e for errors contained herein or for incidental or consequential damages in connection with the furnishing performance or use of this material This document contains proprietary information which is protected by copyright No part of this document may be photocopied reproduced or translated into another language without the prior written consent of BOX telematics limited The information is provided...

Page 3: ... updates Warning This document supersedes all previous provisional release documents prior to 1 February 2009 Provisional commands and features not detailed in this documentation are no not currently supported and may stop working in future releases of firmware Technical Support For help and assistance please email TechnicalSupport box tracker com Document Conventions Data sent from the tracker to...

Page 4: ...A 15 4 2 No Firmware Available 15 N 15 4 3 Firmware Transfer 15 F FirmwareVersion StartPosition 15 F FirmwareVersion StartPosition Length 15 5 Configuration Update Protocol 16 6 Configuration Commands 17 6 1 ACCESS 17 6 2 ADDKEY 17 6 3 ANC 18 6 4 ANL 18 6 5 CONFIG 18 6 6 DEFAULT 19 6 7 DELKEY 19 6 8 DIR 19 6 9 FWS_TIME 19 6 10 GEOF 20 6 11 GPRS_APN 20 6 12 GPRS_USERNAME 20 6 13 GPRS_PASSWORD 20 6 ...

Page 5: ...7 6 38 SERVER1_PORT 27 6 39 SERVER2_ADDR 27 6 40 SERVER2_PASS 28 6 41 SERVER2_PORT 28 6 42 SIM_SN_ALWAYS 28 6 43 SPEEDALM 28 6 44 SYNC 29 6 45 TIME 29 6 46 UPLOADI 29 6 47 UPLOADI_BOFF 29 6 48 UPLOADI_IOFF 29 6 49 UPLOADD 30 6 50 UPLOADHC 30 6 51 VALIDATE_KEY 30 6 52 VBAT12 30 6 53 VER 31 7 Appendix 32 7 1 CRC Check Sum Algorithm 32 7 2 Example Communication Sessions 33 7 2 1 Disconnected Session ...

Page 6: ...RM_CON permanent connection added 5 32 SERVER2_ADDR added 5 33 SERVER2_PASS added 5 34 SERVER2_PORT added 5 35 SIM_SN_ALWAYS added 5 42 VBAT12 added 6 3 Road map updated 1 5 19 6 09 6 15 GPSD added 6 49 UPLOADD added 6 50 UPLOADHC added 3 2 1 Event code 24 modified and event code 25 39 40 41 added 6 10 GEOFx added 6 19 IMMOBILISER added 6 51 VALIDATE_KEY added 6 2 ADDKEY added 6 7 DELKEY added 6 2...

Page 7: ...nd the server can be minimal making it easy and quick to develop a communication interface During a connection the server may also send commands to BOX tracker thus providing two way communications If a connection is interrupted BOX tracker will initiate a new connection and resume communication without loss of data as long as these protocols are followed When a connection is first opened a header...

Page 8: ...eading or trailing spaces within the command name or each parameter are ignored Each command sent must be terminated by a Carriage Return 0xD or within an SMS by a percentage symbol The only exception is a command sent via SMS where the last command need not be terminated A command may contain mandatory or optional parameters Parameters are separated by a comma and if a parameter is not required i...

Page 9: ...SerialNum DateTime SecurityToken FirmwareVer SimNumber eg H BT N878123 080415081234 D63E6DD9 6D6E6DC2 8944100300825505377 Device Type BT Serial Number N78123 Date Time 2008 04 15 08 12 34 Security Token D63E6DD9 Firmware 6D6E6DC2 SIM number 8944100300825505377 Device Type The device Type defines the type of device the server is communicating with Currently BOX tracker only returns the string BT In...

Page 10: ...calculated by concatenating the Serial Number Date Time string as passed in the header command and a secret password which can be configured into a single string and using this to obtaining a CRC32 value Commas are not included in this string The default secret password is password without the quotation marks This password can be changed The CRC calculation is based on a case sensitive string For ...

Page 11: ...Item Date Time The date and time is always in the format YYMMDDHHmmss and is the time the log record was made If multiple Data Items are included in the log command then all were recorded at this time Data Item BOX tracker can log a variety of Data Items the name of which is passed prior to its values The Data Item name allows the server to identify how to handle its values The following Data Item...

Page 12: ...lt this contains the distance travelled since the start of the journey travel This can be configured to return the odometer reading if required Distance is returned as a floating point number in Kilometers Event Code The event code defines the reason why the log entry was made The following event codes are returned however future firmware releases may return additional event codes The event code i...

Page 13: ...nce Exited A geofence has been exited 28 External Power On See the VBAT12 command The external power vehicle battery has been turned on Usually in a vehicle this will only occur once when first installing or when the vehicles battery is reconnected after servicing 29 External Power off See the VBAT12 command The external power vehicle battery has been removed 32 Idle Event Occurs when the tracker ...

Page 14: ...egative Longitude 1 3 degrees west east is positive and west is negative Speed 101 kph Bearing 94 degrees 0 degrees north Distance 23 89 kilometers since ignition on may be blank in certain applications Event Code 1 Status 1 ignition on End MaxSpeed IdleTime StartTime Returns information relating to the last journey This Data Item is passed when an ignition off occurs MaxSpeed Maximum speed which ...

Page 15: ...d DI value Defines the status of a specific digital input DI The Data Item name where defines the digital input number 0 or 1 Value Either the value 0 or 1 indicating the state of the input AI value Defines the status of a specific Analogue input AI The Data Item name where defines the analogue input number 0 to 3 Value Floating point number representing the measured Voltage BOOT message Message i...

Page 16: ...ting the FWS_TIME parameter See section 6 9 4 1 Firmware Available FA The server should check the firmware version number passed in the Header H command to see if a later version is available If a new version is available then the server should send an FA command to the tracker On receipt of the FA command and after all logs have been sent BOX tracker will send an F Command see below requesting th...

Page 17: ...ested If on resuming a download the server has a new firmware version available then instead of resuming the sending of the requested firmware it may instead send the new firmware from the start If this happens the F Command should be sent with the new firmware version a start position of zero and the length of the firmware data BOX tracker will see the firmware version is different to that reques...

Page 18: ...s a more comprehensive security method Bit Access Method 0 RS232 Command line 1 USB Command line 2 GSM Command Line 3 SMS Command Line E g USB and SMS requires a password ACCESS 10 Default value 12 password required for GSM and SMS access Range Decimal number representing a single 8 bit byte See also the PASSWORD command section 6 32 6 2 ADDKEY This command is used in conjunction with the immobili...

Page 19: ...es the rate in seconds the enabled analogue channels are logged See ANC command If this value is set to zero then no Analogue channels will be logged even when enabled via the ANC command Default value 0 seconds Range 0 to 4 294 967 47 days 6 5 CONFIG Returns the current settings the order and specific settings returned may vary depending on the firmware version CONFIG ACCESS 12 ANC 0 0 0 0 0 ANL ...

Page 20: ...56789ABC from group A enter delkey A 123456789ABC The DELKEY ALL command will delete all keys in all groups 6 8 DIR Returns a list of all files on the tracker 6 9 FWS_TIME 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 upd...

Page 21: ... to configure geofence 2 geof2 1 1 0 53 58688 2 40346 2 79 6 11 GPRS_APN Allows a specific GPRS APN to be specified If this is set to an empty string then the public APN contained in the trackers internal APN table is used based on the network of the SIM For a private APN this will always need to be set E g GPRS_APN OrangeInternet Default value A public APN is automatically detected Range 0 to 64 ...

Page 22: ...stance travelled Eg Configure the tracker to log an entry when the distance travelled is greater than or equal 5km GPSD 5 Default value 0 km disabled 6 16 GPSLI Defines the interval in seconds between successive vehicle location logs whilst the ignition is on This only defines the interval between logs and not the frequency the data is sent to the server Eg Log vehicle locations every two minutes ...

Page 23: ...king circuit depending on the state of digital output 1 and uses digital output 0 to sound a buzzer IMMOBILISER 0 2 0 Immobiliser is not fitted and the out commands are enabled 1 Immobiliser relay fitted Command out1 is disabled 2 Immobiliser relay and buzzer fitted out commands are disabled Default value 0 See Also IMMOB VALIDATE_KEY ADDKEY DELKEY OUT 6 20 IMMOB The IMMOB command specifies how th...

Page 24: ...seconds IDLEALMT 20 Default value 0 disabled Range 0 to 4 294 967 seconds 49 7 days 6 23 IGN_OFF_CHG When set to zero the internal battery is not recharged when the ignition is off When set to a 1 the internal battery is recharged from the external supply when the ignition is off When the ignition is on the internal battery is always recharged from the external supply car battery IGN_OFF_CHG 1 Def...

Page 25: ...so the format of the data needs to be agreed this with the server provider The data must not have any non ASCII characters be enclosed in double quote characters if it contains spaces not contain double quote characters in the data not exceed 70 characters in length E g these two examples produce exactly the same result log temp 12 34 humidity 45 67 io 0x45 log temp 12 34 humidity 45 67 io 0x45 E ...

Page 26: ...or 1 6 29 OFFSW Enable or disable the use of the trackers inbuilt push button switch to turn the tracker off Set to 1 to allow the tracker to be turned off and 0 to prevent this To prevent the off pushbutton turning the tracker off OFFSW 0 Default value 1 enabled Range 0 or 1 6 30 OUT Allows the trackers digital output to be turned on or off The output number should be used in place of the in the ...

Page 27: ...word This password is not used to calculate the security token passed in the header command sent over GPRS instead see Server1_Pass command section 6 37 The password is case sensitive E g PASSWORD myPassword Default value password Range 0 to 20 characters 6 33 PERM_CON Enables or disables permanent TCP connections with the server A permanent connection can help reduce the amount of GPRS data used ...

Page 28: ...ssword is case sensitive E g SERVER1_PASS MyPassword Default value password Range 0 to 20 characters 6 38 SERVER1_PORT The port number to be used for GPRS communication Setting to zero will disable all GPRS communication E g SERVER1_PORT 9002 Default value 0 Range 0 to 65535 6 39 SERVER2_ADDR A secondary fall back TCP IP server address may be specified If the tracker fails to connect to the SERVER...

Page 29: ...nly passed in the TCP Communication header command when the SIM is first changed or once every 48 hours This is intended to reduce the amount of data passed when making a connection If this command is set to 1 then the SIM number is passed in each header command allowing the tracker to be identified by its SIM number instead of it serial number E g SIM_SN_ALWAYS 1 Default value 0 Range 0 or 1 6 43...

Page 30: ... any control over this On Vehicle trackers this defines the frequency data is sent to the server whilst the ignition is ON E g UPLOADI 60 Default value 300 seconds 5 minutes Range 0 to 4 294 967 seconds 49 7 days 6 47 UPLOADI_BOFF On Vehicle trackers this defines the frequency data is sent to the server whilst the external battery supply is OFF On Asset trackers this has no affect E g UPLOADI_BOFF...

Page 31: ...and the immobiliser is disabled allowing the vehicle to start 1 validate key Any Ibutton Key presented to the reader is looked up in the stored keys file If the key is not present in the file then the key is rejected buzzer sounds for 1 second if fitted enabled and the immobiliser is not disabled E g All keys must be validated before immobiliser is deactivated VALIDATE_KEY 1 See Also IMMOBILISER I...

Page 32: ...a 24 volt supply VBAT12 0 Default value 1 12 Volt Range 0 or 1 6 53 VER Returns version and firmware information on the tracker VER 1 12 OK VER 1 URL file C SvnRepos Tracker Tags 1 12 version c Aug 1 2008 12 58 41 GCC 4 1 1 FW id 5AA5A55A len 68492 crc D23795E8 OK ...

Page 33: ...ic enum CrcType CRC16CCITT 0 CRC32 1 private static readonly int crcBit 16 32 private static readonly long crcPoly 0x1021 0xEDB88320 private static readonly bool crcReflectIn false true private static readonly bool crcReflectOut false true private static readonly bool crcXor false true public static long CrcCheckSum byte data CrcType crcType if data Length 0 return 0 int crcIndex int crcType int b...

Page 34: ...153209 9F84265E 12F4A98D L 080528113335 G 52 4 1 3 101 6 94 23 89 1 03 L 080528113435 G 52 4 1 3 101 6 94 23 89 1 03 L 080528113535 G 52 4 1 3 101 6 94 23 89 1 03 L 080528113635 G 52 4 1 3 101 6 94 23 89 1 03 L 080528113735 G 52 4 1 3 101 6 94 23 89 1 03 E 0 A 0 7 2 2 Permanent connection H BT 358281000146500 080401153209 9F84265E 12F4A98D L 080528112835 G 52 4 1 3 101 6 94 23 89 1 03 L 0805281129...

Page 35: ...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 E 2 A 2 7 2 3 Firmware Download H BT 358281000146500 080401153209 9F84265E 12F4A98D FA L 080528112501 AI1 145 56 L 080528112630 DI3 1 L 080528112730 FAULT A very bad fault has occurred L 080528112835 G 52 4 1 3 101 6 94 23 89 1 03 DI3 1 L 080528112935 DEBUG Failed connections 23 L 080528152501 AI1 145 56...

Page 36: ...e H BT 358281000146500 080401153209 9F84265E 12F4A98D CR 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 E 0 A 0 CP JDISTALM 200 JTIMEALM 7200 UPLOADI 60 E 1 A 1 ...

Page 37: ...n 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 Instant GPRS connection on a digital status change Accelerometer used to detect motion or an Impact Binary UDP protocol Peripheral hardware connectivity CANBUS interface ...