As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
Como migrar da versão 1 para a versão 3 para os aplicativos OTA
Este guia ajudará você a migrar sua aplicação da versão 1 da biblioteca OTA para a versão 3.
nota
As APIs OTA versão 2 são iguais às APIs OTA v3. Portanto, se sua aplicação estiver usando a versão 2 das APIs, as alterações não serão necessárias para as chamadas de API, mas é recomendada a integração da versão 3 da biblioteca.
As demonstrações da versão 3 do OTA estão disponíveis aqui:
Resumo das alterações da API
API OTA versão 1 |
API OTA versão 3 |
Descrição das alterações |
---|---|---|
OTA_AgentInit |
OTA_Init |
Os parâmetros de entrada são alterados, assim como o valor retornado da função devido às mudanças na implementação no OTA v3. Consulte a seção OTA_Init abaixo para obter detalhes. |
OTA_AgentShutdown |
OTA_Shutdown |
Alteração nos parâmetros de entrada, incluindo um parâmetro adicional para um cancelamento opcional de assinatura dos tópicos do MQTT. Consulte a seção OTA_Shutdown abaixo para obter detalhes. |
OTA_GetAgentState |
OTA_GetState |
O nome da API foi alterado sem alterações no parâmetro de entrada. O valor de retorno é o mesmo, mas o enum e os membros são renomeados. Consulte a seção OTA_GetState abaixo para obter detalhes. |
n/a |
OTA_GetStatistics |
Foram adicionadas novas APIs que substitui as APIs OTA_GetPacketsReceived, OTA_GetPacketsQueued, OTA_GetPacketsProcessed e OTA_GetPacketsDropped. Consulte a seção OTA_GetStatistics abaixo para obter detalhes. |
OTA_GetPacketsReceived |
n/a |
Esta API foi removida da versão 3 e substituída pela OTA_GetStatistics. |
OTA_GetPacketsQueued |
n/a |
Esta API foi removida da versão 3 e substituída pela OTA_GetStatistics. |
OTA_GetPacketsProcessed |
n/a |
Esta API foi removida da versão 3 e substituída pela OTA_GetStatistics. |
OTA_GetPacketsDropped |
n/a |
Esta API foi removida da versão 3 e substituída pela OTA_GetStatistics. |
OTA_ActivateNewImage |
OTA_ActivateNewImage |
Os parâmetros de entrada são os mesmos, mas o código de erro OTA de retorno é renomeado e novos códigos de erro são adicionados na versão 3 da biblioteca OTA. Consulte a seção OTA_ActivateNewImage para obter detalhes. |
OTA_SetImageState |
OTA_SetImageState |
Os parâmetros de entrada são os mesmos e renomeados, o código de erro OTA de retorno é renomeado e novos códigos de erro são adicionados na versão 3 da biblioteca OTA. Consulte a seção OTA_SetImageState para obter detalhes. |
OTA_GetImageState |
OTA_GetImageState |
Os parâmetros de entrada são os mesmos. O enum de retorno é renomeado na versão 3 da biblioteca OTA. Consulte a seção OTA_GetImageState para obter detalhes. |
OTA_Suspend |
OTA_Suspend |
Os parâmetros de entrada são os mesmos, o código de erro OTA de retorno é renomeado e novos códigos de erro são adicionados na versão 3 da biblioteca OTA. Consulte a seção OTA_Suspend para obter detalhes. |
OTA_Resume |
OTA_Resume |
O parâmetro de entrada para a conexão é removido quando a conexão é tratada na demonstração/aplicação OTA, o código de erro OTA de retorno é renomeado e novos códigos de erro são adicionados na versão 3 da biblioteca OTA. Consulte a seção OTA_Resume para obter detalhes. |
OTA_CheckForUpdate |
OTA_CheckForUpdate |
Os parâmetros de entrada são os mesmos, o código de erro OTA de retorno é renomeado e novos códigos de erro são adicionados na versão 3 da biblioteca OTA. Consulte a seção OTA_CheckForUpdate para obter detalhes. |
n/a |
OTA_EventProcessingTask |
Uma nova API foi adicionada e é o principal loop de eventos para lidar com eventos para atualização do OTA e deve ser chamada pela tarefa da aplicação. Consulte a seção OTA_EventProcessingTask para obter detalhes. |
n/a |
OTA_SignalEvent |
Uma nova API foi adicionada e adiciona o evento ao final da fila de eventos OTA e é usada por módulos OTA internos para sinalizar a tarefa do atendente. Consulte a seção OTA_SignalEvent para obter detalhes. |
n/a |
OTA_Err_strerror |
Nova API para conversão de código de erro em string para erros OTA. |
n/a |
OTA_JobParse_strerror |
Nova API para conversão de código de erro em string para erros de Job Parsing. |
n/a |
OTA_OsStatus_strerror |
Nova API para conversão de código de status em string para status de porta do sistema operacional OTA. |
n/a |
Erro do OTA_PALStatus_STR |
Nova API para conversão de código de status em string para status de porta do sistema operacional PAL OTA. |
Descrição das alterações necessárias
OTA_Init
Ao inicializar o atendente OTA na v1, a API OTA_AgentInit
é usada, que usa parâmetros para contexto de conexão, nome da coisa, retorno de chamada completo e tempo limite como entrada.
OTA_State_t OTA_AgentInit( void * pvConnectionContext,
const uint8_t * pucThingName,
pxOTACompleteCallback_t xFunc,
TickType_t xTicksToWait );
Essa API agora foi alterada para OTA_Init
com parâmetros para os buffers necessários para ota, interfaces ota, nome da coisa e retorno de chamada da aplicação.
OtaErr_t OTA_Init( OtaAppBuffer_t * pOtaBuffer,
OtaInterfaces_t * pOtaInterfaces,
const uint8_t * pThingName,
OtaAppCallback OtaAppCallback );
- Parâmetros de entrada removidos:
-
- pvConnectionContext:
-
O contexto de conexão é removido porque a Biblioteca OTA Versão 3 não exige que o contexto de conexão seja passado para ela e as operações MQTT/HTTP são tratadas por suas respectivas interfaces na demonstração/aplicação OTA.
- xTicksToWait:
-
O parâmetro ticks to wait também é removido quando a tarefa é criada na demonstração/aplicação OTA antes de chamar OTA_init.
- Parâmetros de entrada renomeados:
-
- xFunc:
-
O parâmetro é renomeado para OtaAppCallback e seu tipo é alterado para OtaAppCallback_t.
- Novos parâmetros de entrada:
-
- pOtaBuffer
-
A aplicação deve alocar os buffers e passá-los para a biblioteca OTA usando a estrutura OTAAppBuffer_t durante a inicialização. Os buffers necessários diferem um pouco dependendo do protocolo usado para baixar o arquivo. Para o protocolo MQTT, os buffers para o nome do fluxo são necessários e, para o protocolo HTTP, os buffers para URL pré-assinado e esquema de autorização são necessários.
Buffers necessários ao usar MQTT para baixar arquivos:
static OtaAppBuffer_t otaBuffer = { .pUpdateFilePath = updateFilePath, .updateFilePathsize = otaexampleMAX_FILE_PATH_SIZE, .pCertFilePath = certFilePath, .certFilePathSize = otaexampleMAX_FILE_PATH_SIZE, .pStreamName = streamName, .streamNameSize = otaexampleMAX_STREAM_NAME_SIZE, .pDecodeMemory = decodeMem, .decodeMemorySize = ( 1U << otaconfigLOG2_FILE_BLOCK_SIZE ), .pFileBitmap = bitmap, .fileBitmapSize = OTA_MAX_BLOCK_BITMAP_SIZE };
Buffers necessários ao usar HTTP para baixar arquivos:
static OtaAppBuffer_t otaBuffer = { .pUpdateFilePath = updateFilePath, .updateFilePathsize = otaexampleMAX_FILE_PATH_SIZE, .pCertFilePath = certFilePath, .certFilePathSize = otaexampleMAX_FILE_PATH_SIZE, .pDecodeMemory = decodeMem, .decodeMemorySize = ( 1U << otaconfigLOG2_FILE_BLOCK_SIZE ), .pFileBitmap = bitmap, .fileBitmapSize = OTA_MAX_BLOCK_BITMAP_SIZE, .pUrl = updateUrl, .urlSize = OTA_MAX_URL_SIZE, .pAuthScheme = authScheme, .authSchemeSize = OTA_MAX_AUTH_SCHEME_SIZE };
Onde:
pUpdateFilePath Path to store the files. updateFilePathsize Maximum size of the file path. pCertFilePath Path to certificate file. certFilePathSize Maximum size of the certificate file path. pStreamName Name of stream to download the files. streamNameSize Maximum size of the stream name. pDecodeMemory Place to store the decoded files. decodeMemorySize Maximum size of the decoded files buffer. pFileBitmap Bitmap of the parameters received. fileBitmapSize Maximum size of the bitmap. pUrl Presigned url to download files from S3. urlSize Maximum size of the URL. pAuthScheme Authentication scheme used to validate download. authSchemeSize Maximum size of the auth scheme.
- pOtaInterfaces
-
O segundo parâmetro de entrada para OTA_Init é uma referência às interfaces OTA para o tipo OtaInterfaces_t. Este conjunto de interfaces deve ser passado para a Biblioteca OTA e inclui na interface do sistema operacional a interface MQTT, a interface HTTP e a interface da camada de abstração da plataforma.
- Interface do sistema operacional OTA
-
A interface funcional do sistema operacional OTA é um conjunto de APIs que devem ser implementadas para que o dispositivo use a biblioteca OTA. As implementações de funções para essa interface são fornecidas à biblioteca OTA na aplicação do usuário. A biblioteca OTA chama as implementações de funções para executar funcionalidades que normalmente são fornecidas por um sistema operacional. Isto inclui o gerenciamento de eventos, temporizadores e alocação de memória. As implementações para FreeRTOS e POSIX são fornecidas com a biblioteca OTA.
Exemplo para FreeRTOS usando a porta FreeRTOS fornecida:
OtaInterfaces_t otaInterfaces; otaInterfaces.os.event.init = OtaInitEvent_FreeRTOS; otaInterfaces.os.event.send = OtaSendEvent_FreeRTOS; otaInterfaces.os.event.recv = OtaReceiveEvent_FreeRTOS; otaInterfaces.os.event.deinit = OtaDeinitEvent_FreeRTOS; otaInterfaces.os.timer.start = OtaStartTimer_FreeRTOS; otaInterfaces.os.timer.stop = OtaStopTimer_FreeRTOS; otaInterfaces.os.timer.delete = OtaDeleteTimer_FreeRTOS; otaInterfaces.os.mem.malloc = Malloc_FreeRTOS; otaInterfaces.os.mem.free = Free_FreeRTOS;
Exemplo para Linux usando a porta POSIX fornecida:
OtaInterfaces_t otaInterfaces; otaInterfaces.os.event.init = Posix_OtaInitEvent; otaInterfaces.os.event.send = Posix_OtaSendEvent; otaInterfaces.os.event.recv = Posix_OtaReceiveEvent; otaInterfaces.os.event.deinit = Posix_OtaDeinitEvent; otaInterfaces.os.timer.start = Posix_OtaStartTimer; otaInterfaces.os.timer.stop = Posix_OtaStopTimer; otaInterfaces.os.timer.delete = Posix_OtaDeleteTimer; otaInterfaces.os.mem.malloc = STDC_Malloc; otaInterfaces.os.mem.free = STDC_Free;
- Interface MQTT
-
A interface OTA MQTT é um conjunto de APIs que devem ser implementadas em uma biblioteca para permitir que a biblioteca OTA baixe um bloco de arquivos do serviço de streaming.
Exemplo de uso do atendente coreHTTP da demonstração OTA por HTTP
: OtaInterfaces_t otaInterfaces; otaInterfaces.mqtt.subscribe = prvMqttSubscribe; otaInterfaces.mqtt.publish = prvMqttPublish; otaInterfaces.mqtt.unsubscribe = prvMqttUnSubscribe;
- Interface HTTP
-
A interface HTTP OTA é um conjunto de APIs que devem ser implementadas em uma biblioteca para permitir que a biblioteca OTA baixe um bloco de arquivos conectando-se a um URL pré-assinado e buscando blocos de dados. É opcional, a menos que a biblioteca OTA seja configurada para fazer o download de um URL pré-assinado em vez de um serviço de streaming.
Exemplo de uso das APIs coreHTTP da demonstração OTA por HTTP
: OtaInterfaces_t otaInterfaces; otaInterfaces.http.init = httpInit; otaInterfaces.http.request = httpRequest; otaInterfaces.http.deinit = httpDeinit;
- Interface PAL OTA
-
A interface PAL OTA é um conjunto de APIs que devem ser implementadas para que o dispositivo use a biblioteca OTA. A implementação específica do dispositivo para o OTA PAL é fornecida à biblioteca na aplicação do usuário. Estas funções são usadas pela biblioteca para armazenar, gerenciar e autenticar downloads.
OtaInterfaces_t otaInterfaces; otaInterfaces.pal.getPlatformImageState = otaPal_GetPlatformImageState; otaInterfaces.pal.setPlatformImageState = otaPal_SetPlatformImageState; otaInterfaces.pal.writeBlock = otaPal_WriteBlock; otaInterfaces.pal.activate = otaPal_ActivateNewImage; otaInterfaces.pal.closeFile = otaPal_CloseFile; otaInterfaces.pal.reset = otaPal_ResetDevice; otaInterfaces.pal.abort = otaPal_Abort; otaInterfaces.pal.createFile = otaPal_CreateFileForRx;
- Alterações em retorno:
-
O retorno é alterado do estado do atendente OTA para o código de erro OTA. Consulte Atualização do AWS IoT Over-the-Air v3.0.0: Otaerr_t
.
OTA_Shutdown
Na versão 1 da Biblioteca OTA, a API usada para desligar o atendente OTA era OTA_AgentShutdown, que agora foi alterada para OTA_Shutdown junto com as alterações nos parâmetros de entrada.
- Desligamento do atendente OTA (versão 1)
-
OTA_State_t OTA_AgentShutdown( TickType_t xTicksToWait );
- Desligamento do atendente OTA (versão 3)
-
OtaState_t OTA_Shutdown( uint32_t ticksToWait, uint8_t unsubscribeFlag );
- ticksToWait:
-
O número de tiques que aguardam até que o atendente OTA conclua o processo de desligamento. Se for definido como zero, a função retornará imediatamente sem esperar. O estado real é retornado ao chamador. O atendente não fica em repouso nesse tempo, mas é usado para fazer loops ocupados.
- Novo parâmetro de entrada:
-
unsubscribeFlag:
Sinalize para indicar se as operações de cancelamento de assinatura devem ser realizadas nos tópicos do trabalho quando o encerramento é chamado. Se o sinalizador for 0, as operações de cancelamento de inscrição não serão chamadas para tópicos de trabalho. Se a aplicação precisar cancelar a assinatura dos tópicos do trabalho, esse sinalizador deverá ser definido como 1 ao chamar OTA_Shutdown.
- Alterações em retorno:
-
OtaState_t:
O enum para o estado do atendente OTA e seus membros é renomeado. Consulte Atualização do AWS IoT Over-the-Air v3.0.0
.
OTA_GetState
O nome da API foi alterado de OTA_AgentGetState para OTA_GetState.
- Desligamento do atendente OTA (versão 1)
-
OTA_State_t OTA_GetAgentState( void );
- Desligamento do atendente OTA (versão 3)
-
OtaState_t OTA_GetState( void );
- Alterações em retorno:
-
OtaState_t:
O enum para o estado do atendente OTA e seus membros é renomeado. Consulte Atualização do AWS IoT Over-the-Air v3.0.0
.
OTA_GetStatistics
Nova API única adicionada para estatísticas. Ele substitui as APIs OTA_GetPacketsReceived, OTA_GetPacketsQueued, OTA_GetPacketsProcessed e OTA_GetPacketsDropped. Além disso, na versão 3 da Biblioteca OTA, os números das estatísticas estão relacionados apenas ao trabalho atual.
- Biblioteca OTA versão 1
-
uint32_t OTA_GetPacketsReceived( void ); uint32_t OTA_GetPacketsQueued( void ); uint32_t OTA_GetPacketsProcessed( void ); uint32_t OTA_GetPacketsDropped( void );
- Biblioteca OTA versão 3
-
OtaErr_t OTA_GetStatistics( OtaAgentStatistics_t * pStatistics );
- pStatistics:
-
O parâmetro de entrada/saída para dados estatísticos, como pacotes recebidos, descartados, colocados em fila e processados para o trabalho atual.
- Parâmetro de saída:
-
Código de erro OTA.
- Exemplo de uso:
-
OtaAgentStatistics_t otaStatistics = { 0 }; OTA_GetStatistics( &otaStatistics ); LogInfo( ( " Received: %u Queued: %u Processed: %u Dropped: %u", otaStatistics.otaPacketsReceived, otaStatistics.otaPacketsQueued, otaStatistics.otaPacketsProcessed, otaStatistics.otaPacketsDropped ) );
OTA_ActivateNewImage
Os parâmetros de entrada são os mesmos, mas o código de erro OTA de retorno é renomeado e novos códigos de erro são adicionados na versão 3 da biblioteca OTA.
- Biblioteca OTA versão 1
-
OTA_Err_t OTA_ActivateNewImage( void );
- Biblioteca OTA versão 3
-
OtaErr_t OTA_ActivateNewImage( void );
A enumeração do código de erro OTA de retorno é alterada e novos códigos de erro são adicionados. Consulte Atualização do AWS IoT Over-the-Air v3.0.0: Otaerr_t
. - Exemplo de uso:
-
OtaErr_t otaErr = OtaErrNone; otaErr = OTA_ActivateNewImage(); /* Handle error */
OTA_SetImageState
Os parâmetros de entrada são os mesmos e renomeados, o código de erro OTA de retorno é renomeado e novos códigos de erro são adicionados na versão 3 da biblioteca OTA.
- Biblioteca OTA versão 1
-
OTA_Err_t OTA_SetImageState( OTA_ImageState_t eState );
- Biblioteca OTA versão 3
-
OtaErr_t OTA_SetImageState( OtaImageState_t state );
O parâmetro de entrada é renomeado para OtaImageState_t. Consulte Atualização do AWS IoT Over-the-Air v3.0.0
. A enumeração do código de erro OTA de retorno é alterada e novos códigos de erro são adicionados. Consulte Atualização do AWS IoT Over-the-Air v3.0.0 /Otaerr_t
. - Exemplo de uso:
-
OtaErr_t otaErr = OtaErrNone; otaErr = OTA_SetImageState( OtaImageStateAccepted ); /* Handle error */
OTA_GetImageState
Os parâmetros de entrada são os mesmos. O enum de retorno é renomeado na versão 3 da biblioteca OTA.
- Biblioteca OTA versão 1
-
OTA_ImageState_t OTA_GetImageState( void );
- Biblioteca OTA versão 3
-
OtaImageState_t OTA_GetImageState( void );
A enumeração de retorno é renomeada para OtaImageState_t. Consulte Atualização do AWS IoT Over-the-Air v3.0.0
: OtaImageState_t . - Exemplo de uso:
-
OtaImageState_t imageState; imageState = OTA_GetImageState();
OTA_Suspend
Os parâmetros de entrada são os mesmos, o código de erro OTA de retorno é renomeado e novos códigos de erro são adicionados na versão 3 da biblioteca OTA.
- Biblioteca OTA versão 1
-
OTA_Err_t OTA_Suspend( void );
- Biblioteca OTA versão 3
-
OtaErr_t OTA_Suspend( void );
A enumeração do código de erro OTA de retorno é alterada e novos códigos de erro são adicionados. Consulte Atualização do AWS IoT Over-the-Air v3.0.0: Otaerr_t
. - Exemplo de uso:
-
OtaErr_t xOtaError = OtaErrUninitialized; xOtaError = OTA_Suspend(); /* Handle error */
OTA_Resume
O parâmetro de entrada para a conexão é removido quando a conexão é tratada na demonstração/aplicação OTA, o código de erro OTA de retorno é renomeado e novos códigos de erro são adicionados na versão 3 da biblioteca OTA.
- Biblioteca OTA versão 1
-
OTA_Err_t OTA_Resume( void * pxConnection );
- Biblioteca OTA versão 3
-
OtaErr_t OTA_Resume( void );
A enumeração do código de erro OTA de retorno é alterada e novos códigos de erro são adicionados. Consulte Atualização do AWS IoT Over-the-Air v3.0.0: Otaerr_t
. - Exemplo de uso:
-
OtaErr_t xOtaError = OtaErrUninitialized; xOtaError = OTA_Resume(); /* Handle error */
OTA_CheckForUpdate
Os parâmetros de entrada são os mesmos, o código de erro OTA de retorno é renomeado e novos códigos de erro são adicionados na versão 3 da biblioteca OTA.
- Biblioteca OTA versão 1
-
OTA_Err_t OTA_CheckForUpdate( void );
- Biblioteca OTA versão 3
-
OtaErr_t OTA_CheckForUpdate( void )
A enumeração do código de erro OTA de retorno é alterada e novos códigos de erro são adicionados. Consulte Atualização do AWS IoT Over-the-Air v3.0.0: Otaerr_t
.
OTA_EventProcessingTask
Esta é uma nova API e é o principal loop de eventos para lidar com eventos para atualizações do OTA. Ele deve ser chamado pela tarefa da aplicação. Esse loop continuará manipulando e executando eventos recebidos pela atualização OTA até que essa tarefa seja encerrada pela aplicação.
- Biblioteca OTA versão 3
-
void OTA_EventProcessingTask( void * pUnused );
- Exemplo para FreeRTOS:
-
/* Create FreeRTOS task*/ xTaskCreate( prvOTAAgentTask, "OTA Agent Task", otaexampleAGENT_TASK_STACK_SIZE, NULL, otaexampleAGENT_TASK_PRIORITY, NULL ); /* Call OTA_EventProcessingTask from the task */ static void prvOTAAgentTask( void * pParam ) { /* Calling OTA agent task. */ OTA_EventProcessingTask( pParam ); LogInfo( ( "OTA Agent stopped." ) ); /* Delete the task as it is no longer required. */ vTaskDelete( NULL ); }
- Exemplo para POSIX:
-
/* Create posix thread.*/ if( pthread_create( &threadHandle, NULL, otaThread, NULL ) != 0 ) { LogError( ( "Failed to create OTA thread: " ",errno=%s", strerror( errno ) ) ); /* Handle error. */ } /* Call OTA_EventProcessingTask from the thread.*/ static void * otaThread( void * pParam ) { /* Calling OTA agent task. */ OTA_EventProcessingTask( pParam ); LogInfo( ( "OTA Agent stopped." ) ); return NULL; }
OTA_SignalEvent
Esta é uma nova API que adiciona o evento ao final da fila de eventos e também é usada por módulos OTA internos para sinalizar a tarefa do atendente.
- Biblioteca OTA versão 3
-
bool OTA_SignalEvent( const OtaEventMsg_t * const pEventMsg );
- Exemplo de uso:
-
OtaEventMsg_t xEventMsg = { 0 }; xEventMsg.eventId = OtaAgentEventStart; ( void ) OTA_SignalEvent( &xEventMsg );
Como integrar a biblioteca OTA como um submódulo em sua aplicação
Se você quiser integrar a biblioteca OTA em sua própria aplicação, você pode usar o comando git submodule. Os submódulos Git permitem que você mantenha um repositório Git como um subdiretório de outro repositório Git. A versão 3 da biblioteca OTA é mantida no repositório ota-for-aws-iot-embedded-sdk
git submodule add https://github.com/aws/ota-for-aws-iot-embedded-sdk.git
destination_folder
git commit -m "Added the OTA Library as submodule to the project."
git push
Para obter mais informações, consulte Como integrar o atendente OTA em sua aplicação no Manual do usuário do FreeRTOS.