getting started with the hca plugin for homebridge started...3 introduction homebridge homebridge is...
TRANSCRIPT
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##