Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

IL device

IL device for Home Assistant

A Home Assistant integration for ildevice (Intermediate Layer device model). It turns the ildevice descriptors that producers publish over MQTT into Home Assistant devices and entities. It knows nothing about any one producer or model: a device from rusthinq, rustuya or anything else that publishes a descriptor gets its device and entities from the descriptor alone.

Setup

Requires Home Assistant's mqtt integration. Install IL device through HACS (or copy custom_components/ildevice), restart, and add the integration. Add it again for each topic prefix you use (see Several hubs).

option meaning
Topic prefix The ildevice prefix the producers publish under (default il), for example il/tuya. Each entry has one prefix, so it must be unique.
Seconds before a device is shown unavailable Keeps a short outage from showing (default 0).
Legacy entity ids JSON aliases that keep the unique ids of an earlier integration, see below.
Add discovered devices automatically Skip the add / ignore question, see below.

For rusthinq scripts that publish <prefix>/<id>/descriptor, set the integration Topic prefix to the host's [drivers] topic_prefix (for example rusthinq). Existing <prefix>/<id> descriptors remain supported. Property and command paths come from the descriptor's x-mqtt block when provided.

Several hubs

Add the integration once per topic prefix, such as il/tuya or il/thinq: each entry is its own hub with its own options (auto-add, offline grace, legacy ids) and shows up in the integration's list under its prefix, with its devices beneath it. A discovered device is offered to, and added to, the entry it was found on. Changing an entry's prefix renames it. A prefix can be used by one entry only. Device ids should be unique across entries, as they are the device identifier and the base of the unique ids.

How it works

docs/examples.md walks through a plug, a light, an air conditioner, a curtain with a light, a button and a valve on its own topics: what the producer publishes, the entities it becomes, and the MQTT messages for commands.

  • It subscribes to <il_prefix>/+ and <il_prefix>/+/descriptor (retained descriptors), and <il_prefix>/_producer/+ (producer presence). For each device it subscribes to the value topics and the reject topic the descriptor points at (x-mqtt, see il-mqtt.md in the ildevice repository).

  • A device's kind and the roles of its properties decide the composite entities. A group with its own kind is a composite of its own, so one device can be a light and a cover.

    kind entity it needs
    climate climate target_temperature
    humidifier humidifier (class dehumidifier for a dehumidifier) on, target_humidity
    fan fan (fan_speed, or speed when the device takes a percentage; oscillate, direction) on
    light light; modes follow from brightness, color_temperature, color on
    cover cover position, open or close
    lock lock writable locked
    valve valve writable opened
    siren siren on
    alarm alarm_control_panel see il.md
    vacuum vacuum see il.md

    A cover without open / close moves by writing position 100 / 0. A cover is closed when its position is 0, or else when its cover_state is closed; cover_state also says opening and closing. A lock shows lock_state (locking, unlocking, jammed, open) when it has one. A lock or valve that is not writable stays a plain binary sensor: a role never implies control.

  • Every other property is a plain entity chosen by its type: sensor / binary_sensor / switch / number / select / text / button / event / image. class, series and category become device_class, state_class and entity_category; a property with no device class gets an icon chosen from its name, unit and kind.

  • An image property (a robot vacuum's map, for one) is an image entity. Its state topic carries the picture itself as raw bytes, retained, of the descriptor's content_type (image/png when absent); each message is a new picture, and an empty payload clears it. image is not yet a type of the ildevice specification: a consumer that does not know it skips the property.

  • A control whose property has requires (a binary that must be true, or a select whose value must be in a list) is unavailable, or for one control of a composite refused, until the condition holds. A refused command arrives as an ildevice_command_rejected event (device_id, prop, reason).

  • Availability is the device's available property and the producer's presence (<il_prefix>/_producer/<source>; offline makes all of its devices unavailable). offline_grace delays unavailability reported by the device; producer-offline presence takes effect immediately.

  • An empty MQTT descriptor payload withdraws the device: its entities, registry entries and value subscriptions go, and it is created again if the descriptor is published again. A changed descriptor re-plans its entities.

  • Unknown fields are ignored. An unknown role falls back to a plain entity; a property with an unknown type is skipped.

Commands have no correlated success acknowledgement or completion deadline. State updates show observed state; a successful trigger or unchanged write can be silent. A rejection reports failure, and silence does not confirm success. Retained replay restores state per topic and is not an atomic snapshot across the device's properties.

Adding devices

A device that publishes a descriptor is not created at once. Home Assistant shows it under "Discovered" (named after the descriptor's label), and you add it or ignore it. An ignored device is not offered again. Deleting a device in Home Assistant makes it a new offer the next time it appears. The option "Add discovered devices automatically" skips the question and creates every device, and turning it off keeps the devices it had added.

Keeping the ids of an earlier integration

An entity's unique id is <device id>-<key>, where the key is the property name, or for a composite its platform (climate, light, ...) or its group name. To keep the ids an earlier integration created, give aliases in the options, as JSON keyed by model (* for any):

{"DHUM_056905_WW": {"uvnano": "uv_nano", "tank_full": "bucket_full"}, "*": {}}

Compared with MQTT discovery

Home Assistant's own MQTT discovery also builds devices from retained MQTT messages. It has no setup, and any producer that follows it works with nothing extra installed. This integration needs a producer that publishes ildevice descriptors, and in return:

  • One descriptor per device, not one config per entity. The producer says what each property is (its role, type and unit), not which Home Assistant entity to build. The same descriptor serves any other ildevice consumer.
  • Devices made of several parts. Roles become climate, humidifier, fan, light, cover, lock, valve, siren, alarm and vacuum entities. Groups let one device hold several of them, such as a light and a cover, next to its plain sensors and switches.
  • Separate hubs per topic prefix. MQTT discovery has one discovery prefix for everything. Here il/tuya and il/thinq can be separate entries, each with its own auto-add, offline grace and alias options, and each lists its own devices.
  • You choose which devices to add. A discovered device is offered to add or ignore, rather than created at once.
  • Refused commands are reported. A producer can refuse a command on the device's reject topic, and Home Assistant fires ildevice_command_rejected with the reason. A control whose requires condition does not hold is unavailable, rather than sending a command that will fail.
  • Availability comes from the producer too. When a producer goes offline, all of its devices go unavailable. The offline grace keeps a short outage from showing.
  • Unique ids can be kept. Aliases map entity keys to the ones that an earlier integration used (see Keeping the ids).
  • It also runs without a broker. Another integration can embed the consumer with an in-process transport (see Embedding).

Layout

ildevice_ha/core/                 Home Assistant free: descriptor, plan (entities), topics, values,
                                  the consumer model, transport interface, in-process broker, icons
ildevice_ha/                      the Home Assistant layer: hub (the model's sink), entity classes,
                                  HA mqtt transport, attach; published to PyPI as `ildevice-homeassistant`
custom_components/ildevice/       the integration: config flow and platforms, requiring `ildevice-homeassistant`
tests/                            core and model tests, the ildevice vectors, and the integration
                                  in a test Home Assistant

core/plan.py is where a descriptor becomes entities; nothing in it looks at a model. core/model.py follows descriptors, values, presence and rejections on a Transport and tells a Sink what changed, so the same core runs without Home Assistant.

Embedding

Another integration that produces ildevice descriptors in the same process can use the consumer instead of going through a broker. It lists ildevice-homeassistant in its manifest requirements (the same pinned version as this integration's manifest), not this integration in dependencies, and calls ildevice_ha.attach.build_hub(hass, options, transport, platform) with its own transport (for example core.memory.InProcessTransport, an in-process broker with MQTT's filters and retained messages) and its own domain. It forwards the platforms listed in const.PLATFORMS to its config entry and hands each one's async_add_entities to hub.register_platform.

InProcessTransport keeps retained values but does not keep a publish history by default. Tests that inspect transport.published should construct it with record_published=True.

Specification baseline

The MQTT consumer is tested against the conformance vectors of ildevice specification v0.1.0 (draft il: 0), commit bc51a9e. CI pins that revision because draft changes can break compatibility without changing il. Local vector tests use the checkout selected by ILDEVICE (or ../ildevice), so they can also check proposed specification changes before the baseline is advanced.

Tests

python3.14 -m venv .venv
.venv/bin/python -m pip install -e ".[test]"
.venv/bin/python -m pytest
  • tests/fixtures/rusthinq/ holds the descriptors the rusthinq drivers publish (ten LG appliances), which cover the composite kinds, trigger / requires and groups.
  • tests/fixtures/sample/ holds descriptors from a Tuya producer with its own topic layout: a plug, bulb, curtain, lock, valve, siren and button.
  • tests/test_vectors.py runs the language-neutral conformance vectors of the ildevice repository. It looks for a checkout at ../ildevice, or at $ILDEVICE, and is skipped without one.

Metadata

Release files for ildevice-homeassistant 0.2.1rc1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ildevice-homeassistant 0.2.1rc1
File Size Uploaded Provenance Actions
ildevice_homeassistant-0.2.1rc1.tar.gz 30.4 kB With provenance Details for ildevice_homeassistant-0.2.1rc1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ildevice-homeassistant 0.2.1rc1
File Interpreter ABI Platform Actions
ildevice_homeassistant-0.2.1rc1-py3-none-any.whl Python 3 none any Details for ildevice_homeassistant-0.2.1rc1-py3-none-any.whl

Total release size: 67.1 kB

Release files / ildevice_homeassistant-0.2.1rc1.tar.gz

Download URL ildevice_homeassistant-0.2.1rc1.tar.gz
Size 30.4 kB
Tags Source
SHA-256 checksum
How to use checksums
7a23c9e6c2328242af3d731347f39eb2626684b6175e6234a091557770517fd2
BLAKE2b-256 checksum
How to use checksums
6a70cfe9cbd0bdd2ce19c2f1bd5a51033711fbddbabba4a4126b0520663be1eb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

Release files / ildevice_homeassistant-0.2.1rc1-py3-none-any.whl

Download URL ildevice_homeassistant-0.2.1rc1-py3-none-any.whl
Size 36.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
bccbd24b2266f7bb1866b426c7988da175c15130c6eb9977ce64370beab45b41
BLAKE2b-256 checksum
How to use checksums
9d9c12dca98c63cba2e62d68f349410a929ce021b8c75171ffe8e37a91a1999e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

Security for ildevice-homeassistant 0.2.1rc1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for ildevice_homeassistant-0.2.1rc1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page