# ezcoo-usb-control

> MQTT bridge for the **EZCOO EZ-MX42HAS-ARC** 4×2 HDMI matrix, with Home Assistant auto-discovery.

`ezcoo-usb-control` is a small Go daemon that talks to an EZCOO HDMI matrix
over USB-UART using its ASCII command set and exposes the routing state to
an MQTT broker. It publishes Home Assistant MQTT discovery payloads so the
matrix shows up automatically as two `select` entities — one per output —
ready to be used in dashboards and automations.

Built for, and running on, a Raspberry Pi 4, but the binary is plain Go and
works on any Linux/arm64, Linux/armhf or Linux/amd64 host that can see the
matrix as a serial device.

---

## Table of contents

- [Features](#features)
- [Hardware](#hardware)
- [Quick start](#quick-start)
- [Installation](#installation)
  - [Debian / Raspberry Pi OS (.deb)](#debian--raspberry-pi-os-deb)
  - [From source](#from-source)
- [Configuration](#configuration)
- [Running](#running)
- [MQTT topics](#mqtt-topics)
- [Home Assistant](#home-assistant)
- [Verifying the serial protocol](#verifying-the-serial-protocol)
- [Troubleshooting](#troubleshooting)
- [Project layout](#project-layout)
- [Development](#development)
- [Contributing](#contributing)
- [License](#license)
- [Acknowledgements](#acknowledgements)

---

## Features

- Two-way control of a 4-in / 2-out EZCOO HDMI matrix over USB-UART
- Home Assistant MQTT auto-discovery — zero manual entity wiring
- Periodic polling so external changes (front panel, IR remote) are reflected
  in MQTT
- LWT-based availability (`online` / `offline`)
- Structured logging via `log/slog`, with `--debug` flag
- Hardened `systemd` unit and `.deb` packages for `arm64`, `armhf`, `amd64`

## Hardware

Tested with:

- **EZCOO EZ-MX42HAS-ARC** (4 HDMI inputs, 2 HDMI outputs, ARC) — exposed
  as a USB CDC-ACM serial port (typically `/dev/ttyACM0`, 57600 8N1)
- Raspberry Pi 4 (Raspberry Pi OS, 64-bit) as the host

Other EZCOO matrices that share the same `EZG OUT0 VS` / `EZS OUTx VS INy`
ASCII protocol should work; if your unit speaks a slightly different dialect
see [Verifying the serial protocol](#verifying-the-serial-protocol).

## Quick start

```sh
# 1. Build a Raspberry Pi 4 (arm64) .deb on any Linux host with Go installed
make deb-arm64 VERSION=0.1.0

# 2. Copy and install on the Pi
scp dist/ezcoo-usb-control_0.1.0_arm64.deb pi@raspberrypi:~
ssh pi@raspberrypi 'sudo apt install ./ezcoo-usb-control_0.1.0_arm64.deb'

# 3. Configure and start
ssh pi@raspberrypi 'sudoedit /etc/ezcoo-usb-control/config.yaml'
ssh pi@raspberrypi 'sudo systemctl restart ezcoo-usb-control'
ssh pi@raspberrypi 'sudo journalctl -u ezcoo-usb-control -f'
```

## Installation

### Debian / Raspberry Pi OS (.deb)

Pre-built `.deb` packages are produced for each release; download the
matching architecture from the project's releases page and install:

```sh
sudo apt install ./ezcoo-usb-control_<version>_<arch>.deb
```

The package installs:

| Path | Purpose |
|---|---|
| `/usr/bin/ezcoo-usb-control` | Binary |
| `/etc/ezcoo-usb-control/config.yaml` | Default config (marked `conffile`) |
| `/lib/systemd/system/ezcoo-usb-control.service` | systemd unit |

A dedicated `ezcoo` system user is created with `dialout` as a supplementary
group so the daemon can open the serial device without root.

To build a `.deb` yourself for any supported architecture:

```sh
make deb-arm64 VERSION=0.1.0       # Raspberry Pi 4 / 5 (64-bit)
make deb-armhf VERSION=0.1.0       # Raspberry Pi 2/3 / Zero 2 (32-bit)
make deb-amd64 VERSION=0.1.0       # x86_64
make deb-all   VERSION=0.1.0       # all three
```

Requires `dpkg-dev` on the build host (`sudo apt install dpkg-dev`).

### From source

```sh
# native build
make build
./build/ezcoo-usb-control --config cmd/ezcoo-usb-control/config.example.yaml

# or directly with go
go build -o ezcoo-usb-control ./cmd/ezcoo-usb-control
```

Requires Go ≥ 1.26 (see `go.mod`).

## Configuration

Copy `cmd/ezcoo-usb-control/config.example.yaml` to `/etc/ezcoo-usb-control/config.yaml`
(the `.deb` package does this for you) and edit:

```yaml
device:
  port: /dev/ttyACM0       # serial device exposed by the matrix
  baud: 57600              # EZCOO default
  poll_interval: 15s       # how often to query routing state

mqtt:
  broker: tcp://192.168.1.10:1883
  username: ""
  password: ""
  client_id: ezcoo-usb-control
  base_topic: ezcoo                  # all state/set topics live under this
  discovery_prefix: homeassistant    # Home Assistant discovery root
```

All fields have sensible defaults — the minimum viable config is just
`mqtt.broker`. The config file path is passed via `--config`; if omitted,
defaults are used as-is.

## Running

```sh
ezcoo-usb-control --config /etc/ezcoo-usb-control/config.yaml
```

Flags:

| Flag | Description |
|---|---|
| `--config <path>` | Path to YAML config (optional) |
| `--debug` | Enable debug-level logging |

Under `systemd` the service is started with:

```sh
sudo systemctl enable --now ezcoo-usb-control
sudo journalctl -u ezcoo-usb-control -f
```

To observe what the bridge publishes while running:

```sh
mosquitto_sub -h localhost -t 'homeassistant/#' -v
mosquitto_sub -h localhost -t 'ezcoo/#' -v
```

## MQTT topics

Topic names assume the default `base_topic: ezcoo` and `discovery_prefix: homeassistant`.

| Topic | Direction | Payload | Description |
|---|---|---|---|
| `ezcoo/availability` | publish (retained, LWT) | `online` / `offline` | Bridge liveness |
| `ezcoo/output1/state` | publish (retained) | `IN1`..`IN4` | Current input routed to OUT1 |
| `ezcoo/output2/state` | publish (retained) | `IN1`..`IN4` | Current input routed to OUT2 |
| `ezcoo/output1/set` | subscribe | `IN1`..`IN4` | Switch OUT1 to the given input |
| `ezcoo/output2/set` | subscribe | `IN1`..`IN4` | Switch OUT2 to the given input |
| `homeassistant/device/ezcoo_matrix/config` | publish (retained) | JSON | HA device discovery payload |

## Home Assistant

If Home Assistant is connected to the same MQTT broker, the matrix appears
automatically as a single device with two `select` entities — no YAML
required. See [`docs/home-assistant.md`](docs/home-assistant.md) for
discovery details, example automations (including a "mirror both outputs"
recipe), and a Lovelace card snippet.

## Verifying the serial protocol

Before first deployment, probe the exact command set of your unit:

```sh
picocom -b 57600 /dev/ttyACM0
# then type:  EZH          (dumps all supported commands)
# then type:  EZG OUT0 VS  (shows current routing of all outputs)
```

The bridge expects responses in the form `OUT1 VS IN3`. If your unit
replies differently, adjust the `reOutVS` regular expression in
[`pkg/ezcoo/utils.go`](pkg/ezcoo/utils.go).

## Troubleshooting

- **`permission denied: /dev/ttyACM0`** — the `ezcoo` user must be in the
  group that owns the device (`dialout` on Debian/RPi OS). The `.deb` adds
  this automatically; for custom installs, do it manually.
- **Entities don't appear in Home Assistant** — confirm the discovery prefix
  matches HA's MQTT integration setting (default `homeassistant`), and that
  the broker shows a retained payload on `homeassistant/device/ezcoo_matrix/config`.
- **State never changes** — run with `--debug` and watch for `state update`
  log lines. If polling never returns matches, the regex likely needs
  adjusting (see above).
- **Bridge reports `offline` after connecting** — check that the systemd
  unit has access to the serial char device; the unit ships with
  `DeviceAllow=char-ttyACM rw` and `DeviceAllow=char-ttyUSB rw`.

## Project layout

```
.
├── cmd/ezcoo-usb-control/    # main entrypoint, config loader, example config
├── pkg/
│   ├── bridge/               # MQTT side: connect, subscribe, publish, HA discovery
│   └── ezcoo/                # serial side: device driver, protocol, polling loop
├── packaging/
│   ├── DEBIAN/               # control, postinst, prerm, postrm, conffiles
│   └── systemd/              # hardened service unit
├── .gitea/workflows/         # CI: build .deb packages on release
└── Makefile                  # build + multi-arch .deb targets
```

## Development

```sh
go build ./...
go vet  ./...
go test ./...
```

## Contributing

Issues and pull requests are welcome. For non-trivial changes please open
an issue first so the design can be discussed. When submitting a PR:

1. Run `go vet ./...` and `go test ./...`.
2. Keep changes focused and the commit history clean.
3. Update this README if you add a flag, change a topic, or alter the
   config schema.

## License

Released under the [MIT License](LICENSE.md)

## Acknowledgements

- The EZCOO ASCII command set documented in the EZ-MX42HAS-ARC manual.
- [`paho.mqtt.golang`](https://github.com/eclipse/paho.mqtt.golang) for the MQTT client.
- [`go.bug.st/serial`](https://github.com/bugst/go-serial) for cross-platform serial I/O.
- Home Assistant's
  [MQTT discovery](https://www.home-assistant.io/integrations/mqtt/#mqtt-discovery)
  schema.