Add support for Matter in your smart home app

Add support for Matter in your smart home app

The enhanced and new APIs in HomeKit enable smart home developers to integrate with the new Matter protocol in the most convenient way. Tour the Matter protocol, and discover how to set up and manage Matter accessories on our platforms and within your smart home apps.

Resources
- - HD Video
  - SD Video
Download

Hello, everyone! Welcome to our WWDC21 session, "Add support for Matter in your smart home app." I'm Selina from Home Engineering. Today, my colleague, Chris, Sagar, and I will walk you through the exciting features we've added this year for Matter support. As mentioned in Monday's keynote, Matter is a new standard for smart home accessories being developed by Apple and other industry leaders to ensure that all smart home accessories work together seamlessly moving forward. Its vision is to democratize home automation worldwide, making it possible for people to begin building smart homes, and then continue adding to them for years to come. The Matter protocol is being developed as an open source effort which leverages proven technologies, including HomeKit, ensuring that it will support the broadest amount of smart home devices, and then make it easy for manufacturers to begin integrating it into their products. Using Matter, smart home accessory manufacturers no longer need to support multiple protocols in parallel, truly simplifying the development effort of making a product and supporting it on an ongoing basis. It also gives app developers an opportunity to focus on developing the best app experience for their customers, without the burden to create and then maintain proprietary protocols. By creating such a unified protocol for accessories, customers can easily enjoy the conveniences of a smart home and then confidently bring products into their homes, knowing they will all work together. It will enable more accessories for people to choose from in stores, and then builders everywhere will be able to install them as standard into homes. Motivated by these, we would love our developers to be able to use Matter the soonest in your accessory and app development. We're glad to let you know that the support for Matter is coming in iOS, iPadOS, and in tvOS 15 as a developer preview. There are many great features that we would like to introduce to you today. First and then foremost, let's talk about how you can integrate with Matter accessories via HomeKit. Today, an accessory implementing the HomeKit Accessory Protocol integrates with Apple Home via the HomeKit framework. Over the years, we have built great features on top of HomeKit that provides full control and then management of HAP accessories. When we look at integrating Matter accessories with Apple Home, we naturally came to the conclusion that we could expand the responsibility of the HomeKit framework to support Matter as a parallel protocol. Architecturally, this means that a HomeKit calls into the open source Matter implementation, as known as CHIP framework, in order to communicate with Matter accessories. For your context, the earlier name for the Matter project was Connected Home over IP, or, in short, CHIP. That's why, throughout today's talk, you will still see the reference of CHIP, both in the open source project and our APIs. We expect to have updated naming for the APIs in a later release. Back to our main topic, the encapsulation provided by HomeKit allows all existing Apple Home features to begin working with Matter accessories seamlessly and immediately. For example, setting up a Matter accessory using identical flows to HAP accessory setup, controlling Matter accessories in Control Center with just one swipe down, and the great hands-free integration with Siri for Matter accessory status and then control across all your Apple devices. But HomeKit's responsibility isn't just to support first-party features. In fact, since day 1, we designed HomeKit with the vision that app developers should be able to leverage HomeKit to build creative and then delightful smart home apps for their customers, without the burden to implement communication protocols with accessories. This continues to be true with Matter accessories. Keep using existing APIs as you've been using in HomeKit. They will all just start working with Matter accessories, no code change needed. Let's take accessory setup as an example. This code shows how you could call the addAndSetupAccessories API in your HomeKit app today. With iOS 15 developer preview, the QR code scanner you invoke by this API will not only work for HAP QR codes, but also start recognizing Matter QR codes, providing your customers a familiar and a consistent experience for accessory setup. For a bit of fun, those of you who have been paying close attention to this year's Swift updates know that there's a shift underway in the world of Swift concurrency. We are glad to let you know that the same APIs you are used to can now be invoked via the new Swift async/await paradigm, as well. Besides setup, with iOS 15 developer preview, you will also be able to use existing HomeKit APIs to read and write Matter accessory states. Moreover, you will automatically get remote access and timely notifications for Matter accessories, and then be able to add and edit Matter accessories using scene and automation APIs, all in the same way as what you do with HAP accessories.
Let's also take a sneak peak into the future. As Matter project continues to develop, we expect it to provide support for more and more accessory categories. We will continue integrating these new Matter accessory categories into HomeKit, making it effortless for our developers to use them. Secondly, HAP, as a protocol, supports custom characteristics. It allows manufacturers to build creative custom features with their accessories and access them through HomeKit. Matter, as a protocol, supports custom features, too. So, we'd like to connect the dots here and then provide you access to Matter custom features via HomeKit framework. This feature will be coming in the later release, so stay tuned, and let us know if you have early thoughts. In short, we are committed to seamlessly integrating Matter with HomeKit. Whether you are an accessory developer, a HomeKit app developer, or a HomeKit customer, rest easy, as Matter "Just Works." When you use HomeKit to integrate with Matter accessories, you get features like secured remote control and automations for free, thanks to the power and intelligence of Apple smart home hubs, such as HomePod and Apple TV. But if you also have a need to help your customers to connect Matter accessories with other smart home hubs in your homes, we are making it easy for you to do so from your iOS app, as well. Next, I'm going to pass to Chris to tell you more about it. Thank you, Selina. For this year's developer preview, we are building a new, yet conceptually familiar setup API that enables you to establish a direct connection between a Matter accessory and your home hubs. Let's start by exploring the user experience. As you can see here, this flow strongly resembles how we set up both Apple products and HomeKit accessories today. We know our customers are familiar with this flow, we know they love it, and we want you to benefit from it, too. It is important to note here that while this is system UI, the homes and rooms the user selects from are vended from your app. Your app is responsible for completing required operations and providing requested information to set up via a new app extension type. Let's unpack this for you step by step. Before beginning setup, your app creates a topology object representing the homes it manages. It then passes this topology object to a new setup API. At this point, setup is launched and ready to scan a Matter QR code. Here's a code example for invocation. As you can see, this API is conceptually very similar to the existing HomeKit APIs for accessory setup. The major difference is the addition of the HMCHIPServiceTopology object, which is used to inform setup of the homes your app manages. When the user scans a Matter QR code with the scanner, setup will automatically progress to a Detected card that shows the category of accessory detected. The user is now presented with the option of adding the accessory to your app, in this example, Autohome. Once the user has elected to connect the accessory to your home hub, they may need to specify which specific home to add to. We present this screen in the event you initiated setup with a topology consisting of more than one home. If your topology consisted of only a single home, this card is skipped, as the user's intent is already known. Once the user selects a home, iOS sends a request to your extension asking it to pair with the scanned accessory's Matter payload. Your extension responds to this request via it's principle HMCHIPServiceRequestHandler subclass. When called, use CHIP framework APIs to create a secure pairing between the Matter accessory and your home hub. Next, iOS will request a list of rooms from your extension that corresponds to the selected home. These rooms are presented in UI for user selection. The code to respond to this request in your extension is straightforward. Just like the pair request, it revolves around your extension's principle HMCHIPServiceRequestHandler subclass. Simply implement this function and return the corresponding rooms that match the user's selected home. Once the user has selected a name and room for their accessory, we provide that information to your extension and ask it to configure the accessory. Just like the other request types, your extension will respond to the configuration request by using CHIP framework APIs to directly configure the accessory. Finally, after the accessory is fully configured for your app, the user will also be offered with the opportunity to use the Apple Home app, Control Center, and Siri to control this accessory. Collected in its entirety here again is the code we expect your extension to implement. Three simple functions: room request, pair accessory request, and accessory configuration request. Once you have subclassed HMCHIPServiceRequestHandler and overridden these methods, the rest of the setup experience is essentially free from a developer perspective. Things like UI presentation, transitions between steps, error handling, etc., are all handled for you. This greatly reduces the amount of code you need to write, while simultaneously providing your users a truly first-class experience. So far, we have talked about how you can use existing HomeKit APIs to integrate with Matter accessories, as well as a new API if you need to connect Matter accessories with another smart home hub. If you're a Matter accessory developer, you will also need to get familiar with the protocol itself for the purposes of firmware development. So next, my colleague, Sagar, will take us on a tour of the Matter protocol and show you the similarities between Matter and HAP.
Thanks, Chris. Let's start with the Matter data model. Every Matter accessory exposes its capabilities via the Matter data model. We can individually address these capabilities starting from the top with endpoints. Endpoints can be thought of as logically separate features of an accessory. Most accessories will only have a couple of these: one for information, like name, vendor, and model; and the other for the primary function of the accessory, for example, a light. Each endpoint can have multiple clusters within it. Each cluster represents a specific capability of that endpoint. For our light example, its light endpoint might have clusters for brightness, color, and power control. For those of us familiar with HomeKit, clusters can be thought of as equivalent to HomeKit services.
Next up, we look at what a cluster has within it. A cluster can have one or more attributes. Each attribute represents some state of the accessory. For our light example, the brightness cluster on the light will have an attribute that lets us read and control the brightness of the light. Again, Matter's attributes can be thought of as equivalent to HomeKit characteristics.
Finally, here you can see that each attribute may support a set of actions ranging from reading, writing, and reporting. In our light example, we might want reporting enabled on the on-off cluster to receive notifications from the accessory every time the light turns on or off. Matter usually offers a broad selection of APIs to configure and interact with each attribute based on its function.
These concepts we just talked about are being implemented in the open source CHIP framework, with Apple being one of the key contributors. As Selina mentioned earlier, CHIP has been renamed to Matter, but the framework and the code will be updated in a future release. A fully-certified version of CHIP framework will be distributed in iOS, which enables HomeKit integration with Matter accessories, and also provides access to open source APIs if you need to use them in your app. Let's take a look at an example of using CHIP framework to interact with a light accessory. This exercises the core concepts of the Matter data model we just went over. We start off by accessing the shared CHIPController. This controller is our primary handle to Matter. Next, we get a handle to the light by using the device ID that we assigned to it during pairing. Then, we initialize a handle to the on-off cluster on the light endpoint. And now, with this on-off cluster, we can perform reads and writes on the on-off attribute. First, we request to toggle the on-off attribute, which just toggles the state of the light. Then, we request to read the state of the on-off attribute. The accessory then sends us a response with the status of the attribute, which we can use to update our application.
So, that's a quick look into CHIP framework. Before we conclude our session today, we'd like to go over a new concept introduced in Matter and show some new features we've introduced in the Home app that leverage it. As you may already know, the Matter protocol allows multiple admins to connect to an accessory at the same time. This is a great feature for providing customers choices, but it also poses challenges to us when it comes to accessory management. Let's take a look at how the Home app incorporates this. The Home app can now present a list of all the connected admins on an accessory under this new Connected Services section. Users are also given the option to manage connected admins. And finally, users have the option to turn on pairing mode again to allow a new admin to connect with the accessory. Our goal here is simple: we want to ensure that our customers have the freedom to choose what's best for them, and also the confidence to tell how their smart home accessories are being managed.
So, Matter support will first be available in the iOS, iPadOS, and tvOS 15 developer preview, and a developer profile must be installed on these platforms to enable it. You will also need a home hub to control Matter accessories via HomeKit. While we expect Matter to publish qualified vendor IDs and certified product IDs once they become available for the market, we will provide a list of sample vendor IDs and product IDs with the developer preview to facilitate your development. These IDs are pre-configured to represent Matter accessory categories that are already supported in the developer preview. As always, you can find more information about our APIs on developer.apple.com. And more information about the Matter open source APIs and Matter accessory definitions can be found on Github.
So, in conclusion, we are bringing seamless Matter support via HomeKit for accessory developers, HomeKit apps, and HomeKit users. There will be a new setup API in an upcoming seed for developers who need to connect Matter accessories with other smart home hubs. And all of this will be available starting with the iOS, iPadOS, and tvOS 15 developer preview.
Thank you for watching, and from my team and I, goodbye. [percussive music]

4:58 - Add a Matter accessory to your HomeKit app

home.addAndSetupAccessories() { error in
    if let error = error {
         print("Error occurred in accessory setup \(error)”)
    } else {
         print("Successfully added accessory to HomeKit")
    }
}

9:12 - Invocation example

let homes = proprietaryHomeStorage.homes.map { home in
    HMCHIPServiceHome(uuid: home.uuid, name: home.name)
}

let topology = HMCHIPServiceTopology(homes: homes)
let setupManager = HMAccessorySetupManager()

do {
    try await setupManager.addAndSetUpAccessories(for: topology)
    print("Successfully added accessory to my app”)
} catch {
    print("Error occurred in accessory setup \(error)")
}

10:15 - Extension communication

class RequestHandler: HMCHIPServiceRequestHandler, CHIPDevicePairingDelegate {

   // . . .

   override func pairAccessory(in: HMCHIPServiceHome, onboardingPayload: String) async throws -> Void {
        // iOS is instructing the extension to pair the accessory via CHIP.framework
  }     // . . .
}

10:39 - Extension communication

class RequestHandler: HMCHIPServiceRequestHandler, CHIPDevicePairingDelegate {

   // . . .

   override func rooms(in: HMCHIPServiceHome) async throws -> [HMCHIPServiceRoom] {
        // iOS is querying for a room list that corresponds to the given home
    }     // . . .
}

11:03 - Extension communication

class RequestHandler: HMCHIPServiceRequestHandler, CHIPDevicePairingDelegate {

   // . . .

   override func configureAccessory(named accessoryName: String, room accessoryRoom: HMCHIPServiceRoom) async throws -> Void {
        // iOS is instructing the extension to apply configuration via CHIP.framework.
    }     // . . .
}

11:27 - Extension communication

class RequestHandler: HMCHIPServiceRequestHandler, CHIPDevicePairingDelegate {

    override func rooms(in: HMCHIPServiceHome) async throws -> [HMCHIPServiceRoom] {
        // iOS is querying for rooms that match the given home.  These rooms will be shown in system UI and the selection will be vended back to your extension's `configureAccessory` function
   }

    override func pairAccessory(in: HMCHIPServiceHome, onboardingPayload: String) async throws -> Void {
        // iOS is instructing the extension to pair the accessory via CHIP.framework
   }
    
    override func configureAccessory(named accessoryName: String, room accessoryRoom: HMCHIPServiceRoom) async throws -> Void {
       // iOS is instructing the extension to apply configuration via CHIP.framework.
    }
}

14:27 - Status and Control

let controller = CHIPDeviceController.shared()
do {
    let device = try controller.getPairedDevice(accessoryDeviceID)
    let onOffCluster = CHIPOnOff(device: device,
                               endpoint: lightEndpoint,
                                  queue: DispatchQueue.main)
    onOffCluster?.toggle({ (error, values) in
        // Error handling code here
    })
    onOffCluster?.readAttributeOnOff(responseHandler: { error, response in
        if let state = response?[VALUE_KEY] as? NSInteger {
           updateLightState(state: state)
        }
    })
} catch {
    print("Error occurred in accessory control \(error)")
}

Looking for something specific? Enter a topic above and jump straight to the good stuff.

An error occurred when submitting your query. Please check your Internet connection and try again.

Resources