Metadata-Version: 2.5
Name: ildevice-homeassistant
Version: 0.2.0
Summary: The IL device consumer for Home Assistant: IL descriptors become entities
Project-URL: Source, https://github.com/3735943886/ildevice-homeassistant
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.12
Provides-Extra: test
Requires-Dist: pytest-homeassistant-custom-component==0.13.366; extra == 'test'
Description-Content-Type: text/markdown

![IL device](custom_components/ildevice/brand/icon.png)

# IL device for Home Assistant

A Home Assistant integration for [ildevice](https://github.com/3735943886/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](#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](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`. `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.
- 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):

```json
{"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](#keeping-the-ids-of-an-earlier-integration)).
- **It also runs without a broker.** Another integration can embed the consumer with an in-process
  transport (see [Embedding](#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](https://github.com/3735943886/ildevice/tree/bc51a9ef8ac46770f67a02722c5c92907d1019ee).
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.

