README.md

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