Configure Homebridge as a Service on Debian

Homebridge is a fantastic mechanism for getting non-HomeKit-certified smart home tech talking to Apple. It’s nerd tech written for nerds, so it’s not the easiest thing in the world to get running. Here are some instructions to make things work on Debian and friends (including Raspberry Pi and Ubuntu):

Note that these instructions are going off old memory, so they may be slightly wrong – I’ll retest and fix anything that needs fixing soon!

First thing’s first – make sure everything is up to date:

sudo apt-get update
sudo apt-get upgrade

Install Node.js

Next, install Node.js from the NodeSource GitHub (don’t use the repositories of your distro, as they’re probably outdated). After installation, update to the latest release and install build tools:

curl -sL https://deb.nodesource.com/setup_12.x | sudo -E bash -
sudo apt-get install -y nodejs

sudo npm cache clean -f
sudo npm install -g n
sudo n stable

sudo apt-get install -y build-essential

I like to reboot at this point, but that’s in no way essential.

Install Homebridge

The following installs Homebridge (note the --unsafe-perm flag) and the Homebridge Dummy Switches plugin. The plugin isn’t critical, but I seem to remember having difficulties getting things working without at least one plugin. Besides, the Dummy Switches plugin can be fairly handy for certain types of automation..:

sudo apt-get install libavahi-compat-libdnssd-dev
sudo npm install -g --unsafe-perm homebridge
sudo npm install -g homebridge-dummy

Next, create a very basic config at ~/.homebridge/config.json:

{
  "bridge": {
    "name": "Homebridge",
    "username": "CC:22:3D:E3:CE:30",
    "port": 51826,
    "pin": "031-45-154"
  },
  "description": "Homebridge Server",
  "platforms": [
    {}
  ],
  "accessories": [
    {
      "accessory": "DummySwitch",
      "name": "My First Switch"
    }
  ]
}

Run Homebridge directly at the command line to test:

homebridge

An ascii-art QR code will appear; you can use this code to add Homebridge to HomeKit using the Home app. Ignore warnings about the accessory not being certified.

Create systemd service for Homebridge

The instructions below assume you used the instructions above to install Node.js and Homebridge – paths may be different if you didn’t.

Pre-requisites

The following commands create the service user and directories, then moves the existing configuration into the appropriate locations for starting Homebridge as a service. Finally, set the relevant permissions..:

sudo useradd -M --system homebridge
sudo mkdir /var/lib/homebridge

sudo cp ~/.homebridge/config.json /var/lib/homebridge/
sudo cp -r ~/.homebridge/persist /var/lib/homebridge

sudo chmod -R 0777 /var/lib/homebridge

Systemd config files

Create /etc/default/homebridge:

# Defaults / Configuration options for homebridge
# The following settings tells homebridge where to find
# the config.json file and where to persist the data
# (i.e. pairing and others)
HOMEBRIDGE_OPTS=-U /var/lib/homebridge

# If you uncomment the following line, homebridge will log more
# You can display this via systemd's journalctl:
# journalctl -f -u homebridge
#DEBUG=*

Create /etc/systemd/system/homebridge.service:

[Unit]
Description=Node.js HomeKit Server
After=syslog.target network-online.target

[Service]
Type=simple
User=homebridge
EnvironmentFile=/etc/default/homebridge
ExecStart=/usr/local/bin/homebridge $HOMEBRIDGE_OPTS
Restart=on-failure
RestartSec=10
KillMode=process

[Install]
WantedBy=multi-user.target

Finally, enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable homebridge
sudo systemctl start homebridge

Links and Howtos

Here’s what I used to get myself up and running:
https://github.com/nfarina/homebridge
https://github.com/nfarina/homebridge/blob/master/config-sample.json
https://gist.github.com/johannrichard/0ad0de1feb6adb9eb61a/
https://timleland.com/setup-homebridge-to-start-on-bootup/

Connect a Sensibo Sky to HomeKit via Homebridge

Very few smart thermostat / smart air conditioner controls are available in Australia, and exactly none of them work with HomeKit out of the box. I have a Sensibo Sky in my lounge room, and with the help of some Homebridge tomfoolery – it works brilliantly with HomeKit!

Here’s how it works:

Configure controller

You need to be able to control your air conditioner via the Sensibo app before anything is going to work with Homebridge. Use the included instructions to download the app, connect the Sensibo Sky to your WiFi network and set things up.

Next, log into https://home.sensibo.com/, click the hamburger menu and select Create API Key. The API is how the Homebridge plugin communicates with the Sensibo servers and ultimately controls your air conditioner.

Homebridge plugin and config

First, you should definitely check out my guide for getting Homebridge up and running – come back here once you’re done:

Configure Homebridge as a Service on Debian

There are a number of Homebridge plugins for controlling Sensibo devices – the one I’ve had the most success with is Homebridge Sensibo Sky 7 modes Plugin:

sudo npm install -g homebridge-sensibo-sky-7modes
Once the plugin is installed, use the configuration below – all you should need to do is add your own API key, but you can adjust settings to taste:

"platforms": [
    {
        "platform": "SensiboSky",
        "name": "Sensibo",
        "apiKey": "YOURAPIKEYGOESHERE",
        "timeLapse": 5,
        "ai": false,
        "hideFan": false,
        "hideHumidity": true,
        "fixedState": "auto"
    }
]

Keep in mind this is just a snippet and needs to be added to your Homebridge config.json file. If you’re not 100% sure you have the right syntax, check it at JSONLint.

Time to restart Homebridge:

sudo systemctl restart homebridge

After a few moments you should have two new icons in the Home app:

  1. A thermostat icon with the temperature
  2. A fan icon that allows you to set the fan speed

I’ve set it up this way because I’ve had very little luck with letting Homebridge control the fan speed automatically. It’s possible that it’s just my air conditioner; you may have better luck in using the automatic fan settings with yours.

Automation

Once the Sensibo Sky is working with Homebridge, you can set up some pretty cool automation! I’ve got “Auto Cool” and “Auto Heat” scenes that automagically turn the air conditioner on and off to maintain a consistent temperature in the room.

To set this up yourself, you need to use a 3rd party HomeKit app – I use Home. At A$22.99 it’s quite an expensive app, but it’s definitely been one of my better buys.

The magic trick is using “Any Change” in temperature as detected by the Sensibo Sky as the trigger event. I’ve tried (and failed) to make this work using other triggers, but this one actually works!

The remaining steps are fairly straight forward: use current temperature and power state of the air conditioner as conditions, then finally set the power state to on or off as the action.

Notes

Placement of the Sensibo Sky is critical! If you still use the regular remote control, the Sensibo Sky has to be somewhere where it can “see” the infrared commands that the remote sends. Even when it can, it will occasionally get out of sync with the actual state of the air conditioner – the only time I actually use the Sensibo app is to get it back in sync again.

Connect a TP-Link HS110 Smart Plug to HomeKit with Homebridge

As of right now, the only HomeKit-certified smart plug available in Australia is the Elgato Eve Energy – which is bulky, expensive, and uses Bluetooth LE rather than Zigbee, Z-Wave or WiFi.

TP-Link have two WiFi-enabled smart plugs available (HS100 / HS110). While these smart plugs can’t be directly used with HomeKit – by using Homebridge as a software HomeKit bridge, they work great!

Here’s the recipe:

Connect Smart Plug to WiFi

Follow the instructions that came with the smart plug to connect it to WiFi (ensure that this is the same WiFi network that everything else is connected to). Once the smart plug is connected to WiFi, there is no further need for the Kasa app.

Homebridge plugin and config

Don’t already have Homebridge up and running? You should really check out my guide for setting Homebridge up – come back here once you’re done:

Configure Homebridge as a Service on Debian

TP-Link Smart Home plugin and config

A quick one-liner to install the TP-Link Smart Home plugin:

sudo npm install -g homebridge-tplink-smarthome

Once the plugin is installed, use the configuration below – there’s no real need to change anything, but be aware that this is just a snippet and needs to be added to your Homebridge config.json file. If you don’t find yourself writing JSON regularly, it’s probably a good idea to check the syntax at JSONLint.

"platforms": [
    {
        "platform": "TplinkSmarthome",
        "name": "TplinkSmarthome",

        "broadcast": "255.255.255.255",
        "devices": [],
        "deviceTypes": [],
        "macAddresses": [],
        "pollingInterval": 10,

        "addCustomCharacteristics": true,
        "inUseThreshold": 0,
        "switchModels": ["HS200"],
        "timeout": 5
    }
]

Restart Homebridge

After the config.json file is updated, you need to restart Homebridge for the device to be recognised:

sudo systemctl restart homebridge

..and that’s it!