Homebridge Philips Ambilight TV

A Homebridge plugin to control Philips Android TVs with Ambilight as HomeKit Television accessories.

Originally based on homebridge-philips-tv-ambilight by Konrad Knitter, licensed under the Apache License 2.0. This fork has been substantially rewritten by MP Consulting.

Features

• Power ON/OFF with Wake-on-LAN support
• Input source selection (HDMI, TV tuner, apps)
• Dynamic app discovery — automatically finds all installed apps on the TV
• Volume control and mute
• Remote control (D-Pad, Back, Menu, Play/Pause, etc.)
• Ambilight color control with brightness, color picker, and Adaptive Lighting
• Long-poll state detection — near-instant updates when TV state changes, with interval polling fallback
• State sensors — optional MotionSensor services for power, ambilight, and mute (for HomeKit automations)
• Multi-TV support
• Custom UI for easy setup and configuration

Ambilight Control

The Ambilight appears as a color lightbulb in HomeKit with:

• On/Off toggle - Turn Ambilight on or off
• Brightness slider - Control light intensity (0-100%)
• Color wheel - Pick any color using the HSB color picker
• Adaptive Lighting - Color temperature adjusts automatically throughout the day
• Color temperature slider - Manual control from 140 mireds (cool) to 500 mireds (warm)

When you select a color in HomeKit, the TV switches to "Follow Color" mode with your chosen color. The plugin also syncs the current color state from the TV back to HomeKit.

State Sensors

You can enable optional MotionSensor services that expose TV state for HomeKit automations:

{
  "stateSensors": ["power", "ambilight", "mute"]
}

Each sensor appears as a MotionSensor — "motion detected" means the state is active (TV on, ambilight on, or muted). This allows creating automations like "When TV turns on, turn on the lights".

Requirements

• Philips Android TV with JointSpace API v6 (2016+ models)
• TV and Homebridge on the same network
• Node.js 20.18.0 or later

Installation

Via Homebridge UI (Recommended)

1. Open the Homebridge UI
2. Go to the Plugins tab
3. Search for "homebridge-philips-ambilight-tv"
4. Click Install

Via Command Line

npm install -g homebridge-philips-ambilight-tv

Setup

Using the Custom UI (Recommended)

1. Open the Homebridge UI and go to the plugin settings
2. Click "Discover TVs" to find your TV on the network
3. Select your TV and follow the pairing wizard
4. Enter the PIN displayed on your TV screen
5. Customize sources and save

Manual Configuration

Add the following to your config.json:

{
  "platforms": [
    {
      "platform": "PhilipsAmbilightTV",
      "devices": [
        {
          "name": "Living Room TV",
          "ip": "192.168.1.10",
          "mac": "AA:BB:CC:DD:EE:FF",
          "username": "your_device_id",
          "password": "your_auth_key"
        }
      ]
    }
  ]
}

Configuration Options

| Key | Description | Required | | --- | --- | --- | | platform | Must be PhilipsAmbilightTV | Yes | | devices | Array of TV configurations | Yes | | devices[].name | Display name for the TV | Yes | | devices[].ip | IP address of your TV | Yes | | devices[].mac | MAC address (for Wake-on-LAN) | Yes | | devices[].username | Device ID from pairing | Yes | | devices[].password | Auth key from pairing | Yes | | devices[].sources | Custom source configuration | No | | devices[].ambilightMode | Ambilight mode on turn-on (e.g. "FOLLOW_VIDEO/NATURAL") | No | | devices[].stateSensors | Array of state sensors: "power", "ambilight", "mute" | No | | devices[].pollingInterval | Polling interval in ms (1000-60000, default: 10000) | No |

Getting Credentials

The username and password are obtained during the pairing process:

1. Use the plugin's custom UI to pair (recommended)
2. Or use the TV's built-in pairing API:
   • Send a pairing request to https://<TV_IP>:1926/6/pair/request
   • Complete the pairing with the PIN shown on TV
   • The response contains your credentials

Editing Sources

The plugin supports customizing which sources appear in HomeKit:

1. Go to the plugin settings in Homebridge UI
2. Click "Edit Sources" on your configured TV
3. Drag and drop to reorder sources
4. Toggle visibility for each source
5. Click "Done" to save

The plugin supports up to 30 input sources (5 static + 25 apps).

Troubleshooting

TV not discovered

• Ensure the TV is powered on (not in standby)
• Check that TV and Homebridge are on the same network/VLAN
• Try entering the IP address manually

Pairing fails

• Make sure no other device is pairing simultaneously
• Try restarting the TV
• Check the TV's network settings

TV not responding

• Verify the TV's IP hasn't changed (consider a static IP)
• Check if Wake-on-LAN is enabled in TV settings
• Ensure the TV's API is accessible (port 1926)

"Write handler didn't respond at all" warnings

If you see these warnings in the Homebridge logs, make sure you are running v1.0.4 or later. Earlier versions used a 15-second API timeout that exceeded Homebridge's handler deadline, causing the plugin to slow down the entire instance when the TV was unreachable.

Debug logging

Run Homebridge with the -D flag to enable debug mode. The plugin logs state changes as they happen:

[Living Room TV] Power: On
[Living Room TV] Volume: 17
[Living Room TV] Ambilight: FOLLOW_VIDEO (STANDARD)
[Living Room TV] Active app: com.netflix.ninja

POST requests (user actions) are always logged. GET polling is silent unless a state change is detected.

Input sources not updating in Home app

This is a known tvOS 18 bug. The plugin includes a workaround that may require removing and re-adding the TV in the Home app.

Development

# Clone the repository
git clone https://github.com/mp-consulting/homebridge-philips-ambilight-tv.git

# Install dependencies
npm install

# Build
npm run build

# Run with test config
npm start

# Test TV endpoints
npm run test:tv

License

This project is derived from homebridge-philips-tv-ambilight by Konrad Knitter, which is licensed under the Apache License 2.0. Modifications and new code are licensed under the MIT License. See the LICENSE file for full details.

Credits

• Homebridge
• Philips JointSpace API documentation