BGX OTA Update

bgx_ota_update contains a class (BGX_OTA_Updater) and other data types that are used to perform an OTA update operation (i.e. More...

Classes

protocol  <BGX_OTA_Updater_Delegate>
 
class  BGX_OTA_Updater
 Performs OTA operations on a BGX device. More...
 

Enumerations

enum  ota_step_t : int {
  ota_step_no_ota, ota_step_init, ota_step_scan, ota_step_connect,
  ota_step_find_services, ota_step_find_characteristics, ota_step_upload_no_response, ota_step_upload_with_response,
  ota_step_upload_finish, ota_step_end, ota_step_error, ota_step_password_required,
  ota_step_canceled, ota_max_step
}
 This enum indicates the steps that occur during an OTA operation. More...
 
enum  ota_operation_t : int { ota_firmware_update_in_progress, ota_firmware_update_complete, ota_no_operation_in_progress, ota_max_operations }
 This enum describes the overall state of the BGX_OTA_Updater object. More...
 

Detailed Description

bgx_ota_update contains a class (BGX_OTA_Updater) and other data types that are used to perform an OTA update operation (i.e.

Firmware Update) of a Silicon Labs BGX device.

To perform a firmware update, your app should:

  1. Get the CBPeripheral object of the BGX to be updated.
  2. Get the unique device id for the peripheral. You can use the BGXpressManager class method
    • (NSString *)uniqueIDForPeripheral:(CBPeripheral *)peripheral for this if needed.
  3. Create an instance of BGX_OTA_Updater.
  4. Setup Key Value Observing (KVO) on this instance to drive your user interface. You probably want to observe operationInProgress, ota_step, and upload_progress.
  5. Call - (void)updateFirmwareWithImageAtPath:(NSString *)path2FWImage withVersion:(NSString *)version.
  6. When the update is complete, release your instance of BGX_OTA_Updater.

Class Documentation

◆ BGX_OTA_Updater_Delegate-p

protocol BGX_OTA_Updater_Delegate-p

Instance Methods

(void) - operationInProgressDidChange:
 
(void) - ota_stepDidChange:
 
(void) - upload_progressDidChange:
 
(void) - ota_requires_password:
 

Method Documentation

◆ operationInProgressDidChange:()

- (void) operationInProgressDidChange: (ota_operation_t)  operation
optional

◆ ota_stepDidChange:()

- (void) ota_stepDidChange: (ota_step_t)  ota_step
optional

◆ upload_progressDidChange:()

- (void) upload_progressDidChange: (float)  upload_progress
optional

◆ ota_requires_password:()

- (void) ota_requires_password: (NSError *)  err
required

◆ BGX_OTA_Updater

class BGX_OTA_Updater

Performs OTA operations on a BGX device.

The BGX_OTA_Updater class performs OTA operations on a BGX device to update the firmware on the BGX. An iOS app performing an OTA update should observe the properties of this object to track the progress of the OTA operation and present a user interface to the user if desired.

Remarks
When the OTA is complete, this object should be discarded.

Inherits NSObject, <CBCentralManagerDelegate>, and <CBPeripheralDelegate>.

Instance Methods

(id) - initWithPeripheral:bgx_device_uuid:
 Initialize a BGX OTA instance for the specified BGX peripheral. More...
 
(void) - updateFirmwareWithImageAtPath:withVersion:
 Update the firmware using the specified image and bundle ID. More...
 
(void) - continueOTAWithPassword:
 If a password is required for an OTA operation to be performed or a previously supplied password fails (i.e., incorrect password), you may ask the user for a password and then call continueOTAWithPassword: to proceed with the OTA operation. More...
 
(void) - cancelUpdate
 Attempts to cancel the update. More...
 
(void) - setPassword:
 Use this to set a password before beginning an update if you already have a password. More...
 

Protected Attributes

__strong CBPeripheral * _peripheral
 
float _upload_progress
 
ota_operation_t _operationInProgress
 
ota_step_t _ota_step
 

Properties

NSObject< BGX_OTA_Updater_Delegate > * delegate
 
ota_operation_t operationInProgress
 You may observe these properties to populate a user interface if desired. More...
 
ota_step_t ota_step
 
float upload_progress
 Indicates the progress of gbl upload. Pertinent only during ota_step_upload_with_response and ota_step_upload_no_response. More...
 

Method Documentation

◆ initWithPeripheral:bgx_device_uuid:()

- (id) initWithPeripheral: (CBPeripheral *)  peripheral
bgx_device_uuid: (NSString *)  bgx_device_id 

Initialize a BGX OTA instance for the specified BGX peripheral.

Parameters
peripheralThe BGX Peripheral to update.
bgx_device_idthe unique id of the device you are updating.
Returns
An initialized instance of BGX_OTA_Updater.

◆ updateFirmwareWithImageAtPath:withVersion:()

- (void) updateFirmwareWithImageAtPath: (NSString *)  path2FWImage
withVersion: (NSString *)  version 

Update the firmware using the specified image and bundle ID.

Parameters
path2FWImageThe path to the firmware image to be used for the update. The update will be finished when the opeartionInProgress is ota_firmware_update_complete. At that point, you can release the instances of the BGX_OTA_Updater.
versionThis can be one of three values: 'release', a specific version number, or nil. The value passed should match what you are trying to install. If you are installing the latest release from DMS, pass the string 'release'. If you are installing DMS firmware other than the latest release, then pass a version number. Pass nil if you are installing firmware from a source other than DMS or wish to suppress analytics.

◆ continueOTAWithPassword:()

- (void) continueOTAWithPassword: (NSString *)  password

If a password is required for an OTA operation to be performed or a previously supplied password fails (i.e., incorrect password), you may ask the user for a password and then call continueOTAWithPassword: to proceed with the OTA operation.

Parameters
passwordThe password for the OTA device.

◆ cancelUpdate()

- (void) cancelUpdate

Attempts to cancel the update.

The step will become ota_step_canceled and the operation is ota_no_operation_in_progress.

◆ setPassword:()

- (void) setPassword: (NSString *)  password

Use this to set a password before beginning an update if you already have a password.

If you do not know if a password is required, wait until you receive a password related error (i.e., state becomes ota_step_password_required or the ota_requires_password: delegate method is called.

Parameters
passwordThe password to use for the update (if a password is required).

Member Data Documentation

◆ _peripheral

- (__strong CBPeripheral*) _peripheral
protected

◆ _upload_progress

- (float) _upload_progress
protected

◆ _operationInProgress

- (ota_operation_t) _operationInProgress
protected

◆ _ota_step

- (ota_step_t) _ota_step
protected

Property Documentation

◆ delegate

- (NSObject<BGX_OTA_Updater_Delegate>*) delegate
readwritenonatomicweak

◆ operationInProgress

- (ota_operation_t) operationInProgress
readnonatomicassign

You may observe these properties to populate a user interface if desired.

◆ ota_step

- (ota_step_t) ota_step
readnonatomicassign

◆ upload_progress

- (float) upload_progress
readnonatomicassign

Indicates the progress of gbl upload. Pertinent only during ota_step_upload_with_response and ota_step_upload_no_response.

Enumeration Type Documentation

◆ ota_step_t

enum ota_step_t : int

This enum indicates the steps that occur during an OTA operation.

Enumerator
ota_step_no_ota 

no OTA update is in progress.

ota_step_init 

An OTA update has been started but no action has happened yet.

ota_step_scan 

Scanning for peripheral.

ota_step_connect 

Connecting to the BGX being updated.

ota_step_find_services 

Discovering services for the peripheral.

ota_step_find_characteristics 

Discovering characteristics for services.

ota_step_upload_no_response 

Performing an OTA update without write verification.

ota_step_upload_with_response 

Performing an OTA update with write verification.

ota_step_upload_finish 

Finished uploading gbl image. Performing finishing operations.

ota_step_end 

This value indicates that the update operation is at an end.

ota_step_error 

< An error has occurred during the OTA.

ota_step_password_required 

< A password is required in order for the OTA to proceed. Call continueOTAWithPassword.

ota_step_canceled 
ota_max_step 

all step values greater or equal to this value are defined as invalid.

◆ ota_operation_t

enum ota_operation_t : int

This enum describes the overall state of the BGX_OTA_Updater object.

Enumerator
ota_firmware_update_in_progress 

An OTA Firmware update is in progress.

ota_firmware_update_complete 

An OTA firmware update is complete.

ota_no_operation_in_progress 

No OTA update operation is in progress.

ota_max_operations 

all operation values greater or equal to this value are defined as invalid.