shards.info
samsung_tv_matter
samsung_tv_matter
A Matter bridge for Samsung Frame TVs. It wraps the local-only samsung_tv client library and exposes the TV to any Matter controller (HomeKit, chip-tool, ...). Everything is local network — no SmartThings / cloud.
Endpoints
| # | Control | Behaviour |
|---|---|---|
| 1 | Power | Real on/off switch. State is polled from the TV (PowerState), so it stays accurate even when the physical remote is used. Off = standby (screen off); turning off holds the power key for ~4 s. |
| 2 | Mute | On/off switch, optimistic: the TV only exposes a mute toggle with no state read-back, so each flip sends one toggle and the switch position is the assumed state (it can drift if the physical remote mutes the TV). |
| 3 | Play | Momentary button — fires once, then resets itself to off. |
| 4 | Pause | Momentary button. |
| 5 | Volume Up | Momentary button (one volume step per press). |
| 6 | Volume Down | Momentary button. |
Volume/mute work over HDMI eARC too (the TV forwards the CEC command to the amp). Art mode is treated as "on" — it is not detectable over the local API on 2024 Frame models.
Running
shards install
TV_IP=192.168.1.40 crystal run src/main.cr
# or: shards build && TV_IP=192.168.1.40 ./bin/samsung_tv_matter
Configuration (env vars, or the matching --flags):
| Variable | Default | Purpose |
|---|---|---|
TV_IP |
(required) | TV IP address / hostname |
TV_TOKEN_FILE |
data/tv.token |
Where the TV pairing token is persisted |
TV_NAME |
MatterBridge |
Client name shown on the TV's Allow prompt |
TV_MAC |
(learned from TV) | MAC for Wake-on-LAN fallback |
MATTER_STORAGE_FILE |
data/samsung_tv_matter_storage.json |
Matter fabric persistence |
POLL_INTERVAL |
5 |
TV power-state poll interval (seconds) |
LOG_LEVEL |
info |
debug / info / warn / error |
Pairing — two steps
- Matter: on start (uncommissioned) the bridge prints a QR code and manual pairing code. Scan it with your controller, or:
chip-tool pairing code 1 <manual-code> - TV: after commissioning, the first TV connection makes the TV show an Allow / Deny prompt — accept it. The token is saved to
TV_TOKEN_FILEand reused silently afterwards (the bridge retries until accepted).
The TV is only contacted once the bridge has been commissioned.
Docker
Before launching, make sure the data folder permissions are correct:
sudo chown -R 10001:10001 ./data/
Then can either pass in the IP like this or edit the docker-compose.yml file
TV_IP=192.168.1.40 docker compose up -d
Uses network_mode: host (required for mDNS/Matter UDP) and persists the Matter fabrics + TV token in ./data.
Development
crystal spec— cluster→action wiring is tested against a fake TV control (no hardware needed).crystal tool format/./bin/ameba— format and lint.
Contributing
- Fork it (https://github.com/stakach/samsung_tv_matter/fork)
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Push to the branch (
git push origin my-new-feature) - Create a new Pull Request
Contributors
- Stephen von Takach - creator and maintainer
samsung_tv_matter
- 0
- 0
- 0
- 0
- 3
- about 1 hour ago
- June 4, 2026
MIT License
Thu, 04 Jun 2026 15:37:45 GMT