A Homebridge plugin for checking updates to Homebridge, Homebridge UI, plugins, and Docker images. Works in both classic HomeKit (HAP) and Homebridge Matter mode.

1. Install Homebridge using the official instructions.
2. Install this plugin using: sudo npm install -g homebridge-plugin-update-check.
3. Update your configuration file. See sample config.json snippet below.

This plugin automatically selects the appropriate platform implementation at runtime:

• HAP mode (classic HomeKit): exposes a HomeKit sensor and updates its characteristic
• Matter mode: registers a Matter accessory with the appropriate device type and cluster(s)

No configuration change is required. When Homebridge runs in Matter mode, the Matter platform is used; otherwise, the HAP platform is used.

Supported sensorType values map to HAP services and Matter device types:

• motion (default) → HAP MotionSensor / Matter MotionSensor with occupancySensing
• contact → HAP ContactSensor / Matter ContactSensor (BooleanState)
• occupancy → HAP OccupancySensor / Matter MotionSensor with occupancySensing
• smoke → HAP SmokeSensor / Matter SmokeSensor (smokeCoAlarm)
• leak → HAP LeakSensor / Matter LeakSensor (BooleanState)
• light, humidity, air, dioxide, monoxide → HAP-only services (Matter defaults to motion)

Update checks run hourly (at 5 minutes past) and once shortly after startup; a daily “first run” elevates logs to Info level for visibility.

Configuration sample:

{
  "platforms": [
    {
      "name": "PluginUpdate",
      "sensorType": "contact",
      "checkHomebridgeUpdates": false,
      "checkHomebridgeUIUpdates": false,
      "checkPluginUpdates": true,
      "checkDockerUpdates": true,
      "autoUpdateHomebridge": false,
      "autoUpdateHomebridgeUI": false,
      "autoUpdatePlugins": false,
      "allowDirectNpmUpdates": false,
      "autoRestartAfterUpdates": false,
      "failureSensorType": "motion",
      "platform": "PluginUpdate"
    }
  ]
}

• "platform": Must always be "PluginUpdate" (required)
• "sensorType": What type of sensor will be exposed. Can be motion, contact, occupancy, humidity, light, air, leak, smoke, dioxide, or monoxide (Default: motion). Note: in Matter mode, unsupported types default to motion.
• "logging": Controls plugin logging verbosity. One of debug, standard (default), or none. Applies to both HAP and Matter. In standard, debug logs are suppressed; in none, all logs are suppressed.
• "checkHomebridgeUpdates": Check if an update is available for the Homebridge server
• "checkHomebridgeUIUpdates": Check if an update is available for the Homebridge UI
• "checkPluginUpdates": Check if updates are available for any installed plugins
• "checkDockerUpdates": If running in Docker, check if newer Docker versions are available. If not running in Docker, does nothing
• "respectDisabledPlugins": When enabled, respects the "Hide update notifications for this plugin" setting from homebridge-config-ui-x. Plugins marked to hide updates will not trigger notifications (applies to both HAP and Matter).

Homebridge, Homebridge UI, plugin, and Docker updates can be selected independently. This allows you for example, to ignore available Homebridge, Homebridge UI available updates if you are running Homebridge in a Docker container and wish to only update these components when a new Docker image is available.

The following options apply only when running in HAP mode (classic HomeKit). They are ignored in Matter mode:

• "autoUpdateHomebridge"
• "autoUpdateHomebridgeUI"
• "autoUpdatePlugins"
• "allowDirectNpmUpdates"
• "autoRestartAfterUpdates"
• "failureSensorType"

Note on Automatic Updates (HAP mode): When automatic updates are enabled, the plugin will:

1. Automatically create a backup before performing any updates (when homebridge-config-ui-x is available)
2. Attempt to install updates via npm commands. This requires:
   • homebridge-config-ui-x to be installed and properly configured (unless allowDirectNpmUpdates is enabled)
   • Sufficient privileges to install global npm packages
3. Automatically restart Homebridge after successful updates (when autoRestartAfterUpdates is enabled)
4. Monitor for failures and provide notifications via a configurable failure sensor (type set by failureSensorType)

Automatic updates are disabled by default for safety. Enable them only if you trust automatic updates. The plugin will automatically create a backup before any updates are performed when homebridge-config-ui-x is available, eliminating the need for manual backup procedures. However, you should still maintain your own backup procedures as a best practice.

Note on Docker Updates: Docker container updates are intentionally not supported via automatic updates for safety reasons. This is because the process performing the update would be running inside the container itself, which would result in the process killing itself halfway through the update, potentially corrupting the container or leaving it in an unusable state.

When allowDirectNpmUpdates is enabled, automatic updates will work even when homebridge-config-ui-x is not available by using direct npm commands. This provides more flexibility but requires ensuring you have the necessary npm privileges.

If you prefer not to allow direct npm updates, this plugin can trigger updates through Homebridge UI (homebridge-config-ui-x) when the Trigger Update API is available.

• Requires homebridge-config-ui-x v5.9.1-beta or later
• Endpoint used: POST /plugins/trigger-update with Bearer authentication
• Behavior: the UI queues updates in the background; this plugin can optionally restart Homebridge after updates if autoRestartAfterUpdates is enabled
• If the endpoint is not available, the plugin will log a warning and skip UI-based updates unless allowDirectNpmUpdates is true

• Build: npm run build
• Lint: npm run lint
• Tests: npx vitest run
• Full docs: npm run prepublishOnly