Skip to content

Latest commit

 

History

History
354 lines (279 loc) · 17.3 KB

darwin.md

File metadata and controls

354 lines (279 loc) · 17.3 KB
Raw

Matter Development and Testing with/on Apple Devices

Overview

  • To develop a Matter Application, learn more about how to develop with Matter on Apple's platforms here

    • Additional documentation about the Matter Support API is here

Filing Issues

  • An issues related to Apple Home, or Development on Apple's Platforms should be reported using Feedback Assistant as described below

  • Any issues related to the Matter SDK should be reported to the project here

Source Compatibility

Each release of an Apple operating system, or developer preview release may bring a new SHA from this repository, which can be helpful for determining which changes are present in the release for testing.

Listed are the Current SHAs:

Supported Platforms for Matter Device Testing

  • Matter is supported by iOS/tvOS/iPadOS/watchOS/HomePod/AppleTV starting with 16.1
  • To test your Matter device with Apple's platforms, all you need is a device with a supported OS
  • Pairing via QR Code or Setup Code is supported directly from the Home App, or any third party Application
  • Please proceed to this section if you're developing a new device
    • If your device has already been certified, or already fully implemented and just awaiting testing, you can just try pairing to Apple Home directly
  • Please provide feedback to Apple if you encounter any issues

Supported Platforms for Application Development

For Context: This is a mapping of platform to OS

  • iPhone (iOS)
  • iPad (iPadOS)
  • mac (macOS)
  • AppleTV (tvOS)
  • HomePod (tvOS)
  • Apple Watch (watchOS)

Setup Requirements for Application Development

  • Devices must support BLE pairing, and have it enabled
  • An iPhone or iPad running iOS/iPadOS at least 16.1.
  • An Apple TV or HomePod running at least tvOS 16.1.
  • The iPhone or iPad with the Matter Developer Profile must belong to the same iCloud account as the Apple TV or HomePod with the Matter Matter Developer Profile.
  • A test iCloud account is highly recommended for Matter development to avoid interference with existing homes.
  • To pair and control Matter Thread devices, you'll need to have a HomePod Mini, Apple TV 4K, or another device that supports Thread
  • Enable Developer Mode during the development phase of your app by following the steps at Enabling Developer Mode on a device.

Profile Installation

Reminder: This is only needed for Application Development

Install the Matter Developer Profile on your iPhone or iPad

Note: For more detailed profile installation instructions, refer to here
Note: The profile will expire automatically after some time

  1. Download the Matter Developer Profile

  2. Email the profile to an account that is configured on your device running iOS/iPadOS 16.1 (or greater)

  3. Selecting the profile in Mail on your iOS/iPadOS 16.1 (or greater) device will present an option to install the profile

    Note: Make sure to head back to system preferences, and you'll see an option to verify and install the profile near the top

  4. (Optional) You may be prompted if you want to install it on other devices. Follow the prompts to install on the HomePod, Apple TV, etc., where you have the described issue and reproduce it.

  5. Restart the device

Install the Matter Profile on your HomePod

Note: The profile will expire automatically after some time
  1. Download the Matter Developer Profile
  2. Email the profile to an account that is configured on your device running iOS/iPadOS 16.1 (or greater)
  3. Selecting the profile in Mail on your iOS/iPadOS 16.1 (or greater) device will present an option to install the profile on the HomePod
  4. Restart the device

Install the Matter Profile on your Apple TV

Note: The profile will expire automatically after some time
  1. Download the profile
  2. Use Apple Configurator to transfer the profile to the Apple TV
  3. Restart the device

Enable Developer Mode on your Apple Device

Note: Developer mode is a great way to get logs from your device as well as enable other useful developer tools

To enable developer mode, please follow the instructions here

Using chip-tool on macOS, or CHIP Tool on iOS

Pairing Matter Accessory using Open Source Matter Darwin chip-tool and iOS chip-tool will require installing the Bluetooth Central Matter Client Developer mode profile on MacOS or iOS/iPadOS.

  • Download the Bluetooth Central Matter Client Developer Mode profile and install it on a supported system.

    • For macOS, Profile can be installed via Settings->Privacy & Security->Profiles
    • For iOS/iPadOS, If necessary, email the profile or use AirDrop to transfer the profile to the iOS/iPadOS device.

  • Restart your system

  • Compile chip-tool for macOS or CHIP Tool for iOS

Supported Device Types in Apple Home

Note: Not exhaustive, and may be out of date, see below for more information
Type Decimal HEX Notes
On/Off Light 256 0100
Dimming Light 257 0101
On/Off Plug-In Unit 266 010A
Dimmable Plug-In Unit 267 010B
On/Off Light Switch 259 0103 Requires both On/Off Client and Server
Dimmer Switch 260 0104 Requires both On/Off Client and Server
Generic Switch (button) 15 000F Supports momentary switch only, and not latching
Contact Sensor 21 0015
Light Sensor 262 0106
Occupancy Sensor 263 0107
Temperature Sensor 770 0302
Humidity Sensor 775 0307
Air Quality Sensor 44 002C
Door Lock 10 000A
Window Covering 514 0202
Heating/Cooling Unit 768 0300
Thermostat 769 0301
Fan 43 002B
Air Purifier 45 002D
Temperature Color Light 268 010C
Enhanced Color Light 269 010D
Bridges 14 000E
Robot Vacuum Cleaner 116 0074 Announced, not yet supported

Additional Device Type Support on Apple's Platforms

Apple's platforms support all device types available in the Matter SDK, so developers can use Matter.framework to develop their own applications that can add devices to Apple Home, or create their own Fabric to manage devices as well.

Please see documentation about -[HMAccessory matterNodeID] here which allows you to use Matter.framework to interact with Matter Devices directly that are paired into Apple Home.

Apple Home Development Guide

Please see here for more general information about developing an Application or a Device for Apple Home. This includes information about best practices, platform developer API, OTA Updates, general adoption Q&A, and the "Works with Apple Home" badge.

General Matter Platform Development Guide

Getting the SDK Ready
Note: Most platforms have very similar, if not the same configuration requirements
  1. Checkout and setup Matter repo as per the instructions above.
  2. Find and edit one of the platform examples to support the fixed device types above.
  3. Read the platform guides on how set up the hardware
    • There is a list of more detailed guides here

Testing your Matter Device with Apple Home

  1. Clone the Matter repository
  2. Checkout the specific commit hash (from above) for maximum compatibility with your installed release:
    • Example command for SHA 2ee90eba27676950fa2f4ef96597d9696f510d5d: $ git checkout 2ee90eba27676950fa2f4ef96597d9696f510d5d

In order to work with iOS/iPadOS/tvOS, device types as defined in the Matter Device Library spec are used to determine accessory categories. Ensure the right device type is set for each endpoint.

  • For the all-clusters-app as an example, this can be set in FIXED_DEVICE_TYPES, FIXED_DEVICE_TYPE_OFFSETS, and FIXED_DEVICE_TYPE_LENGTHS in endpoint_config.h
  • Here's an example from all-clusters-app (feel free to search for more in the tree by looking for the above keys)

Example:

// Array of device types
#define FIXED_DEVICE_TYPES
    {
        { 0x0016, 1 }, { 0x0100, 1 }, { 0x0100, 1 }, { 0xF002, 1 }
    }

// Array of device type offsets
#define FIXED_DEVICE_TYPE_OFFSETS
    {
        0, 1, 2, 3
    }

// Array of device type lengths
#define FIXED_DEVICE_TYPE_LENGTHS
    {
        1, 1, 1, 1
    }

Examples of how to setup devices

Case study 1: Configuring a development M5Stack, as a multi-device to work with iOS/iPadOS/tvOS
Note: These instructions are specific to getting started with the (Matter-provided) all-clusters-app on an ESP32-based M5Stack, however can be generalised to work on most platforms (more listed below)
  1. Checkout and setup Matter repo as per the instructions above.
  2. Follow these instructions to initialize your development environment, compile the firmware and flash your hardware.
Case study 2: a development Nordic board (nRF52840), working as a light to work with iOS/iPadOS/tvOS
Note: These instructions are specific to getting started with the (Matter-provided) "lighting-app" on an Nordic-based NRF52840, however can be generalised to work on most platforms (more listed below)

  1. Checkout and setup Matter repo as per the instructions above.

  2. Follow these instructions initialize your development environment, compile the firmware and flash your hardware.

Platform Guides

Providing Feedback to Apple

Note: For profile installation instructions, refer to here
  • File a feedback assistant ticket. About Feedback Assistant
  • Click this link, and log in using your account: File Feedback
  • Choose iOS/iPadOS to file an issue
  • Choose the area as Home App and fill in the details of the type of issue and the description
  • Please provide the following technical information:
    • sysdiagnose logs for iPhone / iPad with the timestamp / time frame of the issue
    • sysdiagnose logs for all the Home Hubs (HomePod mini / HomePod / Apple TV) with the timestamp / timeframe of the issue
    • Accessory logs with the timestamp / timeframe of the issue
    • mDNS network logs with timestamp / timeframe of the issue
    • Video or screenshot describing the issue (optional but beneficial)
  • Please make sure you download and install the profiles for iOS and tvOS as provided here. The instructions are also in these links.

Release to SHA Mappings

Platform Release Version SHA
iOS 17.6.1 2ee90eba27676950fa2f4ef96597d9696f510d5d
iPadOS 17.6.1 2ee90eba27676950fa2f4ef96597d9696f510d5d
tvOS 17.6 2ee90eba27676950fa2f4ef96597d9696f510d5d
macOS 14.6.1 2ee90eba27676950fa2f4ef96597d9696f510d5d
iOS 17.5.1 d09b5ac98f4d7d8b9f2c307f55ab5462576623a5
iPadOS 17.5.1 d09b5ac98f4d7d8b9f2c307f55ab5462576623a5
tvOS 17.5.1 d09b5ac98f4d7d8b9f2c307f55ab5462576623a5
macOS 14.5 d09b5ac98f4d7d8b9f2c307f55ab5462576623a5
iOS 16.7.8 83f7a2fe136e0b746db09f1d19e36c693a634b66
iPadOS 16.7.8 83f7a2fe136e0b746db09f1d19e36c693a634b66