Skip to content

4. Troubleshooting

Jump to bottom
Mike Kormendy edited this page Apr 3, 2024 · 2 revisions

This is a DIY/hobbiest project and as such, it requires quite a bit of self-guided learning and trial and error. You will need to employ quite a bit of determination and critical analysis to get this up and running. Google is your friend. Support is not guaranteed.

"Did You Try Rebooting It?"

Sometimes fixing a problematic Homebridge/HOOBS/HomeKit accessory is as simple as deleting Homebridge's cachedAccessories file.

  1. First stop Homebridge/HOOBS.

  2. Delete the cachedAccessories file which is commonly located in its respective folder:

    • Homebridge:
      • Linux-based/MacOS: ~/.homebridge/accessories/cachedAccessories
      • Windows: $HOME\.homebridge\Accessories\cachedAccessories
    • HOOBS:
      • HOOBSBox/Linux-based/MacOS:
      • v3.x: ~/.hoobs/etc/accessories/cachedAccessories
      • v4.x: /var/lib/hoobs/accessories/cachedAccessories
      • Windows (HOOBS does not work on Windows)

  3. Once the file is deleted, start up Homebridge/HOOBS and allow it to regenerate your accessories and the cache.

WARNING: Be careful to not delete the persist folder or its contents! Your Homebridge and devices will become unresponsive and you will have to completely re-pair the Homebridge bridge (remove and re-scan the QR-code for Homebridge and set up all of your accessories/devices again).

"I only see an alarm tile with on or off states and not Home, Night or Away"

This means a couple things. First and foremost, to enable those alarm modes you need to assign a the triggerable modes of a zone to activate those features. Those settings are configured under the Panel > Zone > Switch Settings > Triggerable Modes.

The second reason why you might not be seeing this is that your HomeKit hub hasn't pushed them to your device yet. This can happen for two more sub-reasons: 1. because you haven't set your user up on HomeKit to be an "Owner" or "Admin", or two you haven't waited long enough for the configuration to update and apply across the HomeKit hub Home apps. I've witnessed this take upward of 5 mins in some cases.

Missing/Stale Accessories

Sometimes you may need to reboot Homebridge once-more after changes made to the configuration for the zone accessories to show up the first time or to reflect the changes and work properly in HomeKit. This is partially because this Homebridge plugin uses a cache to keep it performant and needs to rebuild it once on launch, and then read from it on second launch to update the accessories in HomeKit.

Also it's always good to restart the HomeKit app after changes made to the Homebridge configuration as HomeKit does some background cleanup to the states and presence of devices in its accessory database.

Check the Forums & Repository Issues

Before anything, please review the Konnected Homebridge Forum (deprecated) GitHub Homebridge Konnected Discussions Forum to see if there's already a similar issue reported where a solution has been proposed.

You can also search the repository issues solutions as well.

Please don't not hijack another person's posted issue with your own issues with the plugin, INSTEAD create a new issue.

If you cannot resolve the issue based on any resolutions in the forums, please create an issue on my personal GitHub repository with the following details:

  • Describe the Bug
  • Steps to Reproduce
  • Expected Behavior
  • Homebridge System:
    • Node.js Version
    • NPM Version
    • Homebridge/HOOBS Version
    • Operating System: (Raspbian / Ubuntu / Debian / Windows / macOS / Docker)
    • Process Supervisor: *(Docker / Systemd / init.d / pm2 / launchctl / hb-service / other / none)
  • Konnected Panel(s):
    • Panel Hardware Version
    • Firmware Version
    • Addon Panel(s)
    • Interface Panel(s)
  • Attach Files to Support Your Experience:
    • Screenshots of your Konnected App device settings screen
    • Debug Log (turn on debugging in Homebridge/HOOBS and copy the results into a text file starting from boot up to shortly after the where the issue occurs)
    • Homebridge/HOOBS config.json file and or plugin section from the config.json found in your .homebridge folder.
  • Any Additional Relevant Information

Check the Discord Channel:

Try checking the Homebridge Konnected channel on Discord. Sometimes troubleshooting a problem needs further real-time interaction and live chat can help. If you do visit Discord:

  • don't expect immediate responses as I am not on Discord on a regular basis
  • don't message the entire channel with personally identifiable secret information (DM me personally with those details, e.g., a log file, your config file, etc.)
Clone this wiki locally