From 759874144058f012062e873c00b6b3371806698b Mon Sep 17 00:00:00 2001 From: Justin Wood Date: Fri, 9 Dec 2022 17:33:24 -0800 Subject: [PATCH] Updating Darwin guide with latest info (#23979) * First Update * Update * Updates * Updates * Updating * Clarity about app development * Organization update * Small layout update * Updating based on feedback * Typo * Fixing spelling errors and dictionary * Updating dictionary * Updating --- .github/.wordlist.txt | 10 ++- docs/guides/darwin.md | 197 +++++++++++++++++++++++++++++------------- 2 files changed, 145 insertions(+), 62 deletions(-) diff --git a/.github/.wordlist.txt b/.github/.wordlist.txt index c78b7f05e5907a..18c158117a1a88 100644 --- a/.github/.wordlist.txt +++ b/.github/.wordlist.txt @@ -292,8 +292,8 @@ connstring conntype const ContentApp -ContentAppPlatform ContentApp's +ContentAppPlatform ContentLaunch ContentLauncher continuousHinting @@ -1120,8 +1120,8 @@ REPL repo req Requestor -RequestorCanConsent Requestor's +RequestorCanConsent Requestors responder RestrictedEvent @@ -1170,8 +1170,8 @@ SDB SDC SDHC SDK -sdkconfig SDK's +sdkconfig SDKs SDKTARGETSYSROOT sdl @@ -1199,6 +1199,7 @@ sexualized sfv SHA ShadeConfiguration +SHAs showDocumentation shubhamdp SIGINT @@ -1323,14 +1324,15 @@ ths Thunderboard timedInteractionTimeoutMs TimeFormatLocalization +timeframe timeoutMs TimeSynchronization tinycrypt Tizen TKIP +TLS tlsr TLV -TLS tmp tngvndl TODO diff --git a/docs/guides/darwin.md b/docs/guides/darwin.md index b580bfd82fe774..f9d430e9f683e7 100644 --- a/docs/guides/darwin.md +++ b/docs/guides/darwin.md @@ -4,9 +4,40 @@ Learn more about Matter [here](https://buildwithmatter.com/) -## Setup Requirements +## Source Compatibility + +Each release of an Apple operating system, or developer preview release may +bring a new SHA from this repository, which can be helpful for determining which +changes are present in the release for testing. + +Listed are the Current SHAs: + +- iOS/iPadOS/tvOS 16.1: + [`33f6a910cd9a8a0cfdd7088e2f43efd2f7f566a7`](https://github.com/project-chip/connectedhomeip/commits/33f6a910cd9a8a0cfdd7088e2f43efd2f7f566a7) + +- iOS/iPadOS/tvOS 16.2 Developer Preview: + [`c279578c5bc37f117335aa96cec6c5552f070cc0`](https://github.com/project-chip/connectedhomeip/commits/c279578c5bc37f117335aa96cec6c5552f070cc0) + +## Supported Platforms for Matter Device Testing + +- Matter is supported by iOS/tvOS/iPadOS/watchOS/HomePod/AppleTV starting with + 16.1 -Note: These steps are supported on: +- To test your Matter device with Apple's platforms, all you need is a device + with a supported OS +- Pairing via QR Code or Setup Code is supported directly from the Home App +- Please proceed to + [this section](#testing-your-matter-device-with-apple-home) if you're + developing a new device + - If your device has already been certified, or already fully implemented + and just awaiting testing, you can just try pairing to Apple Home + directly +- Please provide [feedback to Apple](#providing-feedback-to-apple) if you + encounter any issues + +## Supported Platforms for Application Development + +For Context: This is a mapping of platform to OS - iPhone _(iOS)_ - iPad _(iPadOS)_ @@ -15,72 +46,75 @@ Note: These steps are supported on: - HomePod _(tvOS)_ - Apple Watch _(watchOS)_ -### Current requires for testing with Apple Devices +### Overview + +- To develop a Matter Application, learn more about how to develop with Matter + on Apple's platforms [here](https://developer.apple.com/apple-home/matter/) + + - Additional documentation about the Matter Support API is + [here](https://developer.apple.com/documentation/mattersupport) -##### Note: Matter functionality is currently a Developer Preview +### Setup Requirements for Application Development - Devices must support BLE pairing, and have it enabled -- An iPhone or iPad running iOS/iPadOS at least 15.6. You will need to install - a [profile](#profile-installation) on it. -- An Apple TV or HomePod running at least tvOS 15.6. You will need to install - a [profile](#profile-installation) on it. If you have multiple Apple TVs - and/or HomePods, you will need to install the - [profile](#profile-installation) on all of them. -- The iPhone or iPad with the Matter [profile](#profile-installation) must - belong to the same iCloud account as the Apple TV or HomePod with the Matter - [profile](#profile-installation). +- An iPhone or iPad running iOS/iPadOS at least 16.1. +- An Apple TV or HomePod running at least tvOS 16.1. +- The iPhone or iPad with the + [Matter Developer Profile](#profile-installation) must belong to the same + iCloud account as the Apple TV or HomePod with the Matter + [Matter Developer Profile](#profile-installation). - A test iCloud account is highly recommended for Matter development to avoid interference with existing homes. - To pair and control Matter Thread devices, you'll need to have a HomePod - Mini or Apple TV 4K -- To pair to devices via BLE, you must either use the Matter Pairing API - documented - [here](https://developer.apple.com/documentation/homekit/hmmatterhome), or - enable [Developer mode](#enable-developer-mode-on-your-apple-device). + Mini, Apple TV 4K, or another device that supports Thread +- Enable Developer Mode during the development phase of your app by following + the steps at + [Enabling Developer Mode](https://developer.apple.com/documentation/xcode/enabling-developer-mode-on-a-device) + on a device. -## Source Compatibility +## Profile Installation -Each developer preview release is compatible with a certain SHA from this -repository. +#### Reminder: This is only needed for Application Development -- iOS/iPadOS/tvOS 16.0 Developer Preview: - [`aa9457e6b94b735076dff6297176183bf9780177`](https://github.com/project-chip/connectedhomeip/commits/aa9457e6b94b735076dff6297176183bf9780177) +### Install the Matter Developer Profile on your iPhone or iPad -## Profile Installation +##### Note: For more detailed profile installation instructions, refer to [here](https://developer.apple.com/bug-reporting/profiles-and-logs) -### Install the Matter Profile on your iPhone or iPad - -Note: The profile will expire automatically after some time +##### Note: The profile will expire automatically after some time 1. Download the - [profile](https://developer.apple.com/services-account/download?path=/iOS/iOS_Logs/EnableMatter.mobileconfig) + [Matter Developer Profile](https://developer.apple.com/services-account/download?path=/iOS/iOS_Logs/EnableBluetoothCentralMatterClientDeveloperMode.mobileconfig) 2. Email the profile to an account that is configured on your device running - iOS/iPadOS 15.6 (or greater) -3. Selecting the profile in Mail on your iOS/iPadOS 15.6 (or greater) device + iOS/iPadOS 16.1 (or greater) +3. Selecting the profile in Mail on your iOS/iPadOS 16.1 (or greater) device will present an option to install the profile ##### Note: Make sure to head back to system preferences, and you'll see an option to verify and install the profile near the top -4. Restart the device +4. (Optional) You may be prompted if you want to install it on other devices. + Follow the prompts to install on the HomePod, Apple TV, etc., where you have + the described issue and reproduce it. + +5. Restart the device ### Install the Matter Profile on your HomePod -Note: The profile will expire automatically after some time +##### Note: The profile will expire automatically after some time 1. Download the - [profile](https://developer.apple.com/services-account/download?path=/iOS/iOS_Logs/EnableMatter.mobileconfig) + [Matter Developer Profile](https://developer.apple.com/services-account/download?path=/iOS/iOS_Logs/EnableBluetoothCentralMatterClientDeveloperMode.mobileconfig) 2. Email the profile to an account that is configured on your device running - iOS/iPadOS 15.6 (or greater) -3. Selecting the profile in Mail on your iOS/iPadOS 15.6 (or greater) device + iOS/iPadOS 16.1 (or greater) +3. Selecting the profile in Mail on your iOS/iPadOS 16.1 (or greater) device will present an option to install the profile on the HomePod 4. Restart the device ### Install the Matter Profile on your Apple TV -Note: The profile will expire automatically after some time +##### Note: The profile will expire automatically after some time 1. Download the - [profile](https://developer.apple.com/services-account/download?path=/iOS/iOS_Logs/EnableMatter.mobileconfig) + [profile](https://developer.apple.com/services-account/download?path=/iOS/iOS_Logs/EnableBluetoothCentralMatterClientDeveloperMode.mobileconfig) 2. Use [Apple Configurator](https://apps.apple.com/us/app/apple-configurator/id1037126344?mt=12) to transfer the profile to the Apple TV @@ -88,21 +122,43 @@ Note: The profile will expire automatically after some time ### Enable Developer Mode on your Apple Device -Note: Developer mode is a great way to get logs from your device as well as +##### Note: Developer mode is a great way to get logs from your device as well as + enables other useful developer tools To enable developer mode, please follow the instructions [here](https://developer.apple.com/documentation/xcode/enabling-developer-mode-on-a-device) -### Ensuring Your Matter Accessory Works with iOS/iPadOS/tvOS +## Using chip-tool on macOS, or CHIP Tool on iOS + +Pairing Matter Accessory using Open Source Matter Darwin chip-tool and iOS +chip-tool will require installing the +[Bluetooth Central Matter Client Developer mode profile](https://developer.apple.com/services-account/download?path=/iOS/iOS_Logs/EnableBluetoothCentralMatterClientDeveloperMode.mobileconfig) +on MacOS or iOS/iPadOS. + +- Download the Bluetooth Central Matter Client Developer Mode profile and + install it on a iOS/iPadOS 16.1 beta 3 and MacOS 13.1 beta 3 or later + system. + + - For _macOS_, Profile can be installed via Settings->Privacy & + Security->Profiles + - For _iOS/iPadOS_, If necessary, email the profile or use AirDrop to + transfer the profile to the _iOS/iPadOS 16 beta 3_ device. + +- Restart your system + - For _iOS/iPadOS_, enable Developer Mode. Refer to + [this developer page](https://developer.apple.com/documentation/xcode/enabling-developer-mode-on-a-device) +- Compile chip-tool for macOS or CHIP Tool for iOS + +## Testing your Matter Device with Apple Home 1. Clone the [Matter repo](https://github.com/project-chip/connectedhomeip.git) 2. Checkout the specific commit hash (from [above](#source-compatibility)) for maximum compatibility with your installed release: - - Example command for SHA `aa9457e6b94b735076dff6297176183bf9780177`: - `$ git checkout aa9457e6b94b735076dff6297176183bf9780177` + - Example command for SHA `c279578c5bc37f117335aa96cec6c5552f070cc0`: + `$ git checkout c279578c5bc37f117335aa96cec6c5552f070cc0` -In order to work with iOS/iPadOS/tvOS 15.6 or greater, device types as defined +In order to work with iOS/iPadOS/tvOS 16.1 or greater, device types as defined in the Matter Device Library spec are used to determine accessory categories. Ensure the right device type is set for each endpoint. @@ -156,9 +212,7 @@ Example: ##### Case study 1: Configuring a development M5Stack, as a multi-device to work with iOS/iPadOS/tvOS -Note: These instructions are specific to getting started with the -(Matter-provided) `all-clusters-app` on an ESP32-based M5Stack, however can be -generalised to work on most platforms ([more listed below](#guides)) +##### Note: These instructions are specific to getting started with the (Matter-provided) `all-clusters-app` on an ESP32-based M5Stack, however can be generalised to work on most platforms ([more listed below](#guides)) 1. Checkout and setup [Matter repo](https://github.com/project-chip/connectedhomeip.git) as per the @@ -171,9 +225,7 @@ generalised to work on most platforms ([more listed below](#guides)) ##### Case study 2: a development Nordic board (nRF52840), working as a light to work with iOS/iPadOS/tvOS -Note: These instructions are specific to getting started with the -(Matter-provided) "lighting-app" on an Nordic-based NRF52840, however can be -generalised to work on most platforms (more listed below) +##### Note: These instructions are specific to getting started with the (Matter-provided) "lighting-app" on an Nordic-based NRF52840, however can be generalised to work on most platforms (more listed below) 1. Checkout and setup [Matter repo](https://github.com/project-chip/connectedhomeip.git) as per the @@ -185,12 +237,11 @@ generalised to work on most platforms (more listed below) initialize your development environment, compile the firmware and flash your hardware. -#### General Platform Guides +#### General Matter Platform Development Guide ##### Getting the SDK Ready -Note: Most platforms have very similar, if not the same configuration -requirements +##### Note: Most platforms have very similar, if not the same configuration requirements 1. Checkout and setup [Matter repo](https://github.com/project-chip/connectedhomeip.git) as per the @@ -224,16 +275,46 @@ requirements - [TI All Clusters](/examples/all-clusters-app/cc13x2x7_26x2x7/README.md) - [Tizen](/examples/lighting-app/tizen/README.md) +## Providing Feedback to Apple + +##### Note: For profile installation instructions, refer to [here](#profile-installation) + +- File a feedback assistant ticket. + [About Feedback Assistant](https://developer.apple.com/bug-reporting/#feedback-assistant) +- Click this link, and log in using your account: + [File Feedback](https://feedbackassistant.apple.com/new-form-response) +- Choose iOS/iPadOS to file an issue +- Choose the area as Home App and fill in the details of the type of issue and + the description +- Please provide the following technical information: + - `sysdiagnose` logs for iPhone / iPad with the timestamp / time frame of + the issue + - `sysdiagnose` logs for all the Home Hubs (HomePod mini / HomePod / Apple + TV) with the timestamp / timeframe of the issue + - Accessory logs with the timestamp / timeframe of the issue + - mDNS network logs with timestamp / timeframe of the issue + - Video or screenshot describing the issue (optional but beneficial) +- Please make sure you download and install the profiles for iOS and tvOS as + provided here. The instructions are also in these links. + - iOS: + - [Apple Home Profile](https://developer.apple.com/bug-reporting/profiles-and-logs/?platform=ios&name=homekit) + - [Network Profile](https://developer.apple.com/bug-reporting/profiles-and-logs/?platform=ios&name=network) + - [mDNS Profile](https://developer.apple.com/bug-reporting/profiles-and-logs/?platform=ios&name=mdns) + - tvOS: + - [Apple Home Profile](https://developer.apple.com/bug-reporting/profiles-and-logs/?platform=tvos&name=homekit) + - [Network Profile](https://developer.apple.com/bug-reporting/profiles-and-logs/?platform=tvos&name=network) + - [mDNS Profile](https://developer.apple.com/bug-reporting/profiles-and-logs/?platform=tvos&name=mdns) + ### Release Notes & Known Issues -- Please refer to the iOS/iPadOS 15.6 - [Release Notes](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-ipados-15_6-release-notes) - for currently known issues. -- Please refer to the iOS/iPadOS 16.0 - [Release Notes](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-16-release-notes) - for currently known issues. - Please refer to the iOS/iPadOS 16.1 [Release Notes](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-16_1-release-notes) for currently known issues. -- Further issues should be reported +- Please refer to the iOS/iPadOS 16.2 beta 3 + [Release Notes](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-ipados-16-release-notes) + for currently known issues +- An issues related to Apple Home integration should be reported + [feedback](#providing-feedback-to-apple) as described in this section + +- Any issues related to the Matter SDK should be reported to the project [here](https://github.com/project-chip/connectedhomeip/issues)