Getting Started With HomeKit and NativeScript

HomeWhat?

HomeKit is Apple's gateway to all your (compatible) home automation devices. You can either use the Home app on your iOS device to control them or be a cool kid and build your own app with the freshly released NativeScript HomeKit plugin.

You're a cool kid, right?

Yes, but I don't have any HomeKit devices.

No worries! Just download the HomeKit Simulator, which is part of the Hardware IO Tools, open the downloaded Simulator, then add a new accessory as shown in this picture. Now you're ready to build and play! 

Just Want to Play With a {N} HomeKit app?

Head over to the plugin's GitHub repo and follow the instructions on how to deploy the demo app to on phone. Here's the demo app in action:

First Up: Creating a Home

As the name suggests, HomeKit revolves around (one or more) Homes, so we need to start there. Let's use TypeScript as this plugin exposes convenient TS wrapper classes like Home, Room, Zone, Accessory, and Service.

import { HomeKit } from "nativescript-homekit";
import { prompt, PromptResult } from "ui/dialogs";
​
// instantiate the plugin's main Class
const homeKit = new HomeKit();
​
// ask the user for a name and add it to HomeKit
prompt("Name the home").then((promptResult: PromptResult) => {
if (promptResult.result) {
homekit.addHome(promptResult.text).then(
(home: Home) => console.log(`Added home named ${home.name}`),
err => alert(err)
);
}
});

Note that, as with any entity you feed to HomeKit, the Home is saved to the HomeKit database on your device and is shared with other iOS devices connected to the same Apple ID.

Adding Rooms to Homes

As that demo app video above shows, you can add rooms to a home. An accessory (a HomeKit compatible device) can be added to either the home or the room.

// the home you created earlier
let homeName = home.name;
​
// ask the user for a name and add it to HomeKit
prompt(`Name the room to add to ${homeName}`).then((promptResult: PromptResult) => {
if (promptResult.result) {
homekit.addRoomToHome(promptResult.text, homeName).then(
(room: Room) => console.log(`Added room ${room.name} to home ${homeName}`),
err => alert(err)
);
}
});

You can also add "zones" (upstairs, downstairs, garden) to your home and assign multiple rooms to a zone. It's surprisingly easy once you know how to work with rooms. Read the plugin documentation for details and code samples.

Searching and Assigning Accessories

To add an accessory to a home or room we first need to "search" for them. Once found, we can assign them to a home. For brevity, assigning to a room is not shown here.

// start searching
homekit.startSearchingForAccessories(
// event handler which is triggered when a new accessory is found
(accessory: Accessory) => {
console.log(`New accessory found: ${accessory.name}`);
// once found you can assign it to a home
homekit.addAccessoryToHome(accessory.name, homeName)
.then(added => console.log(`Added? ${added}`));
},
// event handler which is triggered when an accessory was removed
(accessory: Accessory) => {
console.log(`Accessory removed: ${accessory.name}`);
});
​
// stop searching
homekit.stopSearchingForAccessories().then(() => console.log("Stopped searchin'"));

Working With Services and Characteristics

An accessory has services. A garage door opener may have a service to actually open or close the garage door. A service has characteristics (current door state). Both of these can be queried with the plugin:

// import a few Classes we're gonna use
import { Accessory, Service, Characteristic } from 'nativescript-homekit';
​
// given an accessory..
let accessory: Accessory = myPreviouslyFoundAccessory;
​
// .. you can now list its services..
accessory.services.forEach((s: Service) => {
console.log(`Service ${s.name} of type ${s.type} has ${s.characteristics.length} characteristics`);
​
// .. and the service characteristics
s.characteristics.forEach((c: Characteristic) => {
console.log(`Characteristic ${c.description} is of type ${c.type}`);
});
});

Where to Go From Here

To further interact with any of the Classes shown here (Home, Room, Zone, Accessory, Service, and Characteristic), the plugin exposes an ios property on all of those. The plugin documentation links to the native Classes represented by those properties so you can invoke any additional functions your app may require.

Did you add a feature to your fork of the plugin that others may find useful, as well? As always, please submit a pull request.