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
peripheral The BGX Peripheral to update.
bgx_device_id the 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
path2FWImage The 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 .
version This 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
password The 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
password The 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
read write nonatomic weak

◆ operationInProgress

- ( ota_operation_t ) operationInProgress
read nonatomic assign

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

◆ ota_step

- ( ota_step_t ) ota_step
read nonatomic assign

◆ upload_progress

- (float) upload_progress
read nonatomic assign

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.