example: add example for adding external platform

2026-04-27 19:13:13 +00:00 · 2022-03-24 22:20:30 +08:00
parent d1be1d898a
commit 82c5c7b686
2 changed files with 149 additions and 0 deletions
@@ -0,0 +1,116 @@
+# Copyright (c) 2021 Project CHIP Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import("//build_overrides/chip.gni")
+
+import("${chip_root}/build/chip/buildconfig_header.gni")
+import("${chip_root}/src/platform/device.gni")
+
+config("ESP32_custom_include") {
+  include_dirs = [ "../../" ]
+}
+
+buildconfig_header("custom_buildconfig") {
+  header = "CHIPDeviceBuildConfig.h"
+  header_dir = "platform"
+  
+  defines = [
+    "CHIP_DEVICE_CONFIG_ENABLE_WPA=false",
+    "CHIP_ENABLE_OPENTHREAD=${chip_enable_openthread}",
+    "CHIP_DEVICE_CONFIG_THREAD_FTD=${chip_openthread_ftd}",
+    "OPENTHREAD_CONFIG_ENABLE_TOBLE=false",
+    "CHIP_BYPASS_RENDEZVOUS=false",
+    "CHIP_STACK_LOCK_TRACKING_ENABLED=false",
+    "CHIP_STACK_LOCK_TRACKING_ERROR_FATAL=false",
+    "CHIP_ENABLE_ADDITIONAL_DATA_ADVERTISING=false",
+    "CHIP_DEVICE_CONFIG_RUN_AS_ROOT=false",
+    "CHIP_DEVICE_LAYER_TARGET_ESP32=1",
+    "CHIP_DEVICE_LAYER_TARGET=ESP32_custom",
+    "BLE_PLATFORM_CONFIG_INCLUDE=<platform/ESP32_custom/BlePlatformConfig.h>",
+    "CHIP_DEVICE_PLATFORM_CONFIG_INCLUDE=<platform/ESP32_custom/CHIPDevicePlatformConfig.h>",
+    "CHIP_PLATFORM_CONFIG_INCLUDE=<platform/ESP32_custom/CHIPPlatformConfig.h>",
+    "INET_CONFIG_INCLUDE=<platform/ESP32_custom/InetPlatformConfig.h>",
+    "SYSTEM_PLATFORM_CONFIG_INCLUDE=<platform/ESP32_custom/SystemPlatformConfig.h>",
+  ]
+ 
+  if (chip_enable_ota_requestor) {
+    defines += [ "CHIP_DEVICE_CONFIG_ENABLE_OTA_REQUESTOR=1" ]
+  }
+}
+
+group("platform_buildconfig") {
+  public_deps = [
+    ":custom_buildconfig",
+  ]
+
+  public_configs = [
+    ":ESP32_custom_include", 
+  ]
+}
+
+static_library("ESP32_custom") {
+  sources = [
+    "${chip_root}/src/platform/SingletonConfigurationManager.cpp",
+    "BLEManagerImpl.h",
+    "CHIPDevicePlatformConfig.h",
+    "CHIPDevicePlatformEvent.h",
+    "ConfigurationManagerImpl.cpp",
+    "ConfigurationManagerImpl.h",
+    "ConnectivityManagerImpl.cpp",
+    "ConnectivityManagerImpl.h",
+    "DeviceNetworkProvisioningDelegateImpl.cpp",
+    "DeviceNetworkProvisioningDelegateImpl.h",
+    "DiagnosticDataProviderImpl.cpp",
+    "DiagnosticDataProviderImpl.h",
+    "ESP32Config.cpp",
+    "ESP32Config.h",
+    "ESP32Utils.cpp",
+    "ESP32Utils.h",
+    "KeyValueStoreManagerImpl.cpp",
+    "KeyValueStoreManagerImpl.h",
+    "Logging.cpp",
+    "LwIPCoreLock.cpp",
+    "NetworkCommissioningDriver.h",
+    "NetworkCommissioningDriver.cpp",
+    "PlatformManagerImpl.cpp",
+    "PlatformManagerImpl.h",
+    "SystemTimeSupport.cpp",
+    "SystemTimeSupport.h",
+    "bluedroid/BLEManagerImpl.cpp",
+    "nimble/BLEManagerImpl.cpp",
+    "ConnectivityManagerImpl_WiFi.cpp",
+  ]
+
+  deps = [
+    "${chip_root}/src/lib/dnssd:platform_header",
+    "${chip_root}/src/setup_payload",
+  ]
+
+  public_deps = [
+    "${chip_root}/src/crypto",
+    "${chip_root}/src/platform:platform_base",
+    ":platform_buildconfig",
+  ]
+
+  public_configs = [
+    ":ESP32_custom_include", 
+  ]
+
+  if (chip_enable_ota_requestor) {
+    sources += [
+      "OTAImageProcessorImpl.cpp",
+      "OTAImageProcessorImpl.h",
+    ]
+  }
+}
@@ -0,0 +1,33 @@
+# Adding External Platforms for Matter
+
+esp-matter provides support for overriding the device layer in Matter. Here are the required steps for adding an external platform.
+
+## Creating the external platform directory
+
+Create a directory `platform/${NEW_PLATFORM_NAME}` in your codebase. You can typically copy `${ESP_MATTER_PATH}/connectedhomeip/connectedhomeip/src/platform/ESP32` as a start. Note that the new platform name shall be different with name `ESP32`. In this article we'll use `ESP32_custom` as an example. The directory must be under `platform` folder to meet the Matter include path conventions.
+
+## Modifying the BUILD.gn target
+
+We've provided an example BUILD.gn file for the `ESP32_custom` example platform. It simply compiles the ESP32 platform in Matter without any modifications.
+
+The new platform directory must be added to the Matter include path. See the `ESP32_custion_include` config in the [BUILD.gn](./BUILD.gn).
+
+Multiple build configs must be exported to the build system. See the `buildconfig_header` section in the [BUILD.gn](./BUILD.gn) for the required definitions.
+
+## Required Kconfigs
+
+The config `CONFIG_CHIP_ENABLE_EXTERNAL_PLATFORM` shall be enabled.
+The config `CONFIG_CHIP_EXTERNAL_PLATFORM_TARGET` shall be the relative path from `${ESP_MATTER_PATH}/connectedhomeip/connectedhomeip/config/esp32` to the external platform directory. For instance, if your source tree is:
+
+```
+.
+├── esp-matter
+└── platform
+    └── ESP32_custom
+```
+
+Then `CONFIG_CHIP_EXTERNAL_PLATFORM_TARGET` will be `//../../../../../platform/ESP32_custom`
+
+The config `CONFIG_BUILD_CHIP_TESTS` shall be disabled.
+
+If your external platform does not support the [shell interface](../../connectedhomeip/connectedhomeip/src/lib/shell) provided in the Matter shell library, then `CONFIG_ENABLE_CHIP_SHELL` shall also be disabled.