From: Eugene Crosser Date: Mon, 23 May 2022 23:31:12 +0000 (+0200) Subject: Update README X-Git-Tag: 0.92.d~1 X-Git-Url: http://www.average.org/gitweb/?p=loctrkd.git;a=commitdiff_plain;h=202323a1affa06a86ace1191975c77282f8395aa Update README --- diff --git a/README.md b/README.md index f49dbd3..deebfc2 100644 --- a/README.md +++ b/README.md @@ -11,26 +11,28 @@ but it is more of a complete reimplementation than a derived work. When powered up, the module makes TCP connection to the configured (via SMS) server, identifies itself (via IMEI) in the first message, -and continue to send periodic messages with location and other status +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 -derived from this data. That may require querying some external service. +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 in -"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 that -keeps TCP connections with the modules. +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. This leads us to the current implementation that has consists of five daemons that talk to each other via zeromq: - **collector** that keeps open TCP connections with the terminals - and publishes received messages _and_ sent responses, + 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 @@ -38,31 +40,32 @@ five daemons that talk to each other via zeromq: the terminal, hence the name), - **lookaside** that subscribes to "rough" location messages, quieries an external source (in our implementation, opencellid database), - and responds with approximated location, and + and prepares the response to the terminal containing approximated + location, and - **wsgateway** that is a websockets server that translaes messages - between our internal zeromq messaging and websocket clients, i.e. - web pages. This daemon is also capable of responding to http with + 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. There is also a command-line tool to send messages to the terminal. -There is a number of useful things that can be requested in this way. +A number of useful actions can be initiated in this way. ## Websocket messages -Websockets server communicates with the web page with json encoded +Websockets server communicates with the web page via json encoded text messages. The only supported message from the web page to the server is subscription message. Recognized elements are: - **type** - a string that must be "subscribe" - **backlog** - an integer specifying how many previous locations to - to send for the start. Limit is per-imei. + send for the start. Limit is per-imei. - **imei** - a list of 16-character strings with IMEIs of the tracker terminals to watch. Each subscription request nullifies preexisting list of IMEIs -associated with the client, and replaces it with the list supplied +associated with the web client, and replaces it with the list supplied in the message. Example of a subscription request: @@ -78,19 +81,32 @@ Server sends to the client a backlog of last locations of the terminals, that it fetches from the database maintained by the storage service, one location per websocket message. It then continues to send further messages when they are received from -the module, in real time. +the module, in real time, including gps location, responses with +approximated location, and status with the precentage of battery +charge. Example of a location message: ``` -{"imei": "8354369077195199", +{"type": "location", + "imei": "8354369077195199", "timestamp": "2022-05-09 21:52:34.643277+00:00", "longitude": 17.465816, - "latitude": 47.52013} + "latitude": 47.52013, + "accuracy": "gps"} // or "approximate" +``` + +Example of a status message + +``` +{"type": "status", + "imei": "8354369077195199", + "timestamp": "2022-05-09 21:52:34.643277+00:00", + "battery": 46} ``` ## 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 [Github mirror](https://github.com/crosser/gps303). +Get the source from the origin `git://git.average.org/gps303.git` +or from [Github mirror](https://github.com/crosser/gps303).