From 93692407dcc2634b50d4faf5a6efc6eda6f40c39 Mon Sep 17 00:00:00 2001
From: Jan Koppe <post@jankoppe.de>
Date: Sat, 16 Oct 2021 20:15:36 +0200
Subject: [PATCH] expanded readme

---
 README.md  | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 README.txt |  3 ---
 2 files changed, 53 insertions(+), 3 deletions(-)
 create mode 100644 README.md
 delete mode 100644 README.txt

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a72e4f4
--- /dev/null
+++ b/README.md
@@ -0,0 +1,53 @@
+# durchsage
+
+Daemon that will follow a pretalx conference schedule.json ("fahrplan") and make announcements ("durchsage") on a MQTT topic when an event starts. 
+
+## architecture
+
+The whole daemon is based around a blocking scheduler based on APscheduler. When launched, it will set up a `update_event_jobs` cron schedule per configured fahrplan.
+
+When this cron is invoked, it will fetch the current fahrplan from the source url, and filter out all events/talks in the past. For each remaining event a new `announce_event` job will be generated that sends out the job data to an MQTT topic exactly when the event starts.
+
+It will use these MQTT topics:
+
+* `fahrplan/<fahrplan>/version`: When a schedule with a different version has been imported, a message containing the version string will be published here.
+* `fahrplan/<fahrplan>/now`: When an event begins the whole event data structure is dumped in JSON and published here.
+* `fahrplan/<fahrplan>/soon`: (Optional) Just before an event begins the whole event data structure is dumped in JSON and published here. You can configure how many minutes before the actual event start this will happen, or not at all.
+
+## configuration
+
+Create a `config.ini` and either drop it in the same folder as `durchsage.py` or pass the path with a `--config` flag.
+
+There can be only one `mqtt` section defining the connection parameters to the broker.
+
+There can be many `fahrplan:<fahrplan>` sections, where `<fahrplan>` is a user definable name. This will be used internally and for the MQTT topic selection.
+
+`<fahrplan>` needs to begin with a lowercase letter or digit, and can contain lowercase letters, digits, dashes or underscores after the first char.
+
+```INI
+[mqtt]
+host = 127.0.0.1
+port = 8883
+
+tls = yes
+tls_verify = yes
+
+username = hans
+password = wurst
+
+[fahrplan:example]
+# the url is required.
+url = https://pretalx.example.com/example-conference/schedule/export/schedule.json
+
+# optional: refresh/pull the fahrplan according to this crontab expression
+# defaults to every 5 minutes.
+cron = * * * * *
+
+# optional: give an advance notice x minutes before the talk starts on the 'soon' topic
+# defaults to no advance notice
+pre_announce = 1
+
+[fahrplan:anotherconf]
+url = ...
+
+```
\ No newline at end of file
diff --git a/README.txt b/README.txt
deleted file mode 100644
index 18460b2..0000000
--- a/README.txt
+++ /dev/null
@@ -1,3 +0,0 @@
-# durchsage
-
-Daemon that will follow a pretalx conference schedule.json ("fahrplan") and make announcements ("durchsage") on a MQTT topic when an event starts. 
\ No newline at end of file