Apple Matter OTA Software User Guide

: June 17, 2024
: Apple

Table of Contents

Introduction
Overview
Requirements
Testing
Diagnostics
Release Notes
Known Issues
FAQs
Appendix
References
Revision History
References
Read User Manual Online (PDF format)
Download This Manual (PDF format)

Apple Matter OTA – User
Guide
Release R2

Introduction

NOTICE OF PROPRIETARY PROPERTY: THIS DOCUMENT AND THE INFORMATION CONTAINED HEREIN IS THE PROPRIETARY PROPERTY OF APPLE INC. THE POSSESSOR AGREES TO THE FOLLOWING: (I) TO MAINTAIN THIS DOCUMENT IN CONFIDENCE, (II) NOT TO REPRODUCE OR COPY IT, (III) NOT TO REVEAL OR PUBLISH IT IN WHOLE OR IN PART, (IV) ALL RIGHTS RESERVED.
1.1. Purpose
This document provides an overview of Matter OTA with Apple Home, and how to enable and test this feature with Apple devices. This document assumes that the developer is familiar with Matter Speciﬁcation.
1.2. Terminology
– Controller: iOS or iPadOS device
– MainNet DCL: The production version of DCL (Distributed Compliance Ledger) that lists certiﬁed accessories
– OTA: Over-The-Air
– OTA Requestor: It is the developer’s Matter Accessory
– OTA Provider: Primary Apple device as a home hub
– Primary home hub: Apple TV or HomePod or HomePod mini that is in the ‘Connected’ state under Home settings > Home Hubs & Bridges.
– ProductID: Product ID of the Matter Accessory
– Proﬁle: The XML conﬁguration ﬁle that helps provision your Apple device for testing.
– TestNet DCL: Test version of Distributed Compliance Ledger
– VendorID: Vendor ID of the Matter Accessory

Overview

Matter OTA allows an OTA requestor to receive ﬁrmware updates from an OTA Provider.
Please refer to Matter Core Speciﬁcation Version 1.0 section Over-the-Air (OTA) Software Update for more details on implementing OTA Software Update Requestor Cluster for the Matter accessory. A high-level architecture for Matter OTA with Apple devices is described below. The Primary home hub is the OTA Provider that provides the ﬁrmware update to an OTA Requester.

The developer creates a model and model version in DCL and enters the ﬁrmware OTA URL. For more information on DCL (Distributed Compliance Ledger), refer to Matter Speciﬁcation Version 1.0. For details on how to create a model and include the required ﬁelds, refer to Appendix.
The OTA requestor requests the ﬁrmware binary from the Apple device that is the primary home hub.
The OTA Provider provides the ﬁrmware to the OTA Requestor when available.
OTA Requestor downloads the update. For a more detailed workﬂow, refer to 11.19.3. Software update workﬂow in Matter Speciﬁcation Version 1.0.

Requirements

Below are the 16.5 beta 3 or above requirements for testing Matter OTA with Apple devices. Please note that you do not need a proﬁle to test Matter OTA with MainNet DCL after the 16.5 public release.
However, you are still required to use the proﬁle if you use TestNet DCL to test Matter OTA with Apple.
3.1 Accessory

Software image format
– The developer must follow the Matter Software image ﬁle format described in Matter Speciﬁcation Version 1.0.
– Apple recommends verifying the software update using the OTA requestor and OTA Provider apps available in the open-source Matter Github.
OTA image header
– The OTA ﬁrmware image must contain the SoftwareVersion, VendorID, ProductID, SoftwareVersionString, PayloadSize, ImageDigest, and ImageDigestType.
– The optional ﬁelds in the ﬁrmware image are MinApplicableSoftwareVersion, MaxApplicableSoftwareVersion, and ReleaseNotesURL.
For more information, follow the format provided in the Matter Speciﬁcation Version 1.0 section
11.20.2.4. Header ﬁeld.

3.2 Apple Devices

Minimum version of iOS/tvOS
Matter OTA using Apple as the OTA Provider is available in beta 3 iOS16.5 (20F5050f) / tvOS 16.5 (20L5549e) or above.
Apple home hub
– It is required to use an Apple home hub in your setup. Apple home hubs include Apple TV, HomePod, HomePod mini.
– When using Thread Matter Accessory, it is required to use the Apple home hub with Thread support.
Proﬁle enablement
– A proﬁle is required when using TestNet DCL.
– The proﬁle points to the data from TestNet DCL. By default (without the proﬁle), MainNet DCL is used.
– The proﬁle can be downloaded here. It expires on Dec 02, 2023.
– To install the proﬁle, you may AirDrop it to your iPhone and select the device as the home hub/ controller and follow the instructions for installing the proﬁle.
– Reboot the home hubs/controllers after installing the proﬁle.

3.3 TestNet DCL
TestNet DCL is used for testing uncertiﬁed ﬁrmware. The developer must enter the OTA URL in TestNet DCL to enable testing. The other required ﬁelds included are SoftwareVersion, SoftwareVersionString, ProductID, VendorID, MinApplicableSoftwareVersion, and MaxApplicableSoftwareVersion. OTA checksum must be in base64 format. Different ﬁrmware versions are tested by entering speciﬁc URLs to the developer’s ProductIDs or DeviceTypes created on TestNet DCL. For more information on the required ﬁelds, please refer to the Appendix.

Testing

To test Matter OTA using Apple devices and TestNet DCL, the developer must follow the steps below: Apple Matter OTA Software -
Testing

Firmware URL: The developer enters the OTA ﬁrmware URL on TestNet DCL and includes all the required ﬁelds. See section TestNet DCL.
Proﬁle: The developer installs the Apple Matter OTA proﬁle on all home hubs and controllers.
Ensure you reboot the home hubs/controllers after installing the proﬁle.
Testing: The developer tests if the Home app shows the new ﬁrmware version from TestNet DCL and that the home hub applies it to the accessory successfully. This can be veriﬁed under
Accessory settings on the Home App.
– The developer may expect a ﬁrmware update notiﬁcation in the Home App within 24 hours.
This is the approximate wait time from when the new ﬁrmware version is entered into TestNet DCL to when the notiﬁcation is seen in the Home App.
– Apple recommends waiting 48 hours before seeing the ﬁrmware update applied to the accessory. This is the approximate wait time from when the TestNet DCL is updated with a new ﬁrmware version to when the update is applied to the accessory. This assumes that the Matter accessory is using the default OTA Requestor implementation.
– If Automatic update is disabled on the Home Settings > Software Update > Other Accessories, developer consent is needed in the Home App to update the ﬁrmware manually.
The developer must press ‘Update’ on the Home App to update the accessory.
– Apple recommends that developers test MinApplicableSoftwareVersion and MaxApplicableSoftwareVersion by providing the respective data ﬁelds in the TestNet DCL.
These ﬁelds can be used for testing incremental updates. If not implemented in the ﬁrmware, it is still recommended to provide test versions of MinApplicableSoftwareVersion and MaxApplicableSoftwareVersion in TestNet DCL.
Issues/Feedback: The developer can ﬁle issues or feedback on the feedback assistant. Please follow the procedure of submitting a feedback assistant ticket under iOS/tvOS along with the required logs.

Diagnostics

Apple recommends implementing diagnostics clusters on the Matter accessory. This would help in debugging OTA issues effectively. For more information on the clusters, please refer to the Matter Speciﬁcation Version 1.0, sections 11.10 – 11.15.

Release Notes

Refer to the release notes below:
iOS release notes
tvOS release notes

Known Issues

When the OTA checksum is in base64 format on TestNetDCL and released versions iOS/tvOS 16.4, or
16.4.1 or developer beta iOS 16.5 beta 1 and beta 2 are used for testing, Apple Home does not indicate ﬁrmware updates on the Home App.
Workaround: Ensure iOS/tvOS 16.5 beta 3 or above is used for testing base64 OTA checksum on TestNet DCL.

FAQs

1. I did not receive a ﬁrmware update even though I see an active OTA URL on TestNet DCL.

Below is a checklist of steps the developer should review before ﬁling issues on feedback assistant: Check the iOS/tvOS version used on your Apple devices. Refer to the minimum version number. Check if the proﬁle is installed on all Apple home hubs and controllers in your home and if the home hubs and controllers are rebooted after installation. See proﬁle enablement. The developer can expect a ﬁrmware update notiﬁcation in the Home App within 24 hours. Apple recommends waiting 48 hours before seeing the ﬁrmware update applied to the accessory. Refer to section Testing. If using OTA checksum based on base64 representation on TestNetDCL, ensure 16.5 beta 3 or above is used for testing. Ensure the ﬁrmware image matches the Software image ﬁle format per Matter speciﬁcation version 1.0. Ensure the Software Version Valid is set to True in the TestNet DCL model version ﬁeld. See the Appendix section for diﬀerent ﬁelds.

2. I clicked on ‘Update’ and the Home App reported a ‘Requested’ state. What is Requested?

The developer can enable or disable automatic updates in Home settings > Software Update > Other Accessories. If enabled, the primary home hub will update the accessory automatically. Home App shows an Update and an Installing spinner state in an automatic update. If automatic updates are disabled, the developer can update it manually. The Home App presents three states in this mode: Update > Requested > Installing spinner. - In a manual update, the ‘requested’ state indicates it is waiting for the home hub to transfer the ﬁrmware to the accessory.

3. I have one of the home hubs upgraded to 16.5 beta 3, but my other devices are on older versions. Should I see an update when available?

Only the primary home hub is responsible for providing the ﬁrmware update to the accessory. The developer can see the update when available if the primary home hub is on a supported version.

4. Do I need to use certiﬁcates to test OTA with Apple devices?

You do not need a certiﬁed accessory to use Matter OTA in Apple Home. Certiﬁed ﬁrmware can use MainNet DCL or TestNet DCL for OTA with Apple Home. Uncertiﬁed ﬁrmware updates must use TestNet DCL. If the certiﬁcates are not available, Home App will present an uncertiﬁed accessory to the developer, and the accessory can be added to the Home App by clicking on the prompt ‘Add Anyway.’

Appendix

– To create a model, click on Model on DCL. – Create a new model version under the model you created. Apple Matter OTA Software - Appendix
1 – Add/Update Device Model Version Apple Matter OTA Software -
Appendix 2

References

Matter Speciﬁcation Version 1.0 (https://csa-iot.org/developer-resource/speciﬁcations-downloadrequest/)
Matter Github (https://github.com/project-chip/connectedhomeip)
TestNet DCL (https://TestNet.iotledger.io/)
Certiﬁed DCL (https://webui.dcl.csa-iot.org/)

Revision History

Revision History

Version	Date	Notes
R2	2023-05-05	Release R2

– Added Known Issues
– Updated Requirements
– Updated Testing
– Updated FAQs
R1| 2023-03-08| Release R1

Apple Inc.
Copyright © 2023 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 Applebranded 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.

2023-05-05
Copyright © 2023 Apple Inc.
All Rights Reserved.