Getting Started with the HCA Plugin for Homebridge Updated 12-Nov-17

Transcription

1 Getting Started with the HCA Plugin for Homebridge Updated 12-Nov-17

2 Table of Contents Introduction... 3 Getting Ready... 3 Step 1: Installing Bonjour... 5 Step 2: Installing Homebridge and the HCA Plugin... 8 Step 3: Running Homebridge Step 4: Adding the Homebridge Accessory to ios Step 5: Restarting Apple TVs (HomeKit Hubs) Step 6: Using Siri and HomeKit Step 7: Changes to your HCA design Other Topics Starting Homebridge with HCA Stopping Homebridge Manually Updating the HCA Plugin for Homebridge Uninstalling the HCA Plugin for Homebridge Troubleshooting Common Issues

3 Introduction Homebridge Homebridge is set of software packages that run on a computer on your home network - typically installed on the same computer where you run the HCA server. It provides a connection between the HCA server and Apple HomeKit programs and Siri, the Apple Voice Assistant. Unlike purchased software you might be familiar with like HCA - Homebridge is open source and is supported by many developers. The good news is that there is no cost to set up Homebridge on your system and so get access to all that Apple HomeKit can do. Also, Homebridge supports more than just HCA and once you get it all to work with HCA you can then add more plugin modules to support other home automation gear. The less-than-good news is that it will take a bit of effort to get it all configured on your computer. Quite a bit more than getting HCA installed, but these instructions take you through the process step-by-step and if you carefully follow along then all will install without problems. With Siri and HomeKit you can control all the devices that HCA manages as well as HCA groups and programs. This gives you access to what HomeKit normally can t handle. To use HomeKit and Siri you will need an Apple hardware device. Supported are an Apple TV (4 th generation+), and Apple Watch, or a HomeKit-supported app on an iphone, ipad, or ipod Touch (5 th generation+). More information about what is and isn t supported can be found on the Apple web site. For additional information on Homebridge, please reference: For available Homebridge plugins, please reference: None of this Homebridge and HomeKit support uses the HCA Cloud or requires that you have a HCA Cloud account. Getting Ready Before you begin, make sure that you are running HCA Plus version 14.1 or later and that you are successfully running the HCA Server and can connect to it using the Windows or mobile clients. If you have not already worked with HCA in client-server mode, you should stop and go read the HCA Getting Started guide which takes you through that setup. Get that working then come back to this. 3

4 Unless you have a good reason and have worked with Homebridge already, you should install these new components on the same computer that is running the HCA server. The first step is to download from the HCA web site a zip file that contains files needed for Homebridge. You can save this zip file in any folder, but it would be best if you first created a new folder on your disk and save the file there. This will make it simpler to follow along with the instructions below. Create a folder C:\Homebridge and then click on this link to download using your browser and save the zip file to that folder. Use an unzip program, or the built-in one in Windows explorer, to extract the files contained in the zip file into that same C:\Homebridge folder. Once you have completed the installation, what can you control using Siri and HomeKit? Those devices, programs, and groups that you have assigned a friendly name to and that HomeKit accepts. A friendly name is an alternative name for one of these objects that may be easier to use than the name you gave to it in HCA. For example, you may have a device named Counter left corner light in the Kitchen room. It would be simpler if you could just say kitchen counter light rather than Kitchen counter left corner light. Generally, HomeKit understands devices that have a load and can be controlled on, off, and if the hardware supports it, to a given level. If you supply a friendly name to a device that HomeKit can t handle, then it will be unavailable. Friendly names can be seen on the Name tab of the properties of a device, program, or group. You can also see all your objects at one time and assign friendly names there by pressing the External Assistants Configuration button in the HCA Cloud ribbon category. All friendly names must be unique and can only be composed of letters no special characters and blanks. Remember when assigning friendly names that if you use Siri that you will want to be able to speak them clearly they are all distinct from one another- and remember them. Before going further, you should give a few devices friendly names so they will be available to you when you complete these instructions. Don t do too many! Just do a few for now. You can always add, remove, or modify friendly names later. 4

5 Step 1: Installing Bonjour Getting Bonjour Bonjour is an Apple component that works with Homebridge to provide the network support it needs. This can be downloaded from the Apple web site directly but you ll need an Apple Developer account. (You can use your existing Apple ID to register for a free Developer account.) If you have one, then please download the latest version from here: SDK for Windows If you don t have one, we have captured the current download on the HCA web site and it was in the zip file you downloaded. Once you have downloaded from the Apple Web site, or you are using the installer downloaded in the zip file from the HCA web site, start the Bonjour installer. The Bonjour installer will install the following programs: Bonjour Bonjour SDK To install Bonjour, perform the following steps: 1. Double-click to launch the Bonjour installer you previously downloaded. The Welcome to the Bonjour SDK Installer screen will appear. Click Next. 5

6 2. On the License Agreement screen, read and accept the license agreement and then click Next. 3. On the About the Bonjour SDK screen, confirm the system requirements and then click Next. 6

7 4. On the Installation Options screen, accept the default installation folder and then click Install. 5. When the installer completes, click Finish. 7

8 Step 2: Installing Homebridge and the HCA Plugin Installing Homebridge and the HCA Plugin is done using a script that is run from the Windows tool called PowerShell. If you are unfamiliar with it, it is a more capable command line tool than the old tried-and-true cmd.exe (also known as the Windows DOS prompt ). It s on your computer someplace and is best found using the Windows 7, 8, or 10 Search for programs and files tool. The following instructions are for Windows 10 but starting PowerShell is similar for other versions of Windows. The PowerShell script was included in the zip file you have already downloaded. Hopefully you saved the zip file in the recommended C:\Homebridge folder and extracted it from the zip file. 8

9 To install the HCA plugin for Homebridge, run the installer.ps1 PowerShell script as Administrator. 1. From the Windows Start Menu, type PowerShell to quickly find the Windows PowerShell app. 9

10 2. Right-click Windows PowerShell then select Run as administrator. 3. When prompted Do you want to allow this app to make changes to your device?, select Yes. 4. The Windows PowerShell command window will appear. 10

11 5. Change the directory to the location of the installer.ps1 PowerShell script. a. In these instructions, the installer script has been saved to C:\Homebridge. b. In the command window, type the following command and then press Enter to change the directory: cd C:\Homebridge\ Note: Be sure to enclose the path in double-quotes ( ) if the path you re using contains spaces. 11

12 6. In the command window, carefully type the following command and then press Enter: Set-ExecutionPolicy Bypass When prompted Do you want to change the execution policy?, type Y to confirm the change. 7. In the command window, type.\installer.ps1 and then press Enter to run the script. Be sure to include the.\ prefix. 12

13 Note: When running for the first time, the installation may take several minutes to complete as supporting applications are downloaded and installed. However, you ll see feedback/details in the command window as the installation progresses. Just give it time to run. Note: You may receive a few warnings during installation. They re only warnings, and can be safely ignored. 8. The following Windows applications are installed by the script: a. Node.js b. OpenSSL 1.0.2m c. Python d. Microsoft Visual C++ Build Tools 9. In the PowerShell window, type carefully the following command and then press Enter to restore the previous (restricted) permissions: Set-ExecutionPolicy Restricted When prompted Do you want to change the execution policy?, type Y to confirm the change. 10. After the installation completes successfully, type exit and then press Enter to close the PowerShell window. 13

14 11. Using a text editor such as Notepad.exe, update the config.json configuration file with your HCA Remote Access Password and then save the file. This configuration file is located at: C:\Users\<your_user_id>\.homebridge\config.json Note: If you re installing the plugin on a different computer than the one running HCA Server, set the value of the host property to the IP address of the HCA Server. Otherwise, leave this property empty. Additionally, if you ve changed the Client-Server Communications Port in HCA from the default port 2000, update it accordingly in the config.json file. 12. Exit HCA and restart the computer. Note: This step is important to complete the installation and ensure the Bonjour DNS service is running and discoverable. 14

15 Step 3: Running Homebridge Once installed, Homebridge can be started from a standard Windows command prompt (cmd.exe). 1. From the Windows Start Menu, type cmd to quickly find the Command Prompt app, then click to open it. 2. The Command Prompt window opens. 15

16 3. In the command window type homebridge and then press Enter. Note: When starting Homebridge for the first time, you may receive a Windows Security Alert requesting to allow Node.js to communicate with devices on your local (private) network. At the prompt, choose Allow access. 16

17 4. Homebridge starts, connects to HCA Server and discovers the devices you ve made available to external assistants (via HCA). Homebridge has found all the devices, programs, and groups you provided friendly names to. 17

18 Step 4: Adding the Homebridge Accessory to ios This step works with your Apple device so have it ready and make sure that Homebridge is running and nearby. It should be if you completed the previous steps. 1. Open the Home app on your iphone, ipad, or ipod Touch and tap Add Accessory, or tap the plus (+) button in the upper-right. 2. With the camera on your ios device, scan the eight-digit HomeKit code (or QR code) in the Command Prompt window. a. If the scanned code isn t recognized, tap Don t Have a Code or Can t Scan? to enter it manually. The default code is (but this can be changed in the config.json file). When the Homebridge accessory appears, tap it. b. Depending on the number of devices discovered, you may need to scroll up to see the code. 3. If asked to confirm adding an Uncertified Accessory, tap Add Anyway. 4. Add information about your accessory and each device (as needed) and tap Next. 5. Then tap Done. For additional information on using the Home app please reference Use the Home app on your iphone, ipad, and ipod touch ( on Apple's support site. 18

19 Step 5: Restarting Apple TVs (HomeKit Hubs) If there are any Apple TVs (3 rd generation+) on your local network when you pair Homebridge with ios, they will automatically be set up as HomeKit Hubs. This will allow you to interact with your devices via a HomeKit-enabled app, and Siri, when not at home. After pairing ios with Homebridge be sure to restart all Apple TVs to ensure that everything s synced up completely and remote access is available. 19

20 Step 6: Using Siri and HomeKit Siri support in HomeKit is pretty cool. You can speak to her (or him, depending on which voice you're using) very naturally and it'll understand your requests. So, you don't have to phrase your requests in a specific or robotic manner. For example, if you ask Did I leave any lights on at home? she'll respond with something like: The Kitchen and Master Bedroom lights are on. or There are 17 lights on. if there's more than a handful. Here's some examples of what you can say: Note: Not all devices in these examples are supported by HCA. Turn on the lights. or Turn off the lights. Dim the lights. or Set the brightness to 50%. Set the temperature to 68 degrees. Turn on the coffee maker. Turn on the upstairs lights. Turn off Chloe s light. Turn down the kitchen lights. Dim the lights in the dining room to 50%. Make the living room lights the brightest. Set the Tahoe house to 72 degrees. Set the thermostat downstairs to 70. Turn on the printer in the office. Set up for a party, Siri. Set the dinner scene. Set my bedtime scene. For security purposes, some commands (like unlocking a door, or opening a garage door) require your phone to be unlocked. In these cases, she'll respond, "You'll need to unlock your iphone first." Unlock it, and she'll carry out the request! If you've got an Apple Watch, you unlock the Watch when it's on your wrist. If you don't take it off it remains unlocked and you can issue these commands (along with other things, like using Apple Pay) and Siri will carry them out immediately. 20

21 Step 7: Changes to your HCA Design If you make a change to your HCA design and add a device that you give a friendly name to, or change a friendly name on an existing device, or remove a device that has a friendly name, then you must stop Homebridge and restart it so that the change is seen. On the computer where Homebridge is running, make the Command Window the active window click on it and then press CTRL+C and then press Y when prompted to terminate the job. After that just restart Homebridge as before by typing Homebridge into the command window and pressing enter. Homebridge then starts and incorporates all your changes into what it makes available to Siri and HomeKit. Other Topics Now that you have completed the previous six steps, you should have Homebridge running. The next sections are topics that cover maintaining your work. Starting Homebridge with HCA If desired, you can create an HCA Program that starts Homebridge when HCA starts and loads your design file. Create a HCA program call it whatever you would like. The program contains only one element besides Start-Here and is the Run element. Configure that element as: 21

22 This program can be triggered by the Special Triggers HCA started normally and HCA started after power restoration. Stopping Homebridge Manually Just like HCA Server, Homebridge needs to remain running on your computer 24/7 in order for HomeKit to communicate with HCA and be available for you to interface with the Home app and Siri. When you do need to stop Homebridge manually, in the Command Prompt window press CTRL+C and then press Y when prompted to terminate the job. 22

23 Updating the HCA Plugin for Homebridge As new features and fixes become available, or to simply ensure you re running the latest build. If Homebridge is running, you ll need to stop it as shown above. You can update the plugin by typing the following command (via the Windows Command Prompt), and then press Enter: npm update -g homebridge-hca and then restart Homebridge by typing the following command, and then press Enter: homebridge Tip: To get the version of the plugin that s currently installed, type the following command and then press Enter: npm list -g homebridge-hca 23

24 Uninstalling the HCA Plugin for Homebridge If there s a need to uninstall the HCA Plugin for Homebridge, you can use the installer script to remove the plugin, along with all of its dependencies (those that were installed by the script). Open a PowerShell command window (as Administrator), type the following command and then press Enter:.\installer.ps1 --uninstall and then press Enter to run the script which will uninstall all of the packages that were installed by the installer. Be sure to include the.\ prefix. 24

25 The following applications will be uninstalled by the script: Node.js OpenSSL 1.0.2m Python Microsoft Visual C++ Build Tools If not used outside of Homebridge, the following applications may be manually uninstalled: Bonjour SDK Bonjour 25

26 Troubleshooting Common Issues My ios App Can't Find Homebridge There are two reasons why Homebridge may not be discoverable: Homebridge server thinks it's been paired with, but ios thinks otherwise. o Fix: Delete the persist/ folder which is next to your config.json file. ios device has gotten your Homebridge username (looks like a MAC address) "stuck" somehow, where it's in the database but inactive. o Fix: Change your username in the "bridge" section of config.json to be some new value. My ios App Shows Devices in an Updating State Ensure you have Wi-Fi or cellular connectivity. Restart the computer hosting Homebridge as well as all Apple TVs (3 rd gen+) on your local network. ##end## 26