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 ## Configuring the Terminal
  56
  57 Send SMS to the number assigned to the SIM card, with the text
  58
  59 ```
  60 server#<your_server_address>#<port>#
  61 ```
  62
  63 Server address may be FQDN or a literal IP address. Port is a number;
  64 by default, this application listens on the port 4303. A different
  65 port can be chosen in the config file.
  66
  67 It is recommended to keep the service running while the terminal is
  68 powered up: it is possible that the terminal is programmed to be reset
  69 to the default configuration if it cannot connect to the servicse for
  70 some time.
  71
  72 ## Websocket messages
  73
  74 Websockets server communicates with the web page via json encoded
  75 text messages. The only supported message from the web page to the
  76 server is subscription message. Recognized elements are:
  77
  78 - **type** - a string that must be "subscribe"
  79 - **backlog** - an integer specifying how many previous locations to
  80   send for the start. Limit is per-imei.
  81 - **imei** - a list of 16-character strings with IMEIs of the
  82   tracker terminals to watch.
  83
  84 Each subscription request nullifies preexisting list of IMEIs
  85 associated with the web client, and replaces it with the list supplied
  86 in the message.
  87
  88 Example of a subscription request:
  89
  90 ```
  91 {"imei":["8354369077195199"],
  92  "type":"subscribe",
  93  "timestamp":1652134234657,
  94  "backlog":5}
  95 ```
  96
  97 Server sends to the client a backlog of last locations of the
  98 terminals, that it fetches from the database maintained by the
  99 storage service, one location per websocket message. It then
 100 continues to send further messages when they are received from
 101 the module, in real time, including gps location, responses with
 102 approximated location, and status with the precentage of battery
 103 charge.
 104
 105 Example of a location message:
 106
 107 ```
 108 {"type": "location",
 109  "imei": "8354369077195199",
 110  "timestamp": "2022-05-09 21:52:34.643277+00:00",
 111  "longitude": 17.465816,
 112  "latitude": 47.52013,
 113  "accuracy": "gps"} // or "approximate"
 114 ```
 115
 116 Example of a status message
 117
 118 ```
 119 {"type": "status",
 120  "imei": "8354369077195199",
 121  "timestamp": "2022-05-09 21:52:34.643277+00:00",
 122  "battery": 46}
 123 ```
 124
 125 ## Lookaside service
 126
 127 When the terminal has no gps reception, it uses secondary sources of
 128 location hints: list of nearby cell towers, and list of MAC addresses
 129 of nearby WiFi access point, with signal strength. It expects a
 130 response from the server with approximated location. In order to get
 131 such approximation, the server system needs a source of information
 132 about cell towers and/or WiFi access points in the area. We support
 133 two ways to get approximated location: querying Google geolocation
 134 service, and using locally installed database filled with data
 135 downloaded from opencellid crowdsourced data. For both options,
 136 you will need an access token. Google service is "online", you are
 137 making a request for each approximation (and thus reveal location of
 138 your users to Google). Opencellid service is "offline": you download
 139 the file with locations of all cell towers in the country (or worldwide)
 140 one, or refresh it relatively long intervals, such as a week or a month,
 141 and then all queries are fulfilled locally. Note that opencellid data
 142 does not contain WiFi access points, so the result will less accurate.
 143
 144 Lookaside service can be configured to use either of the options by
 145 assigning `backend = opencellid` or `backend = googlemaps` in the
 146 configuration file (`/etc/gps303.conf` by default). Then, the file
 147 containing the auth token needs to be specified in the `[googlemaps]`
 148 section or `[opencellid]` section of the configuration file, depenging
 149 on which backend was chosen.
 150
 151 Note that in both cases, statement in the configuration file needs to
 152 point to the _file_ that contains the token, rather then contain the
 153 _token itself_.
 154
 155 This part of setup cannot be automated, because each user needs to
 156 obtain their own access token with one of the above services.
 157
 158 ## Termconfig Service
 159
 160 To configure terminal settings, such as SOS numbers, update intervals etc.,
 161 "termconfig" service consults the configuration file. It should contain
 162 the section `[termconfig]`, and optionally sections named after the IMEIs
 163 of individual terminals. `[termconfig]` values are used when the individual
 164 section is not present.
 165
 166 For a bigger multi-client setup the user will want to reimplement this
 167 service to use some kind of a database, that would be also controllable
 168 by the owners of the terminals.
 169
 170 ## Homepage and source
 171
 172 Home page is [http://www.average.org/gps303/](http://www.average.org/gps303/)
 173 Get the source from the origin `git://git.average.org/gps303.git`
 174 or from [Github mirror](https://github.com/crosser/gps303).