---
id: aiohomematic-config
version: "2026.8.0"
license: MIT License
license_treatment: permissive
maintenance: active
---

# aiohomematic-config — Presentation-layer library for Homematic device configuration UI.

License: permissive · Maintenance: active · Downloads: 231.7K/mo

## What it is and what it does

aiohomematic-config is a presentation-layer library that bridges Homematic device configuration data and UI rendering. It takes paramset descriptions and current device values from aiohomematic, then generates Pydantic-backed form schemas optimized for display in a configuration UI. The library handles grouping flat parameter lists into logical sections, mapping technical parameter IDs to human-readable labels, and selecting appropriate widget types for each parameter.

The package operates purely on data structures—it does not communicate with a CCU or make RPC calls. It includes components for schema generation, parameter grouping, label resolution, change tracking with undo/redo support, and configuration serialization. Output is JSON-serializable Pydantic models, making it straightforward to send schemas to a frontend or API consumer.

Use it for:

- Generate form schemas for a Homematic device configuration web UI from paramset metadata and current values.
- Map device parameter types to appropriate UI widgets (dropdown, text input, slider, etc.) automatically.
- Group flat parameter lists into logical sections for better UX in device configuration interfaces.
- Track configuration changes with undo/redo and dirty-state detection during a user's editing session.
- Serialize and deserialize device configurations for storage or transmission between systems.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Transforms Homematic device paramset descriptions into UI-ready form schemas using Pydantic models, without requiring RPC or CCU access.

Yes, if you are building a Homematic device configuration UI and need to transform paramset data into form schemas. The low install friction, active maintenance, and permissive MIT license make it a straightforward choice. Be aware it is in early alpha (API may shift) and requires Python 3.14, which is not yet widely deployed—verify your target environment supports it before committing.

## Install

pip install aiohomematic-config
uv add aiohomematic-config
poetry add aiohomematic-config

## Installing aiohomematic-config

Before you install: Low install friction; pure Python wheel with three runtime dependencies. Active maintenance with recent release (13 days old) and passing test suite. Early alpha status (Development Status :: 3) means the API may shift.

License in practice: MIT License permits commercial and private use with minimal restrictions; you must retain the license notice in distributions.

Quickstart:

from aiohomematic_config import FormSchemaGenerator

generator = FormSchemaGenerator(locale="en")
schema = generator.generate(
    descriptions=descriptions,
    current_values=current_values,
    channel_type="HEATING_CLIMATECONTROL_TRANSCEIVER",
)
print(schema.model_dump_json(indent=2))

Requires Python 3.14 or later (capped_below_current); aiohomematic and openccu-data must be installed first.

Verify before relying:

- Whether the package supports locales beyond English and German despite declaring both in classifiers.
- What the undo/redo and dirty-state tracking in ConfigSession actually persist to or whether they are in-memory only.
- Whether FormSchemaGenerator's output is compatible with common web form frameworks or if it requires custom rendering.

## Package facts

- License: MIT License (permissive)
- Python support: capped_below_current
- Install friction: low
- Maintenance: active
- Downloads: 231.7K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

homematic device configuration ui, paramset to form schema, home automation config generator, homematic ui schema builder, device parameter ui mapping, homematic configuration presentation, paramset form transformation, home-automation, ui-schema-generation, pydantic

[View on SkillFed](https://skillfed.io/packages/aiohomematic-config) · [View on PyPI](https://pypi.org/project/aiohomematic-config/)