________ TITLE: Brief manual on GPS Track Server ________
Date: 2017/July/27
Version: 1.2
Author and Copyright: Alexander Konovalenko
Content:
I) Introduction
II) License agreement
III) Compilation from source code
IV) Running and testing server functionality
V) Configuring GPS tracking unit
VI) Packet logs format
VII) TBD and what you should not request from me
-------------------------------------------------------------------------
I) Introduction
The GPS Track Server project is brought to you "as is". The main
author's objective is to get minimal and necessary functionality.
A small server-side application is dedicated to provide TCP-packets
response and basic logging functionality from operating low cost
commercially available GPS Vehicle Trackers such as Concox GT06N
and perhaps others. The application is using POSIX API and intended
to run on Unix, Linux and even Windows systems (cygwin environment).
Originally it has been developed and tested on FreeBSD 10.3.
The server application does not communicate with database or web
server. You can modify this (complying with license) and add database
logging or other features.
The package consist of following elements:
bin/
docs/
Makefile
packets_examples/
src/
-------------------------------------------------------------------------
II) License agreement
The GPS Track Server package is licensed under terms and conditions of
the BSD-type license agreement:
####################################################################
Copyright 2017-2019 by Alexander Konovalenko, unixoidal@outlook.com
The GPS Track Server Project. All rights reserved.
Redistribution and use in source and binary forms, with or
without modification, are permitted provided that the following
conditions are met:
1) Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2) Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS
BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
The views and conclusions contained in the software and documentation are
those of the authors and should not be interpreted as representing official
policies, either expressed or implied, of the GPS Track Server Project.
####################################################################
-------------------------------------------------------------------------
III) Compilation from source code
There are indeed minimal requirements to compile and run this server:
gcc, make or gmake.
On BSD like system the gmake should be used, just type in the command line:
> gmake
On Linux and Windows (cygwin) type:
> make
If there are errors then modify Makefile appropriately.
-------------------------------------------------------------------------
IV) Running and testing server functionality
If successfully compiled, there will a binary file bin/tr_server[.exe] created.
Run server as following:
> bin/tr_server
or to specify arbitrary tcp port 1234:
> bin/tr_server 1234
The argument is an integer decimal number 0-65535 representing the TCP port.
The default port (no command line arguments) is 29810. To run this application
on the background add "&" at the end of command. To test functionality without
actual GPS unit perform following (FreeBSD):
> bin/tr_srv 12345 &
Check open sockets by issuing:
> sockstat -4
Send a prepared packet:
> cat packets_examples/x16.hex | nc localhost 12345
Press Ctrl-C to close connection.
The server should respond and print out following:
>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
INFO: Connection accepted
INFO: Handler assigned
Client disconnected
INFO: Connection accepted
INFO: Handler assigned
DEBUG: time-stamp Tue Jul 18 00:40:04 2017
DEBUG: Received packet of length 42 bytes:
0x7fffdfbfb7a0 78 78 25 16 11 07 0F 12 04 33 C3 06 5E 6F E0 01 xx%......3..^o..
0x7fffdfbfb7b0 EB 86 90 00 44 00 09 00 F0 18 34 6D 00 9E 49 20 ....D.....4m..I
0x7fffdfbfb7c0 03 04 01 02 00 08 2D 2F 0D 0A 00 00 00 00 00 00 ......-/........
DEBUG: checkCRC 36 bytes: starting=25
DEBUG: crcPacket=2D2F vs crcCalc=2D2F
INFO: CRC of incoming packet is OK!
|-----DEBUG START in packetLogger-----
| char* data_in= 0x7fffdfbfb7a0
|-----DEBUG END in packetLogger -----
INFO: Reply sent to client!
|-----DEBUG START in terminal_handler-----
DEBUG: Sent 10 bytes:
0x7fffdfbfbb90 78 78 05 16 00 00 C1 C5 0D 0A 00 00 00 00 00 00 xx..............
|-----DEBUG END in terminal_handler -----
Tue Jul 18 00:40:04 2017 IMEI NONE PNo 0x16 Alarm data 17/07/15 18:04:51 Sats195 Pos 59.36240000 17.89590222 Vel 0 Real time GPS GPS isn't posed. E-Long S-Lat Course 0 LSB_LEN 9 MCC/MNC/LAC/CELLID 240/24/13421/4824576 Alarm data Defense off/on:0 ACC low/high:0 Charge off/on:0 GPS tracking off/on:0 Oil&elec. off/on:0 V-Lev(0-6) 3 GSM-Lev(0-4) 4
>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
Note, that debug messages are printed into stderr while packets logs (last
line in above printout) goes to stdout. If you want to redirect logs into a
separate file run server as:
> bin/tr_srv 12345 > filename.log
Recorded logs can be accessed from web (if your host has web server) as:
> bin/tr_srv 12345 > ~/public_html/filename.log
To preserve previously recorded logs run:
> bin/tr_srv 12345 >> ~/public_html/filename.log
To shut down the server perform one or few of following:
- press ctrl-c if process is running on the foreground
- use "kill" command
- use "sockstat -4" to check if socket is still open, if it is then use
tcpdrop (FreeBSD) or similar on your system to force socket drop.
-------------------------------------------------------------------------
V) Configuring GPS tracking unit
This tracking server was originally designed and tested with Concox GT06N unit.
That unit can be configured to communicate with your server host and default
port 29810 (or other) by sending a following SMS command:
Server,1,server.host.whatevername_or_IP.com,29810#
The command format might differs, refer to your unit manual. After configuring
the unit be sure that server firewall is configured to allow TCP connections on
selected port.
-------------------------------------------------------------------------
VI) Packet logs format
NOTE: This section is incomplete!!!! The main reason is that Chinese
documentation is unclear, it contains many typos and errors. Thus, implementation
itself is unfinished and provides basic functionality only.
The packet logger records following information from GPS units:
- Timestamps of arriving packets
- IMEI number of the unit (multiple client connections are supported)
- Packet number (referred as "protocol number" in Chinese documentation)
- Defense and alarm status, ACC/Battery etc connection lines status
- GPS coordinates (latitude and longitude)
- speed of the vehicle
- number of GPS satellites
- GSM network strength signal
- Battery level
- periodic statistics of the traffic to/from/total bytes and estimation of
how many kBytes/h and Mb/Month is expected. Useful for data cost estimate of
your unit.
... etc
The IMEI is remembered for each established connection and partly printed (most
of the digits are masked with "*", user can unmask IMEI by commenting out
SWITCH_SECURE_IMEI define in tr_protocol.h) for all incoming packets from that
particular client. What is NOT logged:
- Emergency cellphone number coming in packet 0x94. This is for security reasons,
you can enable it in the code by commenting out SWITCH_SECURE_PInfoTrans define
in tr_protocol.h
- response packets from server are not logged. No need.
-------------------------------------------------------------------------
VII) TBD and what you should not request from me
What is left Bo Be Done? Beside bugs (which will never be fixed :-D) the
most useful features are:
- convert GPS position into an array and create a clickable URL to online maps
- the database connectivity can be implemented, however, there is no need
in my opinion, because it is better to write log wrapper, a smart shall or perl
script which will convert tr_server stdout into SQL commands in real time.
----- THE MESSAGE TO USERS -----
1) So, guys, you can use, modify and enjoy this small and primitive server, and
please, do not ask me to implement above mentioned or similar features. Unless,
somebody will pay me some bucks I will not do it!
2) Please do not contact me regarding bugs and improvements until you READ
and study in details both the CODE and available DOCUMENTATION!
