Updated documentation

README.md

@@ -1,6 +1,6 @@
-# PyWSClock
+# pyws_clock
 
-Websocket clock server, handling timezones and alarms.
+Websocket clock server, handling timezones, alarms and sessions.
 
 ## Dependencies
 
@@ -86,3 +86,52 @@ systemctl status pyws_clock.service
 
 A sample configuration is available in `nginx_server.conf`.
 
+## Websocket server protocol description
+
+The server replies on any URL.
+
+Before entering the main loop, the listening server waits for 1st message
+containing a session ID. If an empty/dummy/invalid/unknown session ID is sent by the
+client, the server replies with a new, valid, session ID and enter the main loop.
+If a valid session ID is sent, the server reply the same session ID and enter
+the main loop, formated using `SESSION:<SESSION_ID>`.
+
+### Main loop
+
+The server send the current time (ISO 8601 format) every second.
+
+### Command results
+
+The client can interact with the server sending one of the command listed using
+`python3 -m pyws_clock -L`.
+
+When a client send a command, the next message from the server will be a command
+result. Results are string formatted using `<STATUS>:<DETAILS>.` Status can be
+one of `'ERR'` or `'OK'`, details are optionnale for OK statuses.
+
+### Alarms rings
+
+When an alarm is ringing, after sending time, the server send messages formatted
+using `ALRM:<NAME>` where `NAME `is the name of the ringing alarm.
+If multiple alarms are ringing, multiple `ALRM:` messages are sent every second.
+
+### Timezone informations
+
+Before the first time is sent and every time the timezone changes (inclucing
+summer/winter transitions), the clock. Timezones messages are formatted using
+`TZN:<TZNAME>`
+
+### Messages types summary
+
+* Session ID
+	* `SESSION:<SESSION_ID>`
+* Clock tick
+	* `ISO8601_Datetime`
+* Timezone name
+	* `TZN:<TZNAME>`
+* Alarm rings
+	* `ALRM:<JSON_ARRAY>`
+* Command results
+	* `OK:<DETAILS>`
+	* `ERR:<REASON>`
+

pyws_clock/__main__.py

@@ -48,8 +48,8 @@ Alarms rings :
 --------------
 
 When an alarm is ringing, after sending time, the server send messages formatted
-using ALRM:<JSON_ARRAY> where JSON_ARRAY is a JSON array containing the name of
-the ringin alarms.
+using ALRM:<NAME> where NAME is the name of a ringing alarm. If multiple alarms
+are ringing, multiple ALRM: messages are sent every seconds.
 
 Timezone informations :
 -----------------------