project-chip · woody-apple · Jul 20, 2022 · Jul 18, 2022 · Jul 18, 2022 · Jul 19, 2022
diff --git a/.github/.wordlist.txt b/.github/.wordlist.txt
@@ -278,8 +278,8 @@ connstring
 conntype
 const
 ContentApp
-ContentAppPlatform
 ContentApp's
+ContentAppPlatform
 ContentLaunch
 ContentLauncher
 continuousHinting
@@ -614,6 +614,7 @@ IasWd
 iaszone
 ibb
 ICA
+iCloud
 ICMP
 IDF
 IDL
@@ -659,6 +660,7 @@ InvokeCommandRequests
 InvokeCommandResponse
 IoT
 ipaddr
+iPadOS
 ipadr
 ipp
 iptables
@@ -1090,8 +1092,8 @@ REPL
 repo
 req
 Requestor
-RequestorCanConsent
 Requestor's
+RequestorCanConsent
 Requestors
 responder
 RestrictedEvent
@@ -1137,8 +1139,8 @@ SDB
 SDC
 SDHC
 SDK
-sdkconfig
 SDK's
+sdkconfig
 SDKs
 SDKTARGETSYSROOT
 sdl
@@ -1324,6 +1326,7 @@ ttymxc
 ttyUSB
 TurbidityConcentrationMeasurement
 TvCasting
+tvOS
 TXD
 txt
 uargument
@@ -1370,8 +1373,8 @@ util
 utils
 UUID
 ux
-VCP
 validator
+VCP
 Vectorcall
 VendorID
 VendorName

diff --git a/docs/README.md b/docs/README.md
@@ -11,6 +11,11 @@
     [Visual Studio Code](https://code.visualstudio.com/) can be found in
     [the development guide](./VSCODE_DEVELOPMENT.md)
 
+## Platform Guides
+
+-   Various guides are available [here](./guides/README.md) that cover platform
+    bring up, testing, and various troubleshooting things.
+
 ## Project Flow
 
 -   Documentation about general project usage of GitHub, and project tools is

diff --git a/docs/guides/README.md b/docs/guides/README.md
@@ -0,0 +1,47 @@
+# Guides
+
+## Platform Guides
+
+-   [Android - Building](./android_building.md)
+-   [Apple - Testing with iPhone, iPad, macOS, Apple TV, HomePod, Watch, etc](./darwin.md)
+-   [Infineon - Software Update](./infineon_p6_software_update.md)
+-   [Linux - Simulated Devices](./simulated_device_linux.md)
+-   [mbedOS - Adding a new target](./mbedos_add_new_target.md)
+-   [mbedOS - Commissioning](./mbedos_commissioning.md)
+-   [mbedOS - Platform Overview](./mbedos_platform_overview.md)
+-   [nRF Connect - Android Commissioning](./nrfconnect_android_commissioning.md)
+-   [nRF Connect - CLI Guide](./nrfconnect_examples_cli.md)
+-   [nRF Connect - Configuration](./nrfconnect_examples_configuration.md)
+-   [nRF Connect - Factory Data Configuration](./nrfconnect_factory_data_configuration.md)
+-   [nRF Connect - Platform Overview](./nrfconnect_platform_overview.md)
+-   [nRF Connect - Software Update](./nrfconnect_examples_software_update.md)
+-   [NXP - Android Commissioning](./nxp_k32w_android_commissioning.md)
+-   [NXP - Linux Examples](./nxp_imx8m_linux_examples.md)
+-   [Silicon Labs - Building](./silabs_efr32_building.md)
+-   [Silicon Labs - Building](./silabs_efr32_software_update.md)
+-   [TI - Platform Overview](./ti_platform_overview.md)
+
+## Development Guides
+
+-   [Access Control](./access-control-guide.md)
+-   [IP Commissioning](./ip_commissioning.md)
+
+## Setup Guides
+
+-   [Open Thread - Hardware suggestions](./openthread_rcp_nrf_dongle.md)
+-   [Open Thread - Setting up a Pi as a border router](./openthread_border_router_pi.md)
+
+## Troubleshooting Guides
+
+-   [Avahi - Troubleshooting](./troubleshooting_avahi.md)
+
+## Tool Guides
+
+-   [chip-tool](./chip_tool_guide.md)
+-   [Python Matter-Repl](./matter-repl.md)
+-   [python-chip-controller - Advanced](./python_chip_controller_advanced_usage.md)
+-   [python-chip-controller - Building](./python_chip_controller_building.md)
+
+## Build Guides
+
+-   [Building](./BUILDING.md)
diff --git a/docs/guides/darwin.md b/docs/guides/darwin.md
@@ -0,0 +1,202 @@
+# Testing with Apple Devices
+
+### Matter is the foundation for connected things.
+
+Learn more about Matter on the [here](https://buildwithmatter.com/)
+
+## Setup Requirements
+
+Note: These steps are supported on:
+
+-   iPhone _(iOS)_
+-   iPad _(iPadOS)_
+-   mac _(macOS)_
+-   AppleTV _(tvOS)_
+-   HomePod _(tvOS)_
+-   Apple Watch _(watchOS)_
+
+### Matter functionality is currently a Developer Preview, current requirements include:
+
+-   An iPhone or iPad running iOS/iPadOS at least 15.6. You will need to install
+    a profile on it (instructions below).
+-   An Apple TV or HomePod running at least tvOS 15.6. You will need to install
+    a profile on it (instructions below). If you have multiple Apple TVs and/or
+    HomePods, you will need to install the profile on all of them.
+-   The iPhone or iPad with the Matter profile must belong to the same iCloud
+    account as the Apple TV or HomePod with the Matter profile.
+-   A test iCloud account is highly recommended for Matter development to avoid
+    interference with existing homes.
+
+## Source Compatibility
+
+Each developer preview release is compatible with a certain SHA from this
+repository.
+
+-   iOS/iPadOS/tvOS 15.6 Developer Preview:
+    [`cfc35951be66a664a6efdadea56d1b8ea6e63e96`](https://github.com/project-chip/connectedhomeip/commits/cfc35951be66a664a6efdadea56d1b8ea6e63e96)
+-   iOS/iPadOS/tvOS 16.0 Developer Preview:
+    [`cfc35951be66a664a6efdadea56d1b8ea6e63e96`](https://github.com/project-chip/connectedhomeip/commits/cfc35951be66a664a6efdadea56d1b8ea6e63e96)
+
+## Profile Installation
+
+### Install the Matter Profile on your iPhone or iPad
+
+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)
+   and install it on the iOS/iPadOS 15.6 device. If necessary, email the profile
+   or use AirDrop to transfer the profile to the iOS/iPadOS 15.6 device.
+2. Restart the device.
+
+### Install the Matter Profile on your Apple TV or HomePod
+
+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)
+   and install it on the the Apple TV or HomePod running tvOS 15.6. If
+   necessary, use
+   [Apple Configurator 2](https://support.apple.com/guide/apple-configurator-2/connect-devices-to-your-mac-cad9d4b2211e/2.14/mac/11.3.1)
+   to transfer the profile to the Apple TV or HomePod.
+2. Restart the device.
+
+### Ensuring Your Matter Accessory Works with iOS/iPadOS/tvOS
+
+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 `cfc35951be66a664a6efdadea56d1b8ea6e63e96`:
+      `$ git checkout cfc35951be66a664a6efdadea56d1b8ea6e63e96`
+
+In order to work with iOS/iPadOS/tvOS 15.6 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.
+
+-   For the `all-clusters-app` as an example, this can be set in
+    `FIXED_DEVICE_TYPES` in `endpoint_config.h`
+
+-   A light on Endpoint 1 can be set in `FIXED_DEVICE_TYPES` in
+    `endpoint_config.h` for `all-clusters-app` like so:
+
+```
+// Array of device types
+    #define FIXED_DEVICE_TYPES       \
+    {                                \
+        { 0x0016, 1 }, { 0x0100, 1 } \
+    }
+```
+
+#### Examples of how to setup a couple apps
+
+##### Case study 1: Configuring a development M5Stack 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)
+
+1. Checkout and setup
+   [Matter repo](https://github.com/project-chip/connectedhomeip.git) as per the
+   instructions
+   [above](#ensuring-your-matter-accessory-works-with-iosipadostvos)
+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.
+3. Where instructions talk about accessory configuration and specifically
+   "menuconfig" for the ESP32-based M5Stack please defer to the next section for
+   iOS/iPadOS/tvOS specific configuration instructions.
+
+##### Use `idf.py menuconfig` to configure the M5Stack to interact with iOS/iPadOS/tvOS
+
+1. Navigate to "Demo"
+    - Ensure the "Device Type" is "M5Stack"
+    - Set "Rendezvous Mode" to "BLE"
+2. Navigate back to the main menu (use the back arrow keys)
+3. Navigate to "Component Config" → "CHIP Device Layer" → “Wi-Fi Station
+   Options"
+    - Ensure you do not have any entries for SSID and password
+4. Navigate to "Component Config" → "CHIP Device Layer" → "Device Identification
+   Options"
+    - Ensure you are using the correct Vendor ID and a supported Product ID from
+      the “Ensuring Your Matter Accessory Works with the iOS/iPadOS/tvOS section
+      above.
+5. Press "q" and "Y" to quit and save the settings
+
+##### Case Study 2: a development Nordic board (NRF52840) 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](#ensuring-your-matter-accessory-works-with-iosipadostvos)
+
+2. Edit PRODUCT_ID value in the file
+   `connectedhomeip/examples/lighting-app/nrfconnect/main/include/CHIPProjectConfig.h`
+   to ensure you are using a supported Product ID from the “Ensuring Your Matter
+   Accessory Works with iOS iPadOS/tvOS” section above.
+    - 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.
+
+##### Configuring Multiple Hardware Accessories
+
+1. Follow instructions 1 through 5 above for your 2nd of accessory hardware
+2. On your hardware, Navigate to "Component Config" → p device layer → Testing
+   Options.
+3. Edit both the "Use Test Setup Pin Code" and "Use t Setup discriminator" to be
+   unique values not shared with other Hardware. For example: change the last
+   digit of each.
+
+#### General Platform Guides
+
+##### 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](#ensuring-your-matter-accessory-works-with-iosipadostvos)
+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](#ensuring-your-matter-accessory-works-with-iosipadostvos)
+3. Read the [platform guides](.) on how set up the hardware
+
+##### Guides
+
+-   [Bouffalo Lab](/examples/lighting-app/bouffalolab/bl602/README.md)
+-   [EFR32 Window Covering](/examples/window-app/efr32/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](./nrfconnect_examples_configuration.md)
+-   [nRF Connect Pump](/examples/pump-app/nrfconnect/README.md)
+-   [NXP Examples](./nxp_imx8m_linux_examples.md)
+-   [NXP](/examples/all-clusters-app/nxp/mw320/README.md)
+-   [P6](/examples/all-clusters-app/p6/README.md)
+-   [Qorvo](/examples/lighting-app/qpg/README.md)
+-   [SiliconLabs](./silabs_efr32_building.md)
+-   [Simulated Linux](./simulated_device_linux.md)
+-   [Telink](/examples/lighting-app/telink/README.md)
+-   [TI Platform](./ti_platform_overview.md)
+-   [TI All Clusters](/examples/all-clusters-app/cc13x2x7_26x2x7/README.md)
+-   [Tizen](/examples/lighting-app/tizen/README.md)
+
+### 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-ipados-16-release-notes)
+    for currently known issues.
+-   Further issues should be reported
+    [here](https://github.com/project-chip/connectedhomeip/issues)