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 ## Homepage and source
 109
 110 Home page is [http://www.average.org/gps303/](http://www.average.org/gps303/)
 111 Get the source from the origin `git://git.average.org/gps303.git`
 112 or from [Github mirror](https://github.com/crosser/gps303).