Skip to content

Commit

Permalink
Updating Darwin guide with latest info (#23979)
Browse files Browse the repository at this point in the history
* 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
  • Loading branch information
woody-apple authored and pull[bot] committed Jul 27, 2023
1 parent 3d85217 commit 7598741
Show file tree
Hide file tree
Showing 2 changed files with 145 additions and 62 deletions.
10 changes: 6 additions & 4 deletions .github/.wordlist.txt
Original file line number Diff line number Diff line change
Expand Up @@ -292,8 +292,8 @@ connstring
conntype
const
ContentApp
ContentAppPlatform
ContentApp's
ContentAppPlatform
ContentLaunch
ContentLauncher
continuousHinting
Expand Down Expand Up @@ -1120,8 +1120,8 @@ REPL
repo
req
Requestor
RequestorCanConsent
Requestor's
RequestorCanConsent
Requestors
responder
RestrictedEvent
Expand Down Expand Up @@ -1170,8 +1170,8 @@ SDB
SDC
SDHC
SDK
sdkconfig
SDK's
sdkconfig
SDKs
SDKTARGETSYSROOT
sdl
Expand Down Expand Up @@ -1199,6 +1199,7 @@ sexualized
sfv
SHA
ShadeConfiguration
SHAs
showDocumentation
shubhamdp
SIGINT
Expand Down Expand Up @@ -1323,14 +1324,15 @@ ths
Thunderboard
timedInteractionTimeoutMs
TimeFormatLocalization
timeframe
timeoutMs
TimeSynchronization
tinycrypt
Tizen
TKIP
TLS
tlsr
TLV
TLS
tmp
tngvndl
TODO
Expand Down
197 changes: 139 additions & 58 deletions docs/guides/darwin.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)_
Expand All @@ -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.

Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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)

0 comments on commit 7598741

Please sign in to comment.