Porting Guide

Guide for porting OTA to a new platform.

A port to a new platform must provide the following components:

1. Configuration Macros
2. Ports for PAL
3. OS Interface
4. MQTT Interface
5. HTTP Interface

Configuration Macros

Settings that must be set as macros in the config header ota_config.h, or passed in as compiler options.

Note

If a custom configuration header ota_config.h is not provided, then the OTA_DO_NOT_USE_CUSTOM_CONFIG macro must be defined.

See also

Configurations

The following optional logging macros are used throughout the library:

• LogError
• LogWarn
• LogInfo
• LogDebug

OTA PAL requirements:

The OTA library relies on portable abstraction layer (PAL) callbacks that must be implemented to store the download as it is streamed.

See also

OTA PAL documentation

The OTA PAL interface used by the OTA library is defined in ota_platform_interface.h. A port must implement functions corresponding to the following function pointers:

• OTA PAL Abort: A function to abort access to an existing open file.

  OtaPalStatus_t ( * OtaPalAbort_t )(
      OtaFileContext_t * const pFileContext
  );

• OTA PAL Create File: A function to create a new file for receiving data chunks.

  OtaPalStatus_t (* OtaPalCreateFileForRx_t)(
      OtaFileContext_t * const pFileContext
  );

• OTA PAL Close File: A function to authenticate and close a file used for receiving data.

  OtaPalStatus_t ( * OtaPalCloseFile_t )(
      OtaFileContext_t * const pFileContext
  );

• OTA PAL Write Block: A function to write a block of data to the specified file at the given offset.

  int16_t ( * OtaPalWriteBlock_t )(
      OtaFileContext_t * const pFileContext,
      uint32_t offset,
      uint8_t * const pData,
      uint32_t blockSize
  );

• OTA PAL Activate New Image: A function to activate the newest device image received via OTA.

  typedef OtaPalStatus_t ( * OtaPalActivateNewImage_t )(
      OtaFileContext_t * const pFileContext
  );

• OTA PAL Reset Device: A function to reset the device and cause a reboot of the system.

  OtaPalStatus_t ( * OtaPalResetDevice_t )(
      OtaFileContext_t * const pFileContext
  );

• OTA PAL Set Platform Image State: A function to set the state of the OTA update image.

  OtaPalStatus_t ( * OtaPalSetPlatformImageState_t )(
      OtaFileContext_t * const pFileContext,
      OtaImageState_t eState
  );

• OTA PAL Get Platform Image State: A function to get the state of the OTA update image.

  typedef OtaPalImageState_t ( * OtaPalGetPlatformImageState_t )(
      OtaFileContext_t * const pFileContext
  );

OTA OS Functional Interface requirements:

The OTA library relies on several functionalities that are commonly provided by operating systems. This includes timers, events, and memory allocation. This interface must be implemented to provide these functionalities to the OTA library.

See also

OTA OS Functional Interface documentation The OTA OS Functional Interface used by the OTA library is defined in ota_os_interface.h. A port must implement functions corresponding to the following function pointers:

• OTA OS Functional Interface Initialize Event Mechanism: A function to initialize the mechanism used to manage OTA events.

  OtaOsStatus_t ( * OtaInitEvent_t )(
      OtaEventContext_t * pEventCtx
  );

• OTA OS Functional Interface Send Event: A function to send an event to the OTA library event handler.

  OtaOsStatus_t ( * OtaSendEvent_t )(
      OtaEventContext_t * pEventCtx,
      const void * pEventMsg,
      unsigned int timeout
  );

• OTA OS Functional Interface Receive Event: A function to receive the next event from the pending OTA events.

  OtaOsStatus_t ( * OtaReceiveEvent_t )(
      OtaEventContext_t * pEventCtx,
      void * pEventMsg,
      uint32_t timeout
  );

• OTA OS Functional Interface Deinitialize Event: A function to deinitialize the OTA events mechanism and free any resources used.

  OtaOsStatus_t ( * OtaDeinitEvent_t )(
      OtaEventContext_t * pEventCtx
  );

• OTA OS Functional Interface Timer Callback: A function that notifies the OTA library that a timer has triggered. This function must be called when one of the timers trigger.

  void ( * OtaTimerCallback_t )(
      OtaTimerId_t otaTimerId
  );

• OTA OS Functional Interface Start Timer: A function to start a timer or reset it if it has already started.

  OtaOsStatus_t ( * OtaStartTimer_t )(
      OtaTimerId_t otaTimerId,
      const char * const pTimerName,
      const uint32_t timeout,
      OtaTimerCallback_t callback
  );

• OTA OS Functional Interface Stop Timer: A function to stop a timer.

  OtaOsStatus_t ( * OtaStopTimer_t )(
      OtaTimerId_t otaTimerId
  );

• OTA OS Functional Interface Delete Timer: A function to delete a timer.

  OtaOsStatus_t ( * OtaDeleteTimer_t )(
      OtaTimerId_t otaTimerId
  );

• OTA OS Functional Interface Malloc: A function to allocate the requested memory and return a pointer to it.

  void * ( * OtaMalloc_t )(
      size_t size
  );

• OTA OS Functional Interface Free: A function to deallocate the memory previously allocated by a call to a allocation function of type OtaMalloc_t.

  void ( * OtaFree_t )(
      void * ptr
  );

OTA MQTT requirements:

The OTA library relies on a MQTT library to manage control and data operations.

The OTA library needs to connect to AWS IoT using MQTT PUBLISH messages to receive notifications and file blocks. This is done by Subscribing to different notification topics.

See also

OTA MQTT documentation

The OTA MQTT API used by the OTA library is defined in ota_mqtt_interface.h. A library must implement functions corresponding to the following function pointers:

• OTA MQTT Subscribe: A function that is used to subscribe to a given topic filter and QoS.

  OtaMqttStatus_t ( * OtaMqttSubscribe_t ) (  const char * pTopicFilter,
                                              uint16_t topicFilterLength,
                                              uint8_t ucQoS );

• OTA MQTT Unsubscribe: A function that is used to unsubscribe from a given topic filter using provided QoS.

  OtaMqttStatus_t ( * OtaMqttUnsubscribe_t ) (const char * pTopicFilter,
                                              uint16_t topicFilterLength,
                                              uint8_t ucQoS );

• OTA MQTT Publish: A function that is used to publish a message to a given topic filter and QoS.

  OtaMqttStatus_t ( * OtaMqttSubscribe_t ) (  const char * pTopicFilter,
                                              uint16_t topicFilterLength,
                                              uint8_t ucQoS );

OTA HTTP requirements:

The OTA library relies on a HTTP library to manage data operations.

To download a datablock over http, OTA library needs to connect to a pre-signed URL and request data blocks to download the update.

See also

OTA MQTT documentation

The OTA HTTP API used by the OTA library is defined in ota_http_interface.h.

A library must implement functions corresponding to the following function pointers:

• OTA HTTP Initialize: A function to initialize the http connection with a given Pre-signed URL.

  OtaHttpStatus_t ( * OtaHttpInit_t ) ( char * pUrl );

• OTA HTTP Request: A function to request a data block in a given range.

  OtaHttpStatus_t ( * OtaHttpRequest_t )  (  uint32_t rangeStart,
                                              uint32_t rangeEnd );

• OTA HTTP Deinitialize: A function to deinitialize the http connection.

  OtaHttpStatus_t ( * OtaHttpDeinit )( void );