From fc78dc7f4dcc2828ff989aadefff2eb2dbcc9d1c Mon Sep 17 00:00:00 2001
From: Wolfgang Ludger Hottgenroth <wolfgang.hottgenroth@icloud.com>
Date: Tue, 24 Aug 2021 13:55:51 +0200
Subject: [PATCH] documentation

---
 readme.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)
 create mode 100644 readme.md

diff --git a/readme.md b/readme.md
new file mode 100644
index 0000000..c2ad103
--- /dev/null
+++ b/readme.md
@@ -0,0 +1,53 @@
+# DigitalTwin1
+## Digital twin for Beckhoff BK-9000 Modbus-TCP coupler (and compatible Wago device)
+
+
+### Overview 
+
+This tool connects to a Modbus-TCP coupler, reads it process image and publishes
+
+* the new state of a discrete input register (digital input) after a change
+* the new value of an input register (analog input) after a change
+* periodically publishes the current values of all input registers (analog inputs)
+
+using MQTT messages. The topic is built from a configured prefix and the index of the particular registers.
+
+Furthermore it subscribes to MQTT messages related to the coils for the setup and anytime a message is received, it set the particular coils accordingly.
+
+
+### Configuration
+
+Configuration is done using a configuration file
+
+    [modbus]
+    client = 172.16.2.157
+    scanrate = 0.25
+
+    [mqtt]
+    broker = 172.16.2.16
+    digitalOutputTopicPrefix = dt1/coil
+    digitalInputTopicPrefix = dt1/di
+    analogInputEventTopicPrefix = dt1/ai/event
+    analogInputPeriodicTopicPrefix = dt1/ai/periodic
+    analogInputPublishPeriod = 10.0
+
+
+### Operation details
+
+While the input and discrete input registers are scanned with the configured scanrate, an action on a coil according to a received message is issued immediately. At the same time the all input registers are scanned.
+
+The MQTT messages related to change events of input or discrete input registers are marked as //retained//.
+
+
+### Usage
+
+The tool is simply started using
+
+    python digitaltwin1.py
+
+On default it searches the configuration file at ``$PWD/config``. This can be changed using the commandline argument ``-f``.
+
+The Python modules ``pymodbus``, ``loguru`` and ``paho-mqtt`` are required.
+
+A docker image with the required dependencies, the tool and a prepared default configuration in a volume is provided at ``registry.hottis.de/wolutator/digitaltwin1``.
+