Homebridge SmartRent

The most comprehensive SmartRent Homebridge integration to date, Homebridge Verified. Control your SmartRent devices with Apple Home: supporting 6 device types w/ real-time updates, battery monitoring, and advanced status reporting.

Supported Devices

Device	HomeKit Service	Capabilities
🔒 Locks	LockMechanism + Battery	Lock/unlock Battery level Low battery alerts Jam detection Auto-lock timer
🌡️ Thermostats	Thermostat + Fan	Mode control (heat/cool/auto/aux heat) Temperature Humidity Fan mode Real-time operating state
💧 Leak Sensors	LeakSensor + Battery	Leak detection Battery level Low battery alerts
🔍 Motion Sensors	MotionSensor	Motion detection Real-time updates
🔌 Switches	Switch	On/off control
💡 Dimmers	Lightbulb	On/off control Brightness control

All devices report online/offline status via the StatusActive characteristic.

Architecture

graph TD
    Home["🏠 Apple Home"]

    subgraph Homebridge
        platform["<b>SmartRentPlatform</b><br>DynamicPlatformPlugin"]
        accessories["<b>Accessories</b><br>Lock · Thermostat · Leak<br>Motion · Switch · Dimmer"]
    end

    subgraph SmartRent Cloud
        rest["<b>REST API</b><br>control.smartrent.com/api/v3"]
        ws["<b>WebSocket</b><br>Phoenix protocol<br>real-time state updates"]
        auth["<b>OAuth + TOTP</b><br>authentication/sessions"]
    end

    Home <-->|"HomeKit"| accessories
    platform --> accessories
    platform -->|"device discovery<br>state commands"| rest
    platform <-->|"heartbeat 30s<br>attribute events"| ws
    platform -->|"email/password<br>+ optional 2FA"| auth
    auth --> rest
    auth --> ws

Loading

Features

• Real-time updates — WebSocket connection with Phoenix heartbeat for instant state changes across all devices
• 6 device types — Locks, thermostats, leak sensors, motion sensors, switches, and dimmers
• Accurate HVAC status — Uses the thermostat's actual operating state (heating/cooling/idle), not just the target mode
• Lock jam detection — Detects and reports lock jams via SmartRent notification events
• Battery monitoring — Battery level and low-battery alerts for locks and leak sensors
• Device online/offline status — Reports device reachability for all device types
• Two-factor authentication — Full TOTP support for secured SmartRent accounts
• Auto-lock — Configurable timer to automatically re-lock after unlocking
• Per-device toggles — Enable or disable any device type independently via config

Installation

Install Homebridge, add it to Apple Home, then install and configure Homebridge SmartRent.

Recommended

1. Open the Homebridge UI.

2. Open the Plugins tab, search for homebridge-smartrent, and install the plugin.

3. Log in to SmartRent through the settings panel, and optionally set your unit name.

Manual

1. Install the plugin using NPM:

   npm i -g @jackietreeh0rn/homebridge-smartrent

2. Configure the SmartRent platform in ~/.homebridge/config.json as shown in config.example.json.

3. Start Homebridge:

   homebridge -D

Configuration

Property	Type	Default	Description
email	string	required	SmartRent account email
password	string	required	SmartRent account password
tfaSecret	string		32-character TOTP seed for two-factor authentication
unitName	string		Unit name — only needed if you have multiple units. Find it in the SmartRent app under the More tab.
enableLocks	boolean	true	Enable lock accessories
enableThermostats	boolean	true	Enable thermostat accessories
enableLeakSensors	boolean	true	Enable leak sensor accessories
enableMotionSensors	boolean	true	Enable motion sensor accessories
enableSwitches	boolean	true	Enable switch accessories
enableSwitchMultiLevels	boolean	true	Enable dimmer/multilevel switch accessories
enableAutoLock	boolean	false	Automatically re-lock after unlocking
autoLockDelayInMinutes	integer	5	Minutes to wait before auto-locking
excludeDevices	array		List of SmartRent device IDs to exclude from HomeKit. Device IDs are shown in logs at startup.
lowBatteryThreshold	integer	20	Battery percentage at or below which devices report low battery status (5–50)
temperatureUnit	string	fahrenheit	Temperature display unit for thermostats (fahrenheit or celsius)
verboseLogging	boolean	false	Enable verbose debug logging for troubleshooting

Development

Prerequisites

• Node.js 22.10.0+ or 24.0.0+
• Homebridge 1.8.0+ or 2.0.0-beta+

Setup

npm install
npm run build
npm link

Watch Mode

Automatically recompiles and restarts Homebridge on source changes:

npm run watch

This runs a local Homebridge instance in debug mode using the config at ./test/hbConfig/. Stop any other Homebridge instances first to avoid port conflicts. The watch behavior can be adjusted in nodemon.json.

Linting & Formatting

npm run lint        # check for lint errors
npm run lint:fix    # auto-fix lint errors
npm run prettier    # check formatting
npm run format      # auto-fix formatting

Commits must follow Conventional Commits — enforced by pre-commit hooks via commitlint and husky.

Dependency Updates

Dependabot opens grouped pull requests weekly, configured in .github/dependabot.yml. Production and development dependencies are each split into a minor/patch group and a major group. The Dependabot Auto Merge workflow enables auto-merge on patch and minor updates, so they land on their own once CI passes. Major updates stay open for manual review. Production updates are committed as fix(deps), so merging one cuts a patch release; development updates are committed as chore(deps-dev) and do not release. Auto-merge is enabled with a token minted per run from the bitwise-ci GitHub App rather than the workflow's own GITHUB_TOKEN: merges made with GITHUB_TOKEN do not trigger push workflows, so the merged commit would land on main without Build or Release running.

prettier is excluded from the development group. A Prettier minor can change formatting output, which fails the formatting check and would hold up every other update in the group. It gets its own pull request and usually needs an npm run format commit before it merges.

Dependabot only tracks direct dependencies. Advisories against transitive packages, including ones bundled inside another package's tarball (for example npm, pulled in by @semantic-release/npm), show up as alerts without a pull request. Resolve those by raising the matching floor in the overrides block of package.json and regenerating the lockfile:

npm install --package-lock-only
npm audit --omit=dev

npm audit --omit=dev only covers production dependencies, so a clean result can coexist with open development-scope alerts. Check the repository's Dependabot alerts page for those.

Releases

Every push to main runs semantic-release with the conventionalcommits preset. feat commits cut a minor release, fix and perf a patch, and a BREAKING CHANGE footer a major. Other types (docs, chore, ci, build, style, refactor, test) do not release. Each release updates CHANGELOG.md, tags the commit, publishes to npm, and creates a GitHub release.

Publishing requires NPM_TOKEN, a valid npm automation token, plus the CI_APP_ID and CI_APP_PRIVATE_KEY secrets of the bitwise-ci GitHub App. The Release workflow mints a short-lived App token with contents and pull-requests write access that semantic-release uses to push the changelog commit and tag and to create the GitHub release; the App is a bypass actor on the main ruleset, so that push is allowed. The Dependabot auto-merge workflow mints its token the same way. If the Release workflow fails with EINVALIDNPMTOKEN, generate a new npm token, update the secret, and re-run the failed job. EINVALIDGHTOKEN points at the App: check that it is still installed on the repository and that CI_APP_PRIVATE_KEY matches a current key. A run that stops with "local branch main is behind the remote one" published nothing; it happens when another commit reaches main mid-run, and the next successful run picks up every unreleased commit.

Troubleshooting

If you run into issues, check the Homebridge troubleshooting wiki first. If the problem persists, open an issue with as much detail as possible.

Contributing

See CONTRIBUTING.md for guidelines on bug reports, feature requests, and code contributions.

Useful Resources

Read the full write-up: Homebridge SmartRent & Blink — an architectural deep-dive into how both plugins map their respective APIs into HomeKit (HAP service composition, IMMI streaming, OAuth/2FA, motion polling).

• Homebridge Developer Documentation
• Apple HomeKit Documentation

License

GNU GENERAL PUBLIC LICENSE, Version 3

Disclaimer

This project is not endorsed by, directly affiliated with, maintained, authorized, or sponsored by SmartRent Technologies, Inc or Apple Inc. All product and company names are the registered trademarks of their original owners. The use of any trade name or trademark is for identification and reference purposes only and does not imply any association with the trademark holder of their product brand.