X-Git-Url: http://www.average.org/gitweb/?p=loctrkd.git;a=blobdiff_plain;f=README.md;h=bb4c62908f32138ef00578d8ee73ce8accfe05c4;hp=5dca14d0cc9e117b08b7734f732273ce3ddadcca;hb=HEAD;hpb=dd96de9075421e6e30ac0729c5da331d8247af6e diff --git a/README.md b/README.md index 5dca14d..bb4c629 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,12 @@ -# 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 @@ -13,10 +17,10 @@ There also exists an that supports multiple types of trackers. When powered up, the module makes TCP connection to the configured -(via SMS) server, identifies itself (with 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 +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 @@ -42,28 +46,38 @@ that talk to each other over Zeromq: response (most of them are about configuring various settings in the terminal, hence the name), and sends responses to the collector for relaying to the terminal, -- **lookaside** that subscribes to "rough" location messages, queries +- **rectifier** 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 + 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 the package are expected to implement their own web - application that communicates with this server. + 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 -``` -server### -``` +* for zx303: + ``` + server### + ``` +* for D99: + ``` + pw,123456,ip,,# + ``` + +"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 @@ -80,11 +94,14 @@ 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. 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 @@ -127,7 +144,7 @@ Example of a status message "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 @@ -147,16 +164,16 @@ 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 path to +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, 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 +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 @@ -176,6 +193,6 @@ 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).