From 82c5c7b68627b8951bc6aefec59648695e03980d Mon Sep 17 00:00:00 2001 From: Jiacheng Guo Date: Thu, 24 Mar 2022 22:20:30 +0800 Subject: [PATCH] example: add example for adding external platform --- docs/custom_platform_guide/BUILD.gn | 116 +++++++++++++++++++++++++++ docs/custom_platform_guide/README.md | 33 ++++++++ 2 files changed, 149 insertions(+) create mode 100644 docs/custom_platform_guide/BUILD.gn create mode 100644 docs/custom_platform_guide/README.md diff --git a/docs/custom_platform_guide/BUILD.gn b/docs/custom_platform_guide/BUILD.gn new file mode 100644 index 000000000..f4f452c96 --- /dev/null +++ b/docs/custom_platform_guide/BUILD.gn @@ -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=", + "CHIP_DEVICE_PLATFORM_CONFIG_INCLUDE=", + "CHIP_PLATFORM_CONFIG_INCLUDE=", + "INET_CONFIG_INCLUDE=", + "SYSTEM_PLATFORM_CONFIG_INCLUDE=", + ] + + 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", + ] + } +} diff --git a/docs/custom_platform_guide/README.md b/docs/custom_platform_guide/README.md new file mode 100644 index 000000000..265caa8b8 --- /dev/null +++ b/docs/custom_platform_guide/README.md @@ -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.