Updating To Homebridge v2.0

For Users

Plugins

• What would happen if I update to Homebridge v2 and run a plugin that needs updating?
  • If you run the plugin in a child bridge, Homebridge will still load correctly. The plugin's child bridge process would likely continually restart as the error is created each time the plugin tries to load.
  • If you are not running the plugin in a child bridge, then the Homebridge process will likely continually crash and restart.
  • Note that in either case, the Homebridge UI would still be fully accessible to disable specific plugins if needed.
• Will plugins updated for Homebridge v2 still work with Homebridge v1?
  • Yes.
• Do all plugins need to be updated for Homebridge v2?
  • No, most plugins probably won't need any changes and will work properly. Just some plugins that make use of old functions will need updating.

Changes to Default Advertiser

• With Homebridge v2, avahi is now the default MDNSAdvertiser if available; otherwise, ciao will be used. If you experience any issues with no response devices, you can set your default advertiser back to Bonjour HAP in the Homebridge UI → Settings → mDNS Advertiser.
  • If you have already set a specific mDNS advertiser, this will continue to be used.
  • If you do not already have a specific mDNS advertiser set and wish to continue using Bonjour HAP, then you should use the Homebridge settings to choose this option before you update to Homebridge v2.

For Plugin Developers

HAP-NodeJS v1

You may need to change your plugins because of the breaking changes in HAP-NodeJS v1.

To see the complete set of changes between v0.12.3 and v1.0.0, see the version file differences.

• Common long-deprecated code patterns that may need updating:
  • BatteryService has been removed in favour of Battery
  • Use of enums off the Characteristic class is no longer supported:
    • Instead of const Units = Characteristic.Units; you will need to use const Units = api.hap.Units;
    • Instead of const Formats = Characteristic.Formats; you will need to use const Formats = api.hap.Formats;
    • Instead of const Perms = Characteristic.Perms; you will need to use const Perms = api.hap.Perms;
  • Characteristic.getValue() has been removed in favour of Characteristic.value
  • Accessory.getServiceByUUIDAndSubType() has been removed: you can swap this for Accessory.getServiceById()
  • Accessory.updateReachability() has been removed: reachability in general is no longer supported
  • Accessory.setPrimaryService(Service) has been removed: use Service.setPrimaryService() instead
  • Remove the long-deprecated init().
  • Deprecate Core, BridgedCore and legacy Camera characteristics
    • For deprecated Core and BridgedCore see: https://github.com/homebridge/HAP-NodeJS/wiki/Deprecation-of-Core-and-BridgeCore
  • For deprecated storagePath switch to HAPStorage.setCustomStoragePath
  • For AudioCodec switch to AudioStreamingCodec
  • For VideoCodec switch to H264CodecParameters
  • For StreamAudioParams switch to AudioStreamingOptions
  • For StreamVideoParams switch to VideoStreamingOptions
  • For cameraSource switch to CameraController
  • Other deprecated code to highlight removed: useLegacyAdvertiser, AccessoryLoader
  • For Fix: Naming for Characteristic.ProgramMode has been corrected from PROGRAM_SCHEDULED_MANUAL_MODE_ to PROGRAM_SCHEDULED_MANUAL_MODE

Homebridge v2

You may need to change your plugins because of the breaking changes in Homebridge v2.

Once you have tested your plugin(s) function correctly on Homebridge v2, you can update your package.json's engines.homebridge value to show that your plugin is ready.

  "engines": {
    "homebridge": "^1.6.0 || ^2.0.0",
    "node": "^22.12.0 || ^24.0.0"
  },

Users will see a green tick in the readiness check in the UI once they have installed a version of your plugin with this in the engines.