Skip to content

Getting Started

Jump to bottom
oznu edited this page Mar 31, 2020 · 12 revisions

This guide provides step-by-step instructions to show you how to use the Homebridge Raspberry Pi Image to setup Homebridge on your device.

Prerequisites

Before getting started, make sure you have the following:

  • One of the supported Raspberry Pi Models
  • An 4GB or larger SD card (Class 10 40Mb/s or faster is recommended)
  • A Windows, macOS or Linux computer with an SD card reader

Step 1: Download

Downloading the Homebridge Raspberry Pi Image is completely free (no sign up required).

Download Latest Version

Step 2: Flash to SD Card

The easiest way to flash the Homebridge Raspberry Pi Image to your SD card is to use Etcher.

  1. Download and install the latest version of Etcher.
  2. Open Etcher and select the Homebridge-Raspbian-v0.0.0.zip file you have downloaded. There is no need to extract the .zip file first.
  3. Choose the drive your SD card has been inserted into.
  4. Click Flash.

Step 3: Connect To Network

Ethernet

If you have decided to connect your Raspberry Pi using ethernet, do so before you power on your device for the first time.

No additional configuration is required to connect.

WiFi

Follow these steps to connect your device to WiFi:

  1. Power on your device without an Ethernet cable attached.
  2. Wait 1-2 minutes
  3. Use your mobile phone to scan for new WiFi networks
  4. Connect to the hotspot named Homebridge WiFi Setup
  5. Wait a few moments until the captive portal opens, this portal will allow you to connect the Raspberry Pi to your local WiFi network.

If you enter your WiFi credentials incorrectly the Homebridge WiFi Setup hotspot will reappear allowing you to try again.

Step 4: Manage Homebridge

The Homebridge UI web interface will allow you to install, remove and update plugins, and modify the Homebridge config.json and manage other aspects of your Homebridge service.

The default user is admin with password admin.

If you're using macOS or a mobile device, you should be able to access the UI via http://homebridge.local.

If you're using Windows, or http://homebridge.local does not work for you, you will need to find the IP address of your Raspberry Pi another way:

  1. Login to your router and find the "connected devices" or "dhcp clients" page to find the IP address that was assigned to the Raspberry Pi.
  2. Use an iPhone to access http://homebridge.local, once you login using the default username and password (admin/admin) you can find the IP address under System Information.
  3. Download the Fing app for iOS or Android to scan your network to find the IP address of your Raspberry Pi.
  4. As a last resort, if you plug a monitor into your Raspberry Pi, the IP address will be displayed on the attached screen once it has finished booting.

Once you've found your IP address, login to the web interface by going to http://<ip address of your server>.

Step 5: Connect to HomeKit

  1. Open the Home app on your device.
  2. Tap the Home tab, then tap .
  3. Tap Add Accessory, then scan the QR code shown in the Homebridge UI.

Your bridge does not have any accessories yet, so you may receive a message letting you know the bridge contains no accessories, this is ok, as you add plugins they will show up in the Home app without the need to pair again (except for Cameras and TVs).

Step 6: Install and Configure Plugins

Using the Homebridge UI, select the Plugins tab and search for the name of the device or plugin you want to install.

Many plugins will allow you to configure the plugin from the GUI without having to manually edit the JSON config file. Plugins that support this feature have the SETTINGS button shown in their card once installed.

If the plugin you have installed requires manual configuration, go to the Config tab. This is where you can edit the Homebridge config.json file. The Homebridge UI will syntax check your config, and provide hints as to where the errors are, so don't be to worried about messing things up here.

If you need help understanding the JSON structure of the config file, see this wiki article.

Once you have finished configuring your plugin, click the restart button found in the top right hand corner to restart the Homebridge process. You will need to restart Homebridge each time you make a change to a plugin's config.

Further Information

The Homebridge Raspberry Pi Image wiki contains detailed information and instructions on how to further customise your install:

https://github.com/homebridge/homebridge-raspbian-image/wiki

Clone this wiki locally