Apple Matter Accessory Best Practices Instruction Manual

July 6, 2024
Apple

Apple Matter Accessory Best Practices

Apple-Matter-Accessory-Best-Practices-product

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:

  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

Accessory Requirements

Open-Source Matter SDK

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

  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)

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

Read User Manual Online (PDF format)

Read User Manual Online (PDF format)  >>

Download This Manual (PDF format)

Download this manual  >>

Related Manuals