ReadMe

GuiMods has ben revived with combined functionality of the original GuiMods and GuiMods2

GuiMods2 has been decomissioned

The user may not select between enhanced versions of the
	simpler flow (aka Hub) and Grid Parallel overviews

The enhnaced Hub overview includes voltage, current, frequency and input current limit values.

The enhanced Grid Parallel flow overview which presents most components in the system
	but lacks room for any detail. 
    Only total power plus a gauge indicating power on each leg/phase is shown on the overview.
    
The following components have NOT been tested:
    Multi-phase(leg) systems

Configuration settings can be found in:
    Device List / Settings / Display & language/ GuiMods

This package provides the following modificaitons to the VenusOS GUI:
    Grid Parallel Flow overview:
        Tiles have been reduced in size to make room for all components.
        Except for the battery, only a gauge and a total power number are displayed
        Additional details are displayed on full screens devoted to that part of the system.
        Tapping the center of the tile on the overview screen brings up the details.
        When entering the enhanced flow overview page, target areas are displayed for a few seconds
            with a message instructing "tap for details"

    Hub Flow overview:
        This overview provides the tiles for AC in and out, inverter, battery, Solar (PV) charger
            and in some cases PV inverters.
            The Grid Parallel overview is a better choice if this overview hides components
                due to limited real estate.

        In the stock code, different flow overviews were used depending on the system type
            (e.g, ESS active).
        In this version, the user may choose between the enhanced Grid Parallel and simpler enhanced Hub overviews.

        Add tank information (both overviews)
            4 tanks fit along the bottom of the page
            for more than 4 tanks, the list scrolls
        Add temps information (both overviews)
            A combination of up to 4 tanks and temps fit across the bottom
            For more, the bottom row splits into separate rows for temps and tanks
            Each row scrolls horizontally if more than 4 items exist in the row
    
    Move Settings and Notifications to the top of the Device List page

    Optionally hides the Tiles Overview

    Enhances the Mobile Overview
        all new layout and tile organization
        add Inverter Only mode
        shows voltages current and frequency for AC in and out
        shows current for DC loads
        shows solar voltage and current
        hides Pump switch if not enabled to make more space for tanks
            (this became standard in v2.70~9)
        tanks column scrolls if there are more tanks than space allows
        add temeratore sensors to tanks column
            The tanks column is split into separte columns for tanks and temerature sensors
            A common tile height is set for both columns, then each column is filled in separtly
            Any tank that apepars as a dBus temperature sensor should appear
        Adds VE.Direct inverter status and control

    Enhances the Tank Tile
        red indicates low/high fluid levels
        indicates NO RESPONSE if no signal received from tank
        tile shrinks if needed to show more tanks, then list scrolls
        display custom tank names (stock in v2.70~9)
        displays absolute fluid quantity (e.g., gallons) in addition to percentage

    Adds VE.Direct inverter status and control

    Eses custom tank name if it exists and optionally shorten tank names
        beginning with Venus v2.70~16, NEMA2000 tank names can be too long to fit in available space
        enabling this option will shorten the tank name to the first two words
            (first word for compact tank tiles)
            and repalce "Waste" with "Gray" to be consistent with "Black" label for sewage tank

    Adds a Relay Overview page that allows controlling all relays.
        Previously, relay control is several menu levels deep so this is much faster
        Status for all relays is also shown along with the function (manual, generator, pump, alarm)
        Buttons presented for pump and generator affect the actual parameters for those devices,
             not just the relay state.
        A relay name has also been added. This name is shown on the Relay Overview.
            The name scrolls if it won't fit in the avaiable space.
        All relay configurations are in Device List / Settings / Relay.
            That menu has been expanded to set names and control whether the relay is shown on the
                Relay Overview.
        Note that for the Alarm function, there are no controls, yet the current alarm state is show.
        Pump control has three modes: On, Off and Auto which is controlled by the associated tank level.
        Geherator control has buttons for Manual Start and Manual Stop as well as
            AutoEnable which toggles the enables the condition-based run control
        Note that if condition-based run is enabled, Manual Stop may not stop the generator.
            But turning off Auto Enable would cause the generator to stop.
    
each of these enhancements/modificatinos can be selected individually any time
    (while system is runing) via the Settings Display GuiMods menu

Power Gauges

The power gauges provide an indicaton of the inverter's and battery's ability to satisfy the
    AC and DC loads and help the user to manage system loads.
Power gauges for inputs and outputs provide an indication of current power levels
    relative to user-defined limits. Again, providing some help in system management.

Gauges registering in the red region suggest an overload will occur if loads are not reduced immediately.

Gauges registering in the yellow region suggest an overload may occur some time in the future.

The inverter gauge is the main indicator of system health.
    It will indicates an inverter overload more clearly than the AC input and output gauges could.

Showing power at multiple locations in the system permits the user to more easily
    identify the needed correction.

Power gauges display power for each leg of the system as separate horizontal bars.

The AC input has a finite power limit based on the input wiring and breaker.
An adjustable input current limit further restricts available AC input power.
The gauge in this tile reflects the AC input current limit setting so the power at the system input
is shown reliative to this input.

The AC output power is a combination of AC input power and that provided by the inverter.
The AC output power gauge ranges are set by a user-defined limits
The AC output distribution may have it's own limit (e.g., the panel's master breaker).
The gauge is set to this limit so the user can identify a potential breaker trip.

The battery too represents an area of concern. If it is overloaded, the system will shut down.
Many systems include DC loads which draw power from the battery, so it is important to provide
an indication of how much DC power is being extracted from the battery realtive to it's maximum
discharge current. The system also charges the battery so power flow may also be into the battery.
Therefore, the battery gauge must indicate a charging or discharging current.
The zero point is therefore in the middle of the gauge with discharging to the left and charging to the right.

The PV (solar) charger and inverter tiles represent power supplied by these devices. Again, user-defined limit sets the range of the gauge.

The DC System tile shows the combination of Loads and charging sources (such as wind) connected to the battery.

Details pages repeat the associated gauge(s) and provide more detail for that area of the system.
Where possible, voltage, current and frequency for each leg of the system are shown in a table.
The Inverter detail includes inverter mode selection:
    On, Off, Inverter only, Charger only, Eco.
The AC input detail includes a set of buttons to set the input current limit.

The PV charger detail provides a system total as a gauge and power number,
    then lists each charger showing its name, power and the PV array voltage.

The PV inverter detail provides system totals for grid and output connections
    then lists name, total power, power for each leg and where the inverter is connected (input or output) 

The system does not provide current values for the AC input and ouput of the system.
    AC input and output details pages show current values that are calculated based on the power and voltage.
    With a low power factor, actual current values could be significantly higher those shown.

Configuration

    All configuration is done through the main menu system.
    Go to Device List / Settings / Display & language / GuiMods
    Changes to any of these settings are immediately seen on the overviews.
    (Previous versions of GuiMods required running the setup script again to make changes.)
    
    Show Tile Overview controls whether the Tile Overview is shown in the Overview rotation
    
    Move Settings to top of Device List
        Normally, these items appear at the bottom of the Device List
        Turning this option on moves them to the top
    
    Show boat & motorhome overview is a duplication of the button in the Display & language menu
        as a convenience since it interacts with the next button
    
    Use Enhanced Mobile Overview
        When on, the standard mobile overview is replaced with the enhanced version provided
        with this package. Details are explained above
    
    Use Enhanced Flow Overview
        Replaces the standard flow overviews with the enhanced version described above

    Use Grid Parallel Enhaned Flow Overview
        Selects between the simpler Hub and more complete Grid Parallel overviews.
        Use Enhanced Flow Overview must be on to see and change this option
    
    Show tanks on Flow Overview
    Show temperatures on Flow Overview
        Fluid levels and temperatures are displayed at the bottom of the Flow Overview when
        the associated switch is on.
    
    Combine AC input/output loads
        The enhanced flow overview displays two load tiles: Loads on Input and Loads on Output.
        Confusion is likley especially when a system only connects to one load output.
        This option combines the information into a common tile in the upper right of the overview
        and changes the title to AC Loads.
    
    Show Loads On Input
        Not all systems have loads connected to the input side of the inverter/charger.
        This would include loads connected to the AC 2 output.
        To avoid confusion, this option allows you to hide this tile when it is not being used.
        (There is no mechanism to automatically hide this tile.)

    Shorten tank names
        When on, tank names are shortened to one or two words depending on the available space.
        In addition "Waste" is replaced with "Gray" to be consistent with "Black" and in line
        with common RV terminology.
    
    AC Input Limit Preset 1 - 4
        Provides rapid selection of common AC input current limits through the popup
            accessed by touching the lower portion of the AC input tile.
        A preset is active for any value other than 0. For 0 the preset button disappears.
        If you wish to set a preset to the inverter's minimum current limit,
        specify a value of 1 for the preset.
        
    Temperature Scale
        Selects either °C or °F (or both) for temperatures displayed on the Flow and Mobile Overviews.

    Time format
        Selects the time format for the Enhanced Mobile and Enhanced Flow overviews:
            24 hour, 12 hour with AM/PM or don't show time at all

    Inactive Tiles on Flow Overview
        Inactive tiles can be hidden, shown or shown dimmed

    Automatic GitHub updates
        If SetupHelper is up to date, this item controls automatic updates from GitHub
        Normal - enables updates at a rate of 1 package check every 10 minutes
        Fast - enables updates at a rate of 1 package check every 10 seconds
            after all packages have been checked once, Normal mode is automatically selected
            This mode is handy for making a quick check to insure all packages are up to date,
            then allowing the system to check again at the slower rate
        Check packages once - makes one pass through all installe packages at the fast rate
            then disables automatic updates
        Disabled - prevents the system from checking GitHub for updates
        Access level must be set to Installer or above to change this setting.

    Package Versions
        moved to the SetupHelper package and now appears in its own menu:
        Device List / Settings / Package Versions
        The move was so that the versions and automatic updates could be controlled
        even if GuiMods was not installed

    PowerGauges leads to a second menu
    
    Show power gauges
        When on, power gauges are inserted in the AC input and output tiles, The Multi icon, the Battery tile
        and the PV Charger tile.
        
    Access level must be set to Installer or above to change the following gauge limits. 
        
    Inverter peak power is the maximum power the inverter can produce for a limited amount of time.
        This is the maximum power displayed on the gauge
        The inverter spec sheet will list this as "peak power"
        For some inverters, this value is double the continuous value,
            so you may wish to set this to a lower value in order to favor more space
            to display lower values.
    
    Inverter caution power is the maximum power the inverter can produce under the best conditions
        (low temperature, etc.). This is the transition between yellow and red regions on the gauges.
        The inverter spec sheet will list this as the maximum continuous power at low temerature.
    
    Inverter max continuous power is the power the inverter can produce indefinately.
        This is the transition between the green and yellow regions on the gauges.
        The inverter spec sheet will list this as the maximum continuous power at the highest operating temerature.
            
    Max power Loads on Output is the maximum power accepted by devices
        that will be powered by the inverter.
        For example, this is could be the power equivalent to the AC breaker.
        If you do not want this limitation, set the value to 0.

    Max power Loads on Input is the maximum power accepted by devices
        that will be powered only by Grid/Shore power.
        If you do not want this limitation, set the value to 0.
    
    Grid feed-in limit provides the gauge range for power flow INTO the AC input of the system.
        Generally, this should be 0 unless ESS has been configured to feed energy into the grid.
        Note there are other system settings that control the actual grid feed-in.
        This parameter is ONLY for the gauge and is provided because feed-in logic is very complex.
    
    Max power Multi/Quatro charger is the maximum power the charger portion of the inverter will DRAW
        from the AC input. This is generally close to the Continuous Power above but may need some
            experimentaion to display properly without showing an overload.
        Note that the gauge will show power to the left of the zero line when it is charging the battery
            or when it is supplying the DC system loads.
    
    Max PV charger power is the maximum power expected by all PV chargers in the system.

    Max power PV inverter on AC Input is the maximum power expected from all of the PV inverters
        tied to the grid side of the system
        
    Max power PV inverter on AC Output as above for
        the PV inverters attached to the output side of the system.
    
    Max battery discharge current is used for the battery gauge and is the maximum sustained battery draw.

    Max battery charge current is used for the battery gauge and is the maximum sustained battery charging current.
        This parameter, used only for the battery gauge has been added, but should generally be set
            to the same value as the DVCC max charge current.
        It should be set the same as the DVCC max charge current if DVCC is used.

    Max DC load power is the maximum of all DC loads in the system.
        This is usually the DC main breaker/fuse size in amps multiplied with the DC voltage.
        So a 60 amp main breaker on a 12 volt system would be 720 watts.
        If there are no DC loads, set this value to 0.

    Max DC Charger power is the maximum lf all DC charging sources such as a DC-DC converter from the starter battery
        or a wind generator. Set this parameter to the expecte maximum for all charging sources.

    The last two parameters also affect the naming of the DC System tile.
        If the DC Charger power is set to zero but the DC load power is not zero, tile will read DC Loads
        If the DC charger power is not zero but the DC load power is zero, the title will read DC Chargers
        Otherwise, the tile will have a name of DC System indicating there are both loads and charging source.

Installation:

This script should be run manually initally.
It will then called from reinstallMods to reinstall functionality after a Venus update

The easiest way to install GuiMods is to use do "blind install" which installs
    from an SD card or USB stick without any terminal interaction:
    
    1) Download venus-data.tgz from the GitHub repo.
    2) copy it to the root of a freshly formatted SD card or USB memory stick
    3) place the media in the GX device (Cerbo, CCGX, etc)
    4) reboot the GX device TWICE
        after the second reboot, you should see the GUI restart and display
        the enhanced flow overview from GuiMods2
        If GuiMods2 was previously installed, the Grid Parallel overview
            is automatically selected
    5) remove the media from the GX device to prevent the next reboot from
        starting the process all over again

    CAUTION: This mechanism overwrites /data/rcS.local !!!!
        If you are using rcS.local to perform boot-time activities,
        /data/rcS.local must be recreated following this "blind" install
        Note that SetupHelper and GuiMods2 also use /data/rcS.local for
        reinstallation following a firmware update so use caution in
        recreating rcS.local.

    venus-data.tgz is available here:
        https://github.com/kwindrem/SetupHelper/raw/main/venus-data.tgz
    and here:
        https://github.com/kwindrem/GuiMods/raw/main/venus-data.tgz
    One may be newer than the other. In any case, automatic updates
        will update any package that is out of date following the blind install


There are two other methods to fetch a package archive:

If the Venus device has internet access is to run the following command:

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

If the Venus device does not have internet access, you will need to fetch the archive using a computer that does have internet access:

click on this link in a web browser:
https://github.com/kwindrem/GuiMods/archive/current.tar.gz

rename the resulting .tar.gz file to venus-data.tar.gz
copy the venus-data.tar.gz to a USB stick,
put the stick in the Venus device and reboot.
When Venus boots, it will unarchive the file to /data/GuiMods-current

Move the directory into it's active locaiton:
rm -rf /data/GuiMods
mv /data/GuiMods-current /data/GuiMods

Repeat the above for SetupHelper if you haven't done so for another package.

Finally, run the setup script to complete the installation
/data/GuiMods/setup

You will need root access to the Venus device. Instructions can be found here:
https://www.victronenergy.com/live/ccgx:root_access
The root password needs to be reentered following a Venus update.
Setting up an ssh authorization key (see documentation referenced above) will bypass the password request at login
and avoid having to reset the root password after each update.

Note that installing GuiMods will uninstall GuiMods2.
Installing GuiMods2 after installing GuiMods will uninstall GuiMods.