diff --git a/.github/.wordlist.txt b/.github/.wordlist.txt index d27721c7561ae9..e2519b014ef6f2 100644 --- a/.github/.wordlist.txt +++ b/.github/.wordlist.txt @@ -54,6 +54,7 @@ APIs apk AppConfig AppImpl +AppleTV appliable ApplianceControl applianceeventsandalert @@ -278,8 +279,8 @@ connstring conntype const ContentApp -ContentAppPlatform ContentApp's +ContentAppPlatform ContentLaunch ContentLauncher continuousHinting @@ -543,6 +544,7 @@ GDB gdbserver GeneralCommissioning GeneralDiagnostics +generalised GenericConfigurationManagerImpl GenericConnectivityManagerImpl GenericImpl @@ -601,6 +603,8 @@ HKDF HMAC hoc homebrew +HomePod +HomePods hostapd hostname href @@ -614,6 +618,7 @@ IasWd iaszone ibb ICA +iCloud ICMP IDF IDL @@ -659,6 +664,7 @@ InvokeCommandRequests InvokeCommandResponse IoT ipaddr +iPadOS ipadr ipp iptables @@ -1090,8 +1096,8 @@ REPL repo req Requestor -RequestorCanConsent Requestor's +RequestorCanConsent Requestors responder RestrictedEvent @@ -1137,8 +1143,8 @@ SDB SDC SDHC SDK -sdkconfig SDK's +sdkconfig SDKs SDKTARGETSYSROOT sdl @@ -1324,6 +1330,7 @@ ttymxc ttyUSB TurbidityConcentrationMeasurement TvCasting +tvOS TXD txt uargument @@ -1370,8 +1377,8 @@ util utils UUID ux -VCP validator +VCP Vectorcall VendorID VendorName @@ -1395,6 +1402,7 @@ WaitNewInputEvent WakeOnLan WantedBy watchdogTimeout +watchOS webpage wg wget diff --git a/docs/README.md b/docs/README.md index 9b49300f55f6b8..dcb17c3552e56c 100644 --- 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 new file mode 100644 index 00000000000000..34b71306f7aedd --- /dev/null +++ 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 new file mode 100644 index 00000000000000..0ca95cb750a6f7 --- /dev/null +++ b/docs/guides/darwin.md @@ -0,0 +1,225 @@ +# Testing with Apple Devices + +### Matter is the foundation for connected things. + +Learn more about Matter [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)_ + +### Current requires for testing with Apple Devices + +##### Note: Matter functionality is currently a Developer Preview + +- 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). +- 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 + +## 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) +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 + 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 + +### Install the Matter Profile on your 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) +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 + 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/EnableMatter.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 + +### 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`, `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 + } +``` + +- 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 + +##### 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)) + +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. + +##### 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](#ensuring-your-matter-accessory-works-with-iosipadostvos) + +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. + +#### 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)