From 26501411e1e011f8ad231c746b805abcc68ffc51 Mon Sep 17 00:00:00 2001 From: Sergei Lissianoi <54454955+selissia@users.noreply.github.com> Date: Fri, 12 Nov 2021 16:19:31 -0500 Subject: [PATCH] Introduce header files for the OTA Requestor API declarations (#11605) Problem Need to start introducing APIs for the OTA Requestor refactoring Change overview Introduce ota-downloader.h, ota-image-processor.h, ota-requestor-driver.h, ota-requestor.h and ota-requestor-interface.h containing OTA Requestor API declarations. Testing No executable code changed. No testing beyond compilation and CI. * Introduce ota-requestor.h containing Requestor API declarations * Split OTA Requestor class declarations into multiple headers * Restyled by whitespace * Restyled by clang-format * Clean up comments and function names * Misc API format changes based on PR comments * Restyled by clang-format * Rename some classes and methods * Rename a method * Renaming avd vairious formatting changes * Restyled by clang-format * Add an API declaration Co-authored-by: Restyled.io --- .../clusters/ota-requestor/ota-downloader.h | 60 +++++++++++++++++++ .../ota-requestor/ota-image-processor.h | 47 +++++++++++++++ .../ota-requestor/ota-requestor-driver.h | 39 ++++++++++++ .../ota-requestor/ota-requestor-interface.h | 43 +++++++++++++ .../clusters/ota-requestor/ota-requestor.h | 49 +++++++++++++++ 5 files changed, 238 insertions(+) create mode 100644 src/app/clusters/ota-requestor/ota-downloader.h create mode 100644 src/app/clusters/ota-requestor/ota-image-processor.h create mode 100644 src/app/clusters/ota-requestor/ota-requestor-driver.h create mode 100644 src/app/clusters/ota-requestor/ota-requestor-interface.h create mode 100644 src/app/clusters/ota-requestor/ota-requestor.h diff --git a/src/app/clusters/ota-requestor/ota-downloader.h b/src/app/clusters/ota-requestor/ota-downloader.h new file mode 100644 index 00000000000000..1039a5994c14c3 --- /dev/null +++ b/src/app/clusters/ota-requestor/ota-downloader.h @@ -0,0 +1,60 @@ +/* + * + * Copyright (c) 2021 Project CHIP Authors + * All rights reserved. + * + * 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. + */ + +/* This file contains the declarations for the OTADownloader class which + * abstracts the image download functionality from the particular protocol + * used for it. + * Applications and platforms implementing the OTA Requestor functionality + * must include this file + */ + +#include "ota-image-processor.h" + +#pragma once + +// A class that abstracts the image download functionality from the particular +// protocol used for that (BDX or possibly HTTPS) +class OTADownloader +{ +public: + // API declarations start + + // Application calls this method to direct OTADownloader to begin the download + void virtual BeginDownload(); + + // Platform calls this method upon the completion of PrepareDownload() processing + void virtual OnPreparedForDownload(); + + // Action parameter type for the OnBlockProcessed() + enum BlockActionType + { + kGetNext, + kEnd + }; + + // Platform calls this method upon the completion of ProcessBlock() processing + void virtual OnBlockProcessed(BlockActionType action); + + // A setter for the delegate class pointer + void SetImageProcessorDelegate(OTAImageProcessorDriver * delegate); + + // API declarations end + +private: + OTAImageProcessorDriver * mImageProcessorDelegate; +}; diff --git a/src/app/clusters/ota-requestor/ota-image-processor.h b/src/app/clusters/ota-requestor/ota-image-processor.h new file mode 100644 index 00000000000000..b9a7ee9856c261 --- /dev/null +++ b/src/app/clusters/ota-requestor/ota-image-processor.h @@ -0,0 +1,47 @@ +/* + * + * Copyright (c) 2021 Project CHIP Authors + * All rights reserved. + * + * 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. + */ + +/* This file contains the declarations for OTAImageProcessor, a platform-agnostic + * interface for processing downloaded chunks of OTA image data. + * Each platform should provide an implementation of this interface. + */ + +#pragma once + +// This is a platform-agnostic interface for processing downloaded +// chunks of OTA image data (data could be raw image data meant for flash or +// metadata). Each platform should provide an implementation of this +// interface. +class OTAImageProcessorDriver +{ +public: + // Open file, find block of space in persistent memory, or allocate a buffer, etc. + virtual CHIP_ERROR PrepareDownload() = 0; + + // Must not be a blocking call to support cases that require IO to elements such as // external peripherals/radios + virtual CHIP_ERROR ProcessBlock(ByteSpan & data) = 0; + + // Close file, close persistent storage, etc + virtual CHIP_ERROR Finalize() = 0; + + virtual chip::Optional PercentComplete() = 0; + + // Clean up the download which could mean erasing everything that was written, + // releasing buffers, etc. + virtual CHIP_ERROR Abort() = 0; +}; diff --git a/src/app/clusters/ota-requestor/ota-requestor-driver.h b/src/app/clusters/ota-requestor/ota-requestor-driver.h new file mode 100644 index 00000000000000..786c49c27c6715 --- /dev/null +++ b/src/app/clusters/ota-requestor/ota-requestor-driver.h @@ -0,0 +1,39 @@ +/* + * + * Copyright (c) 2021 Project CHIP Authors + * All rights reserved. + * + * 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. + */ + +/* This file contains the declaration for the OTARequestorDriver class, an interface + * that abstracts the OTA-related business logic out of the Requestor functionality in + * the Matter SDK. Applications implementing the OTA Requestor functionality must include + * this file. + */ + +#pragma once + +// Interface class to abstract the OTA-related business logic. Each application +// must implement this interface. All calls must be non-blocking unless stated otherwise +class OTARequestorDriver +{ +public: + // A call into the application logic to give it a chance to allow or stop the Requestor + // from proceeding with actual image download. Returning TRUE will allow the download + // to proceed, returning FALSE will abort the download process. + virtual bool CheckImageDownloadAllowed() = 0; + + // Notify the application that the download is complete and the image can be applied + virtual void ImageDownloadComplete() = 0; +}; diff --git a/src/app/clusters/ota-requestor/ota-requestor-interface.h b/src/app/clusters/ota-requestor/ota-requestor-interface.h new file mode 100644 index 00000000000000..a6c5c592d67d63 --- /dev/null +++ b/src/app/clusters/ota-requestor/ota-requestor-interface.h @@ -0,0 +1,43 @@ +/* + * + * Copyright (c) 2021 Project CHIP Authors + * All rights reserved. + * + * 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. + */ + +/* This file contains the declaration for the OTA Requestor interface. + * Any implementation of the OTA Requestor (e.g. the OTARequestor class) must implement + * this interface. + */ + +#pragma once + +// Interface class to connect the OTA Software Update Requestor cluster command processing +// with the core OTA Requestor logic. The OTARequestor class implements this interface +class OTARequestorInterface +{ +public: + // Handler for the AnnounceOTAProvider command + virtual bool HandleAnnounceOTAProvider( + chip::app::CommandHandler * commandObj, const chip::app::ConcreteCommandPath & commandPath, + const chip::app::Clusters::OtaSoftwareUpdateRequestor::Commands::AnnounceOtaProvider::DecodableType & commandData ch) = 0; + + // Handler for the QueryImageResponse command + virtual bool HandleQueryImageResponse(void * context, uint8_t status, uint32_t delayedActionTime, CharSpan imageURI, + uint32_t softwareVersion, CharSpan softwareVersionString, ByteSpan updateToken, + bool userConsentNeeded, ByteSpan metadataForRequester) = 0; + + // Handler for the ApplyUpdateResponse command + virtual bool HandleApplyUpdateResponse(ApplyUpdateResponse::DecodableType); +}; diff --git a/src/app/clusters/ota-requestor/ota-requestor.h b/src/app/clusters/ota-requestor/ota-requestor.h new file mode 100644 index 00000000000000..4cfacba97b64f1 --- /dev/null +++ b/src/app/clusters/ota-requestor/ota-requestor.h @@ -0,0 +1,49 @@ +/* + * + * Copyright (c) 2021 Project CHIP Authors + * All rights reserved. + * + * 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. + */ + +/* This file contains the declarations for the Matter OTA Requestor implementation and API. + * Applications implementing the OTA Requestor functionality must include this file. + */ + +#include "ota-requestor-driver.h" +#include "ota-requestor-interface.h" + +#pragma once + +// This class implements all of the core logic of the OTA Requestor +class OTARequestor : public OTARequestorInterface +{ +public: + // Application interface declarations start + + // Application directs the Requestor to start the Image Query process + // and download the new image if available + void TriggerImmediateQuery(); + + // Application directs the Requestor to abort any processing related to + // the image update + void AbortImageUpdate(); + + // A setter for the delegate class pointer + void SetOtaRequestorDriver(OTARequestorDriver * driver); + + // Application interface declarations end + +private: + OTARequestorDriver * mOtaRequestorDriver; +};