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
project-chip · Jan 27, 2023 · 1911952 · 1911952
1 parent d908723
commit 1911952
Show file tree

Hide file tree

Showing 2 changed files with 145 additions and 62 deletions.
diff --git 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
@@ -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,94 +46,119 @@ 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
 3. Restart the device
 
 ### 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)