Testing with Apple Devices

Matter is the foundation for connected things.

Learn more about Matter here

Setup Requirements

Note: These steps are supported on:

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

Current requires for testing with Apple Devices

Note: Matter functionality is currently a Developer Preview
  • Devices must support BLE pairing, and have it enabled
  • An iPhone or iPad running iOS/iPadOS at least 15.6. You will need to install a profile on it.
  • An Apple TV or HomePod running at least tvOS 15.6. You will need to install a profile on it. If you have multiple Apple TVs and/or HomePods, you will need to install the profile on all of them.
  • The iPhone or iPad with the Matter profile must belong to the same iCloud account as the Apple TV or HomePod with the Matter 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 or Apple TV 4K
  • To pair to devices via BLE, you must either use the Matter Pairing API documented here, or enable Developer mode.

Source Compatibility

Each developer preview release is compatible with a certain SHA from this repository.

Profile Installation

Install the Matter Profile on your iPhone or iPad

Note: The profile will expire automatically after some time

  1. Download the profile

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

  3. Selecting the profile in Mail on your iOS/iPadOS 15.6 (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. Restart the device

Install the Matter Profile on your HomePod

Note: The profile will expire automatically after some time

  1. Download the profile
  2. Email the profile to an account that is configured on your device running iOS/iPadOS 15.6 (or greater)
  3. Selecting the profile in Mail on your iOS/iPadOS 15.6 (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 enables other useful developer tools

To enable developer mode, please follow the instructions here

Ensuring Your Matter Accessory Works with iOS/iPadOS/tvOS

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

In order to work with iOS/iPadOS/tvOS 15.6 or greater, 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
    }
  • Supported device types are (not exhaustive):
TypeDecimalHEX
Lightbulb2560100
Lightbulb + Dimmer2570101
Switch2590103
Contact Sensor210015
Door Lock10000A
Light Sensor2620106
Occupancy Sensor2630107
Outlet266010A
Color Bulb268010C
Window Covering5140202
Thermostat7690301
Temperature Sensor7700302
Flow Sensor7740306

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.

General Platform Guides

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
Guides

Release Notes & Known Issues

  • Please refer to the iOS/iPadOS 15.6 Release Notes for currently known issues.
  • Please refer to the iOS/iPadOS 16.0 Release Notes for currently known issues.
  • Further issues should be reported here