File

src/interfaces/IDeviceUpgrader.ts

Description

Interface used to perform software upgrades.

Index

Methods

Methods

init
init(opts: UpgradeOpts)

Initializes the upgrader with all the necessary upgrade options such as filepath, verbose level etc.

Parameters :
Name Type Optional Description
opts UpgradeOpts No

Upgrade options

Returns : void
on
on(message: string, callback: any)

EventEmitter on listener

Parameters :
Name Type Optional Description
message string No

The message use to setup the listener for

callback any No

A callback used to perform actions on the caught event

Returns : any
once
once(message: string, callback: any)

EventEmitter once listener

Parameters :
Name Type Optional Description
message string No

The message use to setup the listener for

callback any No

A callback used to perform actions on the caught event

Returns : any
removeListener
removeListener(message: string, callback: any)

EventEmitter removeListener

Parameters :
Name Type Optional Description
message string No

The message use to remove the listener for

callback any No
Returns : any
start
start()

Initiate the upgrade process on the target device. Use event handlers to track the upgrade progress.

Returns : Promise<void>
upgradeIsValid
upgradeIsValid()

Verifies if camera performed a valid upgrade

Returns : Promise<boolean>

A Promise that resolves when upgrade is valid

Upgrader Usage

In order to perform a software upgarde on the camera, this interface should be used. Please note that there is a convenience function in the IDeviceManager for performing the upgrade, but if you want to implement your own handler then this documentation needs to be reviewed.

Each upgrader class (BoxfishUpgrader, HuddlyGoUpgrader, AceUPgrader) requires some options that should be provided when initializing it:

const upgrader = cameraManager.getUpgrader();
const upgradeOptions = {
  file: fs.readSync('/path/to/firmware/image'),
  bootTimeout: 60 // Default is 60 seconds
  verboseStatusLog: true // Default is true
}; // See the `IUpgraderOpts` for explanation of each option

// Initialize upgrader
upgrader.init(upgraderOptions);

After you have initialized the upgrader, then you can proceed with starting the upgrade process.

// Start the upgrade process
upgrader.start();

During the upgrade process, the upgrader class will emit the following events:

Event Description
UPGRADE_START Fired when upgrade is initiated.
UPGRADE_COMPLETE Fired when upgrade is completed successfully.
UPGRADE_FAILED Fired when something fails during upgrade. The handler contains the error trace of the upgrade failure.
TIMEOUT Fired when the camera does not come back up after reboot (reboot is necessary to complete the upgrade sequence.
UPGRADE_PROGRESS Fired when constantly during the upgrade process providing with information on how far the upgrade process is from completion.

The events above can be used as shown below:


const onUpgradeStartHandler = () => {
  // Do something.... Inform your system that upgrade has started
  upgrader.removeListener('UPGRADE_PROGRESS', onUpgradeProgressHandler);
}

const onUpgradeFailedHandler = (e) => {
  // Upgrade has failed. Print error log to debug the reason
  console.error(e);
  upgrader.removeListener('UPGRADE_PROGRESS', onUpgradeProgressHandler);
}

const onUpgradeCompleteHandler = () => {
  // Hurrayyy! Sucessfully upgraded your Huddly camera
  upgrader.removeListener('UPGRADE_PROGRESS', onUpgradeProgressHandler);
}

const onUpgradeTimeoutHandler = () => {
  // Ups! Looks like the camera did not come back up after rebooting during upgrade.
  // This also means that the new software that was loaded into the camera will be discarded.
  // Try to initiate upgrade again.
  upgrader.removeListener('UPGRADE_PROGRESS', onUpgradeProgressHandler);
}

const onUpgradeProgressHandler = (progress) => {
  // The progress object contains the following information:
  /*
   * status: A string representation of how far the upgrade progress has come (ex. Uploading firmware on the device)
   * progress: A numerical value representing the percentage of upgrade completion (ex 30)
   */
  console.log(`Upgrade Progress: ${progress.progress} %`)
}

upgrader.once('UPGRADE_START', onUpgradeStartHandler);
upgrader.once('UPGRADE_FAILED', onUpgradeFailedHandler);
upgrader.once('UPGRADE_COMPLETE', onUpgradeCompleteHandler);
upgrader.once('TIMEOUT', onUpgradeTimeoutHandler);
upgrader.on('UPGRADE_PROGRESS', onUpgradeProgressHandler);

// Finally start the upgrade after having setup all the listeners
upgrader.start();

import UpgradeOpts from './IUpgradeOpts';

/**
 * Interface used to perform software upgrades.
 *
 * @interface IDeviceUpgrader
 */
export default interface IDeviceUpgrader {
  /**
   * Initializes the upgrader with all the necessary upgrade options such as filepath,
   * verbose level etc.
   *
   * @param {*} opts Upgrade options
   * @memberof IDeviceUpgrader
   */
  init(opts: UpgradeOpts): void;

  /**
   * Initiate the upgrade process on the target device.
   * Use event handlers to track the upgrade progress.
   *
   * @memberof IDeviceUpgrader
   */
  start(): Promise<void>;

  /**
   * EventEmitter `on` listener
   *
   * @param {string} message The message use to setup the listener for
   * @param {*} callback A callback used to perform actions on the caught event
   * @memberof Transportable
   */
  on(message: string, callback: any);

  /**
   * EventEmitter `once` listener
   *
   * @param {string} message The message use to setup the listener for
   * @param {*} callback A callback used to perform actions on the caught event
   * @memberof Transportable
   */
  once(message: string, callback: any);

  /**
   * EventEmitter `removeListener`
   *
   * @param {string} message The message use to remove  the listener for
   * @param {*} callback
   * @memberof Transportable
   */
  removeListener(message: string, callback: any);

  /**
   * Verifies if camera performed a valid upgrade
   *
   * @returns {Promise<booleean>} A `Promise` that resolves when upgrade is valid
   * @memberof IDeviceUpgrader
   */
  upgradeIsValid(): Promise<boolean>;
}

results matching ""

    No results matching ""