From 9f96a3e534035ec2e5832086a643282606e9ad6a Mon Sep 17 00:00:00 2001
From: Vladyslav Doloman <git@vaku.org.ua>
Date: Sat, 22 Nov 2025 23:28:57 +0200
Subject: [PATCH] feat: Introduce PDF register extraction utility with a sample
 Deye Modbus manual and update README with comprehensive project details.

---
 README.md                                     |  91 +++++++++++++++++-
 .../Modbus储能-组串-微逆宁波德业V118-1.pdf    | Bin
 docs/extract_pdf.py                           |  39 ++++++++
 3 files changed, 126 insertions(+), 4 deletions(-)
 rename Modbus储能-组串-微逆宁波德业V118-1.pdf => docs/Modbus储能-组串-微逆宁波德业V118-1.pdf (100%)
 create mode 100644 docs/extract_pdf.py

diff --git a/README.md b/README.md
index 6b77458..6a17946 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,90 @@
-# deyeChargeSpeed
+# Deye Charge Speed Monitor
 
-https://github.com/jmccrohan/pysolarmanv5
+A Flask-based application for monitoring Deye Inverters (and compatible models) using the Solarman V5 protocol. This tool connects directly to the inverter via Modbus over TCP to read real-time data including voltages, currents, battery status, and BMS information.
 
-https://pysolarmanv5.readthedocs.io/en/stable/
+## Features
 
-https://pysolarmanv5.readthedocs.io/en/stable/examples.html
\ No newline at end of file
+- **Real-time Monitoring**: Reads critical data such as Input/Output Voltage, Grid/Load Currents, Battery SOC, Temperature, and Power.
+- **BMS Integration**: Retrieves detailed Battery Management System (BMS) data for up to two battery packs.
+- **Web Interface**: Provides a user-friendly dashboard to view inverter status (served at `/`).
+- **JSON API**: Exposes raw data via a RESTful endpoint (`/api/data`) for integration with other systems.
+- **PDF Utility**: Includes a tool to extract register information from Deye Modbus PDF manuals.
+
+## Prerequisites
+
+- Python 3.x
+- A Deye Inverter (or compatible) connected to the network.
+- Inverter IP address, Serial Number, and Modbus Slave ID.
+
+## Installation
+
+1.  **Clone the repository:**
+
+    ```bash
+    git clone <repository-url>
+    cd deyeChargeSpeed
+    ```
+
+2.  **Create and activate a virtual environment:**
+
+    ```bash
+    python -m venv venv
+    # Windows
+    .\venv\Scripts\activate
+    # Linux/Mac
+    source venv/bin/activate
+    ```
+
+3.  **Install dependencies:**
+
+    ```bash
+    pip install -r requirements.txt
+    ```
+
+4.  **Configuration:**
+
+    Copy the example configuration file and update it with your inverter details:
+
+    ```bash
+    cp config.py.example config.py
+    ```
+
+    Edit `config.py`:
+    ```python
+    INVERTER_IP = "192.168.x.x"
+    INVERTER_SERIAL = 1234567890
+    INVERTER_PORT = 8899
+    INVERTER_SLAVE_ID = 1
+    ```
+
+## Usage
+
+1.  **Start the application:**
+
+    ```bash
+    python app.py
+    ```
+
+2.  **Access the dashboard:**
+
+    Open your web browser and navigate to `http://localhost:5000`.
+
+## Utilities
+
+### PDF Register Extractor
+
+Located in `docs/extract_pdf.py`, this script helps identify Modbus registers from Deye PDF manuals.
+
+**Usage:**
+1.  Place your PDF manual in the `docs/` folder.
+2.  Update the filename in `docs/extract_pdf.py` if necessary (defaults to `Modbus储能-组串-微逆宁波德业V118-1.pdf`).
+3.  Run the script:
+    ```bash
+    python docs/extract_pdf.py
+    ```
+4.  Check `pdf_output.txt` for the extracted register locations and context.
+
+## Resources
+
+- [PySolarmanV5 Documentation](https://pysolarmanv5.readthedocs.io/en/stable/)
+- [PySolarmanV5 GitHub](https://github.com/jmccrohan/pysolarmanv5)
\ No newline at end of file
diff --git a/Modbus储能-组串-微逆宁波德业V118-1.pdf b/docs/Modbus储能-组串-微逆宁波德业V118-1.pdf
similarity index 100%
rename from Modbus储能-组串-微逆宁波德业V118-1.pdf
rename to docs/Modbus储能-组串-微逆宁波德业V118-1.pdf
diff --git a/docs/extract_pdf.py b/docs/extract_pdf.py
new file mode 100644
index 0000000..4302fbd
--- /dev/null
+++ b/docs/extract_pdf.py
@@ -0,0 +1,39 @@
+import os
+import pypdf
+import re
+
+pdf_path = os.path.join(os.path.dirname(__file__), "Modbus储能-组串-微逆宁波德业V118-1.pdf")
+
+def extract_text_from_pdf(pdf_path):
+    reader = pypdf.PdfReader(pdf_path)
+    text = ""
+    for page in reader.pages:
+        text += page.extract_text() + "\n"
+    return text
+
+full_text = extract_text_from_pdf(pdf_path)
+
+# Registers to look for
+registers = [94, 245, 320]
+
+print("Searching for registers...")
+
+# Split text into lines for easier processing
+lines = full_text.split('\n')
+
+found_registers = {}
+
+with open("pdf_output.txt", "w", encoding="utf-8") as f:
+    for i, line in enumerate(lines):
+        for reg in registers:
+            if re.search(r'\b' + str(reg) + r'\b', line):
+                f.write(f"MATCH {reg}: {line.strip()}\n")
+                # Write context
+                start = max(0, i - 5)
+                end = min(len(lines), i + 6)
+                for j in range(start, end):
+                    if i != j:
+                        f.write(f"   CTX: {lines[j].strip()}\n")
+                f.write("-" * 20 + "\n")
+
+print("Done. Check pdf_output.txt")