1. Introduction

1.1. Purpose and Scope

This document details Matter accessory implementation best practices to ensure interoperability and reliability when paired with Apple Home app. This document assumes that developers know how to integrate Matter SDK and OpenThread SDK (if applicable) into their accessories and are familiar with Matter Specifications and the CSA standard.

1.2. Terminology

• Accessory: A Matter device containing one or more Nodes.
• Thread Border Router: A Thread Border Router connects a Thread network to other IP-based networks, such as Wi-Fi or Ethernet. More details.
• mdns: Multicast DNS
• OTA: Over-The-Air
• PR: Git Pull Request
• Sleepy End-Devices: Battery-powered Thread accessories. More details.
• SoC: System on Chip

2. Overview

This guide serves as a resource for accessory manufacturers and SoC providers to ensure their implementations are interoperable and work reliably when paired with Apple Home. It is expected that accessory manufacturers and SoC providers check this guide frequently for updates.

The accessory requirement checklist is divided into the following sections:

• 1. Open-Source Matter SDK
• 2. OpenThread SDK (for Thread accessories)
• 3. Matter OTA
• 4. Diagnostics
• 5. CSA Matter Interoperability Testing
• 6. Testing accessories with iOS/tvOS beta releases
• 7. Thread Border Router interoperability testing (for Thread Border Router accessories)
• 8. Feedback to Apple
• 9. Works With Apple Home badge

3. Accessory Requirements

3.1 Open-Source Matter SDK

Minimum Requirements:

• Use the latest Matter SDK main branch certified with v1.3 Matter specification from CSA.

Integrate the following pull requests:

• Packet buffers used during retransmissions: https://github.com/project-chip/connectedhomeip/pull/33334
• Pairing failures due to a memory leak: https://github.com/project-chip/connectedhomeip/pull/31457 if the optional Deferred Attribute color module is used
• Frequent reports from RemainingTime Attribute from the Color Control Cluster may throttle the network https://github.com/project-chip/connectedhomeip/pull/31778/files

3.2 OpenThread SDK

This section applies to Thread accessories.

• Use the minimum commit version: Link
• git checkout 75abc7c871e18b5c41c22f998b9e5cdbb7868d84
• Child Supervision timeout must be enabled for Sleepy End-Devices (SED). Please refer to the Thread v1.3.1 specification request for more details.
• Certify Thread accessories with v1.3 OpenThread specification.

3.3 Matter OTA

Implement Matter OTA To ensure accessories get timely automatic firmware updates that include the latest interoperability and reliability recommendations. Please refer to the Apple Matter OTA guide for more details. In addition, ensure your accessory firmware is tested with the Apple Home before releasing the firmware to end-users.

3.4 Diagnostics

Implement three diagnostic clusters from Matter Core Specification:

• The Diagnostic Logs Cluster will enable users to pull logs from the accessories in the field which will assist in issue investigation.
• The General Diagnostics Cluster and the Network Diagnostic Cluster will provide insights into reliability and assist in understanding the frequency of reboots and issues with network connectivity.

Implement the following clusters:

Implement the network diagnostic cluster that is applicable to the accessory:

3.4.1 Diagnostic Logs Cluster

The Diagnostic Logs Cluster is certifiable with Matter Specification Version 1.3. Implement the mandatory attributes of the Diagnostic Logs Cluster. This enables iOS Matter controller to fetch logs from the accessory. Include log content that is beneficial for debugging process. For example include logs regarding crashes, network failures, read/write events, etc.

3.4.2 General Diagnostics Cluster

Implement the following General Diagnostic Cluster attributes.

3.4.2.1 General Diagnostics Attributes

3.4.2.2 General Diagnostics Events

3.4.3 Thread Network Diagnostics Cluster

Implement the following Thread Network Diagnostic Cluster features, attributes, commands and events.

3.4.3.1 Thread Network Diagnostics Features

3.4.3.2 Thread Network Diagnostics Attributes

3.4.3.3 Thread Network Diagnostics Commands

3.4.3.4 Thread Network Diagnostics Events

3.4.4 Wi-Fi Network Diagnostics Cluster

Implement the following WiFi Network Diagnostic Cluster features, attributes, commands and events.

3.4.4.1 Wi-Fi Network Diagnostics Features

3.4.4.2 Wi-Fi Network Diagnostics Attributes

3.4.4.3 Wi-Fi Network Diagnostics Commands

3.4.4.4 Wi-Fi Network Diagnostics Events

3.4.5 Ethernet Network Diagnostic Cluster

Implement the following Ethernet Network Diagnostic Cluster features, attributes, commands and events.

3.4.5.1 Ethernet Network Diagnostics Attributes

3.4.5.2 Ethernet Network Diagnostics Commands

3.5 CSA Matter Interoperability Testing

Submit your certified accessories to CSA for Matter interoperability testing here. https://csa-iot.org/developer-resource/specifications-download-request/

3.6 Testing Accessories with iOS/tvOS Beta Releases

Test your accessories with the latest iOS/tvOS beta releases at least twice a year.

3.7 Thread Border Router Interoperability Testing

This section is applicable for Thread Border Routers that implement THClient API. Ensure that your accessories pass all the test cases outlined in the following documents:

• Thread Test Plan - THClient API Test Plan
• Thread Test Plan - User Experience Border Router

To access these documents, file a Feedback Assistant.

3.8 Feedback to Apple

Report issues/bugs to Apple through Feedback Assistant or Radar. This will help in timely triage and feedback.

Include the following information when reporting issues to Apple:

3.8.1. Issue Description and Reproducibility

Please provide the details of the issue and list the steps to reproduce them.

3.8.2. Profiles

The following profiles must be installed on the iOS/tvOS devices. Follow the instructions provided in the respective profile instructions document on how to trigger sysdiagnose logs for iPhone, HomePod, HomePod mini, or Apple TV.

• HomeKit :
  • This profile helps in capturing HomeKit layer logs for issues related to Matter on iOS/tvOS.
• Thread (for a Thread Accessory):
  • This profile helps in capturing Thread protocol-related logs for issues related to Thread and IPv6 when interacting with a Thread Border Router (HomePod, HomePod mini, or Apple TV).
• mdns
  • This profile helps in capturing mdns discovery issues related to pairing and reachability of accessories with iOS/tvOS.

3.8.3. Logging

Ensure you attach logs from the accessory and iOS/tvOS devices and provide an approximate time stamp of the issue. Refer to the section on the profiles that must be installed on iOS and tvOS devices. If it is a regression, provide us details on the working and non-working versions of iOS/tvOS with passing and failing logs. It is assumed that the Matter accessory is following the guidelines for Matter diagnostics detailed in this section.

3.8.4. Additional Information

Additional logs and information on the following are recommended depending on the type of issue:

• Please include Wireshark logs.
• Test with different Wi-Fi routers to narrow down the issue. If information about the router is available, please share it on the feedback assistant or radar.

3.9 Works With Apple Home Badge

Submit a request for the Works with Apple Home badge after the accessory receives Matter certification. Additional information regarding Works with Apple Home badge and usage guidelines are listed here. https://csa-iot.org/developer-resource/specifications-download-request/

6. FAQs

• 1. I am currently using an older version of Matter SDK. How do I ensure better interoperability with Apple Home?
  Integrate the latest Matter SDK main branch and certify your accessory with v1.3 Matter specification on your next immediate firmware release. Follow the guidelines in this section on the important pull requests to be implemented for your accessory. Please check this guide frequently for any updates.
• 2. I am currently using an older OpenThread SDK commit version on my Thread accessory. How do I ensure better interoperability with Apple Home?
  Integrate the OpenThread SDK commit version based on this section in the next immediate firmware release. Please check this guide frequently for any updates.
• 3. Do I need to go through CSA Matter Interoperability?
  Matter certification from CSA is the standard for testing and verifying that the Matter protocol is working correctly. CSA Matter Interoperability checks for interoperability with Apple Home to ensure it is working with no issues on accessories or iOS/tvOS.

7. References

1. Matter Specification Version (https://csa-iot.org/developer-resource/specifications-download-request/)
2. Matter Core Specification (https://csa-iot.org/developer-resource/specifications-download-request/)
3. Matter Device Library (https://csa-iot.org/developer-resource/specifications-download-request/)
4. Matter open-source SDK (https://github.com/project-chip/connectedhomeip)

8. Revision History