Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

将OTA代理集成到您的应用程序中

over-the-air(OTA) 代理旨在简化为产品添加OTA更新功能而必须编写的代码量。集成负担主要包括OTA代理的初始化和创建用于响应 Agen OTA t 事件消息的自定义回调函数。在初始化期间MQTT，操作系统、HTTP（如果HTTP用于文件下载）和平台特定的实现 (PAL) 接口将传递给OTA代理。也可以初始化缓冲区并将其传递给代理。OTA

连接管理

OTA代理将该MQTT协议用于所有涉及 Amazon IoT 服务的控制通信操作，但它不管理MQTT连接。为确保OTA代理不会干扰应用程序的连接管理策略，MQTT连接（包括断开连接和任何重新连接功能）必须由主用户应用程序处理。可以通过MQTT或HTTP协议下载该文件。您可以在创建OTA任务时选择哪种协议。如果您选择MQTT，OTA代理将使用相同的连接进行控制操作和下载文件。

简单OTA演示

以下是一个简单OTA演示的摘录，该演示向您展示了代理如何连接到MQTT代理并初始化代理。OTA在此示例中，我们将演示配置为使用默认的OTA应用程序回调，并每秒返回一次统计信息。为简洁起见，我们省略了演示的某些细节。

该OTA演示还通过监视断开MQTT连接回调并重新建立连接来演示连接管理。断开连接时，演示会先暂停OTA代理操作，然后尝试重新建立连接。MQTTMQTT重新连接尝试会延迟一段时间，该时间以指数方式增加到最大值，并且还会增加抖动。如果重新建立连接，OTA代理将继续运行。

有关使用 Amazon IoT MQTT代理的工作示例，请参阅demos/ota目录中的OTA演示代码。

由于OTA代理是它自己的任务，因此本示例中故意延迟一秒钟只会影响此应用程序。对代理的性能不会有任何影响。

static BaseType_t prvRunOTADemo( void )
{
    /* Status indicating a successful demo or not. */
    BaseType_t xStatus = pdFAIL;

    /* OTA library return status. */
    OtaErr_t xOtaError = OtaErrUninitialized;

    /* OTA event message used for sending event to OTA Agent.*/
    OtaEventMsg_t xEventMsg = { 0 };

    /* OTA interface context required for library interface functions.*/
    OtaInterfaces_t xOtaInterfaces;

    /* OTA library packet statistics per job.*/
    OtaAgentStatistics_t xOtaStatistics = { 0 };

    /* OTA Agent state returned from calling OTA_GetState.*/
    OtaState_t xOtaState = OtaAgentStateStopped;

    /* Set OTA Library interfaces.*/
    prvSetOtaInterfaces( &xOtaInterfaces );

    /*************************** Init OTA Library. ***************************/

    if( ( xOtaError = OTA_Init( &xOtaBuffer,
                                &xOtaInterfaces,
                                ( const uint8_t * ) ( democonfigCLIENT_IDENTIFIER ),
                                prvOtaAppCallback ) ) != OtaErrNone )
    {
        LogError( ( "Failed to initialize OTA Agent, exiting = %u.",
                    xOtaError ) );
    }
    else
    {
        xStatus = pdPASS;
    }

    /************************ Create OTA Agent Task. ************************/

    if( xStatus == pdPASS )
    {
        xStatus = xTaskCreate( prvOTAAgentTask,
                               "OTA Agent Task",
                               otaexampleAGENT_TASK_STACK_SIZE,
                               NULL,
                               otaexampleAGENT_TASK_PRIORITY,
                               NULL );

        if( xStatus != pdPASS )
        {
            LogError( ( "Failed to create OTA agent task:" ) );
        }
    }

    /****************************** Start OTA ******************************/

    if( xStatus == pdPASS )
    {
        /* Send start event to OTA Agent.*/
        xEventMsg.eventId = OtaAgentEventStart;
        OTA_SignalEvent( &xEventMsg );
    }

    /******************** Loop and display OTA statistics ********************/

    if( xStatus == pdPASS )
    {
        while( ( xOtaState = OTA_GetState() ) != OtaAgentStateStopped )
        {
            /* Get OTA statistics for currently executing job. */
            if( xOtaState != OtaAgentStateSuspended )
            {
                OTA_GetStatistics( &xOtaStatistics );

                LogInfo( ( " Received: %u   Queued: %u   Processed: %u   Dropped: %u",
                           xOtaStatistics.otaPacketsReceived,
                           xOtaStatistics.otaPacketsQueued,
                           xOtaStatistics.otaPacketsProcessed,
                           xOtaStatistics.otaPacketsDropped ) );
            }

            vTaskDelay( pdMS_TO_TICKS( otaexampleEXAMPLE_TASK_DELAY_MS ) );
        }
    }

    return xStatus;
}

以下是该演示应用程序的主要流程：

对OTA代理事件使用应用程序回调

前面的示例prvOtaAppCallback用作OTA代理事件的回调处理程序。（参见OTA_InitAPI调用的第四个参数）。如果要实现对完成事件的自定义处理，则必须在OTA演示/应用程序中更改默认处理。在此OTA过程中，OTA代理可以向回调处理程序发送以下事件枚举之一。如何以及何时处理这些事件由应用程序开发人员决定。

/**
 * @ingroup ota_enum_types
 * @brief OTA Job callback events.
 *
 * After an OTA update image is received and authenticated, the agent calls the user
 * callback (set with the @ref OTA_Init API) with the value OtaJobEventActivate to
 * signal that the device must be rebooted to activate the new image. When the device
 * boots, if the OTA job status is in self test mode, the agent calls the user callback
 * with the value OtaJobEventStartTest, signaling that any additional self tests
 * should be performed.
 *
 * If the OTA receive fails for any reason, the agent calls the user callback with
 * the value OtaJobEventFail instead to allow the user to log the failure and take
 * any action deemed appropriate by the user code.
 *
 * See the OtaImageState_t type for more information.
 */
typedef enum OtaJobEvent
{
    OtaJobEventActivate = 0,       /*!< @brief OTA receive is authenticated and ready to activate. */
    OtaJobEventFail = 1,           /*!< @brief OTA receive failed. Unable to use this update. */
    OtaJobEventStartTest = 2,      /*!< @brief OTA job is now in self test, perform user tests. */
    OtaJobEventProcessed = 3,      /*!< @brief OTA event queued by OTA_SignalEvent is processed. */
    OtaJobEventSelfTestFailed = 4, /*!< @brief OTA self-test failed for current job. */
    OtaJobEventParseCustomJob = 5, /*!< @brief OTA event for parsing custom job document. */
    OtaJobEventReceivedJob = 6,    /*!< @brief OTA event when a new valid AFT-OTA job is received. */
    OtaJobEventUpdateComplete = 7, /*!< @brief OTA event when the update is completed. */
    OtaLastJobEvent = OtaJobEventStartTest
} OtaJobEvent_t; 

在主应用程序的主动处理期间，OTA代理可以在后台接收更新。交付这些事件的目的在于，允许应用程序决定是立即采取行动，还是应当推迟行动，直到其他某些特定于应用程序的处理过程完成。这可以防止设备在活动处理期间（例如，执行 vacuum 操作时），由于固件更新后的重置而导致意外中断。以下是回调处理程序接收的作业事件：