HomeBridge – Homekit 2 MQTT revised Installation

Because I’m always testing I also need several times a clean install to exclude any errors. This time I found my self having some issues while installing my Homekit 2 MQTT homebridge. The al the used software had some major updates and changes. So time for a revised installation manual.

SD Formatter

Visit the SD Association’s website and download SD Formatter 4.0 for either Windows or Mac. Follow the instructions to install the software. Insert your SD card into the computer or laptop’s SD card reader, select the drive letter for your SD card and format it.


Download  Raspbian lite image

These instructions are for a Raspbian Jessie image that I downloaded from here:

I’m using the lite image (no desktop / headless).

Version:March 2018
Release date:2018-03-13
Kernel version:4.9

Once you download the file, note the location of the *.img file.


Download etcher

Visit etcher.io and download and install the Etcher SD card image utility. Run Etcher and select the Raspbian image you unzipped on your computer or laptop. Select the SD card drive. Note that the software may have already selected the right drive. Finally, click Burn to transfer Raspbian to the SD card. You’ll see a progress bar that tells you how much is left to do. Once complete, the utility will automatically eject/unmount the SD card so it’s safe to remove it from the computer.

Take your SD card out of your computer and place it back so it can be mounted again.


Enable ssh

For security reasons, ssh is no longer enabled by default. Open the Terminal app. Click the Finder icon in your dock. Click Go. Click Utilities. Double-click Terminal. To enable it, run this command:

touch /Volumes/boot/ssh


Add network information

Create a new empty file that will hold network information:

touch /Volumes/boot/wpa_supplicant.conf

then open the file:

sudo nano /Volumes/boot/wpa_supplicant.conf

Edit the file that you just created and paste this into it (adjusting for the name of your country code, network name and network password):

ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev


Save your changes, press CTRL + O, followed by Enter. Then press CTRL + X.


Eject the micro SD card

Issue an eject command:

diskutil eject /dev/disk2

The command won’t physically eject the disk/card. It’s more of a logical eject: meaning it’s safe to remove the card now. You can also do this by right-clicking on the card on your desktop.

Boot the Pi Zero W

Put the SD card into the Pi Zero W. Plug a Micro-USB power cable into the power port (the one closest to the end of the board). Give the Pi Zero plenty of time to bootup (it can take as much as 90 seconds — or more)


Login over Wifi

This part assumes that ssh is enabled for your image and that the default user is pi with a password of raspberry. Open the Terminal app. Click the Finder icon in your dock. Click Go. Click Utilities. Double-click Terminal. Run the following commands:

ssh pi@raspberrypi.local

If prompted with this warning:

The authenticity of host 'raspberrypi.local (xxxxxxxxxxxxxxxxxxxxxxxxxxxxx)' can't be established. 
ECDSA key fingerprint is SHA256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.
Are you sure you want to continue connecting (yes/no)? 

just hit enter to accept the default (Yes). Type in the password — by default this is raspberry. Congratulations! You can now access your Pi Zero W over wifi! If you can’t connect, see the troubleshooting blog here.


Change your Hostname and Password

Because your pi is now on the network, you should immediately change the hostname and password. At the command line type:

sudo raspi-config

Select the options for changing the hostname and password. On a new image, I would also recommend expanding the file system (now under the Advanced options) and set the locale settings. Once the changes are made you need to, reboot. To reboot your raspberry pi zero w, type:

sudo reboot

Remember that once you reboot, you will need to use the new hostname to login over ssh. For example, if your new hostname is Homebridge you would connect like this:

ssh pi@homebridge.local


Fix the locale issue

Last week I was trying to make my Raspberry Pi work again, and while reinstalling and upgrading Raspbian OS packages I run into an issue where a perl warning is displayed.

The warning message apprears during the installation packages(invoking Perl) and it’s due to missing locales. Type:


when you see this message and see that LC_ALL = (unset), and LANG = (unset) are (unset), then proceed with the fix.

perl: warning: Setting locale failed.
perl: warning: Please check that your locale settings:
        LANGUAGE = "en_GB.UTF-8",
        LC_ALL = (unset),
        LC_TIME = "en_GB.UTF-8",
        LC_MONETARY = "en_GB.UTF-8",
        LC_ADDRESS = "en_GB.UTF-8",
        LC_TELEPHONE = "en_GB.UTF-8",
        LC_NAME = "en_GB.UTF-8",
        LC_MEASUREMENT = "en_GB.UTF-8",
        LC_IDENTIFICATION = "en_GB.UTF-8",
        LC_NUMERIC = "en_GB.UTF-8",
        LC_PAPER = "en_GB.UTF-8",
        LANG = (unset),
    are supported and installed on your system.
perl: warning: Falling back to the standard locale ("C").
locale: Cannot set LC_ALL to default locale: No such file or directory

I searched the internet for the fix but non of them where working. But I found one that did. Typ:

sudo nano /etc/default/locale

Change it, and include these three lines:


Save your changes, press CTRL + O, followed by Enter. Then press CTRL + X.


Static Ip adress

After setting up the network connection, all I have to do is configure a static IP address and my Raspberry Pi Zero W is ready for use. Here I will show you how to set a static IP address on your Raspberry Pi Zero W on Raspbian OS.

sudo nano /etc/dhcpcd.conf

Scroll all the way to the bottom of the file and add one, or both of the following snippets.
Depending on whether you want to set a static IP address for a wired connection or a wireless connection eth0 = wired, wlan0 = wireless.

You’ll need to edit the numbers in the snippet so they match your network configuration:

interface wlan0

static ip_address=
static routers=
static domain_name_servers=

interface = This defines which network interface you are setting the configuration for.
static ip_address = This is the IP address that you want to set your device to. (Make sure you leave the /24 at the end)
static routers = This is the IP address of your gateway (probably the IP address or your router)
static domain_name_servers = This is the IP address of your DNS (probably the IP address of your router). You can add multiple IP addresses here separated with a single space.

Save your changes, press CTRL + O, followed by Enter. Then press CTRL + X. Now all you need to do is reboot, and everything should be set!

sudo reboot


Get the updates and upgrade

Once connected over WiFi, the next thing you should do is run some updates:

sudo apt-get update

and then:

sudo apt-get upgrade -y

Now we are ready to install Homekit2MQTT prerequisites.



Before installing the actual Homekit2MQTT software you need two Prerequisites:


Install Node.js 6 or higher

Check the Nodejs.org website to be sure you have the latest version of Node.js then type.

sudo wget https://nodejs.org/dist/v9.11.1/node-v9.11.1-linux-armv6l.tar.gz
sudo tar -xvf node-v9.11.1-linux-armv6l.tar.gz
cd node-v9.11.1-linux-armv6l

Copy to /usr/local/ using the following command to execute :

sudo cp -R * /usr/local/

When the installation is done type:


and then:

node –v

This will show you the version installed of node.js on your system. Now you need to reboot your Raspberry Pi Zero W.

sudo reboot


libavahi-compat-libdnssd-dev package

If you’re running on Linux ( Yes, your raspberry Pi runs on Linux), you’ll need to make sure you have the libavahi-compat-libdnssd-dev package installed. You can do this by typing:

sudo apt-get update

When the updates are downloaded type:

sudo apt-get upgrade -y

and then:

sudo apt-get install libavahi-compat-libdnssd-dev -y

Now, you need to add the Mosquitto repository. Enter the following commands.

sudo wget http://repo.mosquitto.org/debian/mosquitto-repo.gpg.key
sudo apt-key add mosquitto-repo.gpg.key
sudo rm mosquitto-repo.gpg.key

Next, make the repository available to apt-get. First we need to change to the apt sources list directory.

cd /etc/apt/sources.list.d/

Now install the packages list for your version of Raspbian.

For Jessie (old version)

sudo wget http://repo.mosquitto.org/debian/mosquitto-jessie.list

For Stretch (latest, in time of writing)

sudo wget http://repo.mosquitto.org/debian/mosquitto-stretch.list

Now update apt information and install Mosquitto.

sudo apt-get update
sudo apt-get install mosquitto mosquitto-clients -y

That is it. Mosquitto is now installed and running on your Raspberry Pi. Now you need to reboot your Raspberry Pi Zero W.

sudo reboot

Where almost there…



Now that you have installed all the Prerequisites you’re ready for the real deal, installing Homekit2MQTT. Type:

sudo npm install -g homekit2mqtt --unsafe --perm

Installation can take quite some time. Wait quietly until the completion of the installation. When the installation is complete, we can start Homekit2MQTT for the first time. Enter the following command:


Now that you have homekit2mqtt up and running you can add sensors. homekit2mqtt needs a JSON file that defines devices and mappings from MQTT-topics and payloads to HomeKit-characteristics. You can either create this manually or use the Web UI to configure homekit2mqtt.



Now we have to connect our iPhone to the homekit2mqtt and add the new accessories.

On your iOS device launch the Home app.
Tap the Add button in the top right corner of the screen (looks like a plus sign).
Tap Add Accessory.
Tap on the MQTT accessory (mine’s just called MQTT Bridge).
You will see an alert that says, “This accessory is not certified and may not work reliably with HomeKit.” tap Add Anyway.
Tap Enter Code Manually at the bottom of the screen.
Enter the HomeKit code for your MQTT Bridge accessory.

Add your Homebridge accessory and tap Next.
Add the accessories (The are a few preconfigured) and tap Done.



To add the new accessories, homekit2mqtt has a build-in web-server. This allows you that easily add new MQTT accessories for Homekit. So to connect to your homekit2mqtt web-server, open your web browser and type:


Now you can login with the username:


and password:


Congratulations! You’ve successfully linked a HomeKit-enabled smart home accessory to HomeKit.


Sebastian Raff (APR 25 2018), Homekit2MQTT, Use to control a  MQTT-connected “Thing” in your home automation through Siri and with HomeKit apps., https://github.com/hobbyquaker/homekit2mqtt







Scroll to Top