GettingStartedwiththeHCAPluginforHomebridgeUpdated12-Nov-17

2

TableofContents

Introduction...........................................................................................................................3

GettingReady........................................................................................................................3

Step1:InstallingBonjour.......................................................................................................5

Step2:InstallingHomebridgeandtheHCAPlugin..................................................................8

Step3:RunningHomebridge.................................................................................................15

Step4:AddingtheHomebridgeAccessorytoiOS..................................................................18

Step5:RestartingAppleTVs(HomeKitHubs)........................................................................19

Step6:UsingSiriandHomeKit..............................................................................................20

Step7:ChangestoyourHCAdesign......................................................................................21

OtherTopics..........................................................................................................................21StartingHomebridgewithHCA.......................................................................................................21StoppingHomebridgeManually.....................................................................................................22UpdatingtheHCAPluginforHomebridge.......................................................................................23UninstallingtheHCAPluginforHomebridge..................................................................................24

TroubleshootingCommonIssues...........................................................................................26

3

IntroductionHomebridgeHomebridgeissetofsoftwarepackagesthatrunonacomputeronyourhomenetwork-typicallyinstalledonthesamecomputerwhereyouruntheHCAserver.ItprovidesaconnectionbetweentheHCAserverandAppleHomeKitprogramsandSiri,theAppleVoiceAssistant.Unlikepurchasedsoftwareyoumightbefamiliarwith–likeHCA-Homebridgeis“opensource”andissupportedbymanydevelopers.ThegoodnewsisthatthereisnocosttosetupHomebridgeonyoursystemandsogetaccesstoallthatAppleHomeKitcando.Also,HomebridgesupportsmorethanjustHCAandonceyougetitalltoworkwithHCAyoucanthenaddmore“plugin”modulestosupportotherhomeautomationgear.Theless-than-goodnewsisthatitwilltakeabitofefforttogetitallconfiguredonyourcomputer.QuiteabitmorethangettingHCAinstalled,buttheseinstructionstakeyouthroughtheprocessstep-by-stepandifyoucarefullyfollowalongthenallwillinstallwithoutproblems.WithSiriandHomeKityoucancontrolallthedevicesthatHCAmanagesaswellasHCAgroupsandprograms.ThisgivesyouaccesstowhatHomeKitnormallycan’thandle.TouseHomeKitandSiriyouwillneedanApplehardwaredevice.SupportedareanAppleTV(4thgeneration+),andAppleWatch,oraHomeKit-supportedapponaniPhone,iPad,oriPodTouch(5thgeneration+).Moreinformationaboutwhatisandisn’tsupportedcanbefoundontheApplewebsite.ForadditionalinformationonHomebridge,pleasereference:https://www.npmjs.com/package/homebridgeForavailableHomebridgeplugins,pleasereference:https://www.npmjs.com/search?q=homebridge-pluginNoneofthisHomebridgeandHomeKitsupportusestheHCACloudorrequiresthatyouhaveaHCACloudaccount.

GettingReadyBeforeyoubegin,makesurethatyouarerunningHCAPlusversion14.1orlaterandthatyouaresuccessfullyrunningtheHCAServerandcanconnecttoitusingtheWindowsormobileclients.IfyouhavenotalreadyworkedwithHCAinclient-servermode,youshouldstopandgoreadtheHCAGettingStartedguidewhichtakesyouthroughthatsetup.Getthatworkingthencomebacktothis.

4

UnlessyouhaveagoodreasonandhaveworkedwithHomebridgealready,youshouldinstallthesenewcomponentsonthesamecomputerthatisrunningtheHCAserver.ThefirststepistodownloadfromtheHCAwebsiteazipfilethatcontainsfilesneededforHomebridge.Youcansavethiszipfileinanyfolder,butitwouldbebestifyoufirstcreatedanewfolderonyourdiskandsavethefilethere.Thiswillmakeitsimplertofollowalongwiththeinstructionsbelow.Createafolder“C:\Homebridge”andthenclickonthislinktodownloadusingyourbrowserandsavethezipfiletothatfolder.www.HCATech.com/download/Homebridge/Homebridge_HCA.zipUseanunzipprogram,orthebuilt-inoneinWindowsexplorer,toextractthefilescontainedinthezipfileintothatsame“C:\Homebridge”folder.Onceyouhavecompletedtheinstallation,whatcanyoucontrolusingSiriandHomeKit?Thosedevices,programs,andgroupsthatyouhaveassigneda“friendlyname”toandthatHomeKitaccepts.A“friendlyname”isanalternativenameforoneoftheseobjectsthatmaybeeasiertousethanthenameyougavetoitinHCA.Forexample,youmayhaveadevicenamed“Counterleftcornerlight”inthe“Kitchen”room.Itwouldbesimplerifyoucouldjustsay“kitchencounterlight”ratherthan“Kitchencounterleftcornerlight”.Generally,HomeKitunderstandsdevicesthathavealoadandcanbecontrolledon,off,andifthehardwaresupportsit,toagivenlevel.IfyousupplyafriendlynametoadevicethatHomeKitcan’thandle,thenitwillbeunavailable.Friendlynamescanbeseenonthe“Name”tabofthepropertiesofadevice,program,orgroup.Youcanalsoseeallyourobjectsatonetimeandassignfriendlynamestherebypressingthe“ExternalAssistantsConfiguration”buttoninthe“HCACloud”ribboncategory.Allfriendlynamesmustbeuniqueandcanonlybecomposedofletters–nospecialcharacters–andblanks.RememberwhenassigningfriendlynamesthatifyouuseSirithatyouwillwanttobeabletospeakthemclearly–theyarealldistinctfromoneanother-andrememberthem.Beforegoingfurther,youshouldgiveafewdevicesfriendlynamessotheywillbeavailabletoyouwhenyoucompletetheseinstructions.Don’tdotoomany!Justdoafewfornow.Youcanalwaysadd,remove,ormodifyfriendlynameslater.

5

Step1:InstallingBonjourGettingBonjourBonjourisanApplecomponentthatworkswithHomebridgetoprovidethenetworksupportitneeds.ThiscanbedownloadedfromtheApplewebsitedirectlybutyou’llneedanAppleDeveloperaccount.(YoucanuseyourexistingAppleIDtoregisterforafreeDeveloperaccount.)Ifyouhaveone,thenpleasedownloadthelatestversionfromhere:https://developer.apple.com/download/more/?=BonjourSDKforWindowsIfyoudon’thaveone,wehavecapturedthecurrentdownloadontheHCAwebsiteanditwasinthezipfileyoudownloaded.OnceyouhavedownloadedfromtheAppleWebsite,oryouareusingtheinstallerdownloadedinthezipfilefromtheHCAwebsite,starttheBonjourinstaller.TheBonjourinstallerwillinstallthefollowingprograms:

• Bonjour• BonjourSDK

ToinstallBonjour,performthefollowingsteps:

1. Double-clicktolaunchtheBonjourinstalleryoupreviouslydownloaded.The“WelcometotheBonjourSDKInstaller”screenwillappear.ClickNext.

6

2. Onthe“LicenseAgreement”screen,readandacceptthelicenseagreementandthenclickNext.

3. Onthe“AbouttheBonjourSDK”screen,confirmthesystemrequirementsandthenclickNext.

7

4. Onthe“InstallationOptions”screen,acceptthedefaultinstallationfolderandthenclickInstall.

5. Whentheinstallercompletes,clickFinish.

8

Step2:InstallingHomebridgeandtheHCAPluginInstallingHomebridgeandtheHCAPluginisdoneusingascriptthatisrunfromtheWindowstoolcalled“PowerShell”.Ifyouareunfamiliarwithit,itisamorecapablecommandlinetoolthantheoldtried-and-truecmd.exe(alsoknownasthe“WindowsDOSprompt”).It’sonyourcomputersomeplaceandisbestfoundusingtheWindows7,8,or10“Searchforprogramsandfiles”tool.ThefollowinginstructionsareforWindows10butstartingPowerShellissimilarforotherversionsofWindows.ThePowerShellscriptwasincludedinthezipfileyouhavealreadydownloaded.HopefullyyousavedthezipfileintherecommendedC:\Homebridgefolderandextracteditfromthezipfile.

9

ToinstalltheHCApluginforHomebridge,runtheinstaller.ps1PowerShellscriptasAdministrator.

1. FromtheWindowsStartMenu,type“PowerShell”toquicklyfindtheWindowsPowerShellapp.

10

2. Right-clickWindowsPowerShellthenselect“Runasadministrator”.

3. Whenprompted“Doyouwanttoallowthisapptomakechangestoyourdevice?”,selectYes.

4. TheWindowsPowerShellcommandwindowwillappear.

11

5. Changethedirectorytothelocationoftheinstaller.ps1PowerShellscript.a. Intheseinstructions,theinstallerscripthasbeensavedto“C:\Homebridge”.b. Inthecommandwindow,typethefollowingcommandandthenpressEnterto

changethedirectory:cd “C:\Homebridge\”Note:Besuretoenclosethepathindouble-quotes(“”)ifthepathyou’reusingcontainsspaces.

12

6. Inthecommandwindow,carefullytypethefollowingcommandandthenpressEnter:Set-ExecutionPolicy BypassWhenprompted“Doyouwanttochangetheexecutionpolicy?”,typeYtoconfirmthechange.

7. Inthecommandwindow,type.\installer.ps1andthenpressEntertorunthescript.Besuretoincludethe“.\”prefix.

13

Note:Whenrunningforthefirsttime,theinstallationmaytakeseveralminutestocompleteassupportingapplicationsaredownloadedandinstalled.However,you’llseefeedback/detailsinthecommandwindowastheinstallationprogresses.Justgiveittimetorun.Note:Youmayreceiveafewwarningsduringinstallation.They’reonlywarnings,andcanbesafelyignored.

8. ThefollowingWindowsapplicationsareinstalledbythescript:a. Node.jsb. OpenSSL1.0.2mc. Python2.7.13d. MicrosoftVisualC++BuildTools

9. InthePowerShellwindow,typecarefullythefollowingcommandandthenpressEnter

torestoretheprevious(restricted)permissions:Set-ExecutionPolicy Restricted Whenprompted“Doyouwanttochangetheexecutionpolicy?”,typeYtoconfirmthechange.

10. Aftertheinstallationcompletessuccessfully,typeexitandthenpressEntertoclosethePowerShellwindow.

14

11. UsingatexteditorsuchasNotepad.exe,updatetheconfig.jsonconfigurationfilewithyourHCARemoteAccessPasswordandthensavethefile.Thisconfigurationfileislocatedat:C:\Users\<your_user_id>\.homebridge\config.json

Note:Ifyou’reinstallingthepluginonadifferentcomputerthantheonerunningHCAServer,setthevalueofthehostpropertytotheIPaddressoftheHCAServer.Otherwise,leavethispropertyempty.Additionally,ifyou’vechangedtheClient-ServerCommunicationsPortinHCAfromthedefaultport‘2000’,updateitaccordinglyintheconfig.jsonfile.

12. ExitHCAandrestartthecomputer.Note:ThisstepisimportanttocompletetheinstallationandensuretheBonjourDNSserviceisrunninganddiscoverable.

15

Step3:RunningHomebridgeOnceinstalled,HomebridgecanbestartedfromastandardWindowscommandprompt(cmd.exe).

1. FromtheWindowsStartMenu,type“cmd”toquicklyfindtheCommandPromptapp,thenclicktoopenit.

2. TheCommandPromptwindowopens.

16

3. InthecommandwindowtypehomebridgeandthenpressEnter.

Note:WhenstartingHomebridgeforthefirsttime,youmayreceiveaWindowsSecurityAlertrequestingtoallowNode.jstocommunicatewithdevicesonyourlocal(private)network.Attheprompt,choose“Allowaccess”.

17

4. Homebridgestarts,connectstoHCAServeranddiscoversthedevicesyou’vemadeavailabletoexternalassistants(viaHCA).

Homebridgehasfoundallthedevices,programs,andgroupsyouprovidedfriendlynamesto.

18

Step4:AddingtheHomebridgeAccessorytoiOSThisstepworkswithyourAppledevicesohaveitreadyandmakesurethatHomebridgeisrunningandnearby.Itshouldbeifyoucompletedtheprevioussteps.

1. OpentheHomeapponyouriPhone,iPad,oriPodTouchandtapAddAccessory,ortaptheplus(+)buttonintheupper-right.

2. WiththecameraonyouriOSdevice,scantheeight-digitHomeKitcode(orQRcode)intheCommandPromptwindow.

a. Ifthescannedcodeisn’trecognized,tap“Don’tHaveaCodeorCan’tScan?”toenteritmanually.Thedefaultcodeis031-45-154(butthiscanbechangedintheconfig.jsonfile).WhentheHomebridgeaccessoryappears,tapit.

b. Dependingonthenumberofdevicesdiscovered,youmayneedtoscrolluptoseethecode.

3. Ifaskedtoconfirmaddingan“UncertifiedAccessory”,tapAddAnyway.4. Addinformationaboutyouraccessoryandeachdevice(asneeded)andtapNext.5. ThentapDone.

ForadditionalinformationonusingtheHomeapppleasereferenceUsetheHomeapponyouriPhone,iPad,andiPodtouch(https://support.apple.com/en-us/HT204893)onApple'ssupportsite.

19

Step5:RestartingAppleTVs(HomeKitHubs)IfthereareanyAppleTVs(3rdgeneration+)onyourlocalnetworkwhenyoupairHomebridgewithiOS,theywillautomaticallybesetupasHomeKitHubs.ThiswillallowyoutointeractwithyourdevicesviaaHomeKit-enabledapp,andSiri,whennotathome.AfterpairingiOSwithHomebridgebesuretorestartallAppleTVstoensurethateverything’ssyncedupcompletelyandremoteaccessisavailable.

20

Step6:UsingSiriandHomeKit SirisupportinHomeKitisprettycool.Youcanspeaktoher(orhim,dependingonwhichvoiceyou'reusing)verynaturallyandit'llunderstandyourrequests.So,youdon'thavetophraseyourrequestsinaspecificorroboticmanner.Forexample,ifyouask“DidIleaveanylightsonathome?”she'llrespondwithsomethinglike:“TheKitchenandMasterBedroomlightsareon.”or“Thereare17lightson.”ifthere'smorethanahandful.Here'ssomeexamplesofwhatyoucansay:Note:NotalldevicesintheseexamplesaresupportedbyHCA.

• “Turnonthelights.”or“Turnoffthelights.”• “Dimthelights.”or“Setthebrightnessto50%.”• “Setthetemperatureto68degrees.”• “Turnonthecoffeemaker.”• “Turnontheupstairslights.”• “TurnoffChloe’slight.”• “Turndownthekitchenlights.”• “Dimthelightsinthediningroomto50%.”• “Makethelivingroomlightsthebrightest.”• “SettheTahoehouseto72degrees.”• “Setthethermostatdownstairsto70.”• “Turnontheprinterintheoffice.”• “Setupforaparty,Siri.”• “Setthedinnerscene.”• “Setmybedtimescene.”

Forsecuritypurposes,somecommands(likeunlockingadoor,oropeningagaragedoor)requireyourphonetobeunlocked.Inthesecases,she'llrespond,"You'llneedtounlockyouriPhonefirst."Unlockit,andshe'llcarryouttherequest!Ifyou'vegotanAppleWatch,youunlocktheWatchwhenit'sonyourwrist.Ifyoudon'ttakeitoffitremainsunlockedandyoucanissuethesecommands(alongwithotherthings,likeusingApplePay)andSiriwillcarrythemoutimmediately.

21

Step7:ChangestoyourHCADesignIfyoumakeachangetoyourHCAdesignandaddadevicethatyougiveafriendlynameto,orchangeafriendlynameonanexistingdevice,orremoveadevicethathasafriendlyname,thenyoumuststopHomebridgeandrestartitsothatthechangeisseen.OnthecomputerwhereHomebridgeisrunning,maketheCommandWindowtheactivewindow–clickonit–andthenpressCTRL+Candthenpress“Y”whenpromptedtoterminatethejob.AfterthatjustrestartHomebridgeasbeforebytyping“Homebridge”intothecommandwindowandpressingenter.HomebridgethenstartsandincorporatesallyourchangesintowhatitmakesavailabletoSiriandHomeKit.

OtherTopicsNowthatyouhavecompletedtheprevioussixsteps,youshouldhaveHomebridgerunning.Thenextsectionsaretopicsthatcovermaintainingyourwork.StartingHomebridgewithHCAIfdesired,youcancreateanHCAProgramthatstartsHomebridgewhenHCAstartsandloadsyourdesignfile.CreateaHCAprogram–callitwhateveryouwouldlike.Theprogramcontainsonlyoneelementbesides“Start-Here”andisthe“Run”element.Configurethatelementas:

22

ThisprogramcanbetriggeredbytheSpecialTriggers“HCAstartednormally”and“HCAstartedafterpowerrestoration”.

StoppingHomebridgeManuallyJustlikeHCAServer,Homebridgeneedstoremainrunningonyourcomputer24/7inorderforHomeKittocommunicatewithHCAandbeavailableforyoutointerfacewiththeHomeappandSiri.WhenyoudoneedtostopHomebridgemanually,intheCommandPromptwindowpressCTRL+Candthenpress“Y”whenpromptedtoterminatethejob.

23

UpdatingtheHCAPluginforHomebridgeAsnewfeaturesandfixesbecomeavailable,ortosimplyensureyou’rerunningthelatestbuild.IfHomebridgeisrunning,you’llneedtostopitasshownabove.Youcanupdatethepluginbytypingthefollowingcommand(viatheWindowsCommandPrompt),andthenpressEnter:npm update -g homebridge-hca andthenrestartHomebridgebytypingthefollowingcommand,andthenpressEnter:homebridge Tip:Togettheversionofthepluginthat’scurrentlyinstalled,typethefollowingcommandandthenpressEnter:npm list -g homebridge-hca

24

UninstallingtheHCAPluginforHomebridgeIfthere’saneedtouninstalltheHCAPluginforHomebridge,youcanusetheinstallerscripttoremovetheplugin,alongwithallofitsdependencies(thosethatwereinstalledbythescript).OpenaPowerShellcommandwindow(asAdministrator),typethefollowingcommandandthenpressEnter:.\installer.ps1 --uninstall andthenpressEntertorunthescriptwhichwilluninstallallofthepackagesthatwereinstalledbytheinstaller.Besuretoincludethe“.\”prefix.

25

Thefollowingapplicationswillbeuninstalledbythescript:• Node.js• OpenSSL1.0.2m• Python2.7.13• MicrosoftVisualC++BuildTools

IfnotusedoutsideofHomebridge,thefollowingapplicationsmaybemanuallyuninstalled:

• BonjourSDK• Bonjour

26

TroubleshootingCommonIssuesMyiOSAppCan'tFindHomebridgeTherearetworeasonswhyHomebridgemaynotbediscoverable:

• Homebridgeserverthinksit'sbeenpairedwith,butiOSthinksotherwise.o Fix:Deletethepersist/folderwhichisnexttoyourconfig.jsonfile.

• iOSdevicehasgottenyourHomebridgeusername(lookslikeaMACaddress)"stuck"somehow,whereit'sinthedatabasebutinactive.

o Fix:Changeyourusernameinthe"bridge"sectionofconfig.jsontobesomenewvalue.

MyiOSAppShowsDevicesinan“Updating…”State

• EnsureyouhaveWi-Fiorcellularconnectivity.• RestartthecomputerhostingHomebridgeaswellasallAppleTVs(3rdgen+)onyour

localnetwork.##end##