FAQ

Frequently Asked Questions

Apple's Home app

Why does Home show a Not Supported tile?

Normally, Home shows a tile per supported HomeKit service. If an accessory doesn't expose any supported services, Home shows a Not Supported tile. Use another HomeKit app, like Eve to interact with the accessory.

How can I remove the Not Supported tile for the Hue bridge or deCONZ gateway?

You cannot, it is needed by Homebridge Hue. Use another HomeKit app, like Eve to interact with the bridge or gateway accessory.

How can I unset the Not Supported tile for the Hue bridge or deCONZ gateway as favourite?

Apple has removed the Favorite setting from unsupported accessories in iOS 14. Use Home on iOS 13 or on macOS Catalina to change the setting. If you don't have access to these, set linkButton in config.json, to have Homebridge Hue expose the Hue bridge or deCONZ gateway as dummy Stateless Programmable Switch, so Home supports it. You can then deselect the Favorite setting. The setting sticks if you later remove linkButton and once again expose the bridge or gateway as Not Supported accessory.

Why does Home show an exclamation point for my wireless switch?

Wireless switches require a home hub.

Why does Home show No Response on a tile?

The accessory returned an error response or didn't respond at all. See No Response for details. Unless you set noResponse, this is not caused by Homebridge Hue, but by connectivity issues between your iDevice and Homebridge.

To troubleshoot these connectivity issues:

• Force-quit and restart Home;
• Double-check that Homebridge is up and running;
• Try refreshing your screen, or switch between the Home and Rooms view;
• Double-check if you can access the accessory from another iDevice;
• Try switching the WiFi on your iDevice off and back on;
• Double-check (using netstat) that your iDevice has connected to Homebridge (there should be an incoming TCP session from your iDevice to the Homebridge port specified in config.json);
• Restart Homebridge.

Note that HomeKit needs to be able to find the accessories over Bonjour (multicast DNS) before it connects over HAP (HTTPS). Apple devices don't work well with routers, access points and switches that try to be smart and forward multicast traffic only to ports with devices subscribed to the multicast address. Be sure to turn off IGMP snooping on your routers, access points, and switches.

HomeKit

Why isn't my device state updated in HomeKit?

Probably because the deCONZ REST API hasn't properly setup binding and attribute reporting.

To troubleshoot these connectivity issues:

• Double-check in Phoscon, or in another REST API client like ph, that the API doesn't update the device state.
• Double-check in the deCONZ GUI that the device state is updated when manually reading the corresponding cluster attributes.
• Re-set and re-pair the device with deCONZ. Do not delete the device from the deCONZ REST API nor from the deCONZ GUI.
• Alternatively, manually setup the binding and attribute reporting configuration in the deCONZ GUI. See the User Manual under the Help menu for more info.

Why does my wireless switch not work in HomeKit even though the tile in the Home app bounces?

Your home hub isn't connected to Homebridge. Note that button actions are executed by the home hub, whereas bouncing the tile is executed locally on your iDevice.

To troubleshoot these connectivity issues:

• Double-check under Hubs & Bridges under the Home Settings in the Home app that the home hub shows as Connected;
• Double-check (using netstat) that the home hub has connected to Homebridge (there should be an incoming TCP session from the home hub to the Homebridge port specified in config.json);
• Restart (power cycle) the home hub;
• Restart Homebridge.

Note that your home hub needs to be able to find the accessories over Bonjour (multicast DNS) before it connects over HAP (HTTPS). Apple devices don't work well with routers, access points and switches that try to be smart and forward multicast traffic only to ports with devices subscribed to the multicast address. Be sure to turn off IGMP snooping on your routers, access points, and switches. Be sure to use the latest released software version for your Home hub. For reliability, best use for home hub an Apple TV connected over wired Ethernet.

Homebridge

How do I turn on Homebridge debug mode?

• In the Homebridge UI, turn on Homebridge Debug Mode -D under Homebridge Settings;
• In the Homebridge UI, press the Restart button.

How do I capture and download a debug log file?

• In the Homebridge UI, turn on Homebridge Debug Mode -D under Homebridge Settings;
• In the Homebridge UI, press the Restart button;
• Interact with HomeKit as you would normally, reproducing the issue;
• In the Homebridge UI, press Download Log File under View Logs.

How do I capture and download a debug log file, in a non-standard Homebridge installation?

• If you're running Homebridge as a service, stop that service;
• Run Homebridge manually, capturing the output into a file, by issuing:

  $ homebridge -CD 2>&1 | tee homebridge.log
  

• Interact with HomeKit as you would normally, reproducing the issue;
• Hit interrupt (ctrl-C) to stop Homebridge;
• If you're running Homebridge as a service, restart the service;
• Compress the log file by issuing:

  $ gzip homebridge.log
  

How do I run Homebridge Hue solo?

• In the Homebridge UI, select Plugins;
• For each of the other plugins, select Disable on the Configuration button on the plugin;
• Press the Restart button.

How do I run Homebridge Hue solo, in a non-standard Homebridge installation?

• Make a backup of your config.json;
• Edit config.json (using a text editor - not a document editor):
  • On the top-level object, add a "plugins": [ "homebridge-config-ui-x", "homebridge-hue" ],;
  • For each of the other plugins, remove the section for that plugin from the "platforms" or "accessories"` array;
• Restart Homebridge.

Homebridge Hue

How can I make Homebridge Hue not expose the accessory for the Hue bridge or deCONZ gateway?

You cannot, the accessory is needed by Homebridge Hue.

Why is my smart plug exposed as a Lightbulb?

By default, Homebridge Hue exposes /lights resources as Lightbulb. Too many Zigbee devices identify themselves wrongly, frustrating automated discovery of plugs vs lights. Create an outlet resource link to list the resources that should be exposed as Outlet instead of Lightbulb. See Resource Links for more info.

Why is Homebridge Hue exposing my wireless switch as Lightbulb?

It is not. You're probably seeing the /groups resource associated with the wireless switch. Double-check the value of the Resource characteristic in the Eve app to be sure.

Why is Homebridge Hue exposing a device I've never seen before?

You're probably seeing a virtual sensor (CLIP sensor) created by a Hue app or by Phoscon. Double-check the value of the Resource characteristic in the Eve app to be sure. Set excludeSensorTypes in config.json to prevent exposing CLIP sensors, see Configuration.

Why do I need to press the link button / unlock the gateway every time Homebridge restarts?

You need to edit config.json manually, entering the bridgeid and username (API key), see the README

How do I download the debug dump file?

• In the Homebridge UI, select Plugins;
• Press SETTINGS on the Homebridge Hue plugin;
• In the popup window, press DOWNLOAD DUMP FILE.

How do I download the debug dump file, in a non-standard Homebridge installation?

On startup, Homebridge Hue writes the file homebridge-hue.json.gz to the Homebridge user directory (~/.homebridge by default). This is the directory where you keep config.json. Homebridge Hue logs a message with the full path:

[Hue] masked debug info dumped to /var/lib/homebridge/homebridge-hue.json.gz

ph

I'm getting "ph: error: localhost: not a Hue bridge nor deCONZ gateway"?

You need to specify where ph can find the Hue bridge or deCONZ gateway, through ph -H hostname:port or by setting PH_HOST. See ph --help for more info.

Use ph discover to find you bridges and/or gateways.