README.md

   1 # A server to collect data from zx303 ZhongXun Topin Locator
   2
   3 zx303 GPS+GPRS module is a cheap and featureful GPS tracker for pets,
   4 children, elderly family members, and, of course, illegal tracking
   5 of people and objects, though the latter absolutely must not be done.
   6
   7 ## Introduction
   8
   9 This work is inspired by [this project](https://github.com/tobadia/petGPS),
  10 but it is more of a complete re-implementation than a derived work.
  11 There also exists an
  12 [industrial strength open source server](https://www.traccar.org/)
  13 that supports multiple types of trackers.
  14
  15 When powered up, the module makes TCP connection to the configured
  16 (via SMS) server, identifies itself (with IMEI) in the first message,
  17 and continues to send periodic messages with location and other status
  18 updates. Some of these messages require a response from the server.
  19 In particular, when the module has no GPS coverage, it sends information
  20 about nearby GSM+ cell towers and WiFi access points, to which the server
  21 is expected to respond with a message containing approximate location
  22 derived from this data. To do that, the server may need to consult with
  23 some external service.
  24
  25 Because we would usually want location information reach consumer
  26 instantly upon arrival, and _also_ to be stored, it makes sense to
  27 design the system in "microservices" way, using a message bus in
  28 "publish-subscribe" model. And then, since we already have a
  29 message-passing infrastructure anyway, it makes sense to decouple
  30 the server process that maintains TCP connections with the the tracker
  31 terminals from the processes that analyses messages and prepares responses.
  32
  33 This leads us to this implementation, that has consists of five daemons
  34 that talk to each other over Zeromq:
  35
  36 - **collector** that keeps open TCP connections with the terminals
  37   and publishes received messages _and_ sent responses on the message
  38   bus,
  39 - **storage** that subscribes to the messages and responses from the
  40   collector and stores them in a database,
  41 - **termconfig** that subscribes to messages that need nontrivial
  42   response (most of them are about configuring various settings in
  43   the terminal, hence the name), and sends responses to the collector
  44   for relaying to the terminal,
  45 - **lookaside** that subscribes to "rough" location messages, queries
  46   an external source (in our implementation, either google maps "API",
  47   or a local opencellid database), and prepares responses with
  48   approximated location, and
  49 - **wsgateway** that is a websockets server that translates messages
  50   between our internal zeromq bus and websocket clients, i.e. web
  51   pages. This daemon is also capable of responding to http with
  52   a single html file. This functionality is mainly for debugging.
  53   Users of the package are expected to implement their own web
  54   application that communicates with this server.
  55
  56 There is also a command-line tool to send messages to the terminal.
  57 A number of useful actions can be initiated in this way.
  58
  59 ## Configuring the Terminal
  60
  61 Send SMS to the telephone number of the SIM card plugged in the terminal,
  62 with the text
  63
  64 ```
  65 server#<your_server_address>#<port>#
  66 ```
  67
  68 Server address may be FQDN or a literal IP address. Port is a number;
  69 by default, this application listens on the port 4303. A different
  70 port can be configured in the config file.
  71
  72 It is recommended to always keep the service running while the terminal
  73 is powered up: it is possible that the terminal is programmed to reset
  74 itself to the default configuration if it cannot connect to the server
  75 for prolonged time.
  76
  77 ## Websocket messages
  78
  79 Websockets server communicates with the web page using json encoded
  80 text messages. The only supported message from the web page to the
  81 server is subscription message. Recognised elements are:
  82
  83 - **type** - a string that must be "subscribe"
  84 - **backlog** - an integer specifying how many previous locations to
  85   send for the start. Limit is per-imei.
  86 - **imei** - a list of 16-character strings with IMEIs of the
  87   tracker terminals to watch.
  88
  89 Each subscription request nullifies preexisting list of IMEIs
  90 associated with the web client, and replaces it with the list supplied
  91 in the message.
  92
  93 Example of a subscription request:
  94
  95 ```
  96 {"imei":["8354369077195199"],
  97  "type":"subscribe",
  98  "timestamp":1652134234657,
  99  "backlog":5}
 100 ```
 101
 102 Server sends to the client a backlog of last locations of the
 103 terminals, that it fetches from the database maintained by the
 104 storage service, one location per websocket message. It then
 105 continues to send further messages when they are received from
 106 the module, in real time, including gps location, responses with
 107 approximated location, and status with the precentage of battery
 108 charge.
 109
 110 Example of a location message:
 111
 112 ```
 113 {"type": "location",
 114  "imei": "8354369077195199",
 115  "timestamp": "2022-05-09 21:52:34.643277+00:00",
 116  "longitude": 17.465816,
 117  "latitude": 47.52013,
 118  "accuracy": "gps"} // or "approximate"
 119 ```
 120
 121 Example of a status message
 122
 123 ```
 124 {"type": "status",
 125  "imei": "8354369077195199",
 126  "timestamp": "2022-05-09 21:52:34.643277+00:00",
 127  "battery": 46}
 128 ```
 129
 130 ## Lookaside service
 131
 132 When the terminal has no gps reception, it uses secondary sources of
 133 location hints: list of nearby cell towers, and list of MAC addresses
 134 of nearby WiFi access point, with signal strength. It expects a
 135 response from the server with approximated location. In order to get
 136 such approximation, the server system needs a source of information
 137 about cell towers and/or WiFi access points in the area. We support
 138 two ways to get approximated location: querying Google geolocation
 139 service, and using locally installed database filled with data
 140 downloaded from opencellid crowdsourced source. For both options,
 141 you will need an access token. Google service is "online", you are
 142 making a request for each approximation (and thus reveal location of
 143 your users to Google). Opencellid service is "offline": you download
 144 the file with locations of all cell towers in the country (or worldwide)
 145 once, or refresh it at relatively long intervals, such as a week or a
 146 month, and then all queries are fulfilled locally. Note that opencellid
 147 data does not contain WiFi access points, so the approximation will
 148 less accurate.
 149
 150 Lookaside service can be configured to use either of the options by
 151 assigning `backend = opencellid` or `backend = googlemaps` in the
 152 configuration file (`/etc/loctrkd.conf` by default). Then, the path to
 153 the file with the auth token needs to be specified in the `[opencellid]`
 154 section or `[googlemaps]` section of the configuration file respectively.
 155
 156 Note that in both cases, the value in the configuration file needs
 157 to _point to the file_ that contains the token, rather than contain
 158 the token itself. The file needs to be readable for the user under which
 159 services are executed. That is the user `loctrkd` if this software was
 160 installed as the Debian package.
 161
 162 This part of setup cannot be automated, because each user needs to
 163 obtain their own access token for one of the above services.
 164
 165 ## Termconfig Service
 166
 167 To configure terminal settings, such as SOS numbers, update intervals etc.,
 168 "termconfig" service consults the configuration file. It should contain
 169 the section `[termconfig]`, and optionally sections named after the IMEIs
 170 of individual terminals. `[termconfig]` values are used when the individual
 171 section is not present.
 172
 173 For a bigger multi-client setup the user will want to re-implement this
 174 service to use some kind of a database, with the data configurable by the
 175 owners of the terminals.
 176
 177 ## Homepage and source
 178
 179 Home page is [http://www.average.org/loctrkd/](http://www.average.org/loctrkd/)
 180 Get the source from the origin `git://git.average.org/loctrkd.git`
 181 or from [Github mirror](https://github.com/crosser/loctrkd).