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 therejecttopic the descriptor points at (x-mqtt, seeil-mqtt.mdin the ildevice repository). -
A device's kind and the roles of its properties decide the composite entities. A group with its own
kindis a composite of its own, so one device can be a light and a cover.kind entity it needs climateclimatetarget_temperaturehumidifierhumidifier(classdehumidifierfor a dehumidifier)on,target_humidityfanfan(fan_speed, orspeedwhen the device takes a percentage;oscillate,direction)onlightlight; modes follow frombrightness,color_temperature,coloroncovercoverposition,openorcloselocklockwritable lockedvalvevalvewritable openedsirensirenonalarmalarm_control_panelsee il.mdvacuumvacuumsee il.mdA cover without
open/closemoves by writingposition100 / 0. A cover is closed when itspositionis 0, or else when itscover_stateisclosed;cover_statealso says opening and closing. A lock showslock_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.class,seriesandcategorybecomedevice_class,state_classandentity_category; a property with no device class gets an icon chosen from its name, unit and kind. -
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 anildevice_command_rejectedevent (device_id,prop,reason). -
Availability is the device's
availableproperty and the producer's presence (<il_prefix>/_producer/<source>;offlinemakes all of its devices unavailable).offline_gracedelays 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/tuyaandil/thinqcan 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
rejecttopic, and Home Assistant firesildevice_command_rejectedwith the reason. A control whoserequirescondition 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/requiresand 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.pyruns 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.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ildevice_homeassistant-0.2.0.tar.gz | 29.7 kB | With provenance | Details for ildevice_homeassistant-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ildevice_homeassistant-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for ildevice_homeassistant-0.2.0-py3-none-any.whl |
Total release size: 65.7 kB
Release files / ildevice_homeassistant-0.2.0.tar.gz
| Download URL | ildevice_homeassistant-0.2.0.tar.gz |
|---|---|
| Size | 29.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
cc3e1022717ce2c3b8f5306f2a68318d707b859fed9854f01cea3e951bc0248b
|
|
BLAKE2b-256 checksum How to use checksums |
b571a0be0f7805e217470bdc18c27fcf566092ca97e337acc50134d15675fd85
|
| 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 1, 2026.
Transparency logRelease files / ildevice_homeassistant-0.2.0-py3-none-any.whl
| Download URL | ildevice_homeassistant-0.2.0-py3-none-any.whl |
|---|---|
| Size | 36.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b3590ab907206a79c0ae9b27cf5cbb4dc042bc0fb6c227a330d98ff52105357b
|
|
BLAKE2b-256 checksum How to use checksums |
5739e6264ba97804ce43ada02e3bccb531c1ce519f69f41deb3bb609f86876a6
|
| 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 1, 2026.
Transparency logSecurity for ildevice-homeassistant 0.2.0
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.
Attestation for ildevice_homeassistant-0.2.0.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 1, 2026.
Transparency logA 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.