ota: Add OTA orchestrator

Add an OTA orchestrator as a helper within the applications/ directory.
The OTA orchestrator uses functionality from the Jobs and MQTT File
Streaming libraries to enable OTA updates.

In addition, update the keyword detection CMakeLists.txt to allow this
example to use the new modular OTA.

Signed-off-by: Chuyue Luo <[email protected]>

Author: chuyue-luo-arm

.github/.cSpellWords.txt

@@ -39,6 +39,7 @@ coef
 compatibil
 coremqtt
 COSE
+coverity
 CLRF
 Cqqpk
 CSRS
@@ -147,6 +148,7 @@ Merkle
 Mfcc
 MFCC
 MFLN
+MISRA
 mlek
 mqtt
 mqttconfig

applications/helpers/CMakeLists.txt

@@ -7,6 +7,7 @@ add_subdirectory(device_advisor)
 add_subdirectory(events)
 add_subdirectory(hdlcd)
 add_subdirectory(logging)
+add_subdirectory(ota_orchestrator)
 add_subdirectory(provisioning)
 # sntp helper library depends on FreeRTOS-Plus-TCP connectivity stack as it
 # includes `FreeRTOS_IP.h` header file in one of its source files (sntp_client_task.c),

applications/helpers/ota_orchestrator/CMakeLists.txt

@@ -0,0 +1,33 @@
+# Copyright 2024 Arm Limited and/or its affiliates
+# <[email protected]>
+# SPDX-License-Identifier: MIT
+
+if(BUILD_TESTING AND NOT CMAKE_CROSSCOMPILING)
+    # Left empty for future mocks.
+else()
+    add_library(ota-update
+        src/mqtt_helpers.c
+        src/ota_orchestrator_helpers.c
+        src/ota_os_freertos.c
+        src/ota_orchestrator.c
+    )
+
+    target_include_directories(ota-update
+        PUBLIC
+            inc/
+    )
+
+    target_link_libraries(ota-update
+        jobs-for-aws-iot-embedded-sdk
+        aws-iot-core-mqtt-file-streams-embedded-c
+        freertos_kernel
+        corejson
+        coremqtt
+        coremqtt-agent
+        tinycbor
+        freertos-ota-pal-psa
+        helpers-events
+        backoff-algorithm
+        crt-helpers
+    )
+endif()

applications/helpers/ota_orchestrator/inc/mqtt_helpers.h

@@ -0,0 +1,78 @@
+/* Copyright 2023-2024 Arm Limited and/or its affiliates
+ * <[email protected]>
+ * SPDX-License-Identifier: MIT
+ */
+
+#ifndef MQTT_HELPERS_H
+#define MQTT_HELPERS_H
+
+/* Standard includes. */
+#include <stdlib.h>
+#include <stdint.h>
+
+/**
+ * @ingroup ota_enum_types
+ * @brief The OTA MQTT interface return status.
+ */
+typedef enum OtaMqttStatus
+{
+    OtaMqttSuccess = 0,          /*!< @brief OTA MQTT interface success. */
+    OtaMqttPublishFailed = 0xa0, /*!< @brief Attempt to publish a MQTT message failed. */
+    OtaMqttSubscribeFailed,      /*!< @brief Failed to subscribe to a topic. */
+    OtaMqttUnsubscribeFailed     /*!< @brief Failed to unsubscribe from a topic. */
+} OtaMqttStatus_t;
+
+/**
+ * @brief Subscribe to a specified topic.
+ *
+ * Precondition: pTopicFilter is not null.
+ *
+ * @param[in] pTopicFilter The topic filter to subscribe to.
+ * @param[in] topicFilterLength Length of the topic filter.
+ * @param[in] ucQoS Quality of Service (QoS), the level of reliability for
+ * message delivery. Can be 0, 1 or 2.
+ *
+ * @return OtaMqttSuccess if the subscribe completed successfully, otherwise
+ * OtaMqttSubscribeFailed.
+ */
+OtaMqttStatus_t prvMQTTSubscribe( const char * pTopicFilter,
+                                  uint16_t topicFilterLength,
+                                  uint8_t ucQoS );
+
+/**
+ * @brief Publish a message to a specified topic.
+ * *
+ * @param[in] pacTopic The topic that the message should be published to.
+ * @param[in] topicLen Length of the topic.
+ * @param[in] pMsg The message to be published.
+ * @param[in] msgSize Size of the message.
+ * @param[in] ucQoS Quality of Service (QoS), the level of reliability for
+ * message delivery. Can be 0, 1 or 2.
+ *
+ * @return OtaMqttSuccess if the subscribe completed successfully, otherwise
+ * OtaMqttSubscribeFailed.
+ */
+OtaMqttStatus_t prvMQTTPublish( const char * const pacTopic,
+                                uint16_t topicLen,
+                                const char * pMsg,
+                                uint32_t msgSize,
+                                uint8_t ucQoS );
+
+/**
+ * @brief Unsubscribe from a specified topic.
+ *
+ * Precondition: pTopicFilter is not null.
+ *
+ * @param[in] pTopicFilter The topic filter to unsubscribe from.
+ * @param[in] topicFilterLength Length of the topic filter.
+ * @param[in] ucQoS Quality of Service (QoS), the level of reliability for
+ * message delivery. Can be 0, 1 or 2.
+ *
+ * @return OtaMqttSuccess if the unsubscribe completed successfully, otherwise
+ * OtaMqttSubscribeFailed.
+ */
+OtaMqttStatus_t prvMQTTUnsubscribe( const char * pTopicFilter,
+                                    uint16_t topicFilterLength,
+                                    uint8_t ucQoS );
+
+#endif /* MQTT_HELPERS_H */

applications/helpers/ota_orchestrator/inc/ota_appversion32.h

@@ -0,0 +1,88 @@
+/*
+ * AWS IoT Over-the-air Update v3.4.0
+ * Copyright (C) 2020 Amazon.com, Inc. or its affiliates.  All Rights Reserved.
+ * Copyright 2024 Arm Limited and/or its affiliates
+ * <[email protected]>
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to
+ * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ * the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+ * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+/**
+ * @file ota_appversion32.h
+ * @brief Structure to represent the application build version.
+ */
+
+#ifndef IOT_APPVERSION32_H
+#define IOT_APPVERSION32_H
+
+/* *INDENT-OFF* */
+#ifdef __cplusplus
+    extern "C" {
+#endif
+/* *INDENT-ON* */
+
+/* Standard includes. */
+#include <stdint.h>
+
+/**
+ * @ingroup ota_struct_types
+ * @brief Application version structure.
+ *
+ */
+typedef struct
+{
+    /* MISRA Ref 19.2.1 [Unions] */
+    /* More details at: https://github.com/aws/ota-for-aws-iot-embedded-sdk/blob/main/MISRA.md#rule-192 */
+    /* coverity[misra_c_2012_rule_19_2_violation] */
+    union
+    {
+        #if ( defined( __BYTE_ORDER__ ) && defined( __ORDER_LITTLE_ENDIAN__ ) && ( __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__ ) ) || ( __little_endian__ == 1 ) || WIN32 || ( __BYTE_ORDER == __LITTLE_ENDIAN )
+            struct version
+            {
+                uint16_t build; /*!< @brief Build of the firmware (Z in firmware version Z.Y.X). */
+                uint8_t minor;  /*!< @brief Minor version number of the firmware (Y in firmware version Z.Y.X). */
+
+                uint8_t major;  /*!< @brief Major version number of the firmware (X in firmware version Z.Y.X). */
+            } x;                /*!< @brief Version number of the firmware. */
+        #elif ( defined( __BYTE_ORDER__ ) && defined( __ORDER_BIG_ENDIAN__ ) && __BYTE_ORDER__ == __ORDER_BIG_ENDIAN__ ) || ( __big_endian__ == 1 ) || ( __BYTE_ORDER == __BIG_ENDIAN )
+            struct version
+            {
+                uint8_t major;  /*!< @brief Major version number of the firmware (X in firmware version X.Y.Z). */
+                uint8_t minor;  /*!< @brief Minor version number of the firmware (Y in firmware version X.Y.Z). */
+
+                uint16_t build; /*!< @brief Build of the firmware (Z in firmware version X.Y.Z). */
+            } x;                /*!< @brief Version number of the firmware. */
+        #else /* if ( defined( __BYTE_ORDER__ ) && defined( __ORDER_LITTLE_ENDIAN__ ) && __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__ ) || ( __little_endian__ == 1 ) || WIN32 || ( __BYTE_ORDER == __LITTLE_ENDIAN ) */
+        #error "Unable to determine byte order!"
+        #endif /* if ( defined( __BYTE_ORDER__ ) && defined( __ORDER_LITTLE_ENDIAN__ ) && __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__ ) || ( __little_endian__ == 1 ) || WIN32 || ( __BYTE_ORDER == __LITTLE_ENDIAN ) */
+        uint32_t unsignedVersion32;
+        int32_t signedVersion32;
+    } u; /*!< @brief Version based on configuration in big endian or little endian. */
+} AppVersion32_t;
+
+extern AppVersion32_t appFirmwareVersion; /*!< @brief Making the version number available globally through external linkage. */
+
+/* *INDENT-OFF* */
+#ifdef __cplusplus
+    }
+#endif
+/* *INDENT-ON* */
+
+#endif /* ifndef IOT_APPVERSION32_H */

applications/helpers/ota_orchestrator/inc/ota_orchestrator_helpers.h

@@ -0,0 +1,51 @@
+/*
+ * Copyright Amazon.com, Inc. and its affiliates. All Rights Reserved.
+ * Copyright 2024 Arm Limited and/or its affiliates
+ * <[email protected]>
+ *
+ * SPDX-License-Identifier: MIT
+ * Licensed under the MIT License. See the LICENSE accompanying this file
+ * for the specific language governing permissions and limitations under
+ * the License.
+ */
+
+#ifndef OTA_ORCHESTRATOR_HELPERS_H
+#define OTA_ORCHESTRATOR_HELPERS_H
+
+/* Standard includes. */
+#include <stdbool.h>
+#include <stdint.h>
+
+#include "job_parser.h"
+
+/**
+ * @brief Convert a job document signature into DER format.
+ *
+ * @param[in] dest The destination buffer to be populated with the decoded
+ * signature
+ * @param[in] destLength Length of the dest buffer.
+ * @param[in] jobFields Pointer to the structure holding the job document
+ * parameters, which will be populated with the decoded signature.
+ *
+ * @return true if the signature was successfully decoded, otherwise false.
+ */
+bool convertSignatureToDER( uint8_t * dest,
+                            size_t destLength,
+                            AfrOtaJobDocumentFields_t * jobFields );
+
+/**
+ * @brief Parse the job document to extract the parameters needed to download
+ * the new firmware.
+ *
+ * @param[in] message The jobs message received from AWS IoT core.
+ * @param[in] messageLength Length of the message.
+ * @param[in] jobFields Pointer to the structure to be populated with the job
+ * document fields.
+ *
+ * @return true if all files processed, otherwise false.
+ */
+bool jobDocumentParser( char * message,
+                        size_t messageLength,
+                        AfrOtaJobDocumentFields_t * jobFields );
+
+#endif /* OTA_ORCHESTRATOR_HELPERS_H */

applications/helpers/ota_orchestrator/inc/ota_os_freertos.h

@@ -0,0 +1,104 @@
+/*
+ * Copyright Amazon.com, Inc. and its affiliates. All Rights Reserved.
+ * Copyright 2024 Arm Limited and/or its affiliates
+ * <[email protected]>
+ *
+ * SPDX-License-Identifier: MIT
+ * Licensed under the MIT License. See the LICENSE accompanying this file
+ * for the specific language governing permissions and limitations under
+ * the License.
+ */
+
+/**
+ * @file ota_os_freertos.h
+ * @brief Function declarations for the example OTA OS Functional interface for
+ * FreeRTOS.
+ */
+
+#ifndef _OTA_OS_FREERTOS_H_
+#define _OTA_OS_FREERTOS_H_
+
+/* Standard library includes. */
+#include <stdbool.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <string.h>
+
+/**
+ * @ingroup ota_enum_types
+ * @brief The OTA OS interface return status.
+ */
+typedef enum OtaOsStatus
+{
+    OtaOsSuccess = 0,                    /*!< @brief OTA OS interface success. */
+    OtaOsEventQueueCreateFailed = 0x80U, /*!< @brief Failed to create the event
+                                          * queue. */
+    OtaOsEventQueueSendFailed,           /*!< @brief Posting event message to the event
+                                          * queue failed. */
+    OtaOsEventQueueReceiveFailed,        /*!< @brief Failed to receive from the event
+                                          * queue. */
+    OtaOsEventQueueDeleteFailed,         /*!< @brief Failed to delete the event queue.
+                                          */
+} OtaOsStatus_t;
+
+/**
+ * @brief Initialize the OTA events.
+ *
+ * This function initializes the OTA events mechanism for freeRTOS platforms.
+ *
+ * @param[pEventCtx]     Pointer to the OTA event context.
+ *
+ * @return               OtaOsStatus_t, OtaOsSuccess if success , other error
+ * code on failure.
+ */
+OtaOsStatus_t OtaInitEvent_FreeRTOS();
+
+/**
+ * @brief Sends an OTA event.
+ *
+ * This function sends an event to OTA library event handler on FreeRTOS
+ * platforms.
+ *
+ * @param[pEventCtx]     Pointer to the OTA event context.
+ *
+ * @param[pEventMsg]     Event to be sent to the OTA handler.
+ *
+ * @param[timeout]       The maximum amount of time (msec) the task should
+ * block.
+ *
+ * @return               OtaOsStatus_t, OtaOsSuccess if success , other error
+ * code on failure.
+ */
+OtaOsStatus_t OtaSendEvent_FreeRTOS( const void * pEventMsg );
+
+/**
+ * @brief Receive an OTA event.
+ *
+ * This function receives next event from the pending OTA events on FreeRTOS
+ * platforms.
+ *
+ * @param[pEventCtx]     Pointer to the OTA event context.
+ *
+ * @param[pEventMsg]     Pointer to store message.
+ *
+ * @param[timeout]       The maximum amount of time the task should block.
+ *
+ * @return               OtaOsStatus_t, OtaOsSuccess if success , other error
+ * code on failure.
+ */
+OtaOsStatus_t OtaReceiveEvent_FreeRTOS( void * pEventMsg );
+
+/**
+ * @brief Deinitialize the OTA Events mechanism.
+ *
+ * This function deinitialize the OTA events mechanism and frees any resources
+ * used on FreeRTOS platforms.
+ *
+ * @param[pEventCtx]     Pointer to the OTA event context.
+ *
+ * @return               OtaOsStatus_t, OtaOsSuccess if success , other error
+ * code on failure.
+ */
+void OtaDeinitEvent_FreeRTOS();
+
+#endif /* ifndef _OTA_OS_FREERTOS_H_ */