pydsvdcapi 0.8.0

Python library for the digitalSTROM vDC API

pydsvdcapi

Python library for the digitalSTROM virtual Device Connector (vDC) API.

What this library does

• Implements the full vDC protobuf protocol over TCP
• Manages the session lifecycle (hello/pong, announcement, reconnect)
• Models all device classes: lights, blinds, sensors, buttons, heating, audio, and more
• Provides a composable API: VdcHost → Vdc → Vdsd → components
• Persists device state across restarts via a YAML property store
• Automatically derives modelFeatures flags from configured components
• Supports value converters for uplink/downlink data transformation

Installation

pip install pydsvdcapi

Requires Python 3.10+.

Quick start

import asyncio
from pydsvdcapi import (
    VdcHost, Vdc, Device, Vdsd,
    DsUid, DsUidNamespace,
    Output, OutputFunction, OutputMode, OutputUsage,
    ColorGroup,
)

async def main():
    host = VdcHost(dsuid=DsUid.new_uuid_based(), name="My VDC Host")

    vdc = Vdc(dsuid=DsUid.new_uuid_based(), name="My VDC")
    host.add_vdc(vdc)

    device = Device(dsuid=DsUid.new_gtin_based("0000000000001", 0))
    vdsd = Vdsd(dsuid=DsUid.new_uuid_based(), name="My Light")
    output = Output(
        function=OutputFunction.LIGHT,
        mode=OutputMode.SWITCH,
        usage=OutputUsage.ROOM,
        group=ColorGroup.YELLOW,
    )
    vdsd.set_output(output)
    device.add_vdsd(vdsd)
    vdc.add_device(device)

    await host.run()  # connects and blocks until stopped

asyncio.run(main())

See examples/getting_started.py for a minimal runnable example and examples/full_showcase.py for all 27 device classes.

Development

git clone https://github.com/KarlKiel/pyDSvDCAPI.git
cd pyDSvDCAPI
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

Command	Purpose
python -m pytest	Run tests
ruff check src/ tests/	Lint
ruff format src/ tests/	Format
mypy src/pydsvdcapi	Type-check

See CONTRIBUTING.md for full guidance.

Documentation

API reference: pydsvdcapi.readthedocs.io

Domain documentation lives in docs/:

• vDC API Properties
• VDC Host Behavior
• Device Splitting Guidelines

License

GPLv3 — see LICENSE.