See my updated instructions in the first comment. This is now INCREDIBLY EASY.
First off, this is probably a horrible admission prior to creating a "how to", but I am one of those complete newbs, who somehow is able to figure out how to make something very complicated work, but is not any sort of expert and honestly doesn't really understand how any of this actually works.
With that out of the way, I wanted to give a complete run down on how I got this to work, because now that I do, I am very happy with this set up. Works so well that I am decommissioning 8 Amazon Alexas as we have 4 iPhones, 3 Apple Watches, 4 Apple TVs, and 2 HomePods throughout the house that now can do 95% of what I was previously doing with ISY 994i + ISY Portal + Amazon Echo.
My Environment
ISY 994i IR/Pro v4.7.3 purchased in 2013 (I haven't tested on the 5 beta..)
90 Insteon Dual Band Switches (On/Of and Dimmers)
5 Insteon LampLincs
5 Insteon Leak Detectors
2 Insteon v2 Motion Detectors
2 Insteon Garage Door Relays
Insteon 2441 Thermostat --> changed to Ecobee 3 lite; using directly with Homekit
Phillips Hue with 25 bulbs - Whites and Colors. for now, using directly through it's hub with Homekit
Logitech Harmony Hub - have yet to set up with it's individual Homekit plugin
Ring Pro - waiting for 1st party Homekit support...
Dedicated Raspberry Pi 2 model B
Limitations
As of this writing, and may only be specific to my set up and lack of knowledge, these are the following limitations:
My instructions below are the notes I used as I did this 3 times, it made sense to me... I hope it does to you. I also assume you know how to use SSH (I didn't until I did this, so I assume you're able to figure it out too!). As a side note, you don't have to SSH if you just plug in a keyboard and monitor to the Raspberry Pi..
I cannot control my old Venstar Insteon thermostat.
I haven't found a way, yet, to program alternative names for devices, like what I can with ISY Portal.
This took A SHIT-TON of time, research, and experimentation to get up and running.
It is minor, but you need about $50 to get a Raspberry Pi, memory card, charger, and optional case. This should work perfectly fine with a v2 or higher (currently on v3).
The author of Homebridge ISY JS (which is essential for this to work) no longer actively supports this. I am very hopeful that some smart chap will pick it up...
Some essential resource Links:
Homebridge
This is the main program that everything else plugs into. I'll show what is helpful for this particular post, but you can add other plugins, i.e. for for Logitech Harmony Hub
Github
NPM
Reddit
Homebridge ISY JS
This is the plugin which will connect your ISY to homebridge (and thus to Apple Homekit)
Github
NPM
Homebridge Config UI X
Not necessary, but very helpful so that once you get things set up, you can copy/paste new JSON config files and reset your homebridge on the fly through a web portal
Github
NPM
This is a fork of the original Homebridge Config UI; it's probably something I screwed up, but I had a problem getting the original to work. But this X version also has some additional options, so I'm sticking with it.
Homebridge ISY Maker
Not necessary and I am not using this yet, but I have it installed; looks like it will open up a lot more options as I continue to work on this setup.
Github
NPM
JSON Validator
Use this to test every time you make a change to your JSON config file. Trust me.
Text Editors
Don't directly copy and paste many of the text from websites (including this post). It doesn't always copy the intended text for when you paste into your Linux prompt.
if you are using Windows, Notepad++ is probably the best text editor out there
If you are using Mac, I used Atom, apparently there are various options but I'm new to using a Mac
SSH
On Windows, I used PuTTY
And, on MAC, I used Finder then use COMMAND+K to bring up "Connect to Server" then type ssh://pi@XXX.XXX.XXX.XXX (pi as the default login username and XXX.XXX.XXX.XXX as the IP address for your Raspberry Pi)
Raspbian
Main page
Image Download
Installation Guide
Guide to The Raspi-Config Tool
https://pimylifeup.com/raspi-config-tool/
My Exact Step by Step Process
Quick Note for newbs (like me): the dollar sign "$" indicates that you enter the remainder of that line as a command. You don't actually type the "$"
Quick Note #2: I put "sudo" prior to all commands, because I don't otherwise know what I'm doing, and it just makes things work
Quick Note #3: if you get an error on step #5 while on a Mac, scroll down to TroubleShooting at the bottom of this post.
Part 1: Homebridge Setup
General Setup
1. Download the Raspbian Lite image file at https://www.raspberrypi.org/downloads/raspbian/
Install Raspbian Lite Image to an SD card using the instructions at https://www.raspberrypi.org/documentation/installation/installing-images/ for Windows, Mac, or Linux.
Open the SD card (in File Explorer on Windows or in Finder on a Mac) and add a file named “ssh” with no suffix extension - this is NECESSARY to that you can SSH to the RPi
Put the SD card into your Raspberry Pi, power it on, and ensure it's connected to your network (i.e. via ethernet, or look up how to set up on WiFi)
take note of your Pi's IP address (i.e. log into your router and look for it under attached devices)
SSH to Raspberry Pi
Default username: pi
Default password: raspberry
tip: ssh pi@xxx.xxx.xxx.xxx
$ sudo dpkg-reconfigure tzdata
choose the appropriate time zone
$ sudo raspi-config
“Change User Password” -> change password !
"Update"
“Advanced Options” -> “Expand Filesystem”
“Finish” - >“Reboot” -> SSH back into RPi
$ sudo apt update
$ sudo apt full-upgrade (choose “Y” if asked)
"q" through any changelogs that pop up
$ sudo apt-get autoremove
$ sudo reboot -> SSH back into RPi
Homebridge Setup (including dependencies)
DO THIS FIRST
$ uname -m
You will get a result; I don't know what this does. I think it tells you something about the CPU in your Pi. It will be "arm" and a number
If the number is > 61 (mine is arm71), then go to my manual instructions.
Otherwise, use this script from: https://www.youtube.com/watch?v=_S66mtwNkQo
$ curl -sSL goo.gl/Ksdhph | bash
If any questions, you can still use the script, but it installs an older version of things
Manual Instructions:
$ sudo apt-get remove node nodejs nodejs-legacy -y
$ sudo apt-get install git-core libnss-mdns libavahi-compat-libdnssd-dev -y
$ sudo curl -sL https://deb.nodesource.com/setup_11.x | sudo -E bash -
NOTE: you may want to see if there is a newer version of Node.js
https://github.com/nodesource/distributions
$ sudo apt-get install -y nodejs
$ sudo npm install -g n
$ sudo rm /usr/local/bin/node
note: it might tell you there is no such directory
$ sudo rm -rf /usr/local/lib/node_modules/npm
$ sudo n prune
$ sudo useradd -M --system homebridge
$ sudo npm install -g --unsafe-perm homebridge
$ homebridge
test to see that homebridge is working
You should get a print out and the code for scanning into Homekit
DO NOT install this to HomeKit yet.
CTRL-C to stop homebridge
$ cd .homebridge/
$ ls
[this lists the files in this directory, you probably see no config.json file listed, that's OK, go to next step]
$ nano config.json
[this creates config.json and opens edtor]
Copy and Paste, or type in the following simple configuration which changes default PIN (you can pick any 8 digits you want)
REMEMBER to put any JSON stuff into a validator first, then copy/paste that to your Pi (otherwise, sometimes your'e copying/pasting buggy "non-plain-text" stuff for lack of a better explanation"
https://jsonlint.com
{
"bridge": {
"name": "Homebridge",
"username": "CC:22:3D:E3:CE:30",
"port": 51826,
"pin": "123-45-678"
}
}
19. CTRL+X to exit and save, choose “yes”
20. $ cd
21. $ homebridge [to test your new pin]
22. CTRL+C to exit
Part 2: Setup Homebridge to run at startup using systemd (optional but highly recommended)
This was the hardest thing to get right... I seriously want to put a gun to my head.... so if this doesn't work for you, sorry!
Resource #1: https://github.com/nfarina/homebridge/wiki/Running-HomeBridge-on-a-Raspberry-Pi
Resource #2: https://gist.github.com/johannrichard/0ad0de1feb6adb9eb61a/
Alternative Resource: https://timleland.com/setup-homebridge-to-start-on-bootup/
Note: if you don't know, anything that ends in "d" means "daemon" which means it runs as a service. And, "systemd" is like a service manager for Linux.
$ sudo useradd -M --system homebridge
If you didn't do this above already for some reason (so, you might get a message that it's already done)
$ sudo nano /etc/default/homebridge
Paste:
# 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/homebridge
# If you uncomment the following line, homebridge will log more
# You can display this via systemd's journalctl: journalctl -f -u homebridge
# DEBUG=*
5. Exit and use default name to save
6. $ which homebridge
————————————————————————————————
For Step 8 below:
NOTE what result you get with "$ which homebridge" —> use that directory below for ExecStart=
example: mine is usr/bin/homebridge, but sometimes it is /usr/local/bin/Homebridge ————————————————————————————————
7. $ sudo nano /etc/systemd/system/homebridge.service
8. Paste
[Unit]
Description=Node.js HomeKit Server
After=syslog.target network-online.target
[Service]
Type=simple
User=homebridge
EnvironmentFile=/etc/default/homebridge
ExecStart=/usr/bin/homebridge $HOMEBRIDGE_OPTS
Restart=on-failure
RestartSec=10
KillMode=process
[Install]
WantedBy=multi-user.target
9. $ sudo mkdir /var/homebridge
10. $ sudo cp ~/.homebridge/config.json /var/homebridge/
11. $ sudo cp -r ~/.homebridge/persist /var/homebridge
12. $ sudo chmod -R 0777 /var/homebridge
13. $ sudo systemctl daemon-reload
14. $ sudo systemctl enable homebridge
15. $ sudo systemctl start homebridge
16. $ sudo reboot
17. $ systemctl status homebridge
[test that homebridge is running you might have to CTRL-C to move on]
Part 3: Setup Homebridge Config [Optional but HIGHLY RECOMMEND]
1. $ sudo npm install -g --unsafe-perm homebridge-config-ui-x
2. $ sudo visudo
3. Add to the bottom of this file (this allows homebridge to use the magic sudo thing that makes things work):
homebridge ALL=(ALL) NOPASSWD: ALL
4. $ cd .homebridge/
5. $ nano config.json [creates config.json if it doesn't already exists and opens edtor]
6. Delete current settings, then command+c and command+v to paste a simple configuration
REMEMBER to put any JSON stuff into a validator first, then copy/paste that to your Pi (otherwise, sometimes your'e copying/pasting buggy "non-plain-text" stuff for lack of a better explanation"
https://jsonlint.com
{
"bridge": {
"name": "Homebridge",
"username": "CC:22:3D:E3:CE:30",
"port": 51826,
"pin": "123-45-678"
},
"description": "My Homebridge JSON file for use with ISY",
"platforms": [{
"platform": "config",
"name": "Config",
"port": 8080,
"sudo": true,
"restart": "sudo -n systemctl restart homebridge",
"log": "systemd"
}]
}
7. $ sudo reboot
8. Open a web browser to XXX.XXX.XXX.XXX:8080 (where XXX.XXX.XXX.XXX is the IP address of your Raspberry Pi -- NOT your ISY)
9. Default username: admin
10. Default password: admin
FROM NOW ON YOU SHOULD BE ABLE TO EDIT config.json FROM WITHIN Homebridge UI which is A LOT easier
Part 4: Install homebridge-isy-js
Resource: https://github.com/rodtoll/homebridge-isy-js
1. $ sudo npm install -g homebridge-isy-js
2. $ cd .homebridge/
3. $ ls [just to make sure you see a config.json file listed]
4. $ nano config.json [creates config.json if not done already and opens edtor]
or use the ConfigUI web GUI to enter config.json
5. Delete current settings, then command+c and command+v to paste a simple configuration
NOTE:
Enter your appropriate IP address for: "host": "XXX.XXX.XXX.XXX",
Enter your appropriate ISY username for: "username": "USERNAME",
Enter your appropriate ISY password for: "password": "PASSWORD",
REMEMBER to put any JSON stuff into a validator first, then copy/paste that to your Pi (otherwise, sometimes your'e copying/pasting buggy "non-plain-text" stuff for lack of a better explanation"
https://jsonlint.com
{
"bridge": {
"name": "Homebridge",
"username": "CC:22:3D:E3:CE:30",
"port": 51826,
"pin": "123-45-678"
},
"description": "My Homebridge JSON file for use with ISY",
"platforms": [{
"platform": "isy-js",
"name": "isy-js",
"host": "XXX.XXX.XXX.XXX",
"username": "USERNAME",
"password": "PASSWORD",
"elkEnabled": false,
"useHttps": true,
"debugLoggingEnabled": false,
"includeAllScenes": true
},
{
"platform": "config",
"name": "Config",
"port": 8080,
"sudo": true,
"theme": "red",
"temp": "/sys/class/thermal/thermal_zone0/temp",
"restart": "sudo -n systemctl restart homebridge",
"log": "systemd"
}
]
}
6. $ homebridge [to test]
7. CTRL+C to exit
ALL FOLLOWING STEPS ARE OPTIONAL
Part 5: Setup Homebridge Maker
1. $ sudo npm install -g homebridge-isy-maker
2. Update config.json
{
"bridge": {
"name": "Homebridge",
"username": "CC:22:3D:E3:CE:30",
"port": 51826,
"pin": "123-45-678"
},
"description": "My Homebridge JSON file for use with ISY",
"platforms": [
{
"platform": "isy-js",
"name": "isy-js",
"host": "XXX.XXX.XXX.XXX",
"username": "USERNAME",
"password": "PASSWORD",
"elkEnabled": false,
"useHttps": true,
"debugLoggingEnabled": false,
"includeAllScenes": true
},
{
"platform": "config",
"name": "Config",
"port": 8080,
"sudo": true,
"theme": "red",
"temp": "/sys/class/thermal/thermal_zone0/temp",
"restart": "sudo -n systemctl restart homebridge",
"log": "systemd"
},
{
"platform": "isy-maker",
"name": "ISYMaker",
"host": "XXX.XXX.XXX.XXX",
"username": "USERNAME",
"password": "PASSWORD",
"prefix": "hb"
}
],
"accessories": []
}
Part 6: Now the Real Fun. Customizing
If you've made it this far, then you'll figure out the rest. But just as another example, this is my current config.json so that you can see a few of the optional lines in action.
{
"bridge": {
"name": "Homebridge",
"username": "CC:22:3D:E3:CE:30",
"port": 51826,
"pin": "123-45-678"
},
"description": "Kevin's Homebridge JSON file for use with ISY",
"platforms": [
{
"platform": "isy-js",
"name": "isy-js",
"host": "xxx.xxx.xxx.xxx",
"username": "username",
"password": "password",
"elkEnabled": false,
"useHttps": true,
"debugLoggingEnabled": false,
"includeAllScenes": false,
"includedScenes": [
"46323",
"53376",
"53789",
"55365",
"58030",
"61718",
"62250",
"62883",
"64358"
],
"garageDoors": [
{
"address": "3D 50 A7 1",
"name": "Car Garage Door",
"timeToOpen": 12000,
"alternate": true
},
{
"address": "3D 51 DB 1",
"name": "Bike Garage Door",
"timeToOpen": 12000,
"alternate": true
}
],
"ignoreDevices": [
{
"nameContains": "X ",
"lastAddressDigit": "",
"address": ""
},
{
"description": "Insteon Front Hall Lights",
"nameContains": "",
"lastAddressDigit": "",
"address": "42 C6 8E 1"
},
{
"description": "Insteon Garage Hall Lights",
"nameContains": "",
"lastAddressDigit": "",
"address": "42 B0 26 1"
},
{
"description": "Insteon Main Stair Lights",
"nameContains": "",
"lastAddressDigit": "",
"address": "42 AF C0 1"
},
{
"description": "Insteon Lamplinc Lily's Bedroom Lamp",
"nameContains": "",
"lastAddressDigit": "",
"address": "3E B4 DC 1"
},
{
"description": "Insteon Lily's Bedroom Switch",
"nameContains": "",
"lastAddressDigit": "",
"address": "41 D9 09 1"
},
{
"description": "Insteon Upstairs Landing Lights main",
"nameContains": "",
"lastAddressDigit": "",
"address": "42 C5 E6 1"
},
{
"description": "Insteon Theater Room Lights",
"nameContains": "",
"lastAddressDigit": "",
"address": "46 A8 86 1"
},
{
"description": "Insteon Front Porch Lights",
"nameContains": "",
"lastAddressDigit": "",
"address": "42 37 F1 1"
}
]
},
{
"platform": "config",
"name": "Config",
"port": 8080,
"sudo": true,
"theme": "red",
"temp": "/sys/class/thermal/thermal_zone0/temp",
"restart": "sudo -n systemctl restart homebridge",
"log": "systemd"
},
{
"platform": "isy-maker",
"name": "ISYMaker",
"host": "xxx.xxx.xxx.xxx",
"username": "username",
"password": "password",
"prefix": "hb"
}
],
"accessories": []
}
TROUBLESHOOTING
If you SSH on a Mac to the Raspberry Pi and get this message:
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!
Someone could be eavesdropping on you right now (man-in-the-middle attack)!
It is also possible that a host key has just been changed.
The fingerprint for the ECDSA key sent by the remote host is
SHA256:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.
Please contact your system administrator.
Add correct host key in /Users/XXXXX/.ssh/known_hosts to get rid of this message.
Offending ECDSA key in /Users/XXXXX/.ssh/known_hosts:1
ECDSA host key for XXX.XXX.XXX.XXX has changed and you have requested strict checking.
Host key verification failed.
This is because you've tried to SSH to this Pi before, and something has changed (such as re-formatting it). Do this:
Go into your user folder and hit CMD + Shift + G and type ".ssh"
Delete (move to trash) the file named "known_hosts"
Try to SSH again
Choose "yes" when asked "are you sure you want to continue with connecting"
If you try to SSH to the Pi and "Connection Refused"
1. You forgot to put a blank file named "ssh" (without the quotes) on the SD card
2. Or you're trying to SSH to the wrong device... yes this happened