From e6221b688346bc59a670451c6fcb25572385f5c1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bobo=20B=C3=A4ck=20Engstr=C3=B6m?= <bobo@id8-engineering.io>
Date: Fri, 31 Oct 2025 09:26:11 +0100
Subject: [PATCH] docs(README): Add usage_example and make it more userfriendly
 in README
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Bobo Bäck Engström <bobo@id8-engineering.io>

docs(DEVELOPMENT): add DEVELOPMENT

Signed-off-by: Bobo Bäck Engström <bobo@id8-engineering.io>
---
 DEVELOPMENT.MD | 37 +++++++++++++++++++++++++++++++++
 README.md      | 56 ++++++++++++++++++++++++++++----------------------
 2 files changed, 68 insertions(+), 25 deletions(-)
 create mode 100644 DEVELOPMENT.MD

diff --git a/DEVELOPMENT.MD b/DEVELOPMENT.MD
new file mode 100644
index 0000000..538ee2d
--- /dev/null
+++ b/DEVELOPMENT.MD
@@ -0,0 +1,37 @@
+# python-em511
+
+Driver for Carlo Gavazzi EM511 Series Single Phase Energy Meters using Modbus RTU.
+
+## Get started
+
+### Prerequisites
+
+* Install [Python (>=3.10)](https://www.python.org/downloads/)
+* Install [git](https://git-scm.com/downloads)
+* Install [uv](https://docs.astral.sh/uv/getting-started/installation/)
+
+### Setup development environment
+
+Clone the repository:
+
+```sh
+git clone git@github.com:id8-engineering/python-em511.git
+```
+
+Change directory:
+
+```sh
+cd python-em511
+```
+
+Run pre-commit tests:
+
+```sh
+uv run pre-commit run -a
+```
+
+Build package:
+
+```sh
+uv build
+```
diff --git a/README.md b/README.md
index eb03439..9f3cc4a 100644
--- a/README.md
+++ b/README.md
@@ -1,39 +1,45 @@
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/id8-engineering/python-em511/badge)](https://scorecard.dev/viewer/?uri=github.com/id8-engineering/python-em511)
 
-# python-em511
+## python-em511
 
-Driver for Carlo Gavazzi EM511 Series Single Phase Energy Meters using Modbus RTU.
+python-em511 provides a simple, Pythonic interface for reading and writing data 
+from Carlo Gavazzi EM511 series energy meters over Modbus RTU. It builds on top 
+of [pymodbus](https://pypi.org/project/pymodbus/).
 
-## Get started
+## Example usage:
 
-### Prerequisites
+```python
+from em511 import Em511
+from pymodbus.client import ModbusSerialClient
 
-* Install [Python (>=3.10)](https://www.python.org/downloads/)
-* Install [git](https://git-scm.com/downloads)
-* Install [uv](https://docs.astral.sh/uv/getting-started/installation/)
+# Configure the Modbus client
+client = ModbusSerialClient(
+   port="COM3",  # or "/dev/ttyUSB0" on Linux
+   baudrate=9600,
+   parity="E",
+   stopbits=1,
+   bytesize=8,
+   # datasheet specifies maximum response timeout of 500ms (typical 40ms)
+   timeout=0.5,
+)
 
-### Setup development environment
+# Device Modbus address
+device_address = 1
 
-Clone the repository:
+# Initialize the EM511 driver
+meter = Em511(device_address=device_address, client=client)
 
-```sh
-git clone git@github.com:id8-engineering/python-em511.git
-```
-
-Change directory:
+# Read voltage
+voltage = meter.V
+print(f"Voltage: {voltage} V")
 
-```sh
-cd python-em511
+# Example of writing a password-protected parameter
+meter.password = 1234
 ```
 
-Run pre-commit tests:
+## Report issues
 
-```sh
-uv run pre-commit run -a
-```
+If you run into problems, you can ask for help in our [issue tracker](https://github.com/id8-engineering/python-em511/issues) on GitHub.
 
-Build package:
-
-```sh
-uv build
-```
+## Contributing
+See [CONTRIBUTING.MD](https://github.com/id8-engineering/python-em511/blob/main/CONTRIBUTING.MD) and [DEVELOPMENT.MD](https://github.com/id8-engineering/python-em511/blob/main/DEVELOPMENT.MD).