From 15475aee82ea3a5330a47a430e8dbbfdf2a49419 Mon Sep 17 00:00:00 2001
From: Eugene Crosser <crosser@average.org>
Date: Tue, 10 May 2022 00:22:36 +0200
Subject: [PATCH] Expand README

---
 README.md          | 60 +++++++++++++++++++++++++++++++++++++++++-----
 webdemo/index.html |  2 +-
 2 files changed, 55 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 8247f9f..af6dc64 100644
--- a/README.md
+++ b/README.md
@@ -4,6 +4,8 @@ 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.
 
+## 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.
 
@@ -25,18 +27,64 @@ that prepare responses to the module's messages from the server that
 keeps TCP connections with the modules.
 
 This leads us to the current implementation that has consists of
-four daemons that talk to each other via zeromq:
+five daemons that talk to each other via zeromq:
 
 - **collector** that keeps open TCP connections with the terminals
-  and publishes received messages,
-- **storage** that subscribes to the messages from the collector and
-  stores them in a database,
+  and publishes received messages _and_ sent responses,
+- **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
   response (most of them are about configuring various settings in
-  the terminal, hence the name), and
+  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 responds with 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
+  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.
+
+## Websocket messages
+
+Websockets server communicates with the web page with 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.
+- **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
+in the message.
+
+Example of a subscription request:
+
+```
+{"imei":["8354369077195199"],
+ "type":"subscribe",
+ "timestamp":1652134234657,
+ "backlog":5}
+```
+
+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.
+
+Example of a location message:
+
+```
+{"imei": "8354369077195199",
+ "timestamp": "2022-05-09 21:52:34.643277+00:00",
+ "longitude": 17.465816,
+ "latitude": 47.52013}
+```
diff --git a/webdemo/index.html b/webdemo/index.html
index c3fafb4..fb7ab39 100644
--- a/webdemo/index.html
+++ b/webdemo/index.html
@@ -155,7 +155,7 @@
 		var msg = {
 			imei: Array.from(imeis),
 			type: "subscribe",
-			date: Date.now(),
+			timestamp: Date.now(),
 			backlog: maxmarkers
 		};
 		console.log("sending" + JSON.stringify(msg));
-- 
2.39.2