Apple Matter Accessory Best Practices Instruction Manual
- July 6, 2024
- Apple
Table of Contents
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.
References
- AppleConnect Sign In
- Loading...
- CSA-IOT - Connectivity Standards Alliance
- The Alliance Specifications Download Request Form
- The Alliance Specifications Download Request Form
- Works with Apple Home badge guidelines - Apple Developer
- Bug Reporting - Apple Developer
- THClient | Apple Developer Documentation
- Releases - Apple Developer
- Git
- GitHub - openthread/openthread: OpenThread released by Google is an open-source implementation of the Thread networking protocol
- [key-manager] check if the key is present before exporting the key (#… · openthread/openthread@75abc7c · GitHub
- GitHub - project-chip/connectedhomeip: Matter (formerly Project CHIP) creates more connections between more objects, simplifying development for manufacturers and increasing compatibility for consumers, guided by the Connectivity Standards Alliance.
- [1.1] Cherry pick Thread DNS client and memory leak fixes by Damian-Nordic · Pull Request #31457 · project-chip/connectedhomeip · GitHub
- When dimming a light/bulb over time or changing color the thread network can be spammed by woody-apple · Pull Request #31778 · project-chip/connectedhomeip · GitHub
- [mrp] Make sure not all packet buffers are used for retransmissions by Damian-Nordic · Pull Request #33334 · project-chip/connectedhomeip · GitHub
- Code search results · GitHub
- OpenThread Border Router
- Child Supervision | OpenThread
- Node Roles and Types | OpenThread
- Log in with Atlassian account
- Wireshark · Download
Read User Manual Online (PDF format)
Read User Manual Online (PDF format) >>