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¶

EEPROM_LINK_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¶

bondinfo_t