-# A server to collect data from zx303 ZhongXun Topin Locator
+# A server to collect data from GPS Locators
-zx303 GPS+GPRS module is a cheap and featureful GPS tracker for pets,
-children, elderly family members, and, of course, illegal tracking
-of people and objects, though the latter absolutely must not be done.
+Supported:
+
+* zx303 ZhongXun Topin Locator
+ zx303 GPS+GPRS module is a cheap and featureful GPS tracker for pets,
+ children, elderly family members, and, of course, illegal tracking
+ of people and objects, though the latter absolutely must not be done.
+* Some watches-locators, sometimes identified as D99 or similar
## Introduction
This work is inspired by [this project](https://github.com/tobadia/petGPS),
-but it is more of a complete reimplementation than a derived work.
+but it is more of a complete re-implementation than a derived work.
+There also exists an
+[industrial strength open source server](https://www.traccar.org/)
+that supports multiple types of trackers.
When powered up, the module makes TCP connection to the configured
-(via SMS) server, identifies itself (via IMEI) in the first message,
+(via SMS) server, identifies itself (with IMEI),
and continues to send periodic messages with location and other status
updates. Some of these messages require a response from the server.
-In particular, when the module has no GPS coverage, it sends information
-about neaby GSM+ cell towers and WiFi access points, to which the server
-is expected to respond with a message contaning approximate location
+In particular, when zx303 has no GPS coverage, it sends information
+about nearby GSM+ cell towers and WiFi access points, to which the server
+is expected to respond with a message containing approximate location
derived from this data. To do that, the server may need to consult with
some external service.
Because we would usually want location information reach consumer
instantly upon arrival, and _also_ to be stored, it makes sense to
-design the system in "microservices" way, using a message bus with
-"publish-subscribe" model. And then, as we already have a message-passing
-infrastructure anyway, it makes sense to decouple processes that prepare
-responses to the module's messages from the server process that maintains
-TCP connections to the modules.
+design the system in "microservices" way, using a message bus in
+"publish-subscribe" model. And then, since we already have a
+message-passing infrastructure anyway, it makes sense to decouple
+the server process that maintains TCP connections with the the tracker
+terminals from the processes that analyses messages and prepares responses.
-This leads us to the current implementation that has consists of
-five daemons that talk to each other via zeromq:
+This leads us to this implementation, that has consists of five daemons
+that talk to each other over Zeromq:
- **collector** that keeps open TCP connections with the terminals
and publishes received messages _and_ sent responses on the message
bus,
- **storage** that subscribes to the messages and responses from the
collector and stores them in a database,
-- **termconfig** that subscribes to messages that need non-trivial
+- **termconfig** that subscribes to messages that need nontrivial
response (most of them are about configuring various settings in
- the terminal, hence the name),
-- **lookaside** that subscribes to "rough" location messages, quieries
- an external source (in our implementation, opencellid database),
- and prepares the response to the terminal containing approximated
- location, and
-- **wsgateway** that is a websockets server that translaes messages
+ the terminal, hence the name), and sends responses to the collector
+ for relaying to the terminal,
+- **rectifier** that subscribes to "rough" location messages, queries
+ an external source (in our implementation, either google maps "API",
+ or a local opencellid database), optionally sends a response with
+ approximated location, and publishes (original or rectified) location
+ report reformatted in a unified way, and
+- **wsgateway** that is a websockets server that translates messages
between our internal zeromq bus and websocket clients, i.e. web
pages. This daemon is also capable of responding to http with
a single html file. This functionality is mainly for debugging.
- Users of this package are expected to implement their own single
- page web application that communicates with this server.
+ Users of the package are expected to implement their own web
+ application that communicates with this server. It also have a
+ capability to send a limited number of commands entered via the web
+ interface back to the terminal.
There is also a command-line tool to send messages to the terminal.
-A number of useful actions can be initiated in this way.
+
+## Configuring the Terminal
+
+Send SMS to the telephone number of the SIM card plugged in the terminal,
+with the text
+
+* for zx303:
+ ```
+ server#<your_server_address>#<port>#
+ ```
+* for D99:
+ ```
+ pw,123456,ip,<your_server_address>,<port>#
+ ```
+
+"123456" is the default password on that kind of trackers, that you can
+change. If "123456" does not work, try "523681".
+
+Server address may be FQDN or a literal IP address. Port is a number;
+by default, this application listens on the port 4303. A different
+port can be configured in the config file.
+
+It is recommended to always keep the service running while the terminal
+is powered up: it is possible that the terminal is programmed to reset
+itself to the default configuration if it cannot connect to the server
+for prolonged time.
## Websocket messages
-Websockets server communicates with the web page via json encoded
+Websockets server communicates with the web page using json encoded
text messages. The only supported message from the web page to the
-server is subscription message. Recognized elements are:
+server is subscription message. Recognised elements are:
-- **type** - a string that must be "subscribe"
-- **backlog** - an integer specifying how many previous locations to
- send for the start. Limit is per-imei.
-- **imei** - a list of 16-character strings with IMEIs of the
- tracker terminals to watch.
+- **type** - a string "subscribe", or a command for the terminal.
+- **backlog** - for "subscribe, an integer specifying how many
+ previous locations to send for the start. Limit is per-imei.
+- **imei** - for "subscribe", a list of 10- or 16-character strings
+ with IMEIs of the tracker terminals to watch, for other commands -
+ IMEI of the particular tracker.
+- **txt** - for "msg" command, text of the message to send to the
+ terminal, in UTF-8.
Each subscription request nullifies preexisting list of IMEIs
associated with the web client, and replaces it with the list supplied
"battery": 46}
```
-## Lookaside service
+## Rectifier service
When the terminal has no gps reception, it uses secondary sources of
location hints: list of nearby cell towers, and list of MAC addresses
about cell towers and/or WiFi access points in the area. We support
two ways to get approximated location: querying Google geolocation
service, and using locally installed database filled with data
-downloaded from opencellid crowdsourced data. For both options,
+downloaded from opencellid crowdsourced source. For both options,
you will need an access token. Google service is "online", you are
making a request for each approximation (and thus reveal location of
your users to Google). Opencellid service is "offline": you download
the file with locations of all cell towers in the country (or worldwide)
-one, or refresh it relatively long intervals, such as a week or a month,
-and then all queries are fulfilled locally. Note that opencellid data
-does not contain WiFi access points, so the result will less accurate.
+once, or refresh it at relatively long intervals, such as a week or a
+month, and then all queries are fulfilled locally. Note that opencellid
+data does not contain WiFi access points, so the approximation will
+less accurate.
-Lookaside service can be configured to use either of the options by
+Rectifier service can be configured to use either of the options by
assigning `backend = opencellid` or `backend = googlemaps` in the
-configuration file (`/etc/gps303.conf` by default). Then, the file
-containing the auth token needs to be specified in the `[googlemaps]`
-section or `[opencellid]` section of the configuration file, depenging
-on which backend was chosen.
+configuration file (`/etc/loctrkd.conf` by default). Then, the path to
+the file with the auth token needs to be specified in the `[opencellid]`
+section or `[googlemaps]` section of the configuration file respectively.
-Note that in both cases, statement in the configuration file needs to
-point to the _file_ that contains the token, rather then contain the
-_token itself_.
+Note that in both cases, the value in the configuration file needs
+to _point to the file_ that contains the token, rather than contain
+the token itself. The file needs to be readable for the user under which
+services are executed. That is the user `loctrkd` if this software was
+installed as the Debian package.
This part of setup cannot be automated, because each user needs to
-obtain their own access token with one of the above services.
+obtain their own access token for one of the above services.
## Termconfig Service
of individual terminals. `[termconfig]` values are used when the individual
section is not present.
-For a bigger multi-client setup the user will want to reimplement this
-service to use some kind of a database, that would be also controllable
-by the owners of the terminals.
+For a bigger multi-client setup the user will want to re-implement this
+service to use some kind of a database, with the data configurable by the
+owners of the terminals.
## Homepage and source
-Home page is [http://www.average.org/gps303/](http://www.average.org/gps303/)
-Get the source from the origin `git://git.average.org/gps303.git`
-or from [Github mirror](https://github.com/crosser/gps303).
+Home page is [http://www.average.org/loctrkd/](http://www.average.org/loctrkd/)
+Get the source from the origin `git://git.average.org/loctrkd.git`
+or from [Github mirror](https://github.com/crosser/loctrkd).
projects / loctrkd.git / blobdiff