Install Homebridge on macOS

Kaan edited this page Jul 15, 2018 · 45 revisions

Note: This document is a work in progress, and users are encouraged to improve and update.

Installation and configuration steps

1) Install Xcode

  1. Open the App Store on your macOS device, and install Xcode.
  2. Open Xcode once, then quit the application.

2) Install homebrew — a package manager for macOS — by opening terminal and running the following command:

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Note: If you have issues getting Command Line Tools installed you can resolve it by downloading the package directly. This site has a great guide http://railsapps.github.io/xcode-command-line-tools.html

3) Install Node via homebrew by opening terminal and running the following command:

brew install node

Note: By installing Node via homebrew, you will not need superuser (sudo) permissions when installing Homebridge and Homebridge plugins.

4) Install Homebridge

  • Open terminal, and run the following command to install Homebridge globally:

    • npm -g install homebridge (macOS Sierra and earlier)
    • npm -g install homebridge --unsafe-perm (macOS High Sierra)

If installation proceeds without error, go to step 5.

Installation errors

MDNS install script error

After installing both xcode and nodejs, you may receive the following error message when using the above npm install command:

ERR! node-gyp rebuild","Failed at the mdns@2.3.3 install script.

To correct this error:

  1. Open Xcode.
  2. From the Xcode menu, navigate to Open developer tool > More developer tools
  3. Login to the Apple Developer website with your Apple ID.
  4. Once logged in, download and install the Xcode command line tools for your macOS version.
  5. Reboot.
  6. With Terminal open, re-run the command to install Homebridge.

MDNS install script error instructions for High Sierra Users

In addition to completing the steps above, High Sierra users need to add --unsafe-perm onto the end of the command line instruction for installing Homebridge, to overcome the MDNS install script error.

  • For the avoidance of doubt, High Sierra users must use the following command for installation:

    • npm -g install homebridge --unsafe-perm

For more information, see https://github.com/nfarina/homebridge/issues/1628.

If installing as root

WARNING: Be aware that enabling and using the root account can be dangerous to your operating system, and may require a full erase and install to undo any changes made as the root user.

NOTE: Installation of Homebridge as the root user is not needed. You can safely install and run Homebridge as any normal user of the machine. If Node has been installed using homebrew, using sudo in any terminal commands to invoke elevated privileges should only be required when adjusting launchd permissions (below).

By default, macOS does not enable the root account. To enable the root user, see https://support.apple.com/en-ca/HT204012.

5) Install Homebridge plugins

  • Install the relevant Homebridge plugins globally, using the following terminal command:

    • npm -g install [name of plugin]

To find a list of available plugins, and the information needed for each within the config.json file, go to: https://www.npmjs.com/search?q=homebridge

6) Create the config file

  • Enter the following command: nano /Users/YourUsername/.homebridge/config.json
    • be sure to change the YourUserName to your particular username
  • Paste in the content of the sample config-sample.json
  • Delete the entitreity of line 5 (the port number) to avoid any issues with your particular setup.
  • Modify the username
  • Modify the PIN
  • Type ^X then Y then ENTER to save your changes.

Refer to the Homebridge Readme for additional instructions on where this file should be located and how to edit it.

Note: If you've created config.json in the wrong location, the correct location will be displayed when you first run Homebridge (see below).

Running Homebridge

Run Homebridge for the first time

From terminal, run the following command to make sure everything is set up correctly:

homebridge

If Homebridge runs successfully, you should be able to pair it using the displayed instructions using the Home app on your supported iOS device.

Starting Homebridge automatically with launchd

  1. Create a launchd plist file for Homebridge in ~/Library/LaunchAgents:

    • nano ~/Library/LaunchAgents/com.homebridge.server.plist
  2. Edit the plist file you just created, adding the following content:

Note: Ensure that you update the username portion of the path with your username, shown in the String values for the Key StandardOutPath, StandardErrorPath, and HOME.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>RunAtLoad</key>
        <true/>
    <key>KeepAlive</key>
        <true/>
    <key>Label</key>
        <string>com.homebridge.server</string>
    <key>ProgramArguments</key>
        <array>
             <string>/usr/local/bin/homebridge</string>
             <string>-I</string>
        </array>
    <key>StandardOutPath</key>
        <string>/Users/username/.homebridge/logfile.log</string>
    <key>StandardErrorPath</key>
        <string>/Users/username/.homebridge/logfile.log</string>
    <key>EnvironmentVariables</key>
        <dict>
        <key>PATH</key>
            <string>/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
        <key>HOME</key>
            <string>/Users/username</string>
        </dict>
</dict>
</plist>
  1. Permissions must be correct on ~/Library/LaunchAgents folder and the ~/Library/LaunchAgents/com.homebridge.server.plist file.

    • sudo chown $(whoami) ~/Library/LaunchAgents
    • sudo chown $(whoami) ~/Library/LaunchAgents/com.homebridge.server.plist
    • sudo chmod 700 ~/Library/LaunchAgents
    • sudo chmod 600 ~/Library/LaunchAgents/com.homebridge.server.plist
  2. Reboot your computer. Homebridge will now start automatically at boot and will restart if it crashes.

  • Run the following in a terminal to manually start Homebridge background process:

    • launchctl load ~/Library/LaunchAgents/com.homebridge.server.plist
  • Run the following in a terminal to manually stop homebridge background process:

    • launchctl unload ~/Library/LaunchAgents/com.homebridge.server.plist
  • Combine the two commands in a terminal to restart homebridge background process (Handy if using homebridge-server or homebridge-config-ui to manage your Homebridge instance via a web interface):

    • launchctl unload ~/Library/LaunchAgents/com.homebridge.server.plist && launchctl load ~/Library/LaunchAgents/com.homebridge.server.plist

Maintenance

Updating Homebridge and plugins

Periodically, Homebridge and its plugins may be updated. To see if there are any updates you can run the following command to see what is available:

npm -g outdated

To update a particular plugin or Homebridge itself, run:

sudo npm -g update [homebridge | name-of-plugin]

To force an update, you can re-install it to force the latest version:

sudo npm -g install [homebridge | name-of-plugin]

Troubleshooting

You see the error "throw new Error("The requested platform '" + name + "' was not registered by any plugin." on first load

This means that one (or more) of the homebridge platforms or accessories called by your config.json file hasn't been installed.

Check the packages you have installed by running the following command: npm list -g --depth=0

Compare this against your config.json to ensure all your relevant packages are installed.

Once you've identified the missing package, return to Step 5 above to install the missing package.

Creating and viewing logfiles

If you used launchd to run Homebridge (as described above), then the log files for your Homebridge installation will be available at:

/Users/username/.homebridge/logfile.log

Note: Replace username with the username which Homebridge is running under.

To view the log file, load it using your preferred viewer. From Terminal - you can run the following command to view the log file as it is updated:

tail -f ~/.homebridge/logfile.log

iOS Home app showing Updating...

Often, you may find that when loading the iOS Home app, the devices exposed using homebridge will show the status of Updating... for a long period of time.

To overcome this, using Terminal, run the following command to prevent the computer homebridge is installed on from going to sleep:

sudo systemsetup -setcomputersleep Never

Uninstalling

If you need to uninstall Homebridge, ensure the Homebridge server is first stopped - either by:

  1. If started from the terminal window, pressing Command + C to quit the process, OR
  2. If started using launchd, running the following command: launchctl unload ~/Library/LaunchAgents/com.homebridge.server.plist

Once Homebridge is stopped, run:

npm uninstall -g homebridge

Note: This may not remove configuration files, or logs, and the user may need to remove these manually.

Removing platforms required for Homebridge

NPM

For information on removing NPM, see: https://docs.npmjs.com/misc/removing-npm

Node.JS

You may need to do some research to work out how to uninstall this if you need to.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.