Apple Matter OTA Software User Guide

Apple Matter OTA Software

Apple-Matter-OTA-Software-product

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.

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.

Terminology

Controller: iOS or iPad 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 the 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.

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.
The OTA requestor requests the firmware binary from the Apple device that is the primary home hub.
The OTA Provider provides the firmware to the OTA Requestor when available.
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.

Accessory

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.

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.

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, and HomePod mini.
When using Thread Matter Accessory, it is required to use the Apple home hub with Thread support.

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

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

Firmware URL: The developer enters the OTA firmware URL on TestNet DCL and includes all the required fields. See section TestNet DCL.
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.
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.
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.

Appendix

To create a model, click on Model on DCL
Create a new model version under the model you created.
Add/Update Device Model Version

References

Matter Specification Version 1.0
Matter Github (project-chip/connectedhomeip)
TestNet DCL specifications-downloadrequester.io)
Certified DCL (https://webui.dcl.csa-iot.org/)

Revision History

Apple-Matter-OTA-Software-fig-6

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 concerning any of the technologies 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, CONCERNING 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.

FAQs About Apple Matter OTA Software

How function the OTA update?

When using the secondary boot loader (SBL) and an over-the-air (OTA) firmware update method, or FOTA, the update process is managed by both the application and the SBL without the need for technician assistance. The upgraded firmware sometimes replaces the old firmware. If the firmware received is defective, the system may shut down.

How can I use OTA to upgrade iOS?

Navigate to Automatic Updates under Settings > General > Software Update. Activate the Automatic Install and Download of the iOS Updates listed below.

What uses does OTA serve?

With the use of over-the-air (OTA) technology, SIM cards can have their data updated and changed without needing to be reissued. Another name for it is Over-the-Air provisioning. It is important for carriers as well as subscribers.

Why is OTA utilized?

The capacity to download programs, services, and configurations via a mobile or cellular network is known as over-the-air (OTA) programming. Firmware, software, and encryption keys can all be automatically updated using over-the-air (OTA) programming. Particular OTA classifications include: Over-the-air software (SOTA)

Does Apple permit upgrades via OTA?

procedure for updating or upgrading macOS software. Updates for macOS are currently best applied via the Over-the-Air (OTA) mechanism, however UMA (Universal Mac Assistant) updates are still accessible.

Do OTA updates erase user data?

Android Over-The-Air (OTA) will never remove any data or installed apps. Existing applications may or may not be impacted by in-build issues.

An OTA package what is it?

Over-the-air (OTA) upgrades to the system, application software, and time zone regulations can be downloaded and installed on Android smartphones in the field. The structure of update packages and the tools needed to build them are covered in this section.

Which software is utilized by Apple?

Apple The exclusive operating system that runs on Apple mobile devices, including the iPhone and iPad, is called iOS. After Android, iOS is the second most popular mobile operating system worldwide.

An OTA image what is it?

Complete OTA images, on the other hand, are updates downloaded over the air that must be flashed wirelessly on devices that enable A/B or through a recovery environment. OTA updates can often be complete or incremental.

How much is a software update from Apple?

Updates for iOS are free of cost.

For More Manuals by Apple, Visit LatestManuals