2.8.0 — poll only what you use (beta)

Beta release — the production resolution of the ProjectorService crash investigation (#1), and a rework of how polling works. This is the candidate for 3.0.0: it will be promoted to stable after an extended period of real-world use and the full hardware click-through in TESTING.md.

Polling now follows your entities

• Only enabled entities are polled. Disable an entity in the UI and its RS232 query disappears from the cycle. Fewer enabled entities = shorter cycles = fresher values.
• Device details are read once at startup (firmware, MAC, serial) instead of every cycle, retried only until the projector reports real values.
• The interval adapts to power state: your configured interval while the projector is on, relaxed to ≥60 s in standby. The projector's own power-on push (or an HA power command) restores fast polling instantly.
• Poll-interval changes from the options flow apply live, no restart.

UHZ68LV firmware bug — resolved by default

The investigation in #1 traced the "ProjectorService: Central service has been disconnected" toast to the projector's own firmware: the IP-address query ~XX87 3 intermittently (~1 in 20 calls) crashes its internal service on firmware DDP C22 / MCU M12 / Scalar S32. The IP Address sensor ships disabled, and disabled entities are never polled — so a default install never sends the query. If you enable that sensor and see the toast, disable it again (documented in the README's known issues). Reported to Optoma.

Also included (since 2.7.0)

• Dolby Vision: added Dolby Vision Vivid, corrected the DV read-back codes (45/46/47 — hardware-validated; the official command table is wrong here).
• Filmmaker Mode picture mode (write 54 / read 52), available for SDR and HDR content.
• README: usage examples, rewritten polling docs, beta status.
• TESTING.md: the hardware verification checklist gating the 3.0.0 stable release.

Known gap: HDR10+ has no confirmed read-back code (#2) — selecting it works; the Picture Mode sensor may show a raw number while HDR10+ content plays.

Diagnostic pre-releases 2.7.1–2.7.3 (branch test/no-polling) served the crash investigation and are superseded by this build; that branch is now closed.

2.7.3 — diagnostic: burst-size probe (POLL_PAD_TO)

⚠️ Diagnostic pre-release for #1. Not for general use.

Burst-size probe

Prior rounds ruled out sustained read rate as the crash trigger, and a crash appeared ~10 min after the cycle grew to ~10 reads (power + picture + device_info). This build separates the two remaining hypotheses — burst size vs a specific poison read.

New POLL_PAD_TO knob (const.py) pads each poll cycle up to N reads by repeating a known-safe read (power 124/1), adding no new distinct read.

Default config: power group only + POLL_PAD_TO = 10 → a 10-read burst of identical power queries per cycle.

• Crashes → it's burst / queue depth: too many queries in one tight cycle, regardless of content. Fix = cap/stagger reads per cycle (pairs with the planned poll-gating + tiered polling).
• Stays clean → burst count alone isn't it; the crash is content-specific → re-enable a group and sub-bisect.

How to run

1. Update via HACS (beta channel).
2. Set the poll interval to 5 s in Settings → Devices → Optoma Link → Configure.
3. Reboot HA. Only power is read (10× per cycle); all other entities stay "unknown".
4. Watch lamp hours for a crash. Set POLL_PAD_TO = 0 to disable padding.

See DIAGNOSTICS.md.

2.7.2 — diagnostic: power-only polling

⚠️ Diagnostic pre-release for #1. Not for general use.

The 2.7.1 no-polling baseline ran stable for ~2 days, confirming the projector's ProjectorService crash is triggered by our read/query traffic — not by commands and not by holding the connection open. This build re-enables reads one group at a time to find the specific read that trips the firmware.

What's new

• Replaces the single DISABLE_POLLING switch with a POLL_GROUPS table in const.py (power / source / picture / signal / av / laser / temperature / device_info).
• Default: power only, polled on the interval set in the integration options.
• All other reads are suppressed — those entities show "unknown" until their group is enabled.
• Commands and the projector's unsolicited status pushes work in every configuration.
• Includes the Dolby Vision fix from main: adds Dolby Vision Vivid and corrects the Dolby Vision read codes (45/46/47).

How to use

1. Update via HACS (enable Show beta versions).
2. Set the poll interval to 30 s in Settings → Devices → Optoma Link → Configure.
3. Reload. Power state tracks live; everything else stays "unknown."
4. To advance the investigation, enable one more group in POLL_GROUPS per test run until the crash returns — that group holds the offending read.

See DIAGNOSTICS.md for the group map and full re-enable plan.

Known limitation: HDR10+ picture mode has no known read code and won't display until it's found (#2).

v2.7.1 - Diagnostic no-polling build

Diagnostic build with polling disabled to isolate the UHZ68LV ProjectorService crash.
See DIAGNOSTICS.md. Not for general use.

v2.7.0

Optoma Link 2.7.0

Added

• Image Freeze switch to freeze and unfreeze the projected picture (write-only, remembers the last state you set).
• Dynamic Black 1/2/3 added as options in the Light Source Power control, alongside the fixed brightness percentages.

Changed

• Sharpness now defaults to 8 instead of sitting at its minimum (1) until you set it for the first time.

Fixed

• Added format validation for sensor and diagnostic readings (firmware, MAC address, serial number, IP address, resolution, refresh rate, temperature, projector ID). Each field now checks that a reading matches its expected shape (for example, a MAC address must look like AA:BB:CC:DD:EE:FF) before accepting it. This guards against the projector briefly answering the wrong field during signal or power transitions, which could previously show, for example, a resolution value where the serial number should be.

Full changelog: v2.6.0...v2.7.0

V2.6.0

Optoma Link 2.6.0

Added

• A live Status sensor: Off, Warming up, On, Cooling down, or Error. It is driven by the projector's own status messages, so it reflects power transitions the moment they happen instead of waiting for the next poll. Faults (over-temperature, fan lock, cover open, and so on) show as Error, with the specific event available as a last_message attribute.
• Pressing Power now updates the status immediately (Warming up / Cooling down), so the button gives instant feedback instead of appearing to do nothing for many seconds.

Fixed

• Sensor values could get scrambled after the projector changed power state, with values landing on the wrong entities (for example, the refresh rate showing as the serial number, or firmware as the MAC address). The projector sends unsolicited status messages on power transitions, which could desynchronize the command/reply stream. This release replaces last version's quick fix with a proper one: connections now read the projector's status messages continuously and never mistake one for a command reply.

Full changelog: v2.4.0...v2.6.0

v2.5.0

Optoma Link 2.5.0

Fixes and polish from a fifth round of UHZ68LV hardware testing.

Fixed

• The device "Visit" link now opens the projector's web UI correctly, including https and the management port (https://your-host:8088 on the UHZ68LV).
• Cleared a stray second "MAC" entry on the device page (it was actually the IP address). The projector's real MAC is now the only network connection recorded.
• Picture Mode errors now also explain the reverse case: picking a mode that needs a content type that is not active (for example, choosing a Dolby Vision or 3D mode while an SDR mode is showing) is described instead of a raw rejection.

Changed

• Toggling 3D now refreshes Picture Mode and Resolution within a couple of seconds, instead of waiting for the next poll.
• The IP Address diagnostic sensor is disabled by default. Enable it from the entity settings if you want it.

Full changelog: v2.4.0...v2.5.0

V2.4.0

Optoma Link 2.4.0

Fixes and refinements from a fourth round of UHZ68LV hardware testing.

Fixed

• The device "Visit" link now points to exactly the address you entered during setup. It was using the projector-reported IP, which the projector zero-pads (010.127.040.241) and browsers then misread as octal, sending you to the wrong address.
• The IP Address sensor now strips that zero-padding, so it reads like 10.127.40.241.

Added

• When the projector refuses a picture mode, the error now explains why. The projector keeps SDR, HDR, Dolby Vision, and 3D as separate "universes" that cannot be mixed, so the message names the one that is currently active (for example, "Cinema is not available while the projector is in HDR mode").
• The Resolution sensor now reports pixel dimensions (for example 1920x1080 instead of 1080p), so you can calculate aspect ratio in automations.

Changed

• The Eco standby warning during setup is now a highlighted banner instead of being buried in the body text.
• The Serial Number and Projector ID diagnostic sensors are now disabled by default. Enable them from the entity settings if you want them. The IP Address sensor stays enabled.

Docs

• The README now shows what the integration exposes, and adds a Known issues section (3D playback blocks the setup test pattern; some picture modes are content-specific).

Full changelog: v2.3.0...v2.4.0

v2.3.0

Optoma Link 2.3.0

More device details, a smarter setup, and clearer docs, from a third round of UHZ68LV hardware testing.

Added

• The projector's MAC address now shows in the device's Connections, and its reported IP address is used for the device's "Visit" link.
• New diagnostic entities: IP Address and Projector ID.
• Software version now appears on the device card (as Firmware). It is no longer a separate sensor.

Changed

• Setup now warns you when the projector is in Eco standby, because in that mode it stops answering Power On commands over the network after a while powered off. The warning tells you how to switch it to Active.
• Setup checklist now starts with "turn the projector on", since it must be on during setup.
• The device name now defaults to "Projector" instead of the brand and model. Rename it to something like "Living Room Projector" and your entity IDs and voice commands stay short and readable.
• Clearer message when a 3D Format change is refused: turn on 3D first, and make sure the source is 1080p.

Docs

• The README now explains how local polling works, and why some write-only controls (like 3D and Light Source Power) read Unknown until you set them from Home Assistant.

v2.2.0

Optoma Link 2.2.0

A second round of fixes and features from real UHZ68LV hardware testing.

Fixed

• Model auto-detection now recognizes the UHZ68LV (it reads the Regulatory Model Name), so setup no longer falls back to picking the model by hand.
• System Temperature now reports correctly. It was querying the wrong command and showed Unknown.
• The device page now fills in Serial Number and Firmware once the projector reports them, instead of showing a placeholder.

Added

• Temperature Status sensor (Normal, Notice, Warning), handy for overheating alerts and automations.
• Resolution and Refresh Rate sensors, useful for automations such as adjusting screen masking by aspect ratio.
• Clearer messages when the projector refuses a command. For example, turning on 3D while the source is 4K now explains that 3D needs a 1080p source.

Changed

• Removed Wake-on-LAN. It did not wake the projectors we tested, so the button and the setup MAC address field are gone.
• Removed the 3D Active sensor, which this projector did not answer.
• Updated 3D icons: 3D Sync Invert now uses a glasses icon, and 3D Format uses a 3D video icon.

Notes

• The 3D and 3D Sync Invert controls appear as on/off action buttons rather than a single toggle. That is intentional: the projector gives no way to read back their state, so Home Assistant shows them as assumed-state controls.