FirmwareUpdater Class Reference

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

#include <mvIMPACT_acquire.h>

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::FirmwareUpdater object.
double	getTimeElapsed (void) const
	A method to receive the time in seconds since the update process has been started.
virtual int	onErasingFlash (const int currentProgress_pc, const double timeElapsed_s) const
	This function will be called once the devices flash memory is erased.
virtual int	onErrorMessage (const double timeElapsed_s) const
	This function will be called once a message is waiting to be passed to the user.
virtual int	onHardResetRequired (const int currentProgress_pc, const double timeElapsed_s) const
	This function will be called once the device reboots and a manual hard reset is required.
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.
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.
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.
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.
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.
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.
std::string	statusMessage (void) const
	Returns the current status from the status property.
TDMR_ERROR	update (const std::string &archivePath="", const bool boUpdateDataAsNeeded=true)
	A function to start the firmware update process.
virtual	~FirmwareUpdater ()

Static Public Member Functions
static TDMR_ERROR	verifyFirmwareChecksum (Device *pDev, const std::string &archivePath, std::string *pStatusMessage=0)
	A function to check the integrity of the firmware running on a device.

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

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
mvIMPACT::acquire::FirmwareUpdater fwUpdater( pDev, true );
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;
}

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

mvIMPACT::acquire::FirmwareUpdater fwUpdater( pDev );
// 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::FirmwareUpdater class and re-implementing the various notification functions:

//-----------------------------------------------------------------------------
class MyFirmwareUpdater : public mvIMPACT::acquire::FirmwareUpdater
//-----------------------------------------------------------------------------
{
public:
    explicit MyFirmwareUpdater( mvIMPACT::acquire::Device* pDev, bool boForceOverideSameVersion = false, bool boForceDowngrade = false, bool boForceSameVersion = false, bool boForceBreakingChange = false ) : mvIMPACT::acquire::FirmwareUpdater( pDev, boForceOverideSameVersion, boForceDowngrade, boForceSameVersion, boForceBreakingChange ) {}
    int onErrorMessage( const double timeElapsed_s ) const override
    {
        cout << "Error: " << statusMessage() << "@" << timeElapsed_s << " s" << endl;
        return fuaCancel;
    }
    int onErasingFlash( const int currentProgress_pc, const double timeElapsed_s ) const override
    {
        cout << "Erasing - Update progress: " << currentProgress_pc << ", time " << timeElapsed_s << " s" << endl;
        return fuaContinue;
    }
    int onUnzippingFirmwareArchive( const int currentProgress_pc, const double timeElapsed_s ) const override
    {
        cout << "Unzipping firmware archive - Update progress: " << currentProgress_pc << ", time " << timeElapsed_s << " s" << endl;
        return fuaContinue;
    }
    int onUpdatingBootProgrammer( const int currentProgress_pc, const double timeElapsed_s ) const override
    {
        cout << "Updating boot programmer - Update progress: " << currentProgress_pc << ", time " << timeElapsed_s << " s" << endl;
        return fuaContinue;
    }
    int onUploadingImage( const int currentProgress_pc, const double timeElapsed_s ) const override
    {
        cout << "Uploading - Update progress: " << currentProgress_pc << ", time " << timeElapsed_s << " s" << endl;
        return fuaContinue;
    }
    int onRebooting( const int currentProgress_pc, const double timeElapsed_s ) const override
    {
        cout << "Rebooting - Update progress: " << currentProgress_pc << ", time " << timeElapsed_s << " s" << endl;
        return fuaContinue;
    }
    int onHardResetRequired( const int currentProgress_pc, const double timeElapsed_s ) const override
    {
        cout << "Rebooting - Update progress: " << currentProgress_pc << ", time " << timeElapsed_s << " s" << endl << "Manual hard reset required." << endl;
        return fuaCancel;
    }
    int onSavingUserSets( const int currentProgress_pc, const double timeElapsed_s ) const override
    {
        cout << "Saving sets - Update progress: " << currentProgress_pc << ", time " << timeElapsed_s << " s" << endl;
        return fuaContinue;
    }
    int onLoadingUserSets( const int currentProgress_pc, const double timeElapsed_s ) const override
    {
        cout << "Loading sets - Update progress: " << currentProgress_pc << ", time " << timeElapsed_s << " s" << endl;
        return fuaContinue;
    }
};

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 call the mvIMPACT::acquire::FirmwareUpdater::statusMessage function. It will return useful information about the current status (including issues) of the update procedure.
• The actual mvIMPACT::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

Examples

FirmwareUpdate.cpp.

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::FirmwareUpdater object.

Parameters

[in]	pDev	A pointer to a mvIMPACT::acquire::Device object obtained from a mvIMPACT::acquire::DeviceManager object.
[in]	boForceOverideSameVersion	A boolean value which defines if updates using the same version as installed on the camera should be allowed.
[in]	boForceDowngrade	A boolean value which defines if updates using an older version as installed on the camera should be allowed.
[in]	boKeepUserSets	A boolean value which defines if the user sets of the device will be kept or will be deleted during the update.
[in]	boForceBreakingChange	A 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

• mvIMPACT::acquire::fuaContinue if the current update shall continue.
• mvIMPACT::acquire::fuaCancel otherwise.

Parameters

[in]	currentProgress_pc	The current progress of the erase operation (in percent).
[in]	timeElapsed_s	The total time elapsed since starting the update process (in seconds).

Examples

FirmwareUpdate.cpp.

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

• mvIMPACT::acquire::fuaContinue if the current update shall continue.
• mvIMPACT::acquire::fuaCancel otherwise.

Parameters

[in]

timeElapsed_s

The total time elapsed since starting the update process (in seconds).

Examples

FirmwareUpdate.cpp.

onHardResetRequired()

virtual int onHardResetRequired ( const int currentProgress_pc, const double timeElapsed_s ) const

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

• mvIMPACT::acquire::fuaContinue if the current update shall continue.
• mvIMPACT::acquire::fuaCancel otherwise.

Parameters

[in]	currentProgress_pc	The current progress of the reboot operation (in percent).
[in]	timeElapsed_s	The total time elapsed since starting the update process (in seconds).

Examples

FirmwareUpdate.cpp.

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

• mvIMPACT::acquire::fuaContinue if the current update shall continue.
• mvIMPACT::acquire::fuaCancel otherwise.

Parameters

[in]	currentProgress_pc	The current progress of the load operation (in percent).
[in]	timeElapsed_s	The total time elapsed since starting the update process (in seconds).

Examples

FirmwareUpdate.cpp.

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.

Note

Returning mvIMPACT::acquire::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

• mvIMPACT::acquire::fuaContinue if the current update shall continue.
• mvIMPACT::acquire::fuaCancel otherwise.

Parameters

[in]	currentProgress_pc	The current progress of the reboot operation (in percent).
[in]	timeElapsed_s	The total time elapsed since starting the update process (in seconds).

Examples

FirmwareUpdate.cpp.

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

• mvIMPACT::acquire::fuaContinue if the current update shall continue.
• mvIMPACT::acquire::fuaCancel otherwise.

Parameters

[in]	currentProgress_pc	The current progress of the store operation (in percent).
[in]	timeElapsed_s	The total time elapsed since starting the update process (in seconds).

Examples

FirmwareUpdate.cpp.

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

• mvIMPACT::acquire::fuaContinue if the current update shall continue.
• mvIMPACT::acquire::fuaCancel otherwise.

Parameters

[in]	currentProgress_pc	The current progress of the unzip operation (in percent).
[in]	timeElapsed_s	The total time elapsed since starting the update process (in seconds).

Examples

FirmwareUpdate.cpp.

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

• mvIMPACT::acquire::fuaContinue if the current update shall continue.
• mvIMPACT::acquire::fuaCancel otherwise.

Parameters

[in]	currentProgress_pc	The current progress of the update operation (in percent).
[in]	timeElapsed_s	The total time elapsed since starting the update process (in seconds).

Examples

FirmwareUpdate.cpp.

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

• mvIMPACT::acquire::fuaContinue if the current update shall continue.
• mvIMPACT::acquire::fuaCancel otherwise.

Parameters

[in]	currentProgress_pc	The current progress of the upload operation (in percent).
[in]	timeElapsed_s	The total time elapsed since starting the update process (in seconds).

Examples

FirmwareUpdate.cpp.

statusMessage()

std::string statusMessage ( void ) const

inline

Returns the current status from the status property.

Examples

FirmwareUpdate.cpp.

update()

TDMR_ERROR update ( const std::string & archivePath = "", const bool boUpdateDataAsNeeded = true )

inline

A function to start the firmware update process.

This function is intended to be used to update Balluff imaging and image capture devices.

Note

• Once this function returns, the device will be closed! All objects previously created using the mvIMPACT::acquire::Device pointer must be recreated then.
• For mvBlueFOX device this function needs to be called without passing any parameters to the function!

Returns

• mvIMPACT::acquire::DMR_NO_ERROR if successful.
• A negative error code of type ::TDMR_ERROR otherwise.

Parameters

[in]	archivePath	Path to the file which should be used to update the device. Can be empty if no update archives are needed for the device.
[in]	boUpdateDataAsNeeded	Can 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 either mvIMPACT::acquire::DeviceManager::updateDeviceList must be called or every instance to mvIMPACT::acquire::DeviceManager in the current process needs to be destroyed afterwards before any of those GenICam devices can be used again!

verifyFirmwareChecksum()

TDMR_ERROR verifyFirmwareChecksum ( Device * pDev, const std::string & archivePath, std::string * pStatusMessage = 0 )

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 imaging and image capture devices only. Most Balluff imaging and image capture devices are capable of calculating a hash from the firmware image which is currently running on the device. In addition to that firmware archives for imaging devices 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 most 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.
• If the function returns a negative code of type mvIMPACT::acquire::TDMR_ERROR, the status string will contain a more specific explanation about the root cause for the issue.

Since

2.47.0

Returns

• mvIMPACT::acquire::DMR_NO_ERROR if successful.
• A negative error code of type ::TDMR_ERROR otherwise.

Parameters

[in]	pDev	A pointer to a mvIMPACT::acquire::Device object obtained from a mvIMPACT::acquire::DeviceManager object.
[in]	archivePath	Path to the file which should be used to compare the firmware checksum from with the firmware currently running on the device.
[out]	pStatusMessage	Pointer to a string receiving additional information about the outcome of the operation. This can be 0 if no one is interested in status information.

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