Introduction ============ This file describes how to configure and run the OpenGTS device communication server (DCS) for Astra Telematics vehicle tracking devices. The file also describes the configuration options of the tracking devices necessary to communicate with the DCS. This server supports the following devices: - AT110 - AT210 - AT240 Configuration of the above devices is described in the relevant User Guides available from the following link: http://gps-telematics.co.uk/downloads.htm Additional product documentation is also available for download from this link. Configuring the Server ====================== Changing the Server "Listen" Ports ---------------------------------- The ports on which the Astra DCS listens for incoming data packets is specified on the "ListenPorts" tag within tag in the "dcservers.xml" file: The default is 31090. If required, the "listen" port can be changed to fit the requirements of your runtime environment. The tracking devices will need to be configured to transmit data to the same port as the server used to listen for incoming data packets. See the section "Setting the Astra Device Properties" below The "listen" ports must be open through the firewall in order for the remote device to send data to the Astra server. If packet acknowledgement is required, any acknowledgements sent by the server back to the remote device must be sent from the same IP address to which the remote device sent it's data packet. If your server responds to more than one IP address, then the Astra server listener must be bound to the same IP address/interface used by the remote tracking devices. This is set in the top-level "dcservers.xml" file, on the "DCServerConfig" tag, "bindAddress" attribute. Setting the "Unique-ID" Prefix Characters ----------------------------------------- The Unique-ID prefix characters can be set in the "UniqueIDPrefix" tag section: These prefix characters are used to 'prepend' to the IMEI number as reported by the device to look-up the owning Account/Device record for this device. For instance, if the Astra device IMEI is "123456789012345", then the system will search for the owning Device using the following Unique-ID keys, in the order specified: astra_123456789012345 imei_123456789012345 123456789012345 Note that the '*' character by itself indicates that the system should look up the Astra device IMEI without any prefixing characters. To bind an Astra device to a specified Account/Device record, set the "Unique ID:" field on the Device Admin page to the appropriate prefixed unique-id value. For example: Unique ID: astra_123456789012345 Setting the Astra Device Properties ----------------------------------- Refer to the relevant product User Guide for complete descriptions of the configuration commands. The IP address is set with the following command $IPAD, For example, $IPAD,192.168.1.1 The TCP/UDP port is set with the command $PORT, For example, $PORT,31090 The protocol should be selected as follows: AT210 - Protocol K (6) AT110/AT240 - Protocol M (8) To set the protocol use the command $PROT,, for example to select protocol M use $PROT,8 The MODE must be set to TCP or UDP as required. To select TCP use $MODE,4 To select UDP use $MODE,5 Once configured these settings will be retained by the device. The Astra server will send acknowledgement to the tracking device on successful decoding of received packets. The device time limit from sending a packet to receipt of the acknowledgement is set be the command $TCPT, If the device is to ignore acknowledgements then this can be set to 0, but this is not recommended. Running the Server ================== To begin listening for incoming events the server must be started. This section describes the process for manually starting the Astra server and how to stop it. Manually Starting the Server ---------------------------- The command for manually starting the Astra server on UNIX/Linux is as follows: cd $GTS_HOME bin/runserver.pl -s astra For Windows use cd %GTS_HOME% bin\runserver.bat astra To start the Astra server with debug logging (useful when testing or debugging), the option "-debug" may be added to the command line. The server will start, and logging information will be sent to the file: "$GTS_HOME/logs/astra.log" or "%GTS_HOME%\logs\astra.log" on Windows. To change the listening port from that specified in the "ListenPorts" tag in the "dcservers.xml" file the -port argument can be used from the command line as follows: bin/runserver.pl -s astra -port 8001 or on Windows bin\runserver.bat astra -port:8001 Stopping the Server ------------------- To stop the running Astra server, enter the following commands: cd $GTS_HOME bin/runserver.pl -s astra -kill On Windows use Ctrl-C to terminate the runserver batch job. Adding Devices to an Account ============================ When data is received from a remote Astra tracking device, the Astra server looks up the IMEI number in the Device table to determine which Account/Device owns this device. This section describes how to create a Device record and associate an Astra tracking device with the Device record. Creating a New Device Record ---------------------------- Using the web-interface, log in to the appropriate Account which should own the Astra tracking device, then traverse to the "Vehicle Admin" page. Create a new Device then "Edit" the newly created Device record. On the Edit page, there will be a field described as follows: Unique ID: [ ] In this field enter the value "astra_", replacing "" with the device IMEI number. For instance, if the IMEI number is "123456789012345", then enter the value "astra_123456789012345" in this "Unique ID:" field. You may also use "imei_123456789012345" or just "123456789012345". After making changes to the Device record, click the "Change" button. Testing a New Configured Device =============================== This section describes the process for monitoring newly configured Astra devices that have been assigned to an Account/Device record. Monitoring for Incoming Connections ----------------------------------- The Account report "Last Known Device Location" can be used to display the last known location of a given device, which can also be used to determine whether any events have been received from a specific Astra device. If there are no device reports then the log file itself can be consulted for indications of incoming data packets from the Astra device. The information in the log file can indicate whether an IMEI number may not have been properly assigned. If the device record hasn't been created or the IMEI has been entered incorrectly you will see a message in the log file containing "!!!UniqueID not found!: " where is a 15 digit number. Device Data =========== The following section refers to data stored in the EventData table. Odometer -------- The odometerKM field in the EventData table is populated with data from the device for ignition on and ignition off records. For all other records it is reported as zero. The distanceKM field is populated with the distance travelled during a journey since the last ignition on record. This will be the total distance for the journey when the next ignition off record is inserted. Additional Data --------------- The flag addRawData can be set true in the TrackClientPacketHandler.java class to enable the Astra server to insert additional data in to the rawData field. Please refer to the relevant protocol description documentation. Setting addRawData to false will leave the rawData field empty. Protocol K ---------- For protocol K an example of the contents would be R=000040;S=0101;P=12.2V;B=100%;D=01;A1=0.0V;M=0km/h;X=0,0;Y=0,0;Z=0,0;I=0s;Q=A4;G=00 where R = Reason Code (24 bits) S = Status Code (16 bits) P = External power (Volts) B = Battery level (Percentage) D = Digital input/output status and state changes (8 bits) A1 = External ADC1 reading (0-5 Volts) M = Maximum journey speed (km/h) X = Accelerometer X-axis max, min readings (m/s/s * 10) Y = Accelerometer Y-axis max, min readings (m/s/s * 10) Z = Accelerometer Z-axis max, min readings (m/s/s * 10) I = Journey Idle Time (Seconds) Q = Signal quality (MS nibble: GSM [0-15], LS nibble: number of GPS satellites in use) G = GeoFence Event During a journey the maximum journey speed is the maximum speed attained since the last report. For the next ignition off record it is the maximum speed attained during the entire journey. During a journey the maximum and minimum accelerometer data is since the last report. For the next ignition off record it is the maximum and minimum for the entire journey. Protocol M ---------- For protocol M an example of the contents would be R=000080;S=0100;P=12.4V;B=100%;D=000100;A1=0.0V;A2=0.0V;M=0km/h;X=3,0;Y=0,2;Z=0,8;I=14s;Q=C8;G=00 where R = Reason Code (24 bits) S = Status Code (16 bits) P = External power (Volts) B = Battery level (Percentage) D = Digital input/output status and state changes (24 bits) A1 = External ADC1 reading (0-5 Volts) A2 = External ADC2 reading (0-15 Volts) M = Maximum journey speed (km/h) X = Accelerometer X-axis max, min readings (m/s/s * 10) Y = Accelerometer Y-axis max, min readings (m/s/s * 10) Z = Accelerometer Z-axis max, min readings (m/s/s * 10) I = Journey Idle Time (Seconds) Q = Signal quality (MS nibble: GSM [0-15], LS nibble: number of GPS satellites in use) G = GeoFence Event During a journey the maximum journey speed is the maximum speed attained since the last report. For the next ignition off record it is the maximum speed attained during the entire journey. During a journey the maximum and minimum accelerometer data is since the last report. For the next ignition off record it is the maximum and minimum for the entire journey.