150 lines
4.7 KiB
Markdown
150 lines
4.7 KiB
Markdown
# Home Assistant integration
|
|
|
|
`ezcoo-usb-control` publishes an MQTT discovery payload, so the matrix
|
|
appears in Home Assistant as a single device with two `select` entities —
|
|
one per HDMI output — without any YAML.
|
|
|
|
- [Prerequisites](#prerequisites)
|
|
- [Discovery](#discovery)
|
|
- [Entities](#entities)
|
|
- [Example automations](#example-automations)
|
|
- [Route Apple TV to the living-room TV](#route-apple-tv-to-the-living-room-tv)
|
|
- [Mirror both outputs to the same input](#mirror-both-outputs-to-the-same-input)
|
|
- [Lovelace card](#lovelace-card)
|
|
- [Troubleshooting](#troubleshooting)
|
|
|
|
## Prerequisites
|
|
|
|
- Home Assistant is connected to the **same MQTT broker** that the bridge
|
|
is configured to use.
|
|
- The
|
|
[MQTT integration](https://www.home-assistant.io/integrations/mqtt/) is
|
|
enabled and its **Discovery prefix** matches `mqtt.discovery_prefix` in
|
|
the bridge config (default: `homeassistant`).
|
|
- `ezcoo-usb-control` is running and reports `online` on
|
|
`<base_topic>/availability`.
|
|
|
|
## Discovery
|
|
|
|
On startup the bridge publishes a retained device-level discovery payload to:
|
|
|
|
```
|
|
<discovery_prefix>/device/ezcoo_matrix/config
|
|
```
|
|
|
|
With defaults that resolves to `homeassistant/device/ezcoo_matrix/config`.
|
|
You can inspect it with:
|
|
|
|
```sh
|
|
mosquitto_sub -h <broker> -t 'homeassistant/device/ezcoo_matrix/config' -v
|
|
```
|
|
|
|
Home Assistant picks the payload up automatically and creates the device.
|
|
Removing the retained message (or stopping the bridge with the broker
|
|
configured to drop retained messages) makes the entities disappear.
|
|
|
|
## Entities
|
|
|
|
By default the bridge registers a single device, **EZCOO HDMI Matrix**, with
|
|
two entities:
|
|
|
|
| Entity ID | Type | Options | Source topic |
|
|
|---|---|---|---|
|
|
| `select.ezcoo_hdmi_matrix_output_1` | `select` | `IN1`, `IN2`, `IN3`, `IN4` | `ezcoo/output1/state` |
|
|
| `select.ezcoo_hdmi_matrix_output_2` | `select` | `IN1`, `IN2`, `IN3`, `IN4` | `ezcoo/output2/state` |
|
|
|
|
Setting an option publishes to `ezcoo/output<N>/set`; the bridge then
|
|
issues the corresponding `EZS OUT<N> VS IN<M>` command to the matrix and
|
|
re-publishes the confirmed state.
|
|
|
|
> Entity IDs can be renamed in the Home Assistant UI. The examples below
|
|
> use the default slugs — adjust if you renamed yours.
|
|
|
|
## Example automations
|
|
|
|
### Route Apple TV to the living-room TV
|
|
|
|
Switch output 1 to input 2 whenever the Apple TV starts playing:
|
|
|
|
```yaml
|
|
- alias: "Route Apple TV to living-room TV"
|
|
trigger:
|
|
- platform: state
|
|
entity_id: media_player.apple_tv
|
|
to: "playing"
|
|
action:
|
|
- service: select.select_option
|
|
target:
|
|
entity_id: select.ezcoo_hdmi_matrix_output_1
|
|
data:
|
|
option: "IN2"
|
|
```
|
|
|
|
### Mirror both outputs to the same input
|
|
|
|
Whenever either output is changed (via Home Assistant, the front panel, or
|
|
the IR remote), this automation routes the *other* output to the same
|
|
input — so both displays always show the same source. The template
|
|
condition prevents a feedback loop when the second `select` is already in
|
|
sync.
|
|
|
|
```yaml
|
|
alias: EZCOO HDMI Matrix — sync outputs
|
|
description: ""
|
|
triggers:
|
|
- trigger: state
|
|
entity_id:
|
|
- select.ezcoo_hdmi_matrix_output_1
|
|
- select.ezcoo_hdmi_matrix_output_2
|
|
not_to:
|
|
- unknown
|
|
- unavailable
|
|
conditions: []
|
|
actions:
|
|
- variables:
|
|
target: |-
|
|
{% if trigger.entity_id == 'select.ezcoo_hdmi_matrix_output_1' %}
|
|
select.ezcoo_hdmi_matrix_output_2
|
|
{% else %}
|
|
select.ezcoo_hdmi_matrix_output_1
|
|
{% endif %}
|
|
- condition: template
|
|
value_template: "{{ states(target) != trigger.to_state.state }}"
|
|
- action: select.select_option
|
|
target:
|
|
entity_id: "{{ target }}"
|
|
data:
|
|
option: "{{ trigger.to_state.state }}"
|
|
mode: single
|
|
max_exceeded: silent
|
|
```
|
|
|
|
## Lovelace card
|
|
|
|
A minimal Lovelace entities card:
|
|
|
|
```yaml
|
|
type: entities
|
|
title: HDMI Matrix
|
|
entities:
|
|
- entity: select.ezcoo_hdmi_matrix_output_1
|
|
name: Output 1
|
|
- entity: select.ezcoo_hdmi_matrix_output_2
|
|
name: Output 2
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
- **Entities don't appear.** Confirm the broker has a retained payload on
|
|
`homeassistant/device/ezcoo_matrix/config`, and that Home Assistant's
|
|
MQTT integration uses the same discovery prefix.
|
|
- **Entities are stuck on `unavailable`.** The bridge publishes `offline`
|
|
to `ezcoo/availability` as its Last Will. Check `journalctl -u ezcoo-usb-control`
|
|
for connection errors.
|
|
- **Changing a `select` does nothing.** Watch `ezcoo/output<N>/set` with
|
|
`mosquitto_sub` — if the message arrives, the failure is on the serial
|
|
side; run the bridge with `--debug` to see the command exchange.
|
|
- **Automations fire in a loop.** When reacting to `select` state changes,
|
|
always guard with a template condition that compares current vs target
|
|
state (see the *sync outputs* example above).
|