tuya-matter
Tuya Matter
Bridge Tuya LAN power switches to a Matter controller. The bridge exposes each switch as an On/Off Plug-in Unit. It forwards On, Off, and Toggle commands, polls each switch every five seconds, and reports unreachable devices independently. Tuya client · Crystal Matter
Configuration
Copy config.example.yaml to config.yaml and fill in the local details for each device.
power_switch:
- ip: "192.0.2.10"
device_id: "your-device-id"
key: "0123456789abcdef"
name: "Desk Plug"
- ip: "192.0.2.11"
device_id: "another-device-id"
key: "fedcba9876543210"
| Field | Default | Purpose |
|---|---|---|
ip |
Required | LAN IP address of the device |
device_id |
Required | Tuya device ID, unique within the config |
key |
Required | 16-byte Tuya local key |
name |
Generated | Matter label, up to 32 bytes |
version |
Automatic | Optional protocol override, from "3.1" through "3.5" |
port |
6668 |
Tuya TCP port |
datapoint |
1 |
Boolean power datapoint |
assume_off_when_missing |
false |
Report Off when a successful status reply omits the power datapoint |
query_datapoints |
Device default | IDs to query for devices that use the device22 query format. Include the power datapoint. |
The bridge detects each device’s Tuya version using LAN announcements and a status query. Devices that are offline are retried in the background. Restart the bridge after editing the config.
Enable assume_off_when_missing: true for a switch whose firmware omits the power datapoint when off. The bridge still uses an explicit power value when the device reports one.
Matter endpoints and connectivity
Endpoint 0 is the Matter root and endpoint 1 is the bridge aggregator. On a fresh setup, the first two switches use endpoints 2 and 3. The bridge keeps assigned endpoint numbers in Matter state across restarts and identifies each switch by name and address in its logs.
Some Tuya devices accept only one local TCP client at a time. If a device resets connections, close other apps or integrations using it before retrying. TinyTuya troubleshooting
Docker Compose
Run these commands on a Linux host on the same LAN as the Matter controller and Tuya devices.
Compose mounts ./config.yaml read-only and stores Matter state in ./matter-data/. Host networking provides Matter UDP and multicast DNS. The container user needs read access to config.yaml.
Compose runs as UID and GID 1000 by default. To run as a different deployment account, set MATTER_UID and MATTER_GID in .env to that account's id -u and id -g.
Make sure the container user can write to matter-data/ and any restored files before starting Compose. If you need to fix ownership, this command uses the default IDs.
sudo chown -R 1000:1000 ./matter-data/
Replace both numbers with the configured IDs if you changed them.
docker compose pull
docker compose up -d
docker compose logs -f tuya-matter
To build locally, uncomment build: . in docker-compose.yml and run docker compose up -d --build.
Use the manual pairing code or QR payload printed on first start to add the bridge to your Matter controller. The bridge uses the Crystal Matter development attestation identity.
Back up or move the bridge
Stop the bridge before backing up matter-data/. Copy that directory and config.yaml to the new host, then check ownership before starting Compose. Keep the backup private because it contains Matter pairing keys and Tuya local keys.
Publish the Docker image
Sign in to Docker Hub with access to stakach/tuya-matter, then run the publish script.
docker login
./scripts/publish-image.sh
The script pulls the latest Crystal Alpine builder, builds statically linked binaries for linux/amd64 and linux/arm64, and publishes both as stakach/tuya-matter:latest with a scratch runtime.
Run locally
Requires Crystal 1.22 or later and OpenSSL.
shards install
shards build tuya-matter
bin/tuya-matter
| Environment variable | Default |
|---|---|
TUYA_CONFIG_FILE |
config.yaml |
MATTER_STORAGE_FILE |
data/tuya-matter.yml |
MATTER_PORT |
5540 |
LOG_LEVEL |
info |
Development
shards install
shards build ameba
bin/ameba
crystal spec
tuya-matter
- 0
- 0
- 0
- 0
- 3
- 15 minutes ago
- November 21, 2026
MIT License
Sat, 21 Nov 2026 09:05:37 GMT