Apple Matter Accessory Best Practices
Product Specifications
- Product Name: Matter Accessory for Apple Home
- Compatibility: Apple Home app
- Developer Preview: 1
Introduction
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.
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
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:
- Open-Source Matter SDK
- OpenThread SDK (for Thread accessories)
- Matter OTA
- Diagnostics
- CSA Matter Interoperability Testing
- Testing accessories with iOS/tvOS beta releases
- Thread Border Router interoperability testing (for Thread Border Router accessories)
- Feedback to Apple
- Works With Apple Home badge
Accessory Requirements
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
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.
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.
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:
| ID | Name |
| 0x0032 | Diagnostic Logs Cluster |
| 0x0033 | General Diagnostics Cluster |
Implement the network diagnostic cluster that is applicable to the accessory:
| ID | Name |
| 0x0035 | Thread Network Diagnostics Cluster |
| 0x0036 | Wi-Fi Network Diagnostics Cluster |
| 0x0037 | Ethernet Network Diagnostics Cluster |
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.
General Diagnostics Cluster
Implement the following General Diagnostic Cluster attributes.
General Diagnostics Attributes
| ID | Name | Notes |
| 0x0000 | NetworkInterfaces | |
| 0x0001 | RebootCount | |
| 0x0002 | UpTime | |
| 0x0003 | TotalOperationalHours |
| 0x0004 | BootReason | Avoid use of enum value 0 ‘Unspecified’ as this does not provide actionable insight into the cause of the accessory reboot |
General Diagnostics Events
| ID | Name |
| 0x00 | HardwareFaultChange |
| 0x01 | RadioFaultChange |
| 0x02 | NetworkFaultChange |
| 0x03 | BootReason |
Thread Network Diagnostics Cluster
Implement the following Thread Network Diagnostic Cluster features, attributes, commands and events.
Thread Network Diagnostics Features
| Bit | Code | Feature |
| 0 | PKTCNT | PacketCounts |
Thread Network Diagnostics Attributes
| ID | Name |
| 0x0000 | Channel |
| 0x0001 | RoutingRole |
| 0x0002 | NetworkName |
| 0x0003 | PanId |
| 0x0006 | OverrunCount |
| 0x0007 | NeighborTable |
| 0x0008 | RouteTable |
| 0x00016 | TxTotalCount |
| 0x00017 | TxUnicastCount |
| 0x00018 | TxBroadcastCount |
| 0x00027 | RxTotalCount |
| 0x00028 | RxUnicastCount |
| 0x00029 | RxBroadcastCount |
Thread Network Diagnostics Commands
| ID | Name | Direction |
| 0x00 | ResetCounts | Client -> Server |
Thread Network Diagnostics Events
| ID | Name |
| 0x00 | ConnectionStatus |
| 0x01 | NetworkFaultChange |
Wi-Fi Network Diagnostics Cluster
Implement the following WiFi Network Diagnostic Cluster features, attributes, commands and events.
Wi-Fi Network Diagnostics Features
| Bit | Code | Feature |
| 0 | PKTCNT | PacketCounts |
| 1 | ERRCNT | ErrorCounts |
Wi-Fi Network Diagnostics Attributes
| ID | Name |
| 0x0003 | Channel Number |
| 0x0004 | RSSI |
| 0x0005 | Beacon Lost Count |
| 0x0006 | Beacon Rx Count |
| 0x0007 | Packet Multi cast Rx Count |
| 0x0008 | Packet Multi cast Tx Count |
| 0x0009 | Packet Unicast Rx Count |
| 0x000A | Packet Unicast Tx Count |
| 0x000C | Over run Count |
Wi-Fi Network Diagnostics Commands
| ID | Name | Direction |
| 0x00 | ResetCounts | Client -> Server |
Wi-Fi Network Diagnostics Events
| ID | Name |
| 0x00 | Disconnection |
| 0x01 | AssociationFailure |
| 0x02 | ConnectionStatus |
Ethernet Network Diagnostic Cluster
Implement the following Ethernet Network Diagnostic Cluster features, attributes, commands and events
Ethernet Network Diagnostics Attributes
| ID | Name |
| 0x0000 | PHYRate |
| 0x0001 | FullDuplex |
| 0x0002 | PacketRxCount |
| 0x0003 | PacketTxCount |
| 0x0004 | TxErrCount |
| 0x0005 | CollisionCount |
| 0x0006 | OverrunCount |
| 0x0008 | TimeSinceReset |
Ethernet Network Diagnostics Commands
| ID | Name | Direction |
| 0x00 | ResetCounts | Client -> Server |
CSA Matter Interoperability Testing
Submit your certified accessories to CSA for Matter interoperability testing here.
Testing Accessories with iOS/tvOS Beta Releases
Test your accessories with the latest iOS/tvOS beta releases at least twice a year.
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.
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:
Issue Description and Reproducibility
Please provide the details of the issue and list the steps to reproduce them.
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.
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.
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.
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.
References
- Matter Specification Version (https://csa-iot.org/developer-resource/specifications-download-request/)
- Matter Core Specification (https://csa-iot.org/developer-resource/specifications-download-request/)
- Matter Device Library (https://csa-iot.org/developer-resource/specifications-download-request/)
- Matter open-source SDK (https://github.com/project-chip/connectedhomeip)
Revision History
| Version | Date | Notes |
| Draft | 2024-06-06 | Developer Preview 1 |
Apple Inc.
Copyright © 2024 Apple Inc.
All rights reserved.
No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, electronic, photocopying, recording, or otherwise, without prior written permission of Apple Inc., with the following exceptions: Any person is hereby authorized to store documentation on a single computer or device for personal use only and to print copies of documentation for personal use provided that the documentation contains Apple’s copyright notice.
No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to be used in the development of solutions for Apple-branded products.
Apple Inc.
One Apple Park Way
Cupertino, CA 95014
408-996-1010
Apple, the Apple Logo, and HomeKit are trademarks of Apple Inc., registered in the U.S. and other countries. iOS is a trademark or registered trademark of Cisco in the U.S. and other countries and is used under license.
APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. AS A RESULT, THIS DOCUMENT IS PROVIDED “AS IS,” AND YOU, THE READER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT, ERROR OR INACCURACY IN THIS DOCUMENT, even if advised of the possibility of such damages. Some jurisdictions do not allow the exclusion of implied warranties or liability, so the above exclusion may not apply to you.
Frequently Asked Questions
Q: What is the purpose of the Matter Accessory Best Practices document?
A: The document details best practices for implementing Matter accessories to ensure compatibility and reliability when used with the Apple Home app.
Q: How can I certify my Thread accessories with the OpenThread specification?
A: Follow the guidelines provided in the document, including using the minimum commit version and enabling Child Supervision timeout for Sleepy End-Devices.
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.
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.
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.
Documents / Resources
 |
Apple Matter Accessory Best Practices [pdf] Instruction Manual Matter Accessory Best Practices, Matter Accessory Practices, Best Practices, Practices |
