<p align="center">
<img src="homebridge-ui/public/ambilight-tv.webp" width="300">
</p>

# 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](https://github.com/konradknitter/homebridge-philips-tv-ambilight) by [Konrad Knitter](https://github.com/konradknitter), licensed under the Apache License 2.0. This fork has been substantially rewritten by [MP Consulting](https://github.com/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**
- **Ambilight + Hue switch** — optional switch to toggle the Philips Hue integration independently
- **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.

### Ambilight + Hue

If your TV is paired with Philips Hue lamps, you can enable an extra switch that toggles the **Ambilight + Hue** integration (Hue lamps following Ambilight) independently of the main Ambilight controls:

```json
{
  "ambilightHueSwitch": true
}
```

This appears as a separate Switch accessory in HomeKit, usable in scenes and automations. It is backed by the TV's `/HueLamp/power` endpoint.

### Custom Apps

Some TVs don't report every installed app through their app list — sideloaded or region-specific apps (e.g. EON) can be missing, so they never appear as sources. You can add these manually, **in addition** to auto-discovered apps.

The easiest way is the config UI: edit a TV → **Apps** tab. Usually the **package name** is all you need — click **Add**.

You can also configure them directly:

```json
{
  "customApps": [
    { "name": "EON", "packageName": "com.ug.eon.android.tv" }
  ]
}
```

When no launch activity is given, the plugin launches `<packageName>.MainActivity` (the common Android convention, e.g. `com.netflix.ninja.MainActivity`), which works for most apps. Some apps use a different launcher (e.g. Prime Video is `com.amazon.ignition.IgnitionActivity`) — for those, set the exact **launch activity** (`className`) in the optional field, or capture it with **Detect from TV**.

> **Detect from TV** reads the app currently open on the TV and fills in its package name and exact launch activity. Make sure the app is in the foreground first — if the TV is on live TV or the home screen, it reports that system activity instead.

### State Sensors

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

```json
{
  "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

```bash
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`:

```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[].ambilightOnStart` | Automatically turn Ambilight on (in `ambilightMode`) when the TV powers on | No |
| `devices[].stateSensors` | Array of state sensors: `"power"`, `"ambilight"`, `"mute"` | No |
| `devices[].ambilightHueSwitch` | Expose the Ambilight + Hue integration as a separate switch | No |
| `devices[].customApps` | Apps the TV doesn't report (added on top of discovered apps); each has `name`, `packageName`, optional `className`/`action` | 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

```bash
# 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](https://github.com/konradknitter/homebridge-philips-tv-ambilight) by Konrad Knitter, which is licensed under the [Apache License 2.0](http://www.apache.org/licenses/LICENSE-2.0). Modifications and new code are licensed under the [MIT License](https://opensource.org/licenses/MIT). See the [LICENSE](LICENSE) file for full details.

## Credits

- [Homebridge](https://homebridge.io/)
- Philips JointSpace API documentation