dv-interfaces 2.0.0

Unified Modbus TCP driver library for solar plant hardware used in Direktvermarktung

dv-interfaces

Unified Modbus TCP driver library for solar plant hardware used in Direktvermarktung (direct energy marketing).

Each device — SolarLog, SMA, Meteocontrol, Smartdog — exposes a different Modbus register map. dv-interfaces abstracts all of it into one consistent Python API for reading production data and sending output curtailment commands.

Full documentation →

---

Context

Each device — SolarLog, SMA, Meteocontrol, SmartDog — exposes a different Modbus register map with different byte orders, slave IDs, and conventions. Without a shared layer, every integration has to rediscover and reimplement the same mapping work.

dv-interfaces removes that undifferentiated effort so you can build polling jobs, control paths, and validation tooling without touching raw register math.

The library covers Modbus TCP, the most common protocol for Fernsteuerbarkeit in Direktvermarktung. IEC 60870-5-104 is used in this space too but is not currently supported.

---

Installation

uv add dv-interfaces
# or
pip install dv-interfaces

---

Try it without installing

uvx --from dv-interfaces dv-detect 192.168.1.100
uvx --from dv-interfaces dv-read solarlog 192.168.1.100

Quick example

from dv_interfaces import get_interface

with get_interface('solarlog', '192.168.1.100') as iface:
    ds = iface.read_dataset()
    print(f'Production: {ds.production} W')
    print(f'Grid feed:  {ds.grid_feed:+d} W')

---

Supported devices

Driver	Device	Protocol	Spec
solarlog	SolarLog (Modbus TCP DPM licence required)	Modbus TCP	Datasheet
sma	SMA cluster	Modbus TCP	TI Direktvermarktung
meteocontrol	Meteocontrol blue'Log XC	Modbus TCP	Remote Power Control
smartdog	ecodata PowerDog / SmartDog	Modbus TCP	Modbus Register List

---

Features

• Unified read_dataset() → DVDataset across all drivers
• Write API: turn_on(), turn_off(), limit_plant(percent)
• Typed Modbus configuration with driver default slave IDs
• stream(iface) generator — yields readings continuously, errors yielded not raised
• detect_interface(host) — identify an unknown device by probing Modbus registers
• read_dataset_result().to_dict() — flat dict for direct DB insertion or task queue backends
• Auto-reconnect on dropped TCP connections
• PEP 561 typed

---

Issues and bugs

If you find a bug, a wrong register interpretation, or a device-specific edge case, please open an issue. Include the driver name, device model/firmware if known, the relevant Modbus register values, and the expected behaviour.

---

Development

uv sync
uv run pytest -m "not hardware"
uv run ruff check src/ tests/
uv run ty check
uv run mkdocs serve   # local docs preview

Hardware tests

Set one or more DV_TEST_<DRIVER>_HOST variables and run the hardware marker:

DV_TEST_SOLARLOG_HOST=192.168.1.100 uv run pytest -m hardware -v

Tests for drivers whose host variable is not set are automatically skipped. Multiple drivers can be tested at once:

DV_TEST_SOLARLOG_HOST=192.168.1.100 \
DV_TEST_SMA_HOST=192.168.1.101 \
uv run pytest -m hardware -v

See the hardware testing docs for the full variable reference.

License

MIT, see LICENSE.

---

About

Built by Gregorio Rodrigo
Making energy market data easier to work with

[e-mail]