Troubleshooting & Diagnostic Procedures

Diagnostic workflows, service action error lookup tables, Terms of Use PIN fixes, and standalone CLI testing tools.

Quick Diagnostic Flow
  1. Check TV Network State: Is the TV in deep eco-sleep or can it be reached on your LAN? (VIDAA TVs disable network chips in deep standby unless Fast Power On / Network Wake is enabled).
  2. Inspect Home Assistant Repairs: If session tokens were invalidated, an alert will appear in Settings → Repairs.
  3. Toggle Debug Logging: Flip switch.<tv_name>_debug_logging to stream raw MQTT frames directly into Settings → System → Logs.

⚠️ Service Action Error Reference

Error Message Root Cause Resolution
Failed to send key {key}: {error} TV is disconnected in deep sleep or invalid key name passed. Wake the TV with WoL first, or verify key name matches standard aliases (e.g. home, menu, back, ok).
Channel digits must contain numbers only vidaa.change_channel received non-numeric characters. Provide only integer digits or dot-separated channel numbers (e.g. 10, 70, 7.1).
Failed to send channel confirmation key TV did not acknowledge the trailing confirmation key. Increase digit_delay in the service call (e.g. digit_delay: 0.5) to allow slower TV tuners to buffer digits.
Failed to launch app {app_name} App is not installed on this TV, or TV OS rejected launch payload. Verify app is installed and visible in the native app launcher. Check source_list on media_player.<tv_name> for exact names.
Failed to set picture setting Picture preset value out of range or not supported on this model. Use built-in UI selects (select.<tv_name>_picture_mode) to test supported presets.
Failed to set sound setting Sound mode locked or ARC / eARC soundbar is controlling audio presets. If external AV receiver / soundbar is connected over eARC, TV audio equalizer presets are managed by the soundbar.
Failed to send text input On-screen keyboard dialog or search bar is not active. Ensure an active text input search bar is open on screen (e.g. in YouTube search or browser) before calling vidaa.send_text_input.

📺 Issue 1: 4-Digit PIN Dialog Does Not Appear on Screen

If you enter your TV's IP address in Home Assistant but no 4-digit code appears on your television display:

Vendor Terms of Use & Smart Services Not Accepted

VIDAA OS suppresses on-screen pairing PIN popups if Smart / Connected Services are disabled. To resolve:

  1. On your physical TV remote, press Settings (Gear).
  2. Navigate to Support (or System) → Terms & Conditions (or Connected Services).
  3. Accept the terms of service and ensure connected smart features are turned ON.
  4. Retry pairing in Home Assistant—the 4-digit PIN dialog will pop up instantly!

(Privacy Note: Once pairing is completed, you can safely block internet/WAN access at your router firewall; local Home Assistant control operates completely offline).

💤 Issue 2: TV Shows "Unavailable" When Powered Off

VIDAA televisions shut down their main motherboard and Wi-Fi chip in deep standby to satisfy EU ≤ 0.5W eco regulations. The entity will report unavailable because no TCP connection can be maintained while the hardware is powered down.

⚡ Solution A: Enable Fast Power On

Go to Settings → System → Advanced Settings → Fast Power On → ON.
The TV SoC remains in a low-power listening state, waking instantly over local MQTT.

📡 Solution B: Configure Wake-on-LAN

1. In TV menu: Settings → Network → Wake on LAN / Mobile App Turn On → ON.
2. In Home Assistant: Configure → Enable Wake-on-LAN with burst count 3–5.

🧪 Standalone CLI Diagnostic Tools

The integration includes two standalone Python diagnostic scripts inside the repository's scripts/ folder. You can run these from any machine without starting Home Assistant:

1. test_client.py: Non-Invasive Network & Handshake Probe

Tests network reachability, verifies mutual TLS certificates, and inspects UPnP service descriptors:

BASH
python3 scripts/test_client.py --host 192.168.1.50 --cert /config/ssl/client_mobile_android.p12

2. debug_tv.py: Live MQTT Payload Monitor

Monitors raw state changes, dumps installed TV app IDs, and outputs pre-formatted Markdown blocks for reporting issues on GitHub:

BASH
python3 scripts/debug_tv.py --host 192.168.1.50 --apps --report