| # Matter Development and Testing with/on 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) |
| |
| ### Filing Issues |
| |
| - An issues related to Apple Home, or Development on Apple's Platforms should |
| be reported using Feedback Assistant as described |
| [below](#providing-feedback-to-apple) |
| |
| - Any issues related to the Matter SDK should be reported to the project |
| [here](https://github.com/project-chip/connectedhomeip/issues) |
| |
| ## 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: |
| |
| - Latest macOS/tvOS/iOS/iPadOS: |
| [`2ee90eba27676950fa2f4ef96597d9696f510d5d`](https://github.com/project-chip/connectedhomeip/commits/2ee90eba27676950fa2f4ef96597d9696f510d5d) |
| - Larger list of SHAs are [here](#release-to-sha-mappings) |
| |
| ## Supported Platforms for Matter Device Testing |
| |
| - Matter is supported by iOS/tvOS/iPadOS/watchOS/HomePod/AppleTV starting with |
| 16.1 |
| - 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, |
| or any third party Application |
| - 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)_ |
| - mac _(macOS)_ |
| - AppleTV _(tvOS)_ |
| - HomePod _(tvOS)_ |
| - Apple Watch _(watchOS)_ |
| |
| ### Setup Requirements for Application Development |
| |
| - Devices must support BLE pairing, and have it enabled |
| - 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, 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. |
| |
| ## Profile Installation |
| |
| #### Reminder: This is only needed for Application Development |
| |
| ### Install the Matter Developer Profile on your iPhone or iPad |
| |
| ##### Note: For more detailed profile installation instructions, refer to [here](https://developer.apple.com/bug-reporting/profiles-and-logs) |
| |
| ##### Note: The profile will expire automatically after some time |
| |
| 1. Download the |
| [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 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. (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 |
| |
| 1. Download the |
| [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 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 |
| |
| 1. Download the |
| [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 enable 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) |
| |
| ## 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 supported 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_ 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 |
| |
| ## Supported Device Types in Apple Home |
| |
| ##### Note: Not exhaustive, and may be out of date, see [below](#apple-home-development-guide) for more information |
| |
| | Type | Decimal | HEX | Notes | |
| | ----------------------- | ------- | ---- | ------------------------------------------------ | |
| | On/Off Light | 256 | 0100 | | |
| | Dimming Light | 257 | 0101 | | |
| | On/Off Plug-In Unit | 266 | 010A | | |
| | Dimmable Plug-In Unit | 267 | 010B | | |
| | On/Off Light Switch | 259 | 0103 | Requires both On/Off Client and Server | |
| | Dimmer Switch | 260 | 0104 | Requires both On/Off Client and Server | |
| | Generic Switch (button) | 15 | 000F | Supports momentary switch only, and not latching | |
| | Contact Sensor | 21 | 0015 | | |
| | Light Sensor | 262 | 0106 | | |
| | Occupancy Sensor | 263 | 0107 | | |
| | Temperature Sensor | 770 | 0302 | | |
| | Humidity Sensor | 775 | 0307 | | |
| | Air Quality Sensor | 44 | 002C | | |
| | Door Lock | 10 | 000A | | |
| | Window Covering | 514 | 0202 | | |
| | Heating/Cooling Unit | 768 | 0300 | | |
| | Thermostat | 769 | 0301 | | |
| | Fan | 43 | 002B | | |
| | Air Purifier | 45 | 002D | | |
| | Temperature Color Light | 268 | 010C | | |
| | Enhanced Color Light | 269 | 010D | | |
| | Bridges | 14 | 000E | | |
| | Robot Vacuum Cleaner | 116 | 0074 | Announced, not yet supported | |
| |
| ## Additional Device Type Support on Apple's Platforms |
| |
| Apple's platforms support all device types available in the Matter SDK, so |
| developers can use Matter.framework to develop their own applications that can |
| add devices to Apple Home, or create their own Fabric to manage devices as well. |
| |
| Please see documentation about `-[HMAccessory matterNodeID]` |
| [here](https://developer.apple.com/documentation/homekit/hmaccessory/matternodeid-5zfqo) |
| which allows you to use Matter.framework to interact with Matter Devices |
| directly that are paired into Apple Home. |
| |
| ## Apple Home Development Guide |
| |
| Please see [here](https://developer.apple.com/apple-home/) for more general |
| information about developing an Application or a Device for Apple Home. This |
| includes information about |
| [best practices](https://developer.apple.com/apple-home/downloads/Matter-Accessory-Best-Practices-for-Apple-Home.pdf), |
| [platform developer API](https://developer.apple.com/apple-home/matter/), |
| [OTA Updates](https://developer.apple.com/accessories/Apple-Matter-OTA-User-Guide.pdf), |
| general adoption Q&A, and the "Works with Apple Home" badge. |
| |
| ## General Matter Platform Development Guide |
| |
| ##### Getting the SDK Ready |
| |
| ##### 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 |
| instructions above. |
| 2. Find and edit one of the platform |
| [examples](https://github.com/project-chip/connectedhomeip/tree/master/examples) |
| to support the fixed device types above. |
| 3. Read the [platform guides](README.md) on how set up the hardware |
| - There is a list of more detailed guides [here](#platform-guides) |
| |
| ## Testing your Matter Device with Apple Home |
| |
| 1. Clone the |
| [Matter repository](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 `2ee90eba27676950fa2f4ef96597d9696f510d5d`: |
| `$ git checkout 2ee90eba27676950fa2f4ef96597d9696f510d5d` |
| |
| In order to work with iOS/iPadOS/tvOS, 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. |
| |
| - For the `all-clusters-app` as an example, this can be set in |
| `FIXED_DEVICE_TYPES`, `FIXED_DEVICE_TYPE_OFFSETS`, and |
| `FIXED_DEVICE_TYPE_LENGTHS` in `endpoint_config.h` |
| - Here's an example from `all-clusters-app` (feel free to search for more in |
| the tree by looking for the above keys) |
| |
| Example: |
| |
| ``` |
| // Array of device types |
| #define FIXED_DEVICE_TYPES |
| { |
| { 0x0016, 1 }, { 0x0100, 1 }, { 0x0100, 1 }, { 0xF002, 1 } |
| } |
| |
| // Array of device type offsets |
| #define FIXED_DEVICE_TYPE_OFFSETS |
| { |
| 0, 1, 2, 3 |
| } |
| |
| // Array of device type lengths |
| #define FIXED_DEVICE_TYPE_LENGTHS |
| { |
| 1, 1, 1, 1 |
| } |
| ``` |
| |
| ### Examples of how to setup devices |
| |
| ##### 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](#platform-guides)) |
| |
| 1. Checkout and setup |
| [Matter repo](https://github.com/project-chip/connectedhomeip.git) as per the |
| instructions above. |
| 2. Follow |
| [these](https://github.com/project-chip/connectedhomeip/tree/master/examples/all-clusters-app/esp32) |
| instructions to initialize your development environment, compile the firmware |
| and flash your hardware. |
| |
| ##### 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) |
| |
| 1. Checkout and setup |
| [Matter repo](https://github.com/project-chip/connectedhomeip.git) as per the |
| instructions above. |
| |
| 2. Follow |
| [these instructions](https://github.com/project-chip/connectedhomeip/tree/master/examples/lighting-app/nrfconnect#readme) |
| initialize your development environment, compile the firmware and flash your |
| hardware. |
| |
| ### Platform Guides |
| |
| - [Bouffalo Lab](/examples/lighting-app/bouffalolab/README.md) |
| - [EFR32 Window Covering](/examples/window-app/silabs/README.md) |
| - [ESP32 All Clusters](/examples/all-clusters-app/esp32/README.md) |
| - [ESP32 Lighting](/examples/lighting-app/esp32/README.md) |
| - [ESP32 Temperature Sensor](/examples/temperature-measurement-app/esp32/README.md) |
| - [mbedOS](/examples/all-clusters-app/mbed/README.md) |
| - [nRF Connect All Clusters](../platforms/nrf/nrfconnect_examples_configuration.md) |
| - [nRF Connect Pump](/examples/pump-app/nrfconnect/README.md) |
| - [NXP Examples](../platforms/nxp/nxp_imx8m_linux_examples.md) |
| - [Infineon CYW30739 Lighting](/examples/lighting-app/infineon/cyw30739/README.md) |
| - [Infineon PSoC6](/examples/all-clusters-app/infineon/psoc6/README.md) |
| - [Qorvo](/examples/lighting-app/qpg/README.md) |
| - [Silicon Labs](../platforms/silabs/silabs_getting_started.md) |
| - [Simulated Linux](./simulated_device_linux.md) |
| - [Telink](/examples/lighting-app/telink/README.md) |
| - [TI Platform](../platforms/ti/ti_matter_overview.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) |
| - Any Thread device: |
| [Thread Profile](https://developer.apple.com/bug-reporting/profiles-and-logs/?name=HomeThread) |
| |
| ### Release to SHA Mappings |
| |
| | Platform | Release Version | SHA | |
| | -------- | --------------- | ------------------------------------------ | |
| | iOS | 17.6.1 | `2ee90eba27676950fa2f4ef96597d9696f510d5d` | |
| | iPadOS | 17.6.1 | `2ee90eba27676950fa2f4ef96597d9696f510d5d` | |
| | tvOS | 17.6 | `2ee90eba27676950fa2f4ef96597d9696f510d5d` | |
| | macOS | 14.6.1 | `2ee90eba27676950fa2f4ef96597d9696f510d5d` | |
| | iOS | 17.5.1 | `d09b5ac98f4d7d8b9f2c307f55ab5462576623a5` | |
| | iPadOS | 17.5.1 | `d09b5ac98f4d7d8b9f2c307f55ab5462576623a5` | |
| | tvOS | 17.5.1 | `d09b5ac98f4d7d8b9f2c307f55ab5462576623a5` | |
| | macOS | 14.5 | `d09b5ac98f4d7d8b9f2c307f55ab5462576623a5` | |
| | iOS | 16.7.8 | `83f7a2fe136e0b746db09f1d19e36c693a634b66` | |
| | iPadOS | 16.7.8 | `83f7a2fe136e0b746db09f1d19e36c693a634b66` | |
