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 reimplementation than a derived work.
  11
  12 When powered up, the module makes TCP connection to the configured
  13 (via SMS) server, identifies itself (via IMEI) in the first message,
  14 and continues to send periodic messages with location and other status
  15 updates. Some of these messages require a response from the server.
  16 In particular, when the module has no GPS coverage, it sends information
  17 about neaby GSM+ cell towers and WiFi access points, to which the server
  18 is expected to respond with a message contaning approximate location
  19 derived from this data. To do that, the server may need to consult with
  20 some external service.
  21
  22 Because we would usually want location information reach consumer
  23 instantly upon arrival, and _also_ to be stored, it makes sense to
  24 design the system in "microservices" way, using a message bus with
  25 "publish-subscribe" model. And then, as we already have a message-passing
  26 infrastructure anyway, it makes sense to decouple processes that prepare
  27 responses to the module's messages from the server process that maintains
  28 TCP connections to the modules.
  29
  30 This leads us to the current implementation that has consists of
  31 five daemons that talk to each other via zeromq:
  32
  33 - **collector** that keeps open TCP connections with the terminals
  34   and publishes received messages _and_ sent responses on the message
  35   bus,
  36 - **storage** that subscribes to the messages and responses from the
  37   collector and stores them in a database,
  38 - **termconfig** that subscribes to messages that need non-trivial
  39   response (most of them are about configuring various settings in
  40   the terminal, hence the name),
  41 - **lookaside** that subscribes to "rough" location messages, quieries
  42   an external source (in our implementation, opencellid database),
  43   and prepares the response to the terminal containing approximated
  44   location, and
  45 - **wsgateway** that is a websockets server that translaes messages
  46   between our internal zeromq bus and websocket clients, i.e. web
  47   pages. This daemon is also capable of responding to http with
  48   a single html file. This functionality is mainly for debugging.
  49   Users of this package are expected to implement their own single
  50   page web application that communicates with this server.
  51
  52 There is also a command-line tool to send messages to the terminal.
  53 A number of useful actions can be initiated in this way.
  54
  55 ## Websocket messages
  56
  57 Websockets server communicates with the web page via json encoded
  58 text messages. The only supported message from the web page to the
  59 server is subscription message. Recognized elements are:
  60
  61 - **type** - a string that must be "subscribe"
  62 - **backlog** - an integer specifying how many previous locations to
  63   send for the start. Limit is per-imei.
  64 - **imei** - a list of 16-character strings with IMEIs of the
  65   tracker terminals to watch.
  66
  67 Each subscription request nullifies preexisting list of IMEIs
  68 associated with the web client, and replaces it with the list supplied
  69 in the message.
  70
  71 Example of a subscription request:
  72
  73 ```
  74 {"imei":["8354369077195199"],
  75  "type":"subscribe",
  76  "timestamp":1652134234657,
  77  "backlog":5}
  78 ```
  79
  80 Server sends to the client a backlog of last locations of the
  81 terminals, that it fetches from the database maintained by the
  82 storage service, one location per websocket message. It then
  83 continues to send further messages when they are received from
  84 the module, in real time, including gps location, responses with
  85 approximated location, and status with the precentage of battery
  86 charge.
  87
  88 Example of a location message:
  89
  90 ```
  91 {"type": "location",
  92  "imei": "8354369077195199",
  93  "timestamp": "2022-05-09 21:52:34.643277+00:00",
  94  "longitude": 17.465816,
  95  "latitude": 47.52013,
  96  "accuracy": "gps"} // or "approximate"
  97 ```
  98
  99 Example of a status message
 100
 101 ```
 102 {"type": "status",
 103  "imei": "8354369077195199",
 104  "timestamp": "2022-05-09 21:52:34.643277+00:00",
 105  "battery": 46}
 106 ```
 107
 108 ## Lookaside service
 109
 110 When the terminal has no gps reception, it uses secondary sources of
 111 location hints: list of nearby cell towers, and list of MAC addresses
 112 of nearby WiFi access point, with signal strength. It expects a
 113 response from the server with approximated location. In order to get
 114 such approximation, the server system needs a source of information
 115 about cell towers and/or WiFi access points in the area. We support
 116 two ways to get approximated location: querying Google geolocation
 117 service, and using locally installed database filled with data
 118 downloaded from opencellid crowdsourced data. For both options,
 119 you will need an access token. Google service is "online", you are
 120 making a request for each approximation (and thus reveal location of
 121 your users to Google). Opencellid service is "offline": you download
 122 the file with locations of all cell towers in the country (or worldwide)
 123 one, or refresh it relatively long intervals, such as a week or a month,
 124 and then all queries are fulfilled locally. Note that opencellid data
 125 does not contain WiFi access points, so the result will less accurate.
 126
 127 Lookaside service can be configured to use either of the options by
 128 assigning `backend = opencellid` or `backend = googlemaps` in the
 129 configuration file (`/etc/gps303.conf` by default). Then, the file
 130 containing the auth token needs to be specified in the `[googlemaps]`
 131 section or `[opencellid]` section of the configuration file, depenging
 132 on which backend was chosen.
 133
 134 Note that in both cases, statement in the configuration file needs to
 135 point to the _file_ that contains the token, rather then contain the
 136 _token itself_.
 137
 138 This part of setup cannot be automated, because each user needs to
 139 obtain their own access token with one of the above services.
 140
 141 ## Termconfig Service
 142
 143 To configure terminal settings, such as SOS numbers, update intervals etc.,
 144 "termconfig" service consults the configuration file. It should contain
 145 the section `[termconfig]`, and optionally sections named after the IMEIs
 146 of individual terminals. `[termconfig]` values are used when the individual
 147 section is not present.
 148
 149 For a bigger multi-client setup the user will want to reimplement this
 150 service to use some kind of a database, that would be also controllable
 151 by the owners of the terminals.
 152
 153 ## Homepage and source
 154
 155 Home page is [http://www.average.org/gps303/](http://www.average.org/gps303/)
 156 Get the source from the origin `git://git.average.org/gps303.git`
 157 or from [Github mirror](https://github.com/crosser/gps303).