FirmwareUpdate.cpp

The FirmwareUpdate program is a simple example which illustrates how Balluff/MATRIX VISION cameras can be easily updated using the Impact Acquire API.

Since

2.49.0

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

Program location

The source file FirmwareUpdate.cpp can be found under:

%INSTALLDIR%\apps\FirmwareUpdate\

Note

If you have installed the package without example applications, this file will not be available. On Windows® the sample application can be installed or removed from the target system at any time by simply restarting the installation package.

How it works:

1. Let the user decide which devices to use.
2. Figure out which exact device is selected for the update.
3. Create a MyFirmwareUpdater object, derived from FirmwareUpdater class
4. Override the status callbacks to create status messages at stdout
5. Start the firmware update and check the result.

Note

If some kind of status of the update progress is required (e.g. to display the update progress on a GUI, etc.) it will be necessary to create an object which derives from mvIMPACT::acquire::FirmwareUpdater and to override the virtual callbacks. More details explanation the functionalities of the FirmwareUpdater API can be found at mvIMPACT::acquire::FirmwareUpdater.

Console Output

The camera's firmware is the same as the version being used here.
[0]: BF003939 (mvBlueFOX-223C, mvBlueFOX, interface layout: DeviceSpecific, acquisition start/stop behaviour: Default)
[1]: BN000110 (BVS CA-BN2-0016ZC, BVS CA-BN (mvBlueNAOS), interface layout: GenICam, acquisition start/stop behaviour: User)
[2]: FF001403 (mvBlueFOX3-2004C, mvBlueFOX3, interface layout: GenICam, acquisition start/stop behaviour: User)
[3]: GX000020 (mvBlueCOUGAR-X102dC, mvBlueCOUGAR, interface layout: GenICam, acquisition start/stop behaviour: User)
[4]: GX022189 (mvBlueCOUGAR-X100fC, mvBlueCOUGAR, interface layout: GenICam, acquisition start/stop behaviour: User)

Please enter the number in front of the listed device followed by [ENTER] to open it:

Once the device has been selected, the update process will be started. Depending on the selected device and parameters the console output might and the duration might differ.

Updating GX022189...
Unzipping firmware archive - Update progress: 5, time 0.000000 s
Uploading - Update progress: 25, time 0.501117 s
Uploading - Update progress: 30, time 12.265582 s
Uploading - Update progress: 35, time 24.396343 s
Uploading - Update progress: 40, time 36.197152 s
Uploading - Update progress: 45, time 48.613364 s
Uploading - Update progress: 50, time 61.444290 s
Uploading - Update progress: 55, time 73.644665 s
Uploading - Update progress: 60, time 85.647717 s
Uploading - Update progress: 65, time 97.328879 s
Uploading - Update progress: 70, time 109.088660 s
Uploading - Update progress: 75, time 120.990581 s
Uploading - Update progress: 80, time 132.533798 s
Rebooting - Update progress: 86, time 161.574359 s
Rebooting - Update progress: 90, time 164.087728 s
Result code after updating: 0
Press [ENTER] to end the application

If desired, this sample can also be used as a command-line tool to update Balluff/MATRIX VISION devices. The following command-line parameters might be useful in this case.

Parameter	Functionality
General
serial	Allows the user to specify the serial number of a specific device which should be used by the application.
unattended	Will avoid to ask for user interactions, if possible.
force	Will force the update even if FW is already up-to-date.
help	Will display a help text in the console.
mvBlueCOUGAR-(X/XD/XT) and mvBlueFOX3
forceDowngrade	Will force an update even if the specified FW is older than the version already installed on the selected device.
keepUserSets	If UserSets are stored on the device the should still be present after the update. Otherwise they will be deleted.
forceBreakingChange	Will update the device even if the interface might be different afterwards.
pathToFWArchive	Path to the firmware archive which should be used to update the device. (required)
mvBlueFOX
version	The version that should be used to update the device. For more details please refer to mvIMPACT::acquire::FirmwareUpdater::firmwareVersionToUpload

How it works

The update process itself is very straight forward. It is just necessary to create an instance of mvIMPACT::acquire::FirmwareUpdater. To configure the update process itself it is necessary to pass the correct parameters to the constructor. Afterwards it is sufficient to call mvIMPACT::acquire::FirmwareUpdater::update.

Every setting which is meant to be configurable for the update process can be changed within the constructor or, in case of mvBlueFOX devices within the mvIMPACT::acquire::FirmwareUpdater::firmwareVersionToUpload property.

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!

The callbacks can be customized to get the required behavior. In this example the update status callbacks just return some message to the shell and look like this:

//-----------------------------------------------------------------------------
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, oForceBreakingChange ) }
  virtual int onErrorMessage( const double timeElapsed_s ) const
  {
    cout << "Error: " << statusMessage() << "@" << timeElapsed_s << " s" << endl;
    return fuaCancel;
  }
  virtual int onErasingFlash( const int currentProgress_pc, const double timeElapsed_s ) const
  {
    cout << "Erasing - Update progress: " << currentProgress_pc << ", time " << timeElapsed_s << " s" << endl;
    return fuaContinue;
  }
  virtual int onUnzippingFirmwareArchive( const int currentProgress_pc, const double timeElapsed_s ) const
  {
    cout << "Unzipping firmware archive - Update progress: " << currentProgress_pc << ", time " << timeElapsed_s << " s" << endl;
    return fuaContinue;
  }
  virtual int onUpdatingBootProgrammer( const int currentProgress_pc, const double timeElapsed_s ) const
  {
    cout << "Updating boot programmer - Update progress: " << currentProgress_pc << ", time " << timeElapsed_s << " s" << endl;
    return fuaContinue;
  }
  virtual int onUploadingImage( const int currentProgress_pc, const double timeElapsed_s ) const
  {
    cout << "Uploading - Update progress: " << currentProgress_pc << ", time " << timeElapsed_s << " s" << endl;
    return fuaContinue;
  }
  virtual int onRebooting( const int currentProgress_pc, const double timeElapsed_s ) const
  {
    cout << "Rebooting - Update progress: " << currentProgress_pc << ", time " << timeElapsed_s << " s" << endl;
    return fuaContinue;
  }
  virtual int onHardResetRequired( const int currentProgress_pc, const double timeElapsed_s ) const
  {
    cout << "Rebooting - Update progress: " << currentProgress_pc << ", time " << timeElapsed_s << " s" << endl
         << "Manual hard reset required." << endl;
    return fuaCancel;
  }
  virtual int onSavingUserSets( const int currentProgress_pc, const double timeElapsed_s ) const
  {
    cout << "Saving sets - Update progress: " << currentProgress_pc << ", time " << timeElapsed_s << " s" << endl;
    return fuaContinue;
  }
  virtual int onLoadingUserSets( const int currentProgress_pc, const double timeElapsed_s ) const
  {
    cout << "Loading sets - Update progress: " << currentProgress_pc << ", time " << timeElapsed_s << " s" << endl;
    return fuaContinue;
  }
};

Updating mvBlueFOX3 or mvBlueCOUGAR-X/XD/XT devices

For mvBlueFOX3 or mvBlueCOUGAR-X/XD/XT devices it is necessary to provide the path to a firmware archive (*.mvu file). Some cases might require some specific parameters to be changed e.g. in case of downgrading a device or if there might be a breaking change within the device's software interface.

Note

Downloads to Balluff firmware files can be found at the Balluff website.

//-----------------------------------------------------------------------------
TDMR_ERROR updateBlueCOUGAROrBlueFOX3( Device* pDev, const string& pathToFirmwareArchive, bool boForceOverideSameVersion, bool boForceDowngrade, bool boForceSameVersion, bool boForceBreakingChange, string& status )
//-----------------------------------------------------------------------------
{
  TDMR_ERROR result = DMR_NO_ERROR;
  MyFirmwareUpdater fwu( pDev, boForceOverideSameVersion, boForceDowngrade, boForceSameVersion, boForceBreakingChange );
 
  result = fwu.update( pathToFirmwareArchive );
  if( result == DMR_NO_ERROR )
  {
    result = fwu.verifyFirmwareChecksum( pDev, pathToFirmwareArchive, nullptr );
    if( result != DMR_NO_ERROR )
    {
      cout << "Firmware checksum verification: " << fwu.statusMessage() << endl;
    }
    else
    {
      cout << "Firmware checksum verified successful! " << endl;
    }
  }
  if( result != DMR_NO_ERROR )
  {
    status = fwu.statusMessage();
  }
  return result;
}

Updating BVS CA-BN (mvBlueNAOS) devices

As BVS CA-BN (mvBlueNAOS) devices are very much integrated within the host system, there is no separate firmware file which can be downloaded. The devices firmware is embedded into the Impact Acquire framework and has to be updated once the Impact Acquire framework on the host system contains breaking changes. This applies for upgrades as well as for downgrades.

//-----------------------------------------------------------------------------
TDMR_ERROR updateBVS_CA_BN( Device* pDev, const bool boForce, string& status )
//-----------------------------------------------------------------------------
{
  string latestFirmwareVersion;
  if( GetLatestLocalFirmwareVersion( pDev, latestFirmwareVersion ) )
  {
    if( !boForce )
    {
      cout << "Skipping device " << pDev->serial.read() << " because it already uses the current FW version ("
           << pDev->firmwareVersion.readS() << ")." << endl;
      return DMR_NO_ERROR;
    }
    cout << "Device " << pDev->serial.read() << " already uses the current FW version ("
         << pDev->firmwareVersion.readS() << ")." << endl
         << "Not skipping because 'force' specified'." << endl;
  }
 
  cout << "Updating device " << pDev->serial.read() << " from FW version "
       << pDev->firmwareVersion.readS()
       << " to " << latestFirmwareVersion << "." << endl;
  TDMR_ERROR result = DMR_NO_ERROR;
  MyFirmwareUpdater fwu( pDev );
  result = fwu.update();
  if( result != DMR_NO_ERROR )
  {
    status = fwu.statusMessage();
  }
  return result;
}

Updating mvBlueFOX devices

As mvBlueFOX devices are not capable of the complex functionalities provided by GenICam™ compliant devices the set of configurable parameters is much more limited. There is no specific firmware file available, instead different firmware versions are shipped within the mvBlueFOX package and can be selected for the update via the mvIMPACT::acquire::FirmwareUpdater::firmwareVersionToUpload property.

//-----------------------------------------------------------------------------
TDMR_ERROR updateBlueFOX( Device* pDev, const string& version, string& status )
//-----------------------------------------------------------------------------
{
  TDMR_ERROR result = DMR_NO_ERROR;
  MyFirmwareUpdater fwu( pDev );
 
  if( !version.empty() )
  {
    // use specific version if specified
    fwu.firmwareVersionToUpload.writeS( version );
  }
  cout << "Updating device " << pDev->serial.read() << " from FW version "
       << pDev->firmwareVersion.readS()
       << " to " << fwu.firmwareVersionToUpload.readS() << "." << endl;
  result = fwu.update();
  if( result != DMR_NO_ERROR )
  {
    status = fwu.statusMessage();
  }
  return result;
}

Source code

//
// @description: Example applications for Impact Acquire
// @copyright: Copyright (C) 2023 Balluff GmbH
// @authors: APIs and drivers development team at Balluff GmbH
// @initial date: 2023-02-07
//
// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"),
// to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
// and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice (including the next paragraph) shall be included in all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,i
// WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
//
 
#ifdef _MSC_VER // is Microsoft compiler?
#   if _MSC_VER < 1300  // is 'old' VC 6 compiler?
#       pragma warning( disable : 4786 ) // 'identifier was truncated to '255' characters in the debug information'
#   endif // #if _MSC_VER < 1300
#   include <windows.h>
#endif // #ifdef _MSC_VER
#include <iostream>
#include <apps/Common/exampleHelper.h>
#include <mvIMPACT_CPP/mvIMPACT_acquire.h>
 
// CLI application that can be used to update a GenICam device using the Firmware Updater API.
// At the moment only updating from a local FW version e.g. as used by BVS CA-BN devices is explicitly supported.
 
using namespace mvIMPACT::acquire;
using namespace std;
 
//-----------------------------------------------------------------------------
enum DeviceFamily
//-----------------------------------------------------------------------------
{
    dfBVS_CA_BN,
    dfMvBlueCOUGAR,
    dfMvBlueFOX3,
    dfMvBlueFOX,
    dfUnknown
};
 
//-----------------------------------------------------------------------------
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 ) {}
    virtual int onErrorMessage( const double timeElapsed_s ) const
    {
        cout << "Error: " << statusMessage() << "@" << timeElapsed_s << " s" << endl;
        return fuaCancel;
    }
    virtual int onErasingFlash( const int currentProgress_pc, const double timeElapsed_s ) const
    {
        cout << "Erasing - Update progress: " << currentProgress_pc << ", time " << timeElapsed_s << " s" << endl;
        return fuaContinue;
    }
    virtual int onUnzippingFirmwareArchive( const int currentProgress_pc, const double timeElapsed_s ) const
    {
        cout << "Unzipping firmware archive - Update progress: " << currentProgress_pc << ", time " << timeElapsed_s << " s" << endl;
        return fuaContinue;
    }
    virtual int onUpdatingBootProgrammer( const int currentProgress_pc, const double timeElapsed_s ) const
    {
        cout << "Updating boot programmer - Update progress: " << currentProgress_pc << ", time " << timeElapsed_s << " s" << endl;
        return fuaContinue;
    }
    virtual int onUploadingImage( const int currentProgress_pc, const double timeElapsed_s ) const
    {
        cout << "Uploading - Update progress: " << currentProgress_pc << ", time " << timeElapsed_s << " s" << endl;
        return fuaContinue;
    }
    virtual int onRebooting( const int currentProgress_pc, const double timeElapsed_s ) const
    {
        cout << "Rebooting - Update progress: " << currentProgress_pc << ", time " << timeElapsed_s << " s" << endl;
        return fuaContinue;
    }
    virtual int onHardResetRequired( const int currentProgress_pc, const double timeElapsed_s ) const
    {
        cout << "Rebooting - Update progress: " << currentProgress_pc << ", time " << timeElapsed_s << " s" << endl
             << "Manual hard reset required." << endl;
        return fuaCancel;
    }
    virtual int onSavingUserSets( const int currentProgress_pc, const double timeElapsed_s ) const
    {
        cout << "Saving sets - Update progress: " << currentProgress_pc << ", time " << timeElapsed_s << " s" << endl;
        return fuaContinue;
    }
    virtual int onLoadingUserSets( const int currentProgress_pc, const double timeElapsed_s ) const
    {
        cout << "Loading sets - Update progress: " << currentProgress_pc << ", time " << timeElapsed_s << " s" << endl;
        return fuaContinue;
    }
};
 
//-----------------------------------------------------------------------------
bool IsGigEVisionDevice( const Device* pDev )
//-----------------------------------------------------------------------------
{
    PropertyI64 deviceIPAddress;
    DeviceComponentLocator locator( pDev->hDev() );
    if( locator.bindComponent( deviceIPAddress, "DeviceIPAddress" ) && ( deviceIPAddress.readS() != "Unavailable" ) )
    {
        return true;
    }
    return false;
}
 
//-----------------------------------------------------------------------------
DeviceFamily GetDeviceFamily( const Device* pDev )
//-----------------------------------------------------------------------------
{
    if( ( pDev->family.readS() == "mvBlueCOUGAR" || pDev->family.readS() == "BVS CA" ) && IsGigEVisionDevice( pDev ) )
    {
        return dfMvBlueCOUGAR;
    }
    else if( pDev->family.readS() == "mvBlueFOX3" || pDev->family.readS() == "BVS CA" )
    {
        return dfMvBlueFOX3;
    }
    else if( ( pDev->family.read().find( "mvBlueNAOS" ) == 0 ) || ( pDev->family.read().find( "BVS CA-BN" ) == 0 ) )
    {
        return dfBVS_CA_BN;
    }
    else if( pDev->family.readS() == "mvBlueFOX" )
    {
        return dfMvBlueFOX;
    }
    return dfUnknown;
}
 
//-----------------------------------------------------------------------------
bool GetLatestLocalFirmwareVersion( const Device* pDev, string& latestFirmwareVersion )
//-----------------------------------------------------------------------------
{
    const string currentFirmwareVersion = pDev->firmwareVersion.readS();
    PropertyI64 firmwareVersionLatest;
    DeviceComponentLocator locator( pDev->hDev() );
    if( !locator.bindComponent( firmwareVersionLatest, "FirmwareVersionLatest" ) )
    {
        return false;
    }
    latestFirmwareVersion = firmwareVersionLatest.readS();
    return ( currentFirmwareVersion == latestFirmwareVersion );
}
 
//-----------------------------------------------------------------------------
TDMR_ERROR updateBlueCOUGAROrBlueFOX3( Device* pDev, const string& pathToFirmwareArchive, bool boForceOverideSameVersion, bool boForceDowngrade, bool boForceSameVersion, bool boForceBreakingChange, string& status )
//-----------------------------------------------------------------------------
{
    TDMR_ERROR result = DMR_NO_ERROR;
    MyFirmwareUpdater fwu( pDev, boForceOverideSameVersion, boForceDowngrade, boForceSameVersion, boForceBreakingChange );
 
    result = fwu.update( pathToFirmwareArchive );
    if( result == DMR_NO_ERROR )
    {
        result = fwu.verifyFirmwareChecksum( pDev, pathToFirmwareArchive, nullptr );
        if( result != DMR_NO_ERROR )
        {
            cout << "Firmware checksum verification: " << fwu.statusMessage() << endl;
        }
        else
        {
            cout << "Firmware checksum verified successful! " << endl;
        }
    }
    if( result != DMR_NO_ERROR )
    {
        status = fwu.statusMessage();
    }
    return result;
}
 
//-----------------------------------------------------------------------------
TDMR_ERROR updateBlueFOX( Device* pDev, const string& version, string& status )
//-----------------------------------------------------------------------------
{
    TDMR_ERROR result = DMR_NO_ERROR;
    MyFirmwareUpdater fwu( pDev );
 
    if( !version.empty() )
    {
        // use specific version if specified
        fwu.firmwareVersionToUpload.writeS( version );
    }
    cout << "Updating device " << pDev->serial.read() << " from FW version "
         << pDev->firmwareVersion.readS()
         << " to " << fwu.firmwareVersionToUpload.readS() << "." << endl;
    result = fwu.update();
    if( result != DMR_NO_ERROR )
    {
        status = fwu.statusMessage();
    }
    return result;
}
 
//-----------------------------------------------------------------------------
TDMR_ERROR updateBVS_CA_BN( Device* pDev, const bool boForce, string& status )
//-----------------------------------------------------------------------------
{
    string latestFirmwareVersion;
    if( GetLatestLocalFirmwareVersion( pDev, latestFirmwareVersion ) )
    {
        if( !boForce )
        {
            cout << "Skipping device " << pDev->serial.read() << " because it already uses the current FW version ("
                 << pDev->firmwareVersion.readS() << ")." << endl;
            return DMR_NO_ERROR;
        }
        cout << "Device " << pDev->serial.read() << " already uses the current FW version ("
             << pDev->firmwareVersion.readS() << ")." << endl
             << "Not skipping because 'force' specified'." << endl;
    }
 
    cout << "Updating device " << pDev->serial.read() << " from FW version "
         << pDev->firmwareVersion.readS()
         << " to " << latestFirmwareVersion << "." << endl;
    TDMR_ERROR result = DMR_NO_ERROR;
    MyFirmwareUpdater fwu( pDev );
    result = fwu.update();
    if( result != DMR_NO_ERROR )
    {
        status = fwu.statusMessage();
    }
    return result;
}
 
//-----------------------------------------------------------------------------
// This function will allow to select devices that support the Firmware API
// as the code of the example relies on these feature in the code.
bool isDeviceSupportedBySample( const Device* const pDev )
//-----------------------------------------------------------------------------
{
    return GetDeviceFamily( pDev ) != dfUnknown;
}
 
//-----------------------------------------------------------------------------
void displayCommandLineOptions( void )
//-----------------------------------------------------------------------------
{
    cout << "Available command-line parameters:" << endl
         << " General:" << endl
         << "  'serial'              or 's' to specify the serial number of the device to use (if not specified the user will be asked to select a device)" << endl
         << "  'unattended'          or 'u' to specify no questions asked, if possible" << endl
         << "  'force'               or 'f' to specify force update even if FW is already up-to-date" << endl
         << "  'help'                or 'h' displays this help text" << endl
         << " mvBlueCOUGAR-(X/XD/XT) and mvBlueFOX3:" << endl
         << "  'forceDowngrade'      or 'd' to force an update even if the specified FW is older than the version already installed" << endl
         << "  'keepUserSets'        or 'k' if UserSets stored on the device should still be present after the update" << endl
         << "  'forceBreakingChange' or 'b' if the device should be updated even if the interface might be different afterwards" << endl
         << "  'pathToFWArchive'     or 'p' to specify the firmware archive which should be used to update the device" << endl
         << " mvBlueFOX:" << endl
         << "  'version'             or 'v' to specify the version that should be used to update the device" << endl
 
         << endl
         << "USAGE EXAMPLES:" << endl
         << "  FirmwareUpdate s=BN* f=1" << endl
         << "  FirmwareUpdate s=GX* p=\"path to firmware archive\" k=0" << endl
         << "  FirmwareUpdate s=BF* v=49" << endl << endl;
}
 
//-----------------------------------------------------------------------------
int main( int argc, char* argv[] )
//-----------------------------------------------------------------------------
{
    DeviceManager devMgr;
    Device* pDev = nullptr;
    bool boUnattended = false;
    bool boForceSameVersion = false;
    bool boForceDowngrade = false;
    bool boKeepUserSets = true;
    bool boForceBreakingChange = false;
    string version;
    string pathToFirmwareArchive;
 
    // scan command line
    if( argc > 1 )
    {
        bool boInvalidCommandLineParameterDetected = false;
        for( int i = 1; i < argc; i++ )
        {
            const string param( argv[i] );
            const string::size_type keyEnd = param.find_first_of( "=" );
            if( ( keyEnd == string::npos ) || ( keyEnd == param.length() - 1 ) )
            {
                cout << "Invalid command-line parameter: '" << param << "' (ignored)." << endl;
                boInvalidCommandLineParameterDetected = true;
            }
            else
            {
                const string key = param.substr( 0, keyEnd );
                const string value = param.substr( keyEnd + 1 );
                if( ( key == "serial" ) || ( key == "s" ) )
                {
                    pDev = devMgr.getDeviceBySerial( value );
                }
                else if( ( key == "unattended" ) || ( key == "u" ) )
                {
                    boUnattended = ( atoi( value.c_str() ) != 0 );
                }
                else if( ( key == "force" ) || ( key == "f" ) )
                {
                    boForceSameVersion = ( atoi( value.c_str() ) != 0 );
                }
                else if( ( key == "forceDowngrade" ) || ( key == "d" ) )
                {
                    boForceDowngrade = ( atoi( value.c_str() ) != 0 );
                }
                else if( ( key == "keepUserSets" ) || ( key == "k" ) )
                {
                    boKeepUserSets = ( atoi( value.c_str() ) != 0 );
                }
                else if( ( key == "forceBreakingChange" ) || ( key == "b" ) )
                {
                    boForceBreakingChange = ( atoi( value.c_str() ) != 0 );
                }
                else if( ( key == "version" ) || ( key == "v" ) )
                {
                    version = value;
                }
                else if( ( key == "pathToFWArchive" ) || ( key == "p" ) )
                {
                    pathToFirmwareArchive = value;
                }
                else if( ( key == "help" ) || ( key == "h" ) )
                {
                    displayCommandLineOptions();
                }
                else
                {
                    cout << "Invalid command-line parameter: '" << param << "' (ignored)." << endl;
                    boInvalidCommandLineParameterDetected = true;
                }
            }
        }
        if( boInvalidCommandLineParameterDetected )
        {
            displayCommandLineOptions();
        }
    }
    else
    {
        cout << endl << "No command-line parameters specified." << endl << endl;
        displayCommandLineOptions();
    }
 
    if( pDev == nullptr )
    {
        pDev = getDeviceFromUserInput( devMgr, isDeviceSupportedBySample );
    }
    if( pDev == nullptr )
    {
        cout << "Unable to continue!" << endl;
        return 1;
    }
    const DeviceFamily deviceFamily = GetDeviceFamily( pDev );
    if( deviceFamily == dfUnknown )
    {
        cout << "The selected device is not supported by this sample. Unable to continue!" << endl;
        if( !boUnattended )
        {
            cout << "Press [ENTER] to end the application" << endl;
            cin.get();
        }
        return 1;
    }
 
    if( !boUnattended )
    {
        cout << "Press [ENTER] to update the device." << endl;
        cin.get();
    }
    cout << "Updating " << pDev->serial.read() << "..." << endl;
 
    string status;
    TDMR_ERROR updateResult = DMR_NO_ERROR;
    try
    {
        switch( deviceFamily )
        {
        case dfMvBlueCOUGAR:
        case dfMvBlueFOX3:
            updateResult = updateBlueCOUGAROrBlueFOX3( pDev, pathToFirmwareArchive, boForceSameVersion, boForceDowngrade, boKeepUserSets, boForceBreakingChange, status );
            break;
        case dfMvBlueFOX:
            updateResult = updateBlueFOX( pDev, version, status );
            break;
        case dfBVS_CA_BN:
            updateResult = updateBVS_CA_BN( pDev, boForceSameVersion, status );
            break;
        case dfUnknown:
            // should never get here because it is handled above
            break;
        }
    }
    catch( const ImpactAcquireException& e )
    {
        cout << "An error occurred while updating the firmware of the device " << pDev->serial.read()
             << "(error code: " << e.getErrorCodeAsString() << ")." << endl;
        // reading out potential issues
        cout << "Status: " << status << endl;
    }
    cout << "Result code after updating: " << updateResult << "(" << ImpactAcquireException::getErrorCodeAsString( updateResult ) << ")" << endl;
 
    // update device list explicitly otherwise it contains illegal pointers to the "old" device (mvBlueNAOS)
    devMgr.updateDeviceList();
    if( !boUnattended )
    {
        cout << "Press [ENTER] to end the application" << endl;
        cin.get();
    }
    return updateResult == DMR_NO_ERROR ? 0 : 1;
}