Create Homes and add Accessories


May 22, 2021 01:00 HomeKit App Development guide


Table of contents


Create Homes and add Accessories

HomeKit objects are saved in a shareable HomeKit database that can be accessed by multiple English-ing programs through the HomeKit framework. A ll HomeKit-called methods are written asynchronously, and they contain a completed parameter. I f this method is successful, your app will update the local object in the completion handler. W hen the application starts, does the HomeKit object change and does not receive a proxy callback? only accept callback functions after processing is complete.

To see how the HomeKit object changes when other applications start, see: Observing HomeKit Database Changes. For information about error codes passed over after asynchronous messages have been processed, see: HomeKit Constants Reference.

Object naming rules

The names of HomeKit objects, such as home, room, and zone objects, can be recognized by Siri, as noted in the documentation. The following are the naming rules for HomeKit objects:

  • The object name must be unique within its namespace.
  • The home names that belong to the user are in a namespace.
  • One home object and the objects it contains are in another namespace.
  • A name can only contain numbers, letters, spaces, and ellistic characters.
  • The name must start with a number or letter character.
  • Spaces or omit marks are ignored when comparing names (for example, home1 and home 1 have the same name).
  • The name is not cased.

To think about which languages users can interact with Siri, see Siri Integration in the HomeKit User Interface Guidelines documentation.

Create Homes

Use addHomeWithName:completeHandler in the HMHomeManager class: The asynchronous method can add a home. The name of the home passed to that method as an argument must be unique and the home name that Siri can recognize.

[self.homeManager addHomeWithName:@"My Home"
completionHandler:^(HMHome *home, NSError *error) {
if (error != nil) {
// Failed to add a home
} else {
// Successfully added a home
} }];

In the else statement, write code to update the view of the program you should. To get the home manager object, see Get the Home Manager Object.

Add a Room to Home

Using addRoomWithName:completeHandler: Asynchronous methods can add a room object to a home. The room name passed to that method as an argument must be unique and Siri-recognizable room name.

NSString *roomName = @"Living Room";
[home addRoomWithName:roomName completionHandler:^(HMRoom
*room, NSError *error) {
if (error != nil) {
// Failed to add a room to a home
} else {
// Successfully added a room to a home
} }];

In the else statement, write code to update the view of the application.

Discover accessories

Accessories encapsulates the state of the physical accessory, so it cannot be created by the user. T o allow users to add new accessories to their home, we can have the HMAccessoryBrowser object find an accessory that is not associated with home. T he HMAccessoryBrower object searches for accessories in the background and uses delegates to notify your app when it finds them. The HMAccessoryBrowserDelegate message is sent to the proxy object only after the startSearchingForNewAccessories method call or before the stopSearchingForNewAccessories method call.

Discover accessories in home

1. Add an accessory browser delegate protocol to your class interface and add an accessory browser property. The code is as follows:

@interface EditHomeViewController ()
@property HMAccessoryBrowser *accessoryBrowser;
@end

Replace EditHomeViewController with your own class name

2. Create an accessory browser object and set its proxy

self.accessoryBrowser = [[HMAccessoryBrowser alloc] init];
self.accessoryBrowser.delegate = self;

3. Start searching for accessories

[self.accessoryBrowser startSearchingForNewAccessories];

4. Add the accessories you find to your collection

- (void)accessoryBrowser:(HMAccessoryBrowser *)browser
didFindNewAccessory:(HMAccessory *)accessory {
// Update the UI per the new accessory; for example,
reload a picker
view.
[self.accessoryPicker reloadAllComponents];
}

Use your own code to implement the above accessoryBrowser: didFindNewAccessory: Method. Of course, accessoryBrowser: didRemoveNewAccessory: This method removes accessories that are no longer new to your view or collection.

5. Stop searching for accessories

If a view controller is starting to search for accessories, you can stop searching for accessories by rewriting viewWillDisappear: Method. The code is as follows:

- (void)viewWillDisappear:(BOOL)animated {
[self.accessoryBrowser stopSearchingForNewAccessories];
}

Note: In a WiFi network environment, see External Accessory Framework Reference for secure access to new wireless accessories that can be discovered by HomeKit.

Add accessories for Home and room

The accessory belongs to home, and it can be added to any room in home at will. U se addAccessory:completeHandler: This asynchronous method adds accessories to home. T he name of the accessory is passed as an argument to the asynchronous method above, and the name must be unique in the home to which the accessory belongs. U sing assignAccessory:toRoom:completeHandler: This asynchronous method adds accessories to the room in home. T he default room for accessories is roomForEntireHome, which returns the value room. The following code shows how to add accessories to home and room:

// Add an accesory to a home and a room
// 1. Get the home and room objects for the completion
handlers.
__block HMHome *home = self.home;
__block HMRoom *room = roomInHome;
// 2. Add the accessory to the home
[home addAccessory:accessory completionHandler:^(NSError
*error) {
if (error) {
// Failed to add accessory to home
} else {
if (accessory.room != room) {
// 3. If successfully, add the accessory to
the room
[home assignAccessory:accessory toRoom:room
completionHandler:^(NSError *error) {
if (error) {
// Failed to add accessory to room
} }];
} }
}];

Accessories can provide one or more services that are defined by the manufacturer. For service and feature purposes for accessories, see Accessing Services and Features.

Change the name of the accessory

Use updateName:completeHandler: Asynchronous methods can change the name of an accessory, as follows:

[accessory updateName:@"Kid's Night Light"
completionHandler:^(NSError *error) {
if (error) {
// Failed to change the name
} else {
// Successfully changed the name
}
}];

Add Bridge for Homes and Room

The bridge interface is a special object in the accessory that allows you to communicate with other accessories, but does not allow you to communicate directly with HomeKit. F or example, a bridge interface can be a hub that controls multiple lights, using its own communication protocol instead of the HomeKit accessory communication protocol. T o add multiple bridge interfaces to home, you can add any type of accessory to home by following the steps described in Add Accessories to Homes and Rooms. W hen you add a bridge interface to home, accessories at the bottom of the bridge interface are also added to home. A s described in Observing HomeKit Database Changes, each time you change the notification design mode, home's agent does not receive the home:didAddAccessory: agent message for the bridge interface, but instead receives a home:didAddAccessory: proxy message for the accessory. I n home, look at the accessories behind the bridge interface as if they were of any type -- for example, add them to the configuration table for the accessories list. Conversely, when you add a bridge interface to the room, the accessories at the bottom of the bridge interface are not automatically added to the room because the bridge interface and its accessories can be located in different rooms.

Create a partition

Zone (HMZone) is any optional room grouping; Rooms can be added to one or more areas.

Create Homes and add Accessories

You can create partitions using addZoneWithName:completeHandler: Asynchronous methods. T he name of the partition that was created as an argument passed to this method must be unique in home and should be recognized by Siri. The code is as follows:

__block HMHome *home = self.home;
NSString *zoneName = @"Upstairs";
[home addZoneWithName:zoneName completionHandler:^(HMZone
*zone, NSError *error)
{
if (error) {
// Failed to create zone
} else {
// Successfully created zone, now add the rooms
}
}];

You can use addRoom:completeHandler: Asynchronously to add a room to the partition, code as follows:

__block HMRoom *room = roomInHome;
[zone addRoom:room completionHandler:^(NSError *error) {
if (error) {
// Failed to add room to zone
} else {
// Successfully added room to zone
} }];