The SetupHelper package provides a set of utilities to simplfy
    installing modifications to Victron Venus Os
    and includes a mechanism to automatically reinstall them following a Venus OS update

Setup:
The easiest way to install this code IF the Venus device has internet access is to run the following command:

wget -qO - https://github.com/kwindrem/SetupHelper/archive/current.tar.gz | tar -xzf - -C /data
mv /data/SetupHelper-current /data/SetupHelper

or

wget https://github.com/kwindrem/TankRepeater/archive/current.tar.gz
mv current.tar.gz SetupHelper.tar.gz

Then move rcS.local to /data, or edit that file if it already exists and add:

    /data/SetupHelper/reinstallMods

You can alternatively use rc.local as explained below

The following lines should be inclueded in the setup script to use the functions and variables provided here

#### following lines incorporate SetupHelper utilities into this script
# Refer to the SetupHelper ReadMe file for details.
    
source "/data/SetupHelper/CommonResources"

if [ $scriptAction == 'EXIT' ] ; then
    exit
fi

checkFileSets

#### end of lines to include SetupHelper

A Venus software update overwrites any modifications to the root partition.
It is therefore necessary to reinstall the modifications following the Venus update.


For automatic reinstallation of any modificaitons using SetupHelper following a Venus update,
    add the following line in /data/rcS.local or /data/rc.local to call the reinstaller:
    
    /data/SetupHelper/reinstallMods

Typically, rcS.local is used because it runs prior to starting services
   so conflicts with running services can be avoided
   (services don't need to be restarted after they've been modified)
   and if a reboot is required, it happens faster

If your setup script needs resources launched later in boot, use /data/rc.local

reinstallScriptsList is a list of setup scripts, one per line that will be called from reinstallMods.
Scripts in this list are called EVERY time the system boots. 
The script must avoid repeating work if it can be avoided.

reinstallScriptsList is hard-coded to reside in the /data directory.
The location must match in CommonResources, and in reinstallMods
The file is created by the first setup script to add to it.

reinstallScriptsList should use full path names to avoid problems finding the script
Lines beginning with # or completely blank lines are ignored as is white space at begin and end

When the setup script adds itself to the script list, it includes "reinstall" as the first parameter.
When reinstallMods calls the script, it passes "reinstall" to the setup script so it knows not to prompt the user

When called from reinstallMods:
1)    The setup script must not require user input since there will be no user interface
2)    The setup script should not reboot the system directly
3)    The setup script should avoid reapplying the modifications.
4)    The setup script should avoid making calls to the internet as these could hang the system.

reinstallMods tests the exit code of each setup script.
An exit code of 123 signals that reinstallMods should reboot the system after all scripts have been run.

A "installed flag file" is used to make sure the automatic reinstallation occurs only once after a Venus OS update.

The presence of the installed flag file signals no further work needs to be done to reinstall the package

Running the script manually should typically ignore the installed flag,
but MUST create or remove it as appropriate to control future boot-time execution.

The installed flag file needs to be removed by a Venus OS update so that the script can do it's work again.
Therefore, installed flag files are stored in /etc/venus since a Venus OS update overwrites the entire dirctory.

The installed flag file should be tested early in the script to save time.

A setup script needs to run manually to perform the initial installation or removal of the package.
In this case, user interaction is necessary at least to choose to install or uninstall.
The setup script also needs to run unattended when called from reinstallMods during system boot.
When run by a user, the scrit should prompt the user for neede information.
However, the call from reinstallMods also needs this information and the user won't be available.
Therefore the paremeters taken from user interaction need to be stored in persistent storage,
then recovered from that storage during the reinstall. 
The script's directory is a convenient location for persistent storage since /data survives a Venus OS update.
The $scriptDir variable is set up in CommonResources (see discussion below).
$scriptDir may be prepended to any persistent storage files.

CommonResources contains common functions and variables that can be used by all scripts,
    saving the setup script writer from lots of tedious work and also hooks scripts into
    the reinstall mechanism.

The tools CommonResorces provides are described now.

The following functions manage execution of the script and interfaces to reinstallMods which is run
    at boot from one of the /data/rc scripts:

    Sourcing CommonResources checks the setup script command line and the installed flag
    and sets $scriptAction based on what is found.
        If this is a boot-time reinstall, AND the installed flag is set,
            scriptAction is set to EXIT.
        The setup script should test scripAction immmediately afger sourcing CommonResources
            and skip furter processing if it is 'EXIT'
        If this a boot-time reinstall but the installed flag is NOT set,
            scriptAction is set to INSTALL.

    checkFileSets
        Attempts to create a file set for the current Venus OS version if it does not exist yet.
            If the original files match another version, the file set is created
                so the setup script may continue normally
            However, if the original files for this new version differ from all existing versions
                the new partial file set must not be used
                Flag files ares placed in the file set:
                    basename.NO_REPLACEMENT indicates a new replaement verion must be created manually
                    INCOMPLETE indiates the file set can not be used until issue are corrected
                scriptAction is also set to EXIT
                It is necessary for the user to create new replacement files manually
                    then rerun the setup script to install the package.
                    You can also revert to a previous Venus OS version until the package
                        is updated for the new version.
        Symbolic links are used in the file set to indicate redundancy between versions.
        This provides a visual indication of which versions have changes from a previous one.
        checkFileSets should be called before any attempt is made to modify Venus files

    endScript
        Function to finish up, prompt the user (if not reinstalling) and exit the script
        It updates the installed flag based on the $runAgain variable
            This script is added/removed from the reinstallScriptsList if installing/uninstalling, respectively
        If $runningAtBoot is true (false when CommonResources is sourced)
            the script will exit with $exitReboot if $rebootNeeded is true
            otherwise, the script will exit with $exitSuccess
            endScript NEVER RETURNS to the caller
        If $runningAtBoot is false (script was run manually), user interaction controls further action
            If $rebootNeeded is true, the function asks if the user wishes to reboot now
            If they respond yes, the system will be rebooted
            The user may choose to not reboot now if additional installations need to be done first
            If $rebootNeeded is false, the function notifies the user of any needed actions
        If $restartGui is true (false when CommonResources is sourced)
            the gui service will be restarted
            
        The following variables are available to control behavior:
            $scriptAction provides direction for the setup script and has the following values:
                NONE - setup script should prompt the user for the desired action
                    and set scriptAction accordingly
                EXIT - the setup script should exit immediately
                INSTALL - the setup script should execute code to install the package
                UNINSTALL - the setup script should execute the code to restore the Venus files to stock
            If installaiton errors occur within functions in CommonResources, scriptAction will be changed to UNINSTALL.
                The setup script MUST retest scriptAction after all installation code has been executed
                so the package can be removed, rather than leaving the system with a partially installed package.

            $rebootNeeded - true signifies a reboot is required after the script is run
                if $runningAtBoot is also true, the reboot is actually performed in reinstallMods
            $runAgain - true signifies startup script needs to be run again

 The following useful variables become available as well:
    $scriptDir - the full path name to the startup script
        the script's code can use this to identify the location of files that need to
        persist between reboots and through Venus OS updates
        It must be set in the setup script beause it is needed before sourcing CommonResources
    $scriptName - the basename of the setup script
    $reinstallScriptsList - the file containing a list of scripts to be run at boot to reinstall packages
        after a Venus software update
    $installedFlag - the name of the install flag files including it's full path
        User code may use these variables but should not change their value!
        It must be set in the setup script beause it is needed before sourcing CommonResources
    $venusVersion - the version of VenusOS derived from /opt/victronenergy/version
    $fileSets - the standard location for the replacement files
        equivalent to #scriptDir/FileSets
        Version-dependent replacements are stored in version subdirectories
        Version-INDEPENDENT replacements are stored in FileSets
    $runningAtBoot - true if the script was called from reinstallMods (at boot time)
        signifying this is to be an unattended (automatic) installation
        CommonResoures sets this variable based on command line options

The following functions update or restore Venus files to activate a package
they are intended to simplify common tasks, generally reducing many lines
to a single line that is easier to read/understand

The "active" file is the one used by Venus applications
It is backed up to [activeFile].orig in the same directory
Then a "replacement" file is copied into place and becomes the active file
Backups allow the stock functionality to be restored when the package is uninstalled

Replacement files are expected in the FileSets directory within the script's directory
If the replacement file content differs with VenusOS version,
subdirectories for each version hold the replacement files
If the replacment is independent of version, it can be placed in FileSets
The version subdirectories are checked first.

The version sub-directories also contain the stock files with their name ending in .orig.
These are used to look for a match within previous versions when a new Venus version is detected.
A new Venus version with matching files to a previous version updates the file sets automatically.
If the new version has different file content, replacement file(s) will need to be created MANUALLY.
This is typically easy by inspecting previous active and .orig files and the new .orig file.
The file set for the new version is flagged as INCOMPLETE and
will preven installation until the file set is complete and the INCOMPLETE flag is removed manually.

fileList contains a list of Venus files to be managed by this package. 
Packages may also contain files that do not exist in the stock Venus image.
These are NOT included in fileList!

Use full paths/name for all files to avoid problems when running the script from other locations
such as the boot code, and quote them in case the names contain spaces.

Two flags are set by these routines in order for the setup script to detect changes
    $thisFileUpdated is true of the venus file was modified by the operation
        It can be tested following each update, copy or restore operation
        to determine the success/failure of that one operation
    $filesUpdates is true if ANY file is modified by any of these functions
        It can be tested at the end of the setup script to know if ANY file
        was modified to trigger restarting service or rebooting

Use updateActiveFile to replace the active file with a replacement from the package

    updateActiveFile replacementFile activeFile
        or
    updateActiveFile activeFile
         First backs up the active file
            then copies the replacement version into the active location
        If called with two parameters
            the first is replacement the file (source)
            the second is the active file (destination)
        If called with only one parameter, it specifies the active file 
            the replacement file is selected from FileSets

    restoreActiveFile activeFile
        Moves the backup copy to the active location
        The first parameter is the name of the active file (the one to be restored to stock)
        The file with the same name with .orig at the end is moved
            to the active file
        If the backup copy doesn't exist BUT the noOrig flag is set
            the active copy is deleted to restore the system to stock

    A failure in updateActiveFile and copyToActiveFile set scriptAction to UNINSTALL.
        The setup script MUST then remove the package
        to prevent system instability from a partially installed package

The following functions simplify the task of getting user input

    standardActionPrompt displays a menu of actions and asks the user to choose
        It sets scriptAction accordingly and returns
        It also handles displaying setup and package logs then asks for an action again
        It also handles quitting with no action - the fuction EXITS without returning in this case
        The basic action prompt includes install, reinstall, quit, display logs (2 choices)
        A reinstall option is enabled by including 'enableReinstall' as the first parameter
        When reinstall is enabled, selecting install, returns a scriptAction of PROMPT
        indicating additional prompting may be needed to complete the install
        At the end of these prompts, the main script should set scriptAction to INSTALL
        If reinstall is selected, the script action is set to INSTALL and the main script
        can then skip additional prompts and allow options set previously to control the install

    yesNoPrompt "question"
        Asks the user to answer yes or no to the question
        Any details regarding the question should be output before calling yesNoPrompt
        yesNoPrompt sets $yesResponse to true if the answer was yes and false if the answer was no

LogHandler is a logging and log display mechanism. It is sourced by CommonResources and also by reinstallMods
    Some executions of the setup scripts are during system boot
    where console messages are likely to go unnoticed (if they are visible at all).
    Boot-time scripts that output to the console are diverted to /var/log/boot,var/log/messages or dmesg,
        but these logs retain messages only from the last boot.
    A Setup Helper log is used to make messages from these setup acivities that are more persistent and easier to find.
    The setup helper log file is /var/log/SetupHelper (or $setupLogFile)
    In addition, some packages have their own log file and logging utilities here write to these logs as well
    Finally, when run from the command line, the console (stdout) is also available and provides the most immediate
        interface to the user.
    A tai64n timestamp is added to messages written to both log files.
    This timestamp can be converted to human readable form for display tai64nlocal 
    The script name is also written to logs

    logMessage "message"
        writes "message" the above places 
            
    displayLog logfile
        displays the last 100 lines of the log file
        $1 is the log file to be displayed. Either:
            $setupLogFile or
            $packageLogFile
        The latter must be initialized in setup script code
        If no package log file exists, $packageLogFile shoudl remain null ""