OTA Typedefs

group group_ota_typedefs

Typedefs used by the OTA Agent.

Defines

ADD_QUOTES(str)

Macro combo to add quotes around a define.

Used to define a string value for CY_TARGET_BOARD.

EXPAND_AND_ADD_QUOTES(str)

Macro combo to add quotes around a define.

Used to define a string value for CY_TARGET_BOARD.

CY_TARGET_BOARD_STRING

Macro combo to add quotes around a define.

Used to define a string value for CY_TARGET_BOARD.

CY_OTA_MQTT_FILENAME_BUFF_SIZE

Size for the HTTP filename to get the OTA image.

CY_OTA_MQTT_UNIQUE_TOPIC_BUFF_SIZE

Size for the unique MQTT topic to get the OTA image.

CY_OTA_MQTT_MESSAGE_BUFF_SIZE

Size for MQTT message to request Job.

CY_OTA_CHUNK_SIZE

Size of data chunks for each transfer.

CY_OTA_HTTP_FILENAME_SIZE

Size of the string for the HTTP file name.

CY_OTA_MQTT_MAGIC

First part of the topic to subscribe / publish.

Topic for the device to send messages to the Publisher: “COMPANY_TOPIC_PREPEND / BOARD_NAME / PUBLISHER_LISTEN_TOPIC”

Override in cy_ota_config.h. Last part of the topic to subscribe.

Topic for the device to send messages to the Publisher: “COMPANY_TOPIC_PREPEND / BOARD_NAME / PUBLISHER_LISTEN_TOPIC”

Override in cy_ota_config.h. “Magic” value placed in the MQTT Data Payload header.

Override in cy_ota_config.h.

NOTIFICATION_RESPONSE_NO_UPDATES

End of topic to send a message to the Publisher for Direct download.

Override in cy_ota_config.h. Publisher response when no update is available.

NOTIFICATION_RESPONSE_UPDATES

Publisher response when an update is available.

NOTIFICATION_RESPONSE_RESULT_RECEIVED

Publisher response when receiving results.

CY_OTA_SUBSCRIBE_AVAIL_TOPIC

Topic to receive messages from the Publisher.

SUBSCRIBER_PUBLISH_TOPIC

Topic to send messages to the Publisher.

CY_OTA_INTERVAL_SECS_MIN

Minimum interval check time.

Minimum interval time for any timing specification in seconds.

CY_OTA_INTERVAL_SECS_MAX

Maximum interval check time.

This applies to: Initial wait after call to cy_ota_agent_start() before contacting server. Wait value after failing or completing an OTA download.

EEPROM_SIZE
SIMPLE_MODE
WEAR_LEVELLING_FACTOR
REDUNDANT_COPY
BLOCKING_WRITE
LOGICAL_EEPROM_START
EEPROM_SLOT_DATA
EEPROM_IDENTITY_KEYS_START
GET_ADDR_FOR_DEVICE_KEYS(x)
BOND_MAX
CY_OTA_MESSAGE_FIELD

The Message Name field in a JSON Job document.

The Message Name field indicates the type of request/info that is contained in the Job document.

CY_OTA_MANUF_FIELD

The Manufacturer Name field in a JSON Job document.

The Manufacturer Name can be used to determine if the OTA image available is correct.

CY_OTA_MANUF_ID_FIELD

The Manufacturer ID field in a JSON Job document.

The Manufacturer ID can be used to determine whether the OTA image available is correct.

CY_OTA_PRODUCT_FIELD

The Product ID field in a JSON Job document.

The Product ID can be used to determine whether the OTA image available is correct.

CY_OTA_SERIAL_NUMBER_FIELD

The Serial Number field in a JSON Job document.

The Serial Number can be used to determine whether the OTA image available is correct.

CY_OTA_VERSION_FIELD

The Version field in a JSON Job document.

The Version can be used to determine whether the OTA image available is an upgrade (for example,”1.6.3”).

CY_OTA_BOARD_FIELD

The Board field in a JSON Job document.

The Board can be used to determine whether the OTA image available is correct.

CY_OTA_CONNECTION_FIELD

The Connection field in a JSON Job document.

The Connection defines the connection type to use to obtain the OTA image (“HTTP” or “MQTT”).

CY_OTA_BROKER_FIELD

The Broker field for MQTT connection in a JSON Job document.

MQTT is the MQTT Broker used to obtain the OTA image.

CY_OTA_PORT_FIELD

The Port field in a JSON Job document.

Port is used for HTTP or MQTT connection to obtain the OTA image.

CY_OTA_SERVER_FIELD

The Server field is for HTTP connection in a JSON Job document.

The server is the HTTP server used to obtain the OTA image. See also CY_OTA_PORT_FIELD CY_OTA_FILE_FIELD.

CY_OTA_FILE_FIELD

The File field is for HTTP connection in a JSON Job document.

The File is the name of the OTA image on the HTTP server. See also CY_OTA_PORT_FIELD.

CY_OTA_OFFSET_FIELD

The Offset field is for a JSON Chunk Request document.

The offset is where in the OTA image to start a chunk transfer.

CY_OTA_SIZE_FIELD

The Size field is for a JSON Chunk Request document.

The Size is the size of the chunk to read from the OTA image for a chunk transfer.

CY_OTA_UNIQUE_TOPIC_FIELD

The Unique Topic field is the name of the topic used for receiving Job/data from the Publisher.

The Unique Topic Name used for receipt of the Job/data from the Publisher.

CY_OTA_MQTT_STRING

The MQTT Connection Type used in a JSON Job document.

Test for this string in a JSON Job document for MQTT type connection. CY_OTA_CONNECTION_FIELD.

CY_OTA_HTTP_STRING

The HTTP connection type used in a JSON Job document.

Test for this string in a JSON Job document for HTTP type connection. CY_OTA_CONNECTION_FIELD.

CY_OTA_HTTPS_STRING

The HTTPS connection type used in a JSON Job document.

Test for this string in a JSON Job document for HTTPS type connection. CY_OTA_CONNECTION_FIELD.

CY_OTA_MESSAGE_LEN

The Max length of the “Message” field in a JSON Job document.

CY_OTA_JOB_MANUF_LEN

The Max length of the “Manufacturer” field in a JSON Job document.

CY_OTA_JOB_MANUF_ID_LEN

The Max length of the “ManufacturerID” field in a JSON Job document.

CY_OTA_JOB_PRODUCT_ID_LEN

The Max length of the “ProductID” field in a JSON Job document.

CY_OTA_JOB_SERIAL_NUMBER_LEN

The Max length of the “SerialNumber” field in a JSON Job document.

CY_OTA_JOB_VERSION_LEN

The Max length of the “Version” field in a JSON Job document.

CY_OTA_JOB_BOARD_LEN

The Max length of the “Board” field in a JSON Job document.

CY_OTA_JOB_URL_BROKER_LEN

The Max length of the “Broker” and “Server” fields in a JSON Job document.

CY_OTA_MQTT_BROKER_PORT

The MQTT Broker port for a non-TLS connection.

CY_OTA_MQTT_BROKER_PORT_TLS

The MQTT Broker port for a TLS connection.

CY_OTA_MQTT_BROKER_PORT_TLS_CERT

The MQTT Broker port for a TLS connection with certificates.

CY_OTA_HTTP_SERVER_PORT

The HTTP connection port for a non-TLS connection.

CY_OTA_HTTP_SERVER_PORT_TLS

The HTTP connection port for a TLS connection.

CY_OTA_INITIAL_CHECK_SECS

Initial OTA check.

Time from when cy_ota_start() is called to when the OTA Agent first checks for an update. You can override this define in cy_ota_config.h.

Minimum value is CY_OTA_INTERVAL_SECS_MIN. Maximum value is CY_OTA_INTERVAL_SECS_MAX.

CY_OTA_NEXT_CHECK_INTERVAL_SECS

Next OTA check.

Time from when after the OTA Agent completes or fails an update until the next check. You can override this define in cy_ota_config.h.

Minimum value is CY_OTA_INTERVAL_SECS_MIN. Maximum value is CY_OTA_INTERVAL_SECS_MAX.

CY_OTA_RETRY_INTERVAL_SECS

Retry interval.

Time between failures for connection before you can retry. You can override this define in cy_ota_config.h. Minimum value is CY_OTA_INTERVAL_SECS_MIN. Maximum value is CY_OTA_INTERVAL_SECS_MAX.

CY_OTA_CHECK_TIME_SECS

Length of time to check for downloads.

The OTA Agent wakes up, connects to server, and waits this much time before disconnecting. This allows the OTA Agent to be inactive for long periods of time, only checking for short periods. Use 0x00 to continue checking once started.

CY_OTA_PACKET_INTERVAL_SECS

Expected maximum download time between each OTA packet arrival.

This is used check that the download occurs in a reasonable time frame.

CY_OTA_JOB_CHECK_TIME_SECS

Length of time to check for getting the Job document.

The OTA Agent wakes up, connects to broker/server, and waits this much time before disconnecting. This allows the OTA Agent to be inactive for long periods of time, only checking for short periods. Use 0x00 to continue checking once started.

CY_OTA_DATA_CHECK_TIME_SECS

Length of time to check for getting the OTA image data.

After getting the Job (or during a Direct download), this is the amount of time to wait before canceling the download. Use 0x00 to disable.

CY_OTA_RETRIES

Length of time to check for OTA image downloads.

The OTA Agent wakes up, connects to server, and waits this much time before disconnecting. This allows the OTA Agent to be inactive for long periods of time, only checking for short periods. Use 0x00 to continue checking once started. Number of OTA session retries.

Retry count for overall OTA session attempts.

CY_OTA_CONNECT_RETRIES

Number of OTA connect to server/Broker retries.

Retry count for connection attempts.

CY_OTA_MAX_DOWNLOAD_TRIES

Number of OTA download retries.

Retry count for attempts at downloading the OTA image.

PUBLISHER_LISTEN_TOPIC

Last part of the topic to subscribe.

Topic for the device to send a message to the Publisher: “COMPANY_TOPIC_PREPEND / BOARD_NAME / PUBLISHER_LISTEN_TOPIC” The combined topic must match the Publisher’s subscribe topic.

Override in cy_ota_config.h.

COMPANY_TOPIC_PREPEND

First part of the topic to subscribe/publish.

Topic for the device to send a message to the Publisher: “COMPANY_TOPIC_PREPEND / BOARD_NAME / PUBLISHER_LISTEN_TOPIC”

Override in cy_ota_config.h.

PUBLISHER_DIRECT_TOPIC

End of topic to send a message to the Publisher for Direct download.

Override in cy_ota_config.h.

CY_OTA_RESULT_SUCCESS

“Update successful” message.

Used with sprintf() to create a RESULT message to the Broker/server.

CY_OTA_RESULT_FAILURE

“Update failed” message.

Used with sprintf() to create a RESULT message to the Broker/server.

CY_OTA_HTTP_JOB_FILE

Default Job document name.

Name of the update JSON file for HTTP.

CY_OTA_HTTP_DATA_FILE

Default OTA image file name.

Name of the OTA image for HTTP.

CY_OTA_SUBSCRIBE_UPDATES_AVAIL

Device message to the Publisher to ask about updates.

Used with sprintf() to insert the current version and UniqueTopicName at runtime. Override if required by defining in cy_ota_config.h.

CY_OTA_DOWNLOAD_REQUEST

Device message to the Publisher to ask for a full download with one request.

  • Used with sprintf() to insert the current version and UniqueTopicName at runtime. Override if required by defining in cy_ota_config.h.

CY_OTA_DOWNLOAD_CHUNK_REQUEST

Device message to the Publisher to ask for a chunk of data at a time.

  • Used with sprintf() to insert the current version and UniqueTopicName at runtime. Override if required by defining in cy_ota_config.h.

CY_OTA_DOWNLOAD_DIRECT_REQUEST

Device message to the Publisher to ask for a download.

  • Used with sprintf() to insert the current version and UniqueTopicName at runtime. Override if required by defining in cy_ota_config.h.

CY_OTA_MQTT_RESULT_JSON

Device JSON document to respond to the MQTT Publisher.

Used with sprintf() to create the JSON message. Override if required by defining in cy_ota_config.h.

CY_OTA_HTTP_RESULT_JSON

Device JSON document to respond to the HTTP server.

Used with sprintf() to create the JSON message. Override if required by defining in cy_ota_config.h.

CY_OTA_HTTP_GET_TEMPLATE

HTTP GET template.

Used with sprintf() to create the GET request for the HTTP server. Override if required by defining in cy_ota_config.h.

CY_OTA_HTTP_GET_RANGE_TEMPLATE

HTTP GET Range template.

Used with sprintf() to create the GET request for the HTTP server when requesting a range of data.

CY_OTA_HTTP_POST_TEMPLATE

HTTP POST template.

Used with sprintf() to create the POST message for the HTTP server. Override if required by defining in cy_ota_config.h.

CY_OTA_MQTT_KEEP_ALIVE_SECONDS

Keepalive interval for MQTT.

Maximum number of MQTT topics.

An MQTT ping request will be sent periodically at this interval. The maximum number of topics for subscribing.

CY_OTA_MQTT_MAX_TOPICS

Maximum number of MQTT topics.

The maximum number of topics for subscribing.

CY_OTA_MQTT_TOPIC_PREFIX

Topic prefix.

Used as the prefix for “Will” and “Acknowledgement” messages.

CY_OTA_MQTT_CLIENT_ID_PREFIX

The first characters in the client identifier.

A timestamp is appended to this prefix to create a unique client identifer for each connection.

Typedefs

typedef void *cy_ota_context_ptr

The OTA context pointer.

Returned from cy_ota_agent_start() and used for subsequent calls.

Enums

enum [anonymous]

Values:

enumerator NUM_BONDED
enumerator NEXT_FREE
enum cy_ota_update_flow_t

cy_ota_update_flow_t: The Type of OTA update flow.

Direct Flow: The application knows the location of the update and directly downloads it. Job Flow: The application loads a Job document which describes where the update is located.

Values:

enumerator CY_OTA_JOB_FLOW

Use the Job flow to get the OTA Job document and data.

enumerator CY_OTA_DIRECT_FLOW

Get the OTA image data directly.

enum cy_ota_connection_t

cy_ota_connection_t: The connection type to use.

Values:

enumerator CY_OTA_CONNECTION_UNKNOWN

Unknown connection type.

enumerator CY_OTA_CONNECTION_MQTT

Use MQTT connection.

enumerator CY_OTA_CONNECTION_HTTP

Use HTTP connection.

enumerator CY_OTA_CONNECTION_HTTPS

Use HTTPS connection.

enumerator CY_OTA_CONNECTION_BLE

Use BLE connection.

enum cy_ota_mqtt_session_type_t

cy_ota_mqtt_session_type_t: The MQTT session clean flag.

This flag signals the MQTT Broker to start a new session or restart an existing session.

Values:

enumerator CY_OTA_MQTT_SESSION_CLEAN

Start a clean MQTT session with the Broker.

enumerator CY_OTA_MQTT_SESSION_RESTART

Restart an existing MQTT session with the Broker.

enum cy_ota_cb_reason_t

cy_ota_cb_reason_t: The reasons for OTA callbacks to the application.

Values:

enumerator CY_OTA_REASON_STATE_CHANGE

OTA Agent state changed, see cb_data->state.

enumerator CY_OTA_REASON_SUCCESS

State function successful.

enumerator CY_OTA_REASON_FAILURE

State function failed.

enumerator CY_OTA_LAST_REASON

Placeholder, Do not use.

enum cy_ota_agent_state_t

cy_ota_agent_state_t: The OTA state.

Values:

enumerator CY_OTA_STATE_NOT_INITIALIZED

OTA system is not initialized.

enumerator CY_OTA_STATE_EXITING

OTA system is exiting.

enumerator CY_OTA_STATE_INITIALIZING

OTA system is initializing.

enumerator CY_OTA_STATE_AGENT_STARTED

OTA Agent has started.

enumerator CY_OTA_STATE_AGENT_WAITING

OTA Agent is waiting for the timer to start.

enumerator CY_OTA_STATE_STORAGE_OPEN

OTA Agent will call cy_storage_open.

enumerator CY_OTA_STATE_STORAGE_WRITE

OTA Agent will call cy_storage_write.

enumerator CY_OTA_STATE_STORAGE_CLOSE

OTA Agent will call cy_storage_close.

enumerator CY_OTA_STATE_START_UPDATE

OTA Agent will determine the flow: Job or Direct.

enumerator CY_OTA_STATE_JOB_CONNECT

OTA Agent will connect to the Job Broker/server.

enumerator CY_OTA_STATE_JOB_DOWNLOAD

OTA Agent will get the Job from the Broker/server.

enumerator CY_OTA_STATE_JOB_DISCONNECT

OTA Agent will disconnect from the Job Broker/server.

enumerator CY_OTA_STATE_JOB_PARSE

OTA Agent will parse the Job.

enumerator CY_OTA_STATE_JOB_REDIRECT

OTA Agent will use the Job to change the Broker/server.

enumerator CY_OTA_STATE_DATA_CONNECT

OTA Agent will connect to the data Broker/server.

enumerator CY_OTA_STATE_DATA_DOWNLOAD

OTA Agent will download the data.

enumerator CY_OTA_STATE_DATA_DISCONNECT

OTA Agent will disconnect from the data Broker/server.

enumerator CY_OTA_STATE_VERIFY

OTA Agent will verify the download.

enumerator CY_OTA_STATE_RESULT_REDIRECT

OTA Agent will redirect back to the initial connection.

enumerator CY_OTA_STATE_RESULT_CONNECT

OTA Agent will connecting to the result Broker/server.

enumerator CY_OTA_STATE_RESULT_SEND

OTA Agent will send the result.

enumerator CY_OTA_STATE_RESULT_RESPONSE

OTA Agent will wait for a result response.

enumerator CY_OTA_STATE_RESULT_DISCONNECT

OTA Agent will disconnect from the result Broker/server.

enumerator CY_OTA_STATE_OTA_COMPLETE

OTA Agent is done with current session.

OTA Agent will reboot or will wait.

enumerator CY_OTA_NUM_STATES

Not used, placeholder.

enum cy_ota_callback_results_t

cy_ota_callback_results_t: Results from the registered OTA callback.

These are the return values from the application to the OTA Agent at the end of a callback.

Of the callback reasons, cy_ota_cb_reason_t, the OTA Agent checks only the application callback return values when the reason is CY_OTA_REASON_STATE_CHANGE. The other callback reasons are informational for the application.

When the callback reason is CY_OTA_REASON_STATE_CHANGE, the OTA Agent is about to call the function to act on the new state. The application callback function can return a value that affects the OTA Agent.

There are a few state changes that will pick up changes made by the application and use those changes.

 cb_data->reason             - Reason for the callback.
 cb_data->cb_arg             - Argument provided to cy_ota_agent_start() params.
 cb_data->state              - CY_OTA_REASON_STATE_CHANGE:
                                 - Start of cy_ota_agent_state_t, about to call the default function.
                              - CY_OTA_REASON_SUCCESS:
                                 - Error function succeeded.
                              - CY_OTA_REASON_FAILURE:
                                 - Error function failed.
 cb_data->error              - Same as cy_ota_get_last_error().
 cb_data->storage            - For the CY_OTA_STATE_STORAGE_WRITE callback, points to the storage info.
 cb_data->total_size         - Total # bytes to be downloaded.
 cb_data->bytes_written      - Total # bytes written.
 cb_data->percentage         - Percentage of data downloaded.
 cb_data->connection_type    - Current connection - MQTT or HTTP.
 cb_data->broker_server      - Current server URL and port.
 cb_data->credentials        - Pointer to the current credentials being used.
 cb_data->mqtt_connection    - Current MQTT connection (NULL if not connected):
                                 - For CY_OTA_REASON_STATE_CHANGE
                                   - CY_OTA_STATE_JOB_CONNECT or
                                     CY_OTA_STATE_DATA_CONNECT or
                                     CY_OTA_STATE_RESULT_CONNECT
                                 - OTA Agent about to connect, if Application fills this in;
                                   then the OTA Agent will use the provided connection instance.
 cb_data->http_connection    - Current HTTP connection (NULL if not conencted).
                                 - For CY_OTA_REASON_STATE_CHANGE:
                                   - CY_OTA_STATE_JOB_CONNECT or
                                     CY_OTA_STATE_DATA_CONNECT or
                                     CY_OTA_STATE_RESULT_CONNECT
                                 - OTA Agent about to connect, if Application fills this in;
                                   then the OTA Agent will use the provided connection instance.
 cb_data->file               - Filename for HTTP GET command.
 cb_data->unique_topic       - Unique topic name to receive data from MQTT Broker/Publisher.
 cb_data->json_doc           - JSON document used for:
                                 MQTT:
                                 - Send to request a Job from the MQTT Broker.
                                 - Received Job from the MQTT Broker.
                                 - Send to request data from the MQTT Broker.
                                 - Send to report the result to the MQTT Broker.
                                 HTTP
                                 - HTTP GET command for the Job.
                                 - Received the Job from the HTTP server.
                                 - HTTP GET command for data.
                                 - HTTP PUT command to the report result to the HTTP server (Not implemented yet).

Values:

enumerator CY_OTA_CB_RSLT_OTA_CONTINUE

OTA Agent to continue with the function, using the modified data from the application.

enumerator CY_OTA_CB_RSLT_OTA_STOP

OTA Agent to end the current update session (do not quit the OTA Agent).

enumerator CY_OTA_CB_RSLT_APP_SUCCESS

Application completed task; OTA Agent uses success.

enumerator CY_OTA_CB_RSLT_APP_FAILED

Application failed task; OTA Agent uses failure.

enumerator CY_OTA_CB_NUM_RESULTS

Placeholder, do not use.

struct bondinfo_t