Skip to content

Commit

Permalink
Merge branch 'master' into match_presets_sdk_code_to_test_plan
Browse files Browse the repository at this point in the history
  • Loading branch information
@woody-apple
woody-apple authored Aug 9, 2024
2 parents 25c10af + c0b140b commit a8c3e5b
Show file tree
Hide file tree
Showing 81 changed files with 2,959 additions and 1,159 deletions.
205 changes: 117 additions & 88 deletions docs/guides/darwin.md
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,21 @@
# Testing with Apple Devices
# Matter Development and Testing with/on Apple Devices

### Matter is the foundation for connected things.
### 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)

Learn more about Matter [here](https://buildwithmatter.com/)
### 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

Expand All @@ -12,20 +25,18 @@ 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 and 16.3:
[`c279578c5bc37f117335aa96cec6c5552f070cc0`](https://github.com/project-chip/connectedhomeip/commits/c279578c5bc37f117335aa96cec6c5552f070cc0)
- 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
- 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
Expand All @@ -46,14 +57,6 @@ For Context: This is a mapping of platform to OS
- HomePod _(tvOS)_
- Apple Watch _(watchOS)_

### 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)

### Setup Requirements for Application Development

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

### Enable Developer Mode on your Apple Device

##### Note: Developer mode is a great way to get logs from your device as well as

enables other useful developer tools
##### 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)
Expand All @@ -137,30 +138,96 @@ chip-tool will require installing the
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.
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 16 beta 3_ device.
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 repo](https://github.com/project-chip/connectedhomeip.git)
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 `c279578c5bc37f117335aa96cec6c5552f070cc0`:
`$ git checkout c279578c5bc37f117335aa96cec6c5552f070cc0`
- Example command for SHA `2ee90eba27676950fa2f4ef96597d9696f510d5d`:
`$ git checkout 2ee90eba27676950fa2f4ef96597d9696f510d5d`

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.
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
Expand Down Expand Up @@ -190,29 +257,11 @@ Example:
}
```

- Supported device types are (not exhaustive):

| Type | Decimal | HEX |
| ------------------ | ------- | ---- |
| Lightbulb | 256 | 0100 |
| Lightbulb + Dimmer | 257 | 0101 |
| Switch | 259 | 0103 |
| Contact Sensor | 21 | 0015 |
| Door Lock | 10 | 000A |
| Light Sensor | 262 | 0106 |
| Occupancy Sensor | 263 | 0107 |
| Outlet | 266 | 010A |
| Color Bulb | 268 | 010C |
| Window Covering | 514 | 0202 |
| Thermostat | 769 | 0301 |
| Temperature Sensor | 770 | 0302 |
| Flow Sensor | 774 | 0306 |

#### Examples of how to setup devices
### 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](#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](#platform-guides))

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

#### 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

##### Guides
### Platform Guides

- [Bouffalo Lab](/examples/lighting-app/bouffalolab/README.md)
- [EFR32 Window Covering](/examples/window-app/silabs/README.md)
Expand Down Expand Up @@ -300,26 +335,20 @@ Example:
- [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 16.1
[Release Notes](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-16_1-release-notes)
for currently known issues.
- Please refer to the iOS/iPadOS 16.2
[Release Notes](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-ipados-16_2-release-notes)
for currently known issues
- Please refer to the iOS & iPadOS 16.3
[Release Notes](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-ipados-16_3-release-notes)
for currently known issues
- Please refer to the iOS & iPadOS 16.4
[Release Notes](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-ipados-16_4-release-notes)
for currently known issues
- Please refer to the iOS & iPadOS 16.5
[Release Notes](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-ipados-16_5-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)
- 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` |
35 changes: 19 additions & 16 deletions examples/all-clusters-app/all-clusters-common/all-clusters-app.matter
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4386,7 +4386,7 @@ cluster ElectricalEnergyMeasurement = 145 {

/** This cluster is used to allow clients to control the operation of a hot water heating appliance so that it can be used with energy management. */
provisional cluster WaterHeaterManagement = 148 {
revision 1;
revision 2;

enum BoostStateEnum : enum8 {
kInactive = 0;
Expand All @@ -4398,24 +4398,32 @@ provisional cluster WaterHeaterManagement = 148 {
kTankPercent = 0x2;
}

bitmap WaterHeaterDemandBitmap : bitmap8 {
bitmap WaterHeaterHeatSourceBitmap : bitmap8 {
kImmersionElement1 = 0x1;
kImmersionElement2 = 0x2;
kHeatPump = 0x4;
kBoiler = 0x8;
kOther = 0x10;
}

bitmap WaterHeaterTypeBitmap : bitmap8 {
kImmersionElement1 = 0x1;
kImmersionElement2 = 0x2;
kHeatPump = 0x4;
kBoiler = 0x8;
kOther = 0x10;
struct WaterHeaterBoostInfoStruct {
elapsed_s duration = 0;
optional boolean oneShot = 1;
optional boolean emergencyBoost = 2;
optional temperature temporarySetpoint = 3;
optional percent targetPercentage = 4;
optional percent targetReheat = 5;
}

info event BoostStarted = 0 {
WaterHeaterBoostInfoStruct boostInfo = 0;
}

readonly attribute WaterHeaterTypeBitmap heaterTypes = 0;
readonly attribute WaterHeaterDemandBitmap heatDemand = 1;
info event BoostEnded = 1 {
}

readonly attribute WaterHeaterHeatSourceBitmap heaterTypes = 0;
readonly attribute WaterHeaterHeatSourceBitmap heatDemand = 1;
readonly attribute optional int16u tankVolume = 2;
readonly attribute optional energy_mwh estimatedHeatRequired = 3;
readonly attribute optional percent tankPercentage = 4;
Expand All @@ -4428,12 +4436,7 @@ provisional cluster WaterHeaterManagement = 148 {
readonly attribute int16u clusterRevision = 65533;

request struct BoostRequest {
elapsed_s duration = 0;
optional boolean oneShot = 1;
optional boolean emergencyBoost = 2;
optional temperature temporarySetpoint = 3;
optional percent targetPercentage = 4;
optional percent targetReheat = 5;
WaterHeaterBoostInfoStruct boostInfo = 0;
}

/** Allows a client to request that the water heater is put into a Boost state. */
Expand Down
Loading

0 comments on commit a8c3e5b

Please sign in to comment.