Skip to content

Commit

Permalink
[OTA] Add various Requestor API declarations (#12755)
Browse files Browse the repository at this point in the history
* OTA Requestor: Add several API declarations

* Various OTA Requestor API updates

* Restyled by whitespace

* Restyled by clang-format

* Add CHIP_ERROR_NOT_FOUND and use it in the OTA Requestor API

* Restyled by clang-format

* Comment out download resumption API, the functionality won't be supported in 1.0

* Update README to account for a change from a different PR

* Restyled by prettier-markdown

Co-authored-by: Restyled.io <commits@restyled.io>
  • Loading branch information
2 people authored and pull[bot] committed Nov 29, 2023
1 parent 33153c9 commit 1262857
Show file tree
Hide file tree
Showing 8 changed files with 136 additions and 12 deletions.
7 changes: 7 additions & 0 deletions examples/ota-requestor-app/linux/LinuxOTARequestorDriver.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,8 @@

#include "LinuxOTARequestorDriver.h"

using namespace chip;

// 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.
Expand All @@ -32,3 +34,8 @@ bool LinuxOTARequestorDriver::CheckImageDownloadAllowed()

// Notify the application that the download is complete and the image can be applied
void LinuxOTARequestorDriver::ImageDownloadComplete() {}

UserConsentAction LinuxOTARequestorDriver::RequestUserConsent()
{
return ImmediateYes;
}
8 changes: 8 additions & 0 deletions examples/ota-requestor-app/linux/LinuxOTARequestorDriver.h
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,8 @@
*/
#include "app/clusters/ota-requestor/OTARequestorDriver.h"

namespace chip {

class LinuxOTARequestorDriver : public OTARequestorDriver
{

Expand All @@ -34,5 +36,11 @@ class LinuxOTARequestorDriver : public OTARequestorDriver
// Notify the application that the download is complete and the image can be applied
void ImageDownloadComplete();

// Application is directed to complete user consent: either return ImmediateYes/ImmediateNo
// without blocking or return Requested and call OTARequestor::OnUserConsent() later.
virtual UserConsentAction RequestUserConsent();

// Virtual functions from OTARequestorDriver -- end
};

} // namespace chip
7 changes: 5 additions & 2 deletions examples/ota-requestor-app/linux/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ In terminal 2:
In terminal 3:

```
./chip-ota-requestor-app -d ${REQUESTOR_LONG_DISCRIMINATOR} -u ${REQUESTOR_UDP_PORT} -i ${PROVIDER_IP_ADDRESS} -n ${PROVIDER_NODE_ID} -q ${DELAY_QUERY_SECONDS}
./chip-ota-requestor-app -d ${REQUESTOR_LONG_DISCRIMINATOR} -u ${REQUESTOR_UDP_PORT} -n ${PROVIDER_NODE_ID} -f ${PROVIDER_FABRIC_INDEX} -q ${DELAY_QUERY_SECONDS}
```

- `{REQUESTOR_LONG_DISCRIMINATOR}` is the long discriminator specified for the
Expand All @@ -39,7 +39,10 @@ In terminal 3:
for secure connections
- `${PROVIDER_IP_ADDRESS}` is the IP address of the ota-provider-app that has
been resolved manually
- `${PROVIDER_NODE_ID}` is the node ID of the ota-provider-app assigned above
- `${PROVIDER_NODE_ID}` is the node ID of the ota-provider-app; this is a Test
Mode parameter and should not be used in most scenarios
- `${PROVIDER_FABRIC_INDEX}` is the fabric index of the ota-provider-app; this
is a Test Mode parameter and should not be used in most scenarios
- `${DELAY_QUERY_SECONDS}` is the amount of time in seconds to wait before
initiating secure session establishment and query for software image

Expand Down
1 change: 1 addition & 0 deletions examples/ota-requestor-app/linux/main.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,7 @@ using chip::VendorId;
using chip::Callback::Callback;
using chip::System::Layer;
using chip::Transport::PeerAddress;
using namespace chip;
using namespace chip::ArgParser;
using namespace chip::Messaging;
using namespace chip::app::Clusters::OtaSoftwareUpdateProvider::Commands;
Expand Down
20 changes: 15 additions & 5 deletions src/app/clusters/ota-requestor/OTARequestor.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -330,15 +330,25 @@ void OTARequestor::OnConnected(void * context, OperationalDeviceProxy * devicePr
}
}

// Called whenever FindOrEstablishSession fails
void OTARequestor::OnConnectionFailure(void * context, NodeId deviceId, CHIP_ERROR error)
OTARequestor::OTATriggerResult OTARequestor::TriggerImmediateQuery()
{
ChipLogError(SoftwareUpdate, "Failed to connect to node 0x%" PRIX64 ": %" CHIP_ERROR_FORMAT, deviceId, error.Format());

if (mProviderNodeId != kUndefinedNodeId)
{
ConnectToProvider(kQueryImage);
return kTriggerSuccessful;
}
else
{
ChipLogError(SoftwareUpdate, "No OTA Providers available");
return kNoProviderKnown;
}
}

void OTARequestor::TriggerImmediateQuery()
// Called whenever FindOrEstablishSession fails
void OTARequestor::OnConnectionFailure(void * context, NodeId deviceId, CHIP_ERROR error)
{
ConnectToProvider(kQueryImage);
ChipLogError(SoftwareUpdate, "Failed to connect to node 0x%" PRIX64 ": %" CHIP_ERROR_FORMAT, deviceId, error.Format());
}

CHIP_ERROR OTARequestor::BuildQueryImageRequest(QueryImageRequest & request)
Expand Down
31 changes: 26 additions & 5 deletions src/app/clusters/ota-requestor/OTARequestor.h
Original file line number Diff line number Diff line change
Expand Up @@ -47,9 +47,16 @@ class OTARequestor : public OTARequestorInterface

// Application interface declarations -- start

// Return value for various trigger-type APIs
enum OTATriggerResult
{
kTriggerSuccessful = 0,
kNoProviderKnown = 1
};

// Application directs the Requestor to start the Image Query process
// and download the new image if available
void TriggerImmediateQuery();
OTATriggerResult TriggerImmediateQuery();

// A setter for the delegate class pointer
void SetOtaRequestorDriver(OTARequestorDriver * driver) { mOtaRequestorDriver = driver; }
Expand All @@ -59,20 +66,34 @@ class OTARequestor : public OTARequestorInterface
// The BDXDownloader instance should already have the ImageProcessingDelegate set.
void SetBDXDownloader(chip::BDXDownloader * downloader) { mBdxDownloader = downloader; }

// Application directs the Requestor to abort any processing related to
// the image update
// Application directs the Requestor to abort the download in progress. All the Requestor state (such
// as the QueryImageResponse content) is preserved
void AbortImageUpdate();

// Application directs the Requestor to abort the download in progress. All the Requestor state is
// cleared, UploadState is reset to Idle
void AbortAndResetState();

// Application notifies the Requestor on the user consent action, TRUE if consent is given,
// FALSE otherwise
void OnUserConsent(bool result);

/* Commented out until the API is supported
// Application directs the Requestor to download the image using the suppiled parameter and without
// issuing QueryImage
OTATriggerResult ResumeImageDownload(const BdxDownloadParameters & bdxParameters){ return kTriggerSuccessful;}
*/

// Application interface declarations -- end

// Virtual functions from OTARequestorInterface start
// Virtual functions from OTARequestorInterface -- start

// Handler for the AnnounceOTAProvider command
EmberAfStatus HandleAnnounceOTAProvider(
app::CommandHandler * commandObj, const app::ConcreteCommandPath & commandPath,
const app::Clusters::OtaSoftwareUpdateRequestor::Commands::AnnounceOtaProvider::DecodableType & commandData);

// Virtual functions from OTARequestorInterface -- end

/**
* Called to set the server instance which used to get access to the system resources necessary to open CASE sessions and drive
* BDX transfers
Expand Down
65 changes: 65 additions & 0 deletions src/app/clusters/ota-requestor/OTARequestorDriver.h
Original file line number Diff line number Diff line change
Expand Up @@ -24,19 +24,84 @@

#pragma once

#include <protocols/bdx/BdxMessages.h>

namespace chip {

/* Commented out until the API is supported
// The set of parameters needed for starting a BDX download.
struct BdxDownloadParameters
{
uint32_t delayedActionTime; // Might not be needed
chip::CharSpan imageURI;
uint32_t softwareVersion;
chip::CharSpan softwareVersionString; // Might not be needed
chip::ByteSpan updateToken;
bool userConsentNeeded; // Might not be needed
chip::ByteSpan metadataForRequestor; // Might not be needed
};
*/

// Possible values for the UpdateState attribute
enum UpdateStateEnum
{
Unknown = 0,
Idle = 1,
Querying = 2,
DelayedOnQuery = 3,
Downloading = 4,
Applying = 5,
DelayedOnApply = 6,
RollingBack = 7,
DelayedOnUserConsent = 8,
};

// Return type for RequestUserConsent()
enum UserConsentAction
{
ImmediateYes = 1,
ImmediateNo = 2,
Requested = 3,
};

// 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:
// Mandatory methods, applications are required to implement these

// 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;

// Application is directed to complete user consent: either return ImmediateYes/ImmediateNo
// without blocking or return Requested and call OTARequestor::OnUserConsent() later.
virtual UserConsentAction RequestUserConsent() = 0;

// Notify the application that the download is complete and the image can be applied
virtual void ImageDownloadComplete() = 0;

// Optional methods, applications may choose to implement these

/* Commented out until the API is supported
// This method informs the application of the BDX download parameters. This info can be used
// later on for diecting the Requestor to resume an interrupted download
virtual void PostBdxDownloadParameters(const BdxDownloadParameters & bdxParameters){};
*/

// Return maximum supported download block size
virtual uint16_t GetMaxDownloadBlockSize() { return 1024; }

// Get Version of the last downloaded image, return CHIP_ERROR_NOT_FOUND if none exists
virtual CHIP_ERROR GetLastDownloadedImageVersion(uint32_t & out_version) { return CHIP_ERROR_NOT_FOUND; }

// Notify application of a change in the UpdateState attribute
virtual void NotifyUpdateStateChange(chip::UpdateStateEnum state){};

// Destructor
virtual ~OTARequestorDriver() = default;
};

} // namespace chip
9 changes: 9 additions & 0 deletions src/lib/core/CHIPError.h
Original file line number Diff line number Diff line change
Expand Up @@ -2332,6 +2332,15 @@ using CHIP_ERROR = ::chip::ChipError;
* the required elements
*/
#define CHIP_ERROR_IM_MALFORMED_DATA_VERSION_FILTER_IB CHIP_CORE_ERROR(0xd7)

/**
* @def CHIP_ERROR_NOT_FOUND
*
* @brief
* The item referenced in the function call was not found
*/
#define CHIP_ERROR_NOT_FOUND CHIP_CORE_ERROR(0xd8)

/**
* @def CHIP_ERROR_INVALID_SCHEME_PREFIX
*
Expand Down

0 comments on commit 1262857

Please sign in to comment.