From 99f4abb19d9c4c76b3a97f63527ac2ecbee0fd00 Mon Sep 17 00:00:00 2001
From: Thomas Popp <dev@thomas-popp.de>
Date: Sat, 9 Dec 2023 18:47:55 +0100
Subject: [PATCH] doc(readme): updated readme

---
 AquaMQTT/README.md | 90 ++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 87 insertions(+), 3 deletions(-)

diff --git a/AquaMQTT/README.md b/AquaMQTT/README.md
index 6990a7e..50d472b 100644
--- a/AquaMQTT/README.md
+++ b/AquaMQTT/README.md
@@ -1,5 +1,89 @@
 # AquaMQTT
 
-https://docs.arduino.cc/hardware/nano-esp32
-https://docs.arduino.cc/tutorials/nano-esp32/cheat-sheet
-https://www.circuitstate.com/tutorials/how-to-write-parallel-multitasking-applications-for-esp32-using-freertos-arduino/
+AquaMQTT is designed for an ESP32 microcontroller running Arduino. The project offers two distinct operation modes: "
+Listener" and "Man-in-the-Middle."
+
+### Operation Modes
+
+1. **Listener Mode:**
+    - AquaMQTT acts as an observer, monitoring communication between a heat pump HMI controller and the heat pump main
+      controller.
+    - It parses the serial messages exchanged between the two controllers and publishes relevant data to specified MQTT
+      topics (refer to [../MQTT.MD](../MQTT.MD)).
+
+2. **Man-in-the-Middle Mode:**
+    - AquaMQTT intercepts and sits between the communication channels of the HMI controller and the main heat pump
+      controller. 
+    - It parses the serial messages exchanged between the two controllers and publishes relevant data to specified MQTT
+      topics (refer to [../MQTT.MD](../MQTT.MD)).
+    - This mode additionally enables the modification of communication messages in both directions, allowing for the alteration of
+      various parameters such as operation mode, water target temperature, and more.
+
+## Getting Started
+
+### Hardware Requirements
+
+- [Arduino ESP32 Nano](https://docs.arduino.cc/hardware/nano-esp32)
+- [AquaMQTT Board](../pcb/)
+
+### Installation
+
+1. Clone the AquaMQTT repository to your local machine.
+
+   ```bash
+   git clone https://github.com/tspopp/AquaMQTT.git
+
+2. Configure WiFi and MQTT Settings:
+
+   Open the `config/ExampleConfiguration.h` file and update the following parameters to match your WiFi and MQTT broker
+   settings:
+
+   ```c++
+   namespace aquamqtt
+   {
+   namespace config
+   {
+      constexpr char     ssid[]           = "YourWiFiSSID";
+      constexpr char     psk[]            = "YourWiFiPassword";
+      constexpr char     brokerAddr[]     = "192.168.188.1";
+      constexpr uint16_t brokerPort       = 1883;
+      constexpr char     brokerClientId[] = "aquamqtt";
+      // Leave blank if your broker does not require a username/password
+      constexpr char brokerUser[]     = "";
+      constexpr char brokerPassword[] = "";
+      constexpr char mqttPrefix[]     = "";
+   }  // namespace config
+   }  // namespace aquamqtt
+   ```
+
+   Ensure that the WiFi SSID, password, MQTT broker address, and other parameters are correctly set.
+
+   Additionally, set the operation mode within `config/Configuration.h` to either LISTENER, or MITM.
+
+   ```c++
+   constexpr EOperationMode OPERATION_MODE = EOperationMode::MITM;
+   ```
+
+### Flashing
+
+1. Install PlatformIO IDE
+
+   https://platformio.org/install
+
+2. Build the project using
+
+   ```shell
+   pio run -e arduino_nano_esp32
+   ```
+3. Connect the Arduino and upload the project to your microcontroller via USB
+
+   ```shell
+   pio run -t upload -e arduino_nano_esp32
+   ```
+
+## Contributions
+Contributions to the AquaMQTT project are welcome. Feel free to open issues, submit pull requests, or provide feedback.
+
+
+## License
+This project is licensed under the Apache License 2.0.
\ No newline at end of file