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 continue 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. That may require querying some external service.
  20
  21 Because we would usually want location information reach consumer
  22 instantly upon arrival, and _also_ to be stored, it makes sense to
  23 design the system in "microservices" way, using a message bus in
  24 "publish-subscribe" model. And then, as we already have a message-
  25 passing infrastructure anyway, it makes sense to decouple processes
  26 that prepare responses to the module's messages from the server that
  27 keeps TCP connections with the modules.
  28
  29 This leads us to the current implementation that has consists of
  30 five daemons that talk to each other via zeromq:
  31
  32 - **collector** that keeps open TCP connections with the terminals
  33   and publishes received messages _and_ sent responses,
  34 - **storage** that subscribes to the messages and responses from the
  35   collector and stores them in a database,
  36 - **termconfig** that subscribes to messages that need non-trivial
  37   response (most of them are about configuring various settings in
  38   the terminal, hence the name),
  39 - **lookaside** that subscribes to "rough" location messages, quieries
  40   an external source (in our implementation, opencellid database),
  41   and responds with approximated location, and
  42 - **wsgateway** that is a websockets server that translaes messages
  43   between our internal zeromq messaging and websocket clients, i.e.
  44   web pages. This daemon is also capable of responding to http with
  45   a single html file. This functionality is mainly for debugging.
  46   Users of this package are expected to implement their own single
  47   page web application that communicates with this server.
  48
  49 There is also a command-line tool to send messages to the terminal.
  50 There is a number of useful things that can be requested in this way.
  51
  52 ## Websocket messages
  53
  54 Websockets server communicates with the web page with json encoded
  55 text messages. The only supported message from the web page to the
  56 server is subscription message. Recognized elements are:
  57
  58 - **type** - a string that must be "subscribe"
  59 - **backlog** - an integer specifying how many previous locations to
  60   to send for the start. Limit is per-imei.
  61 - **imei** - a list of 16-character strings with IMEIs of the
  62   tracker terminals to watch.
  63
  64 Each subscription request nullifies preexisting list of IMEIs
  65 associated with the client, and replaces it with the list supplied
  66 in the message.
  67
  68 Example of a subscription request:
  69
  70 ```
  71 {"imei":["8354369077195199"],
  72  "type":"subscribe",
  73  "timestamp":1652134234657,
  74  "backlog":5}
  75 ```
  76
  77 Server sends to the client a backlog of last locations of the
  78 terminals, that it fetches from the database maintained by the
  79 storage service, one location per websocket message. It then
  80 continues to send further messages when they are received from
  81 the module, in real time.
  82
  83 Example of a location message:
  84
  85 ```
  86 {"imei": "8354369077195199",
  87  "timestamp": "2022-05-09 21:52:34.643277+00:00",
  88  "longitude": 17.465816,
  89  "latitude": 47.52013}
  90 ```
  91
  92 ## Homepage and source
  93
  94 Home page is [http://www.average.org/gps303/](http://www.average.org/gps303/)
  95 Get the source from the [origin](git://git.average.org/gps303.git)
  96 or [Github mirror](https://github.com/crosser/gps303).