## 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) in the first message,
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
+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,
+- **lookaside** that subscribes to "rough" location messages, queries
+ an external source (in our implementation, either google maps "API",
+ or a local opencellid database), and prepares responses with
+ approximated location, 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.
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 number assigned to the SIM card, with the text
+Send SMS to the telephone number of the SIM card plugged in the terminal,
+with the text
```
server#<your_server_address>#<port>#
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 chosen in the config file.
+port can be configured in the config file.
-It is recommended to keep the service running while the terminal is
-powered up: it is possible that the terminal is programmed to be reset
-to the default configuration if it cannot connect to the servicse for
-some time.
+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
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
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/gps303.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 `gps303` 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
projects / loctrkd.git / commitdiff