Firmware update operations. More...

Functions

zos_result_t zn_dms_check_for_update (zos_bool_t *update_available, zos_buffer_t *server_msg)
 Query DMS if a firmware update is available. More...
 
zos_result_t zn_dms_update (const char *version_str)
 Update device's firmware. More...
 
zos_result_t zn_dms_update_with_callback (const char *version_str, void(*callback)(void))
 Update device's firmware with callback just before the upate begins. More...
 
zos_update_result_t zn_dms_get_update_result (void)
 Return result of last firmware update (if available) More...
 

Detailed Description

Firmware update operations.

Function Documentation

zos_result_t zn_dms_check_for_update ( zos_bool_t update_available,
zos_buffer_t server_msg 
)

Query DMS if a firmware update is available.

This queries the DMS and returns if an update is available. If thie API returns ZOS_SUCCESS and the update_available argument contains ZOS_FALSE, then the device's current firmware is up-to-date.

If update_available is ZOS_TRUE, then the server_msg argument will contain the available firmware version to update.

See the ZentriOS command documentation for more information: ota

Note
The server_msg argument, a zos_buffer_t, should be pre-configured to point to a buffer that will be populated with a message from the server. The .data member should point to a string buffer. The size to be the size of the string buffer.
Parameters
[out]update_availablePointer to zos_bool_t which will contain if an update is available
[out]server_msgzos_buffer_t pointer to buffer to hold message from server, leave NULL if unused
Returns
Result of API, see zos_result_t
zos_update_result_t zn_dms_get_update_result ( void  )

Return result of last firmware update (if available)

This returns the result of the last firmware update. This is typically called after calling zn_dms_update()

Refer to zos_update_result_t for the available results codes.

Note
The result codes are reset after a power-cycle or another OTA attempt

Use zn_system_get_version_uint32() or zn_system_get_version_str() to get the version of the current firmware.

Returns
Result of update, see zos_update_result_t
Examples:
basic/firmware_update/firmware_update.c.
zos_result_t zn_dms_update ( const char *  version_str)

Update device's firmware.

This API will invoke an OTA update. The firmware the device is update to is determined by the supplied version argument.

If version is:

  • ZOS_DMS_UPDATE_QUERY - update to latest firmware only if out-dated.
  • ZOS_DMS_UPDATE_FORCED - forced update to latest firmware regardless of current version
  • else version string - update to specified version (e.g. "3.3.2.4")

The DMS uses the device's current product to determine the available firmware. The device's product can be configured via webbased DMS GUI or zn_dms_activate().

If successful, this API does NOT return. This API will immediately invoke the ZentriOS Kernel to perform the update. After attempting/performing the update, the Kernel will return control to the ZentriOS Services.

If the Zap is configured to auto_run the (potentially updated) Zap will start from the beginning. See the ZentriOS variable documentation zap.auto_run for more information about enabling Zap auto_run

To determine the result of the update, use zn_dms_get_update_result().

See the ZentriOS command documentation for more information: ota

Note
The API requires valid network credentials with an internet connection. If successful, this API does NOT return. After the update the Zap begins execution from the beginning.
Parameters
[in]version_strVersion to update firmware to, see this function's description for more information
Returns
Result of API, see zos_result_t
zos_result_t zn_dms_update_with_callback ( const char *  version_str,
void(*)(void)  callback 
)

Update device's firmware with callback just before the upate begins.

This has the exact same functionality as zn_dms_update() except the optional callback will be invoked just before the update begins.

This is useful if this API is being called from a serial command. The command response may be returned before ZentriOS reboots into the Kernel to perform the update.

Parameters
[in]version_strversion_str Version to update firmware to, see this function's description for more information
[in]callbackCallback to be invoked just before the firmware update starts
Returns
Result of API, see zos_result_t