Apple Matter OTA Software User Guide

May 15, 2024
Apple

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 Specification.
1.2. Terminology
– Controller: iOS or iPadOS device
– MainNet DCL: The production version of DCL (Distributed Compliance Ledger) that lists certified 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
– Profile: The XML configuration file 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 firmware updates from an OTA Provider.
Please refer to Matter Core Specification 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 firmware update to an OTA Requester.

  1. The developer creates a model and model version in DCL and enters the firmware OTA URL. For more information on DCL (Distributed Compliance Ledger), refer to Matter Specification Version 1.0. For details on how to create a model and include the required fields, refer to Appendix.
  2. The OTA requestor requests the firmware binary from the Apple device that is the primary home hub.
  3. The OTA Provider provides the firmware to the OTA Requestor when available.
  4. OTA Requestor downloads the update. For a more detailed workflow, refer to 11.19.3. Software update workflow in Matter Specification 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 profile to test Matter OTA with MainNet DCL after the 16.5 public release.
However, you are still required to use the profile if you use TestNet DCL to test Matter OTA with Apple.
3.1 Accessory

  1. Software image format
    – The developer must follow the Matter Software image file format described in Matter Specification Version 1.0.
    – Apple recommends verifying the software update using the OTA requestor and OTA Provider apps available in the open-source Matter Github.

  2. OTA image header
    – The OTA firmware image must contain the SoftwareVersion, VendorID, ProductID, SoftwareVersionString, PayloadSize, ImageDigest, and ImageDigestType.
    – The optional fields in the firmware image are MinApplicableSoftwareVersion, MaxApplicableSoftwareVersion, and ReleaseNotesURL.
    For more information, follow the format provided in the Matter Specification Version 1.0 section
    11.20.2.4. Header field.

3.2 Apple Devices

  1. 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.

  2. 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.

  3. Profile enablement
    – A profile is required when using TestNet DCL.
    – The profile points to the data from TestNet DCL. By default (without the profile), MainNet DCL is used.
    – The profile can be downloaded here. It expires on Dec 02, 2023.
    – To install the profile, you may AirDrop it to your iPhone and select the device as the home hub/ controller and follow the instructions for installing the profile.
    – Reboot the home hubs/controllers after installing the profile.

3.3 TestNet DCL
TestNet DCL is used for testing uncertified firmware. The developer must enter the OTA URL in TestNet DCL to enable testing. The other required fields included are SoftwareVersion, SoftwareVersionString, ProductID, VendorID, MinApplicableSoftwareVersion, and MaxApplicableSoftwareVersion. OTA checksum must be in base64 format. Different firmware versions are tested by entering specific URLs to the developer’s ProductIDs or DeviceTypes created on TestNet DCL. For more information on the required fields, 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

  1. Firmware URL: The developer enters the OTA firmware URL on TestNet DCL and includes all the required fields. See section TestNet DCL.

  2. Profile: The developer installs the Apple Matter OTA profile on all home hubs and controllers.
    Ensure you reboot the home hubs/controllers after installing the profile.

  3. Testing: The developer tests if the Home app shows the new firmware version from TestNet DCL and that the home hub applies it to the accessory successfully. This can be verified under
    Accessory settings on the Home App.
    – The developer may expect a firmware update notification in the Home App within 24 hours.
    This is the approximate wait time from when the new firmware version is entered into TestNet DCL to when the notification is seen in the Home App.
    – Apple recommends waiting 48 hours before seeing the firmware update applied to the accessory. This is the approximate wait time from when the TestNet DCL is updated with a new firmware 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 firmware 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 fields in the TestNet DCL.
    These fields can be used for testing incremental updates. If not implemented in the firmware, it is still recommended to provide test versions of MinApplicableSoftwareVersion and MaxApplicableSoftwareVersion in TestNet DCL.

  4. Issues/Feedback: The developer can file 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 Specification 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 firmware 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 firmware update even though I see an active OTA URL on TestNet DCL.

Below is a checklist of steps the developer should review before filing issues on feedback assistant: Check the iOS/tvOS version used on your Apple devices. Refer to the minimum version number. Check if the profile is installed on all Apple home hubs and controllers in your home and if the home hubs and controllers are rebooted after installation. See profile enablement. The developer can expect a firmware update notification in the Home App within 24 hours. Apple recommends waiting 48 hours before seeing the firmware 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 firmware image matches the Software image file format per Matter specification version 1.0. Ensure the Software Version Valid is set to True in the TestNet DCL model version field. See the Appendix section for different fields.

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 firmware 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 firmware 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 certificates to test OTA with Apple devices?

You do not need a certified accessory to use Matter OTA in Apple Home. Certified firmware can use MainNet DCL or TestNet DCL for OTA with Apple Home. Uncertified firmware updates must use TestNet DCL. If the certificates are not available, Home App will present an uncertified 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

  1. Matter Specification Version 1.0 (https://csa-iot.org/developer-resource/specifications-downloadrequest/)
  2. Matter Github (https://github.com/project-chip/connectedhomeip)
  3. TestNet DCL (https://TestNet.iotledger.io/)
  4. Certified 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.

References

Read User Manual Online (PDF format)

Loading......

Download This Manual (PDF format)

Download this manual  >>

Apple User Manuals

Related Manuals