Impact Acquire SDK .NET
Public Member Functions | Static Public Member Functions | Public Attributes | Properties | List of all members
FirmwareUpdater Class Reference
Common

A class to perform a firmware update of a specific device. More...

Public Member Functions

 FirmwareUpdater (mv.impact.acquire.Device pDev, bool boForceOverideSameVersion, bool boForceDowngrade, bool boKeepUserSets, bool boForceBreakingChange)
 Creates a new mv.impact.acquire.FirmwareUpdater object.
 
virtual int onErasingFlash (int currentProgress_pc, double timeElapsed_s)
 This function will be called once the devices flash memory is erased.
 
virtual int onErrorMessage (double timeElapsed_s)
 This function will be called once a message is waiting to be passed to the user.
 
virtual int onHardResetRequired (int currentProgress_pc, double timeElapsed_s)
 This function will be called once the device reboots and a manual hard reset is required.
 
virtual int onLoadingUserSets (int currentProgress_pc, double timeElapsed_s)
 This function will be called when the settings of the device are written back after updating the firmware.
 
virtual int onRebooting (int currentProgress_pc, double timeElapsed_s)
 This function will be called once the device reboots to make sure the new firmware is applied to the device.
 
virtual int onSavingUserSets (int currentProgress_pc, double timeElapsed_s)
 This function will be called when the settings of the device are stored before updating the firmware.
 
virtual int onUnzippingFirmwareArchive (int currentProgress_pc, double timeElapsed_s)
 This function will be called once firmware archive (*.mvu) is unzipped to provide the correct firmware file.
 
virtual int onUpdatingBootProgrammer (int currentProgress_pc, double timeElapsed_s)
 The onUpdatingBootProgrammer-callback function which is called once the boot programmer of an mvBlueFOX3 camera is updated.
 
virtual int onUploadingImage (int currentProgress_pc, double timeElapsed_s)
 This function will be called once the actual firmware file is uploaded to the device's flash memory.
 
TDMR_ERROR update ()
 A function to start the firmware update process.
 
TDMR_ERROR update (String archivePath)
 A function to start the firmware update process.
 
TDMR_ERROR update (String archivePath, bool boUpdateDataAsNeeded)
 A function to start the firmware update process.
 

Static Public Member Functions

static TDMR_ERROR verifyFirmwareChecksum (Device pDev, String archivePath)
 A function to check the integrity of the firmware running on a device.
 
static TDMR_ERROR verifyFirmwareChecksum (Device pDev, String archivePath, out String statusMessage)
 A function to check the integrity of the firmware running on a device.
 

Public Attributes

PropertyI firmwareVersionToUpload = new PropertyI()
 An enumerated integer property containing a list of available firmware versions.
 

Properties

String statusMessage [get]
 Returns the current status from the status property.
 
double timeElapsed_s [get]
 A method to get the elapsed time in seconds since the update process has been started.
 

Detailed Description

A class to perform a firmware update of a specific device.

This class is intended to provide an ease of use possibility to update the firmware of specific devices. It is possible to specify the behavior of the class very detailed to make sure the update suits the users expectations. It is also possible to derive from this class and override various functions in order to get custom notifications e.g. to update a GUI application.

To start a firmware update for Balluff GenICam devices the following code will be sufficient:

// force the update even if the version of the mvu-file is the same as the one on the device
mv.impact.acquire.FirmwareUpdater fwUpdater = new FirmwareUpdater( pDev, true );
// specify the path to the mvu-file
string pathToArchive = "PATH_TO_MVU_FILE"
try
{
// start the whole update process
int FWUpdateResult = fwUpdater.update( pathToArchive );
Console.WriteLine( "Result of 'update' call: " + ImpactAcquireException.getErrorCodeAsString( FWUpdateResult ) + ".");
}
catch( ImpactAcquireException e )
{
Console.WriteLine( "An error occurred while updating the firmware of the device " + pDev.serial.read() + "(error code: " + e.errorCodeAsString + ").");
// reading out potential issues
Console.WriteLine( "Status: " + fwUpdater.statusMessage );
return 1;
}
mv.impact.acquire.EnumPropertyI
A template class to represent 32 bit integer properties and 32 bit enumerated integer properties.
Definition EnumPropertyI.cs:61
mv.impact.acquire.EnumPropertyI.read
T read()
Reads a value from a property.
Definition EnumPropertyI.cs:342
mv.impact.acquire.FirmwareUpdater
A class to perform a firmware update of a specific device.
Definition FirmwareUpdater.cs:129
mv.impact.acquire.ImpactAcquireException
An base class for exceptions generated by Impact Acquire.
Definition Exceptions.cs:9
mv.impact.acquire.ImpactAcquireException.getErrorCodeAsString
static String getErrorCodeAsString(int errorCode)
Returns a string representation of a error.
Definition Exceptions.cs:48

To start a firmware update for Balluff mvBlueFOX devices the following code will be sufficient:

mvIMPACT.acquire.FirmwareUpdater fwUpdater = new FirmwareUpdater( pDev );
// if necessary, a specific version for the update can be selected by using the firmwareVersionToUpload property
try
{
int FWUpdateResult = fwUpdater.update( );
Console.WriteLine( "Result of 'updateFirmware' call: " + ImpactAcquireException.getErrorCodeAsString( FWUpdateResult ) + ".");
}
catch( const ImpactAcquireException e )
{
Console.WriteLine( "An error occurred while updating the firmware of the device " + pDev.serial.read() + "(error code: " + e.errorCodeAsString + ").");
return 1;
}

A more custom behavior can be accomplished by deriving from the mv.impact.acquire.FirmwareUpdater class and re-implementing the various notification functions:

public class MyFWU : mv.impact.acquire.FirmwareUpdater
{
public MyFWU(Device pDev, bool boOverride) : base(pDev, boOverride, true, true, true) { }
public override int onErrorMessage( double progressTimer)
{
Console.WriteLine("Info: {0} @ {1} s", statusMessage, progressTimer);
return (int)TFirmwareUpdateAction.fuaContinue;
}
public override int onErasingFlash(int currentProgress_pc, double timeElapsed)
{
Console.WriteLine("Erasing - Update progress: {0}, time: {1:N2} s", currentProgress_pc, timeElapsed);
return (int)TFirmwareUpdateAction.fuaContinue;
}
public override int onUnzippingFirmwareArchive(int currentProgress_pc, double timeElapsed)
{
Console.WriteLine("Unzipping firmware archive - Update progress: {0}, time: {1:N2} s", currentProgress_pc, timeElapsed);
return (int)TFirmwareUpdateAction.fuaContinue;
}
public override int onUpdatingBootProgrammer(int currentProgress_pc, double timeElapsed)
{
Console.WriteLine("Updating boot programmer - Update progress: {0}, time: {1:N2} s", currentProgress_pc, timeElapsed);
return (int)TFirmwareUpdateAction.fuaContinue;
}
public override int onUploadingImage(int currentProgress_pc, double timeElapsed)
{
Console.WriteLine("Uploading - Update progress: {0}, time: {1:N2} s", currentProgress_pc, timeElapsed);
return (int)TFirmwareUpdateAction.fuaContinue;
}
public override int onRebooting(int currentProgress_pc, double timeElapsed)
{
Console.WriteLine("Rebooting - Update progress: {0}, time: {1:N2} s", currentProgress_pc, timeElapsed);
return (int)TFirmwareUpdateAction.fuaContinue;
}
public override int onHardResetRequired(int currentProgress_pc, double timeElapsed)
{
Console.WriteLine("Rebooting - Update progress: {0}, time: {1:N2} s", currentProgress_pc, timeElapsed);
Console.WriteLine("Manual hard reset required.");
Console.WriteLine("Status message: {0}", statusMessage );
return (int)TFirmwareUpdateAction.fuaCancel;
}
public override int onSavingUserSets(int currentProgress_pc, double timeElapsed)
{
Console.WriteLine("Saving sets - Update progress: {0}, time: {1:N2} s", currentProgress_pc, timeElapsed);
return (int)TFirmwareUpdateAction.fuaContinue;
}
public override int onLoadingUserSets(int currentProgress_pc, double timeElapsed)
{
Console.WriteLine("Loading sets - Update progress: {0}, time: {1:N2} s", currentProgress_pc, timeElapsed);
return (int)TFirmwareUpdateAction.fuaContinue;
}
}
mv.impact.acquire.Device
This class and its functions represent an actual device detected by this interface in the current sys...
Definition Device.cs:91
mv.impact.acquire.TFirmwareUpdateAction
TFirmwareUpdateAction
Definition mvDriverBaseEnums.cs:2779
mv
Definition Enumerations.cs:2
Note
The following device families are currently supported by this API:
  • GenICam compliant Balluff/MATRIX VISION devices
    • BVS CA-GX0 (mvBlueCOUGAR-X)
    • BVS CA-GX2 (mvBlueCOUGAR-XD)
    • BVS CA-GT (mvBlueCOUGAR-XT)
    • BVS CA-SF (mvBlueFOX3)
    • BVS CA-BN (mvBlueNAOS)
  • Other Balluff/MATRIX VISION devices
    • BVS CA-MLC / BVS CA-IGC (mvBlueFOX-MLC/IGC)
    • mvBlueFOX
Attention
  • Do not unplug the device during the update procedure!
  • Once the firmwareUpdate method call returns an error read the mv.impact.acquire.FirmwareUpdater.statusMessage property. It will return useful information about the current status (including issues) of the update procedure.
  • The actual mv.impact.acquire.FirmwareUpdater.update method did get an additional parameter in version 2.48.0 of this SDK! Make sure you understand the intention of this parameter! When using older versions of this API make sure not attempting to use a device without closing, updating the device list and re-opening it again. Undefined behavior might be the result when not doing so!
Since
2.41.0

Constructor & Destructor Documentation

◆ FirmwareUpdater()

FirmwareUpdater ( mv::impact::acquire::Device pDev,
bool boForceOverideSameVersion,
bool boForceDowngrade,
bool boKeepUserSets,
bool boForceBreakingChange )
inline

Creates a new mv.impact.acquire.FirmwareUpdater object.

Parameters
[in]pDevA pointer to a mv.impact.acquire.Device object obtained from a mv.impact.acquire.DeviceManager object.
[in]boForceOverideSameVersionA boolean value to configure if flashing with same version is allowed.
[in]boForceDowngradeA boolean value to configure if flashing with an older version is allowed.
[in]boKeepUserSetsA boolean value which defines if the user sets of the device will be kept or will be deleted during the update.
[in]boForceBreakingChangeA boolean value to configure if flashing with a version that introduces an interface change is allowed. Setting this value to true will also update a device which after the update might have a different interface. See documentation for additional information about breaking changes in firmware versions(there are not too many)!

Member Function Documentation

◆ onErasingFlash()

virtual int onErasingFlash ( int currentProgress_pc,
double timeElapsed_s )
inlinevirtual

This function will be called once the devices flash memory is erased.

Re-implement this function in a derived class in order to implement a custom behaviour.

Note
Only some device types require this step so this callback might not be called for every device type.
Returns
Parameters
[in]currentProgress_pcThe current progress of the erase operation (in percent).
[in]timeElapsed_sThe total time elapsed since starting the update process (in seconds).

◆ onErrorMessage()

virtual int onErrorMessage ( double timeElapsed_s)
inlinevirtual

This function will be called once a message is waiting to be passed to the user.

Re-implement this function in a derived class in order to implement a custom behaviour.

Returns
Parameters
[in]timeElapsed_sThe total time elapsed since starting the update process (in seconds).

◆ onHardResetRequired()

virtual int onHardResetRequired ( int currentProgress_pc,
double timeElapsed_s )
inlinevirtual

This function will be called once the device reboots and a manual hard reset is required.

Re-implement this function in a derived class in order to implement a custom behaviour.

Note
If this function is called, a power cycle is inevitable. Otherwise the new firmware may be broken. The default is to stop the update at this point, so that the user can manually disconnect the power source.
Returns
Parameters
[in]currentProgress_pcThe current progress of the reboot operation (in percent).
[in]timeElapsed_sThe total time elapsed since starting the update process (in seconds).

◆ onLoadingUserSets()

virtual int onLoadingUserSets ( int currentProgress_pc,
double timeElapsed_s )
inlinevirtual

This function will be called when the settings of the device are written back after updating the firmware.

Re-implement this function in a derived class in order to implement a custom behaviour.

This callback will only be called when user sets shall be available after the update. This can be specified by setting the boKeepUserSets flag upon construction of this object.

Returns
Parameters
[in]currentProgress_pcThe current progress of the load operation (in percent).
[in]timeElapsed_sThe total time elapsed since starting the update process (in seconds).

◆ onRebooting()

virtual int onRebooting ( int currentProgress_pc,
double timeElapsed_s )
inlinevirtual

This function will be called once the device reboots to make sure the new firmware is applied to the device.

Re-implement this function in a derived class in order to implement a custom behaviour.

Note
Returning mv.impact.acquire.TFirmwareUpdateAction.fuaCancel on this callback will stop the upgrade process without rebooting the device. However, a new firmware is not active until a reboot or hard reset has been performed.
Returns
Parameters
[in]currentProgress_pcThe current progress of the reboot operation (in percent).
[in]timeElapsed_sThe total time elapsed since starting the update process (in seconds).

◆ onSavingUserSets()

virtual int onSavingUserSets ( int currentProgress_pc,
double timeElapsed_s )
inlinevirtual

This function will be called when the settings of the device are stored before updating the firmware.

Re-implement this function in a derived class in order to implement a custom behaviour.

This callback will only be called when user sets shall be available after the update. This can be specified by setting the boKeepUserSets flag upon construction of this object.

Returns
Parameters
[in]currentProgress_pcThe current progress of the save operation (in percent).
[in]timeElapsed_sThe total time elapsed since starting the update process (in seconds).

◆ onUnzippingFirmwareArchive()

virtual int onUnzippingFirmwareArchive ( int currentProgress_pc,
double timeElapsed_s )
inlinevirtual

This function will be called once firmware archive (*.mvu) is unzipped to provide the correct firmware file.

Re-implement this function in a derived class in order to implement a custom behaviour.

Returns
Parameters
[in]currentProgress_pcThe current progress of the unzip operation (in percent).
[in]timeElapsed_sThe total time elapsed since starting the update process (in seconds).

◆ onUpdatingBootProgrammer()

virtual int onUpdatingBootProgrammer ( int currentProgress_pc,
double timeElapsed_s )
inlinevirtual

The onUpdatingBootProgrammer-callback function which is called once the boot programmer of an mvBlueFOX3 camera is updated.

Re-implement this function in a derived class in order to get the desired behaviour.

Note
  • Only mvBlueFOX3 cameras require this step so this callback might not be called in case of different device types.
  • BootProgrammer updates won't be necessary often, so this callback will not apply in every firmware update process.
Returns
Parameters
[in]currentProgress_pcThe current progress of the update operation (in percent).
[in]timeElapsed_sThe total time elapsed since starting the update process (in seconds).

◆ onUploadingImage()

virtual int onUploadingImage ( int currentProgress_pc,
double timeElapsed_s )
inlinevirtual

This function will be called once the actual firmware file is uploaded to the device's flash memory.

Re-implement this function in a derived class in order to implement a custom behaviour.

Note
  • Depending on the device type this step might take a few seconds up to a few minutes.
  • The callback will be called several times during the upload.
  • Each time there was a progress of 5 percent this callback will be called.
Returns
Parameters
[in]currentProgress_pcThe current progress of the upload operation (in percent).
[in]timeElapsed_sThe total time elapsed since starting the update process (in seconds).

◆ update() [1/3]

TDMR_ERROR update ( )
inline

A function to start the firmware update process.

This function is intended to be used to update Balluff devices.

Note
  • Once this function returns, the device will be closed! All objects previously created using the mv.impact.acquire.Device pointer must be recreated then.
Returns

◆ update() [2/3]

TDMR_ERROR update ( String archivePath)
inline

A function to start the firmware update process.

This function is intended to be used to update Balluff devices.

Note
  • Once this function returns, the device will be closed! All objects previously created using the mv.impact.acquire.Device pointer must be recreated then.
  • For mvBlueFOX device this function needs to be called without passing any parameters to the function!
Returns
Parameters
[in]archivePathPath to the file which should be used to update the device. Can be empty if no update archives are needed for the device.

◆ update() [3/3]

TDMR_ERROR update ( String archivePath,
bool boUpdateDataAsNeeded )
inline

A function to start the firmware update process.

This function is intended to be used to update Balluff devices.

Note
  • Once this function returns, the device will be closed! All objects previously created using the mv.impact.acquire.Device pointer must be recreated then.
  • For mvBlueFOX device this function needs to be called without passing any parameters to the function!
Returns
Parameters
[in]archivePathPath to the file which should be used to update the device. Can be empty if no update archives are needed for the device.
[in]boUpdateDataAsNeededCan be set to false in order to save time when updating multiple devices in one go. Please note that as soon as at least one GenICam device is part of these multiple devices mv.impact.acquire.DeviceManager.updateDeviceList must be called before any of those GenICam devices can be used again!

◆ verifyFirmwareChecksum() [1/2]

static TDMR_ERROR verifyFirmwareChecksum ( Device pDev,
String archivePath )
inlinestatic

A function to check the integrity of the firmware running on a device.

This function is intended to be used to check the firmware integrity of Balluff devices only. Most Balluff devices are capable of calculating a hash from the firmware image which is currently running on the device. In addition to that firmware archives provided by Balluff contain hashes for all the firmware images contained in the update archive. Comparing these 2 hashes will provide additional security when an application wants to make sure that the firmware running on the device is undamaged.

Note
  • When calling this function, the firmware archive path passed to it must contain the exact same firmware that is running on the device.
  • After applying a firmware update the device must be closed and reopened before this function can be called.
  • This feature is currently only available for Balluff GenICam compliant devices.
  • Once this function returns, the device will be closed! All objects previously created using the mvIMPACT::acquire::Device pointer must be recreated then.
Since
2.47.0
Returns
Parameters
[in]pDevA pointer to a mvIMPACT::acquire::Device object obtained from a mvIMPACT::acquire::DeviceManager object.
[in]archivePathPath to the file which should be used to compare the firmware checksum from with the firmware currently running on the device.

◆ verifyFirmwareChecksum() [2/2]

static TDMR_ERROR verifyFirmwareChecksum ( Device pDev,
String archivePath,
out String statusMessage )
inlinestatic

A function to check the integrity of the firmware running on a device.

This function is intended to be used to check the firmware integrity of Balluff devices only. Most Balluff devices are capable of calculating a hash from the firmware image which is currently running on the device. In addition to that firmware archives provided by Balluff contain hashes for all the firmware images contained in the update archive. Comparing these 2 hashes will provide additional security when an application wants to make sure that the firmware running on the device is undamaged.

Note
  • When calling this function, the firmware archive path passed to it must contain the exact same firmware that is running on the device.
  • This feature is currently only available for Balluff GenICam compliant devices.
  • Once this function returns, the device will be closed! All objects previously created using the mvIMPACT::acquire::Device pointer must be recreated then.
Since
2.47.0
Returns
Parameters
[in]pDevA pointer to a mvIMPACT::acquire::Device object obtained from a mvIMPACT::acquire::DeviceManager object.
[in]archivePathPath to the file which should be used to compare the firmware checksum from with the firmware currently running on the device.
[out]statusMessageA string receiving additional information about the outcome of the operation.

Member Data Documentation

◆ firmwareVersionToUpload

PropertyI firmwareVersionToUpload = new PropertyI()

An enumerated integer property containing a list of available firmware versions.

Note
This feature currently is only available for mvBlueFOX devices since here the firmware is part of the driver library. So no additional archive is needed, but the desired firmware version to upload into the device's non-volatile memory can be selected by writing to this property before calling the mv.impact.acquire.FirmwareUpdater.update function.

Property Documentation

◆ statusMessage

String statusMessage
get

Returns the current status from the status property.

◆ timeElapsed_s

double timeElapsed_s
get

A method to get the elapsed time in seconds since the update process has been started.

Returns
The time elapsed since the firmware update currently running has been started.