homebridge-philips-tv-ambilight-extended

Enhanced Homebridge platform plugin for Philips Android TV with proper TV icon, Ambilight control, and extended features.

Features

• Clean TV interface with proper TV icon in HomeKit
• Full Ambilight control with multiple modes (Follow Video, Follow Audio, Lounge Light)
• Native TV speaker volume control
• Launch Netflix, YouTube, and other Android TV apps
• Switch between TV channels with presets
• Full remote control functionality
• Wake on LAN support for powering on TV remotely
• Multiple TV support from single platform
• Improved error handling and network timeout management
• Platform architecture for better stability

Installation

npm install -g homebridge-philips-tv-ambilight-extended

Or search for "philips tv ambilight extended" in Homebridge Config UI X.

TV Pairing

Before using this plugin, pair your TV to get API credentials.

Using pylips (recommended):

pip3 install pylips
python3 -m pylips --host YOUR_TV_IP pair

Using philips_android_tv:

git clone https://github.com/suborb/philips_android_tv
cd philips_android_tv
python ./philips.py --host YOUR_TV_IP pair

The pairing process provides apiUser and apiPass credentials for configuration.

Configuration

Add to your Homebridge config.json:

{
  "platforms": [
    {
      "platform": "PhilipsAndroidTV",
      "debug": false,
      "configVersion": 1,
      "tvs": [
        {
          "name": "Living Room TV",
          "ip": "192.168.1.100",
          "apiUser": "your_api_username",
          "apiPass": "your_api_password",
          "apiVersion": 6,
          "mac": "AA:BB:CC:DD:EE:FF",
          "wakeOnLanRequests": 3,
          "wakeOnLanTimeout": 1000,
          "wakeUntilAPIReadyCounter": 100,
          "alternativePlayPause": false,
          "dedicatedMuteSwitch": false,
          "dedicatedVolumeLightbulb": false,
          "has_ambilight": true,
          "apps": [
            "Netflix",
            "YouTube",
            "Amazon Prime",
            "Disney+"
          ],
          "channels": {
            "useFavorites": false,
            "favoriteListId": "1",
            "includeAll": false,
            "channels": [
              "BBC One",
              "CNN",
              "National Geographic"
            ]
          }
        }
      ]
    }
  ]
}

Configuration Options

Platform Options

| Option | Type | Required | Description | |--------|------|----------|-------------| | platform | string | ✅ | Must be "PhilipsAndroidTV" | | debug | boolean | ❌ | Enable debug logging (default: false) | | configVersion | number | ❌ | Config version for compatibility (default: 1) | | tvs | array | ✅ | Array of TV configurations |

TV Options

| Option | Type | Required | Description | |--------|------|----------|-------------| | name | string | ✅ | Display name for your TV | | ip | string | ✅ | TV's IP address | | apiUser | string | ✅ | API username from pairing | | apiPass | string | ✅ | API password from pairing | | apiVersion | number | ❌ | API version (default: 6) | | mac | string | ❌ | MAC address for Wake on LAN | | wakeOnLanRequests | number | ❌ | Number of WOL requests (default: 3) | | wakeOnLanTimeout | number | ❌ | Timeout between WOL requests in ms (default: 1000) | | wakeUntilAPIReadyCounter | number | ❌ | Connection retry attempts (default: 100) | | alternativePlayPause | boolean | ❌ | Use alternative play/pause (default: false) | | dedicatedMuteSwitch | boolean | ❌ | Create separate mute switch (default: false) | | dedicatedVolumeLightbulb | boolean | ❌ | Create separate volume lightbulb (default: false) | | has_ambilight | boolean | ❌ | Enable ambilight control (default: true) | | apps | array | ❌ | List of app names to show as inputs | | channels | object | ❌ | Channel configuration |

Channel Configuration

| Option | Type | Description | |--------|------|-------------| | useFavorites | boolean | Use TV's favorite channels list | | favoriteListId | string | ID of favorite list to use | | includeAll | boolean | Include all available channels | | channels | array | Manual list of channel names |

Supported Apps

The plugin maps these app names to their package names:

• Netflix → com.netflix.ninja
• YouTube → com.google.android.youtube.tv
• Amazon Prime → com.amazon.avod.thirdpartyclient
• Disney+ → com.disney.disneyplus
• Spotify → com.spotify.tv.android
• Plex → com.plexapp.android
• Kodi → org.xbmc.kodi
• VLC → org.videolan.vlc

HomeKit Interface

The plugin creates a TV accessory with:

• TV icon and power control
• Native TV speaker volume control
• Input selection for apps, channels, and Ambilight modes
• Remote control with navigation and media keys

Remote Control Keys

| HomeKit Button | TV Action | |---------------|-----------| | Play/Pause | PlayPause | | Up/Down/Left/Right | Navigation | | Select | Confirm | | Back | Back | | Exit | Exit | | Info | Info |

Wake on LAN

To enable Wake on LAN:

1. Enable WOL in TV network settings
2. Connect TV via Ethernet
3. Add TV MAC address to mac field in configuration

Multiple TVs

Control multiple TVs by adding them to the tvs array:

{
  "platforms": [
    {
      "platform": "PhilipsAndroidTV",
      "tvs": [
        {
          "name": "Living Room TV",
          "ip": "192.168.1.100",
          "apiUser": "user1",
          "apiPass": "pass1"
        },
        {
          "name": "Bedroom TV", 
          "ip": "192.168.1.101",
          "apiUser": "user2",
          "apiPass": "pass2"
        }
      ]
    }
  ]
}

Troubleshooting

TV not responding:

• Verify TV is on same network and IP is correct
• Check API credentials are valid
• Restart TV if needed
• Re-pair after TV software updates

Volume control issues:

• Ensure TV supports volume API
• Check for external speakers
• Verify TV is not muted

Ambilight not working:

• Confirm TV has Ambilight capability
• Enable Ambilight in TV settings
• Set has_ambilight: true in configuration

App launch failures:

• Verify app names match supported apps
• Check apps are installed on TV
• Ensure apps support intent launching

API Reference

Uses Philips JointSpace API v6. For advanced usage:

• Philips TV API Documentation
• JointSpace API Reference

Compatibility

• TV Models: Philips Android TV 2016+
• API Version: JointSpace API v6
• Homebridge: v1.0.0+
• Node.js: v14+

Changelog

v2.0.0

• Converted from accessory to platform plugin
• Multiple TV support
• Improved stability and error handling
• Better input source management
• Fixed Wake on LAN implementation
• Fixed Ambilight API endpoints
• Enhanced volume and mute state handling

Migration from v1.x

Update your configuration from accessory to platform format:

Old (v1.x):

{
  "accessories": [{
    "accessory": "PhilipsTV",
    "name": "TV",
    "ip_address": "192.168.1.100",
    "username": "user",
    "password": "pass"
  }]
}

New (v2.x):

{
  "platforms": [{
    "platform": "PhilipsAndroidTV",
    "tvs": [{
      "name": "TV",
      "ip": "192.168.1.100",
      "apiUser": "user",
      "apiPass": "pass"
    }]
  }]
}

Support

GitHub Issues

Credits

Based on work from:

• homebridge-philips-tv6
• homebridge-philips-android-tv
• pylips

License

Apache-2.0