Skip to content

Commit 21e1579

Browse files
woody-applekiel-apple
authored and
austina-csa
committed
Updating darwin guide and SHAs (project-chip#34860)
* Updating links * Avoiding spell check confusion * Updating supported list * Update docs/guides/darwin.md Co-authored-by: Kiel Oleson <kielo@apple.com> * Update docs/guides/darwin.md Co-authored-by: Kiel Oleson <kielo@apple.com> * Fixing line breaks * Updating guide * Wording * Updating docs * Updating text --------- Co-authored-by: Kiel Oleson <kielo@apple.com>
1 parent 6a60a22 commit 21e1579

File tree

1 file changed

+117
-88
lines changed

1 file changed

+117
-88
lines changed

‎docs/guides/darwin.md

+117-88
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,21 @@
1-
# Testing with Apple Devices
1+
# Matter Development and Testing with/on Apple Devices
22

3-
### Matter is the foundation for connected things.
3+
### Overview
4+
5+
- To develop a Matter Application, learn more about how to develop with Matter
6+
on Apple's platforms [here](https://developer.apple.com/apple-home/matter/)
7+
8+
- Additional documentation about the Matter Support API is
9+
[here](https://developer.apple.com/documentation/mattersupport)
410

5-
Learn more about Matter [here](https://buildwithmatter.com/)
11+
### Filing Issues
12+
13+
- An issues related to Apple Home, or Development on Apple's Platforms should
14+
be reported using Feedback Assistant as described
15+
[below](#providing-feedback-to-apple)
16+
17+
- Any issues related to the Matter SDK should be reported to the project
18+
[here](https://github.com/project-chip/connectedhomeip/issues)
619

720
## Source Compatibility
821

@@ -12,20 +25,18 @@ changes are present in the release for testing.
1225

1326
Listed are the Current SHAs:
1427

15-
- iOS/iPadOS/tvOS 16.1:
16-
[`33f6a910cd9a8a0cfdd7088e2f43efd2f7f566a7`](https://github.com/project-chip/connectedhomeip/commits/33f6a910cd9a8a0cfdd7088e2f43efd2f7f566a7)
17-
18-
- iOS/iPadOS/tvOS 16.2 and 16.3:
19-
[`c279578c5bc37f117335aa96cec6c5552f070cc0`](https://github.com/project-chip/connectedhomeip/commits/c279578c5bc37f117335aa96cec6c5552f070cc0)
28+
- Latest macOS/tvOS/iOS/iPadOS:
29+
[`2ee90eba27676950fa2f4ef96597d9696f510d5d`](https://github.com/project-chip/connectedhomeip/commits/2ee90eba27676950fa2f4ef96597d9696f510d5d)
30+
- Larger list of SHAs are [here](#release-to-sha-mappings)
2031

2132
## Supported Platforms for Matter Device Testing
2233

2334
- Matter is supported by iOS/tvOS/iPadOS/watchOS/HomePod/AppleTV starting with
2435
16.1
25-
2636
- To test your Matter device with Apple's platforms, all you need is a device
2737
with a supported OS
28-
- Pairing via QR Code or Setup Code is supported directly from the Home App
38+
- Pairing via QR Code or Setup Code is supported directly from the Home App,
39+
or any third party Application
2940
- Please proceed to
3041
[this section](#testing-your-matter-device-with-apple-home) if you're
3142
developing a new device
@@ -46,14 +57,6 @@ For Context: This is a mapping of platform to OS
4657
- HomePod _(tvOS)_
4758
- Apple Watch _(watchOS)_
4859

49-
### Overview
50-
51-
- To develop a Matter Application, learn more about how to develop with Matter
52-
on Apple's platforms [here](https://developer.apple.com/apple-home/matter/)
53-
54-
- Additional documentation about the Matter Support API is
55-
[here](https://developer.apple.com/documentation/mattersupport)
56-
5760
### Setup Requirements for Application Development
5861

5962
- Devices must support BLE pairing, and have it enabled
@@ -122,9 +125,7 @@ For Context: This is a mapping of platform to OS
122125

123126
### Enable Developer Mode on your Apple Device
124127

125-
##### Note: Developer mode is a great way to get logs from your device as well as
126-
127-
enables other useful developer tools
128+
##### Note: Developer mode is a great way to get logs from your device as well as enable other useful developer tools
128129

129130
To enable developer mode, please follow the instructions
130131
[here](https://developer.apple.com/documentation/xcode/enabling-developer-mode-on-a-device)
@@ -137,30 +138,96 @@ chip-tool will require installing the
137138
on MacOS or iOS/iPadOS.
138139

139140
- Download the Bluetooth Central Matter Client Developer Mode profile and
140-
install it on a iOS/iPadOS 16.1 beta 3 and MacOS 13.1 beta 3 or later
141-
system.
141+
install it on a supported system.
142142

143143
- For _macOS_, Profile can be installed via Settings->Privacy &
144144
Security->Profiles
145145
- For _iOS/iPadOS_, If necessary, email the profile or use AirDrop to
146-
transfer the profile to the _iOS/iPadOS 16 beta 3_ device.
146+
transfer the profile to the _iOS/iPadOS_ device.
147147

148148
- Restart your system
149149
- For _iOS/iPadOS_, enable Developer Mode. Refer to
150150
[this developer page](https://developer.apple.com/documentation/xcode/enabling-developer-mode-on-a-device)
151151
- Compile chip-tool for macOS or CHIP Tool for iOS
152152

153+
## Supported Device Types in Apple Home
154+
155+
##### Note: Not exhaustive, and may be out of date, see [below](#apple-home-development-guide) for more information
156+
157+
| Type | Decimal | HEX | Notes |
158+
| ----------------------- | ------- | ---- | ------------------------------------------------ |
159+
| On/Off Light | 256 | 0100 | |
160+
| Dimming Light | 257 | 0101 | |
161+
| On/Off Plug-In Unit | 266 | 010A | |
162+
| Dimmable Plug-In Unit | 267 | 010B | |
163+
| On/Off Light Switch | 259 | 0103 | Requires both On/Off Client and Server |
164+
| Dimmer Switch | 260 | 0104 | Requires both On/Off Client and Server |
165+
| Generic Switch (button) | 15 | 000F | Supports momentary switch only, and not latching |
166+
| Contact Sensor | 21 | 0015 | |
167+
| Light Sensor | 262 | 0106 | |
168+
| Occupancy Sensor | 263 | 0107 | |
169+
| Temperature Sensor | 770 | 0302 | |
170+
| Humidity Sensor | 775 | 0307 | |
171+
| Air Quality Sensor | 44 | 002C | |
172+
| Door Lock | 10 | 000A | |
173+
| Window Covering | 514 | 0202 | |
174+
| Heating/Cooling Unit | 768 | 0300 | |
175+
| Thermostat | 769 | 0301 | |
176+
| Fan | 43 | 002B | |
177+
| Air Purifier | 45 | 002D | |
178+
| Temperature Color Light | 268 | 010C | |
179+
| Enhanced Color Light | 269 | 010D | |
180+
| Bridges | 14 | 000E | |
181+
| Robot Vacuum Cleaner | 116 | 0074 | Announced, not yet supported |
182+
183+
## Additional Device Type Support on Apple's Platforms
184+
185+
Apple's platforms support all device types available in the Matter SDK, so
186+
developers can use Matter.framework to develop their own applications that can
187+
add devices to Apple Home, or create their own Fabric to manage devices as well.
188+
189+
Please see documentation about `-[HMAccessory matterNodeID]`
190+
[here](https://developer.apple.com/documentation/homekit/hmaccessory/matternodeid-5zfqo)
191+
which allows you to use Matter.framework to interact with Matter Devices
192+
directly that are paired into Apple Home.
193+
194+
## Apple Home Development Guide
195+
196+
Please see [here](https://developer.apple.com/apple-home/) for more general
197+
information about developing an Application or a Device for Apple Home. This
198+
includes information about
199+
[best practices](https://developer.apple.com/apple-home/downloads/Matter-Accessory-Best-Practices-for-Apple-Home.pdf),
200+
[platform developer API](https://developer.apple.com/apple-home/matter/),
201+
[OTA Updates](https://developer.apple.com/accessories/Apple-Matter-OTA-User-Guide.pdf),
202+
general adoption Q&A, and the "Works with Apple Home" badge.
203+
204+
## General Matter Platform Development Guide
205+
206+
##### Getting the SDK Ready
207+
208+
##### Note: Most platforms have very similar, if not the same configuration requirements
209+
210+
1. Checkout and setup
211+
[Matter repo](https://github.com/project-chip/connectedhomeip.git) as per the
212+
instructions above.
213+
2. Find and edit one of the platform
214+
[examples](https://github.com/project-chip/connectedhomeip/tree/master/examples)
215+
to support the fixed device types above.
216+
3. Read the [platform guides](README.md) on how set up the hardware
217+
- There is a list of more detailed guides [here](#platform-guides)
218+
153219
## Testing your Matter Device with Apple Home
154220

155-
1. Clone the [Matter repo](https://github.com/project-chip/connectedhomeip.git)
221+
1. Clone the
222+
[Matter repository](https://github.com/project-chip/connectedhomeip.git)
156223
2. Checkout the specific commit hash (from [above](#source-compatibility)) for
157224
maximum compatibility with your installed release:
158-
- Example command for SHA `c279578c5bc37f117335aa96cec6c5552f070cc0`:
159-
`$ git checkout c279578c5bc37f117335aa96cec6c5552f070cc0`
225+
- Example command for SHA `2ee90eba27676950fa2f4ef96597d9696f510d5d`:
226+
`$ git checkout 2ee90eba27676950fa2f4ef96597d9696f510d5d`
160227

161-
In order to work with iOS/iPadOS/tvOS 16.1 or greater, device types as defined
162-
in the Matter Device Library spec are used to determine accessory categories.
163-
Ensure the right device type is set for each endpoint.
228+
In order to work with iOS/iPadOS/tvOS, device types as defined in the Matter
229+
Device Library spec are used to determine accessory categories. Ensure the right
230+
device type is set for each endpoint.
164231

165232
- For the `all-clusters-app` as an example, this can be set in
166233
`FIXED_DEVICE_TYPES`, `FIXED_DEVICE_TYPE_OFFSETS`, and
@@ -190,29 +257,11 @@ Example:
190257
}
191258
```
192259

193-
- Supported device types are (not exhaustive):
194-
195-
| Type | Decimal | HEX |
196-
| ------------------ | ------- | ---- |
197-
| Lightbulb | 256 | 0100 |
198-
| Lightbulb + Dimmer | 257 | 0101 |
199-
| Switch | 259 | 0103 |
200-
| Contact Sensor | 21 | 0015 |
201-
| Door Lock | 10 | 000A |
202-
| Light Sensor | 262 | 0106 |
203-
| Occupancy Sensor | 263 | 0107 |
204-
| Outlet | 266 | 010A |
205-
| Color Bulb | 268 | 010C |
206-
| Window Covering | 514 | 0202 |
207-
| Thermostat | 769 | 0301 |
208-
| Temperature Sensor | 770 | 0302 |
209-
| Flow Sensor | 774 | 0306 |
210-
211-
#### Examples of how to setup devices
260+
### Examples of how to setup devices
212261

213262
##### Case study 1: Configuring a development M5Stack, as a multi-device to work with iOS/iPadOS/tvOS
214263

215-
##### 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))
264+
##### 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))
216265

217266
1. Checkout and setup
218267
[Matter repo](https://github.com/project-chip/connectedhomeip.git) as per the
@@ -235,21 +284,7 @@ Example:
235284
initialize your development environment, compile the firmware and flash your
236285
hardware.
237286

238-
#### General Matter Platform Development Guide
239-
240-
##### Getting the SDK Ready
241-
242-
##### Note: Most platforms have very similar, if not the same configuration requirements
243-
244-
1. Checkout and setup
245-
[Matter repo](https://github.com/project-chip/connectedhomeip.git) as per the
246-
instructions above.
247-
2. Find and edit one of the platform
248-
[examples](https://github.com/project-chip/connectedhomeip/tree/master/examples)
249-
to support the fixed device types above.
250-
3. Read the [platform guides](README.md) on how set up the hardware
251-
252-
##### Guides
287+
### Platform Guides
253288

254289
- [Bouffalo Lab](/examples/lighting-app/bouffalolab/README.md)
255290
- [EFR32 Window Covering](/examples/window-app/silabs/README.md)
@@ -300,26 +335,20 @@ Example:
300335
- [Apple Home Profile](https://developer.apple.com/bug-reporting/profiles-and-logs/?platform=tvos&name=homekit)
301336
- [Network Profile](https://developer.apple.com/bug-reporting/profiles-and-logs/?platform=tvos&name=network)
302337
- [mDNS Profile](https://developer.apple.com/bug-reporting/profiles-and-logs/?platform=tvos&name=mdns)
303-
304-
### Release Notes & Known Issues
305-
306-
- Please refer to the iOS/iPadOS 16.1
307-
[Release Notes](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-16_1-release-notes)
308-
for currently known issues.
309-
- Please refer to the iOS/iPadOS 16.2
310-
[Release Notes](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-ipados-16_2-release-notes)
311-
for currently known issues
312-
- Please refer to the iOS & iPadOS 16.3
313-
[Release Notes](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-ipados-16_3-release-notes)
314-
for currently known issues
315-
- Please refer to the iOS & iPadOS 16.4
316-
[Release Notes](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-ipados-16_4-release-notes)
317-
for currently known issues
318-
- Please refer to the iOS & iPadOS 16.5
319-
[Release Notes](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-ipados-16_5-release-notes)
320-
for currently known issues
321-
- An issues related to Apple Home integration should be reported
322-
[feedback](#providing-feedback-to-apple) as described in this section
323-
324-
- Any issues related to the Matter SDK should be reported to the project
325-
[here](https://github.com/project-chip/connectedhomeip/issues)
338+
- Any Thread device:
339+
[Thread Profile](https://developer.apple.com/bug-reporting/profiles-and-logs/?name=HomeThread)
340+
341+
### Release to SHA Mappings
342+
343+
| Platform | Release Version | SHA |
344+
| -------- | --------------- | ------------------------------------------ |
345+
| iOS | 17.6.1 | `2ee90eba27676950fa2f4ef96597d9696f510d5d` |
346+
| iPadOS | 17.6.1 | `2ee90eba27676950fa2f4ef96597d9696f510d5d` |
347+
| tvOS | 17.6 | `2ee90eba27676950fa2f4ef96597d9696f510d5d` |
348+
| macOS | 14.6.1 | `2ee90eba27676950fa2f4ef96597d9696f510d5d` |
349+
| iOS | 17.5.1 | `d09b5ac98f4d7d8b9f2c307f55ab5462576623a5` |
350+
| iPadOS | 17.5.1 | `d09b5ac98f4d7d8b9f2c307f55ab5462576623a5` |
351+
| tvOS | 17.5.1 | `d09b5ac98f4d7d8b9f2c307f55ab5462576623a5` |
352+
| macOS | 14.5 | `d09b5ac98f4d7d8b9f2c307f55ab5462576623a5` |
353+
| iOS | 16.7.8 | `83f7a2fe136e0b746db09f1d19e36c693a634b66` |
354+
| iPadOS | 16.7.8 | `83f7a2fe136e0b746db09f1d19e36c693a634b66` |

0 commit comments

Comments
 (0)