mvIMPACT Acquire SDK C++
FirmwareUpdater Class Reference

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

Public Member Functions

 FirmwareUpdater (mvIMPACT::acquire::Device *pDev, bool boForceOverideSameVersion=false, bool boForceDowngrade=false, bool boKeepUserSets=true, bool boForceBreakingChange=false)
 Creates a new mvIMPACT::acquire::labs::FirmwareUpdater object. More...
 
double getTimeElapsed (void) const
 A method to receive the time in seconds since the update process has been started. More...
 
virtual int onErasingFlash (const int currentProgress_pc, const double timeElapsed_s) const
 This function will be called once the devices flash memory is erased. More...
 
virtual int onErrorMessage (const double timeElapsed_s) const
 This function will be called once a message is waiting to be passed to the user. More...
 
virtual int onLoadingUserSets (const int currentProgress_pc, const double timeElapsed_s) const
 This function will be called when the settings of the device are written back after updating the firmware. More...
 
virtual int onRebooting (const int currentProgress_pc, const double timeElapsed_s) const
 This function will be called once the device reboots to make sure the new firmware is applied to the device. More...
 
virtual int onSavingUserSets (const int currentProgress_pc, const double timeElapsed_s) const
 This function will be called when the settings of the device are stored before updating the firmware. More...
 
virtual int onUnzippingFirmwareArchive (const int currentProgress_pc, const double timeElapsed_s) const
 This function will be called once firmware archive (*.mvu) is unzipped to provide the correct firmware file. More...
 
virtual int onUpdatingBootProgrammer (const int currentProgress_pc, const double timeElapsed_s) const
 This function will be called once the boot programmer of an mvBlueFOX3 camera is updated. More...
 
virtual int onUploadingImage (const int currentProgress_pc, const double timeElapsed_s) const
 This function will be called once the actual firmware file is uploaded to the device's flash memory. More...
 
std::string statusMessage (void) const
 Returns the current status from the status property. More...
 
TDMR_ERROR update (const std::string &archivePath="")
 A function to start the firmware update process. More...
 
virtual ~FirmwareUpdater ()
 

Public Attributes

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

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 MATRIX VISION 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
try
{
const string pathToFirmwareArchive( "someArchive.mvu" );
// start the whole update process
const int FWUpdateResult = fwUpdater.update( pathToFirmwareArchive );
cout << "Result of 'updateFirmware' call: " << ImpactAcquireException::getErrorCodeAsString( FWUpdateResult ) << "." << endl;
}
catch( const ImpactAcquireException& e )
{
cout << "An error occurred while updating the firmware of the device " << pDev->serial.read()
<< "(error code: " << e.getErrorCodeAsString() << ").";
// reading out potential issues
cout << "Status: " << fwUpdater.statusMessage() << endl;
return 1;
}
std::string getErrorCodeAsString(void) const
Returns a string representation of the error associated with the exception.
Definition: mvIMPACT_acquire.h:280
A class to perform a firmware update of a specific device.
Definition: mvIMPACT_acquire.h:24190

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

// if necessary, a specific version for the update can be selected by using the firmwareVersionToUpload property
try
{
const int FWUpdateResult = fwUpdater.update();
cout << "Result of 'updateFirmware' call: " << ImpactAcquireException::getErrorCodeAsString( FWUpdateResult ) << "." << endl;
}
catch( const ImpactAcquireException& e )
{
cout << "An error occurred while updating the firmware of the device " << pDev->serial.read()
<< "(error code: " << e.getErrorCodeAsString() << ").";
return 1;
}

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

//-----------------------------------------------------------------------------
class MyFirmwareUpdater : public mvIMPACT::acquire::labs::FirmwareUpdater
//-----------------------------------------------------------------------------
{
public:
explicit MyFirmwareUpdater( mvIMPACT::acquire::Device* pDev ) : mvIMPACT::acquire::labs::FirmwareUpdater( pDev ) {}
virtual int onErrorMessage( const double timeElapsed_s ) const
{
printf( "Error: %s @ %f [s]\n", statusMessage().c_str(), timeElapsed_s );
return fuaCancel;
}
virtual int onErasingFlash( const int currentProgress_pc, const double timeElapsed_s ) const
{
printf( "Erasing - Update progress: %d, time %f [s]\n", currentProgress_pc, timeElapsed_s );
return fuaContinue;
}
virtual int onUnzippingFirmwareArchive( const int currentProgress_pc, const double timeElapsed_s ) const
{
printf( "Unzipping firmware archive - Update progress: %d, time %f [s]\n", currentProgress_pc, timeElapsed_s );
return fuaContinue;
}
virtual int onUpdatingBootProgrammer( const int currentProgress_pc, const double timeElapsed_s ) const
{
printf( "Updating boot programmer - Update progress: %, time %f [s]\n", currentProgress_pc, timeElapsed_s );
return fuaContinue;
}
virtual int onUploadingImage( const int currentProgress_pc, const double timeElapsed_s ) const
{
printf( "Uploading - Update progress: %d, time %f [s]\n", currentProgress_pc, timeElapsed_s );
return fuaContinue;
}
virtual int onSavingUserSets( const int currentProgress_pc, const double timeElapsed_s ) const
{
printf( "Saving sets - Update progress: %d, time %f [s]\n", currentProgress_pc, timeElapsed_s );
return fuaContinue;
}
virtual int onLoadingUserSets( const int currentProgress_pc, const double timeElapsed_s ) const
{
printf( "Loading sets - Update progress: %d, time %f [s]\n", currentProgress_pc, timeElapsed_s );
return fuaContinue;
}
virtual int onRebooting( const int currentProgress_pc, const double timeElapsed_s ) const
{
printf( "Rebooting - Update progress: %d, time %f [s]\n", currentProgress_pc, timeElapsed_s );
return fuaContinue;
}
};
This class and its functions represent an actual device detected by this interface in the current sys...
Definition: mvIMPACT_acquire.h:5938
virtual int onErasingFlash(const int currentProgress_pc, const double timeElapsed_s) const
This function will be called once the devices flash memory is erased.
Definition: mvIMPACT_acquire.h:24344
virtual int onUploadingImage(const int currentProgress_pc, const double timeElapsed_s) const
This function will be called once the actual firmware file is uploaded to the device's flash memory.
Definition: mvIMPACT_acquire.h:24407
std::string statusMessage(void) const
Returns the current status from the status property.
Definition: mvIMPACT_acquire.h:24504
virtual int onUpdatingBootProgrammer(const int currentProgress_pc, const double timeElapsed_s) const
This function will be called once the boot programmer of an mvBlueFOX3 camera is updated.
Definition: mvIMPACT_acquire.h:24384
virtual int onRebooting(const int currentProgress_pc, const double timeElapsed_s) const
This function will be called once the device reboots to make sure the new firmware is applied to the ...
Definition: mvIMPACT_acquire.h:24425
FirmwareUpdater(mvIMPACT::acquire::Device *pDev, bool boForceOverideSameVersion=false, bool boForceDowngrade=false, bool boKeepUserSets=true, bool boForceBreakingChange=false)
Creates a new mvIMPACT::acquire::labs::FirmwareUpdater object.
Definition: mvIMPACT_acquire.h:24265
virtual int onErrorMessage(const double timeElapsed_s) const
This function will be called once a message is waiting to be passed to the user.
Definition: mvIMPACT_acquire.h:24327
virtual int onLoadingUserSets(const int currentProgress_pc, const double timeElapsed_s) const
This function will be called when the settings of the device are written back after updating the firm...
Definition: mvIMPACT_acquire.h:24465
virtual int onSavingUserSets(const int currentProgress_pc, const double timeElapsed_s) const
This function will be called when the settings of the device are stored before updating the firmware.
Definition: mvIMPACT_acquire.h:24445
virtual int onUnzippingFirmwareArchive(const int currentProgress_pc, const double timeElapsed_s) const
This function will be called once firmware archive (*.mvu) is unzipped to provide the correct firmwar...
Definition: mvIMPACT_acquire.h:24362
@ fuaContinue
The default return value to tell the driver to continue processing the firmware update.
Definition: mvDriverBaseEnums.h:2881
@ fuaCancel
Return this value to request the driver to terminate an ongoing firmware update as soon as possible.
Definition: mvDriverBaseEnums.h:2883
Definition: mvIMPACT_acquire.h:154
Note
Currently supported are the following device families:
GenICam compliant MATRIX VISION devices
  • mvBlueCOUGAR-X
  • mvBlueCOUGAR-XD
  • mvBlueCOUGAR-XT
  • mvBlueFOX3
Other MATRIX VISION devices
  • mvBlueFOX
  • mvBlueFOX-MLC/IGC
Attention
It is important not to unplug the device during the update procedure.
Once the firmwareUpdate method call returns an error call the mvIMPACT::acquire::labs::FirmwareUpdater::statusMessage function. It will return useful information about the current status (including issues) during the update procedure.
Since
2.41.0

Constructor & Destructor Documentation

◆ FirmwareUpdater()

FirmwareUpdater ( mvIMPACT::acquire::Device pDev,
bool  boForceOverideSameVersion = false,
bool  boForceDowngrade = false,
bool  boKeepUserSets = true,
bool  boForceBreakingChange = false 
)
inlineexplicit

Creates a new mvIMPACT::acquire::labs::FirmwareUpdater object.

Parameters
[in]pDevA pointer to a mvIMPACT::acquire::Device object obtained from a mvIMPACT::acquire::DeviceManager object.
[in]boForceOverideSameVersionA boolean value which defines if updates using the same version as installed on the camera should be allowed.
[in]boForceDowngradeA boolean value which defines if updates using an older version as installed on the camera should be 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 which defines if updates to versions which will deliver interface breaking changes will be 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)!

◆ ~FirmwareUpdater()

virtual ~FirmwareUpdater ( )
inlinevirtual

Member Function Documentation

◆ getTimeElapsed()

double getTimeElapsed ( void  ) const
inline

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

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

◆ onErasingFlash()

virtual int onErasingFlash ( const int  currentProgress_pc,
const double  timeElapsed_s 
) const
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 ( const double  timeElapsed_s) const
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).

◆ onLoadingUserSets()

virtual int onLoadingUserSets ( const int  currentProgress_pc,
const double  timeElapsed_s 
) const
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 ( const int  currentProgress_pc,
const double  timeElapsed_s 
) const
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.

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 ( const int  currentProgress_pc,
const double  timeElapsed_s 
) const
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 store operation (in percent).
[in]timeElapsed_sThe total time elapsed since starting the update process (in seconds).

◆ onUnzippingFirmwareArchive()

virtual int onUnzippingFirmwareArchive ( const int  currentProgress_pc,
const double  timeElapsed_s 
) const
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 ( const int  currentProgress_pc,
const double  timeElapsed_s 
) const
inlinevirtual

This function will be called once the boot programmer of an mvBlueFOX3 camera is updated.

Re-implement this function in a derived class in order to implement a custom 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 ( const int  currentProgress_pc,
const double  timeElapsed_s 
) const
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).

◆ statusMessage()

std::string statusMessage ( void  ) const
inline

Returns the current status from the status property.

◆ update()

TDMR_ERROR update ( const std::string &  archivePath = "")
inline

A function to start the firmware update process.

This function is intended to be used to update MATRIX VISION devices.

Note
The function needs to be called without any additional parameter in case of mvBlueFOX devices.
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.

Member Data Documentation

◆ firmwareVersionToUpload

PropertyI firmwareVersionToUpload

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 mvIMPACT::acquire::labs::FirmwareUpdater::update function.

The documentation for this class was generated from the following file: