########################################################################
### FILE:	firmwareupgrade.mod
### PURPOSE:	Generalized methods for firmware upgrade
### AUTHORS:	Tor Slettnes <tor@slett.net>
###
### Copyrights (C) 2011 Life Technologies.  All rights reserved.
########################################################################

### Methods in this file make use of firmware version and upgrade
### mechanisms specified in "firmware.ini", which is expected to
### contain sections in the following format:
###
### 	[Component]
### 	version = <expected-version>
### 	image = <upgrade file, in "UPGRADE:" context>
### 	query = <SCPI command to read current version>
### 	upgrade = <SCPI command to perform firmware upgrade>
###
### For instance, the following would be used to upgrade the
### Magnum Motion Controller Board to version 2557:
###
###     [MMCB]
###     version = 2557
###     image = MMCB_%(version)s.bin
###     query = MCB:FirmwareVersion?
###     upgrade = FirmWareUPgrade -appswitchDelay=10 0xB1 MMCB UPGRADE:%(image)s


### Set up "FirmWare" branch
    SET branch     FirmWare
    BRANCH+ -replaceExisting ${branch}
    ${branch}:MODule aliases.mod
    ${branch}:VAR configfile firmware.ini



########################################################################
### COMMAND:	AutoUpgrade
### PUPROSE:	Upgrade the selected components if needed.
###             If component is "*", autoupgrade all components.

    ${branch}:DEFine AutoUPgrade $components+ <define>
        IF $[ "$components+" == "*" ] <if>
           SET Components $(COMPonent*)
        </if>
        ELSE <else>
           SET Components "$components+"
        </else>

        ITERate -key=component ${Components} <iterate>
            IF $(AutoUPgrade? ${component}) <if>
                UPGRade ${component}
            </if>
        </iterate>
    </define>



########################################################################
### COMMAND:	AutoUPgrade* 
### PURPOSE:	Return list of components that should be updated

    ${branch}:DEFine AutoUPgrade* <define>
        SET components ""
        ITERate -key=component $(COMPonent*) <iterate>
            IF $(AutoUPgrade? ${component}) <if>
                APPend components " ${component}"
            </if>
        </iterate>

        RETurn ${components:1}
    </define>



########################################################################
### COMMAND:	AutoUPgrade?
### PUPROSE:	Indicate whether the specific component should be upgraded

    ${branch}:DEFINT AutoUPgrade? $component$ <define>
        SET expected $(ExpectedVersion? $component$)
        SET current  $(CurrentVersion? $component$)
        SET file     $(UpgradeFile? $component$)

        IF $[ "${current}" == "${expected}" ] <if>
            INFO "Component '$component$' is at version '${current}': no upgrade needed"
            RETURN False
        </if>

        UNLESS $(:FILe:EXISTs? UPGRADE:${file}) <unless>
            INFO "Component '$component$' should be upgraded from '${current}' to '${expected}', but upgrade image '${file}' is not available"
            RETURN False
        </unless>

        INFO "Component '$component$' needs to be upgraded from '${current}' to '${expected}'"
        RETURN True
    </define>



########################################################################
### COMMAND:	COMPonent*
### PUPROSE:	Retrieve list of firmware components that can be upgraded

    ${branch}:ALIas COMPonent* CONFiguration* $(${branch}:VAR? configfile)


########################################################################
### COMMANDS:   CurrentVersion?, ExpectedVersion?
### PURPOSE:    Return the current/expected version of the given component


    ${branch}:DEFine CurrentVersion? $component$ <define>
         SET check   $(CONF? ${configfile} "$component$" query)
         SET version ""

         TRY <try>
             SET version $(:${check})
         </try> <except>
             INFO "Could not get current '$component$' version: [${error}] ${message}"
         </except>

         RETurn ${version}
    </define>


    ${branch}:ALIas ExpectedVersion? CONFiguration? $(${branch}:VAR? configfile) -option=version
    ${branch}:ALIas UpgradeFile?     CONFiguration? $(${branch}:VAR? configfile) -option=image
    ${branch}:ALIas UpgradeCommand?  CONFiguration? $(${branch}:VAR? configfile) -option=upgrade

    ${branch}:DEFine UPGRade $component$ <quote>
        SET file $(UpgradeFile? $component$)
        SET msg "Upgrading component '$component$' using image '${file}'"

        IF $(:FILE:EXISTS? UPGRADE:${file}) <if>
            TRY <try>
                INFO "${msg} -- starting"
                :RUN $(UpgradeCommand? $component$)
                INFO "${msg} -- completed"
            </try> <except>
                INFO "${msg} -- failed"
                ERRor -id=${error} ${message}
            </except>
        </if>
        ELSE <else>
             INFO "${msg} -- failed"
             ERRor -id=NoUpgradeImage -file=${file} "Upgrade image '${file}' is not available"
        </else>
    </quote>