Last Updated on December 7, 2023 by Freddy Reyes
After researching many hours on the internet and reviewed several sites related to the topic, I decided to summarize the details on how to control your SmartThings hub with Siri and put together this post. Here is how to install Homebridge (Apple HomeKit bridge) on a Raspberry Pi and integrate it with Smartthings:
1- You need to install your Raspberry Pi
- Install your Pi by following these instructions: https://www.raspberrypi.org/help/noobs-setup/
2- Install Node.js on the Raspberry Pi
- sudo wget https://nodejs.org/dist/v9.9.0/node-v9.9.0-linux-armv7l.tar.gz
- tar -xvf node-v9.9.0-linux-armv7l.tar.gz
- cd node-v9.9.0-linux-armv7l
- sudo cp -R * /usr/local/
- To check Node.js is properly install and you have the right version, run the command:
- node āv
3- Install the latest version of NPM
- sudo npm install npm -g
4- Install Homebridge and Homebridge Config UI X
Install Homebridge and Homebridge Config UI X using the following command:
- sudo npm install -g –unsafe-perm homebridge homebridge-config-ui-x
Homebridge Config UI X is a web-based management tool for Homebridge that allows you to manage all aspects of your Homebridge setup.
To setup Homebridge as a service that will start on boot you can use the provided hb-service
command.
- sudo hb-service install –user homebridge
5- Login to the SmartThings IDE (https://graph.api.smartthings.com) and create a JSON API SmartApp
- Log in using your SmartThings account that you created as part of the SmartThings kit/hub install.
- Goto the āMy SmartAppsā tab
- Click ā+ New SmartAppā button top right
- Click āFrom Codeā
- In another browser window, go here:
- Click the āRawā button
- Select all the code (Ctrl-A) and copy it (Ctrl-C)
- Go back to the SmartThings IDE window and paste the code you just copied into the code window.
- Click āCreateā
- Click āApp Settingsā
- Click āOAuthā
- Click āEnable OAuth in Smart Appā leave all settings as defaults
- Click āUpdateā
- Click āPublishā and āFor Meā
6- Install the new JSON API SmartApp in SmartThings
Load the SmartThings app on your iPhone.
Go to the āMarketplaceā by tapping the icon in the bottom right (blue, green and yellow icon that looks a bit like a star).
Tap āMy Appsā
Tap āJSON APIā
You can now select any of the devices that you may want to control with HomeKit.
Tap āConfigā
The next screen should then display the configuration that we need to use in the Homebridge server. It should look something like this (Iāve replaced the actual keys with xxx):
{
"platform": "SmartThings-v2",
"name": "SmartThings-v2",
"app_url": "https://graph.api.smartthings.com:443/api/smartapps/installations/",
"app_id": "xxxxxxxxxxxxxxxxxxxxxxxxx",
"access_token": "xxxxxxxxxxxxxxxxxxxxxxxx",
"temperature_unit": "F",
"validateTokenId": false,
"logConfig": {
"debug": false,
"showChanges": true,
"hideTimestamp": false,
"hideNamePrefix": false,
"file": {
"enabled": true
}
}
}
Tap āDoneā
7- Setup a config.json file for Homebridge
- Connect to your Raspberry Pi:
- cd /home/pi/.homebridge (or /var/lib/homebridge)
- sudo vi config.json
Sample File:
{
"bridge": {
"name": "Homebridge",
"username": "XX:XX:XX:XX:XX:XX",
"port": 51826,
"pin": "XXX-XX-XXX"
},
"description": "JSON API",
"platforms": [
{
"name": "SmartThings-v2",
"app_url": "https://graph.api.smartthings.com:443/api/smartapps/installations/",
"app_id": "xxxxxxxxxxxxxxxxxx",
"access_token": "xxxxxxxxxxxxxxxxx",
"direct_port": 8000,
"temperature_unit": "F",
"validateTokenId": true,
"logConfig": {
"debug": false,
"showChanges": true,
"hideTimestamp": true,
"hideNamePrefix": true,
"file": {
"enabled": true,
"level": "good"
}
},
"platform": "SmartThings-v2"
}]
}
- Now we can start the Homebridge server by running: homebridge
- To view the running logs, you can
tail
the output log or error log:- tail -f /var/log/homebridge.log
- tail -f /var/log/homebridge.err
8- Installing plugins (https://www.npmjs.com/search?q=homebridge-plugin)
Note: If you want to display your devices (accessories) you will need to run Homebridge in insecure mode. The following lines show how to implement this feature.
Command Line:
- Add the
-I
flag: homebridge -I
Systemd
If you have configured Homebridge to start using systemd
by following the guide on the offical wiki then you can enable insecure mode by adding -I
to the HOMEBRIDGE_OPTS
variable in your /etc/default/homebridge
file.
Example:
# 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 -I
# If you uncomment the following line, homebridge will log more
# You can display this via systemd's journalctl: journalctl -f -u homebridge
# DEBUG=*
Other Popular Plugins
These are other plugins popular plugins and it’s respective npm commands:
- sudo npm i homebridge-harmonyhub
- sudo npm i homebridge-people
- sudo npm i homebridge-platform-wemo
- sudo npm i homebridge-lifx-lan
- sudo npm i homebridge-thermostat
The modules will installed in the following directory:
/usr/local/lib/node_modules
If you need to remove a module, you can run the following command:
sudo npm r homebridge-people
9- Add HomeKit to iOS
HomeKit is actually not an app; it’s a “database” similar to HealthKit and PassKit. If you upgraded your device to iOS 10, there is a new app called “Home” where you should be able to discover the “homebridge” device on your network (if you have an older iOS version you can also try iDevice, Eve or Devices to discover “homebridge”).
When you attempt to add Homebridge, it will ask for a “PIN code”. The default code is 031-45-154, but I highly recommend you to change it to something else.
If iOS can’t find Homebridge, it could be related to the fact that the Homebridge server thinks it’s been paired with, but iOS thinks otherwise. It can be fixed by deleting persist/
directory files which are next to your config.json
. If the issue continues, iOS device has gotten your Homebridge username
(looks like a MAC address) “stuck” somehow, where it’s in the database but inactive. Fix: change your username
in the “bridge” section of config.json
to be some new value.
10- Remote Access (outside the home network):
If you own a third-generation Apple TV or newer (or an iPad running iOS 10), HomeKit accessories can be controlled with an iOS device away from home, even when Wi-Fi or Bluetooth is not available and you’re using a phone’s cellular connection.
Instructions:
- Disable 2-factor authentication
- On Apple TV, sign out of iCloud and iTunes Store
- Sign back on both iCloud and iTunes Store
- Verify that you can access Homekit from outside the home network (turn off wifi on your iPhone)
- Re-enable 2-factor authentication
Note:
For additional information please check: https://github.com/nfarina/homebridge/wiki/Running-HomeBridge-on-a-Raspberry-Pi