ReadMe

Recent changes:
	ExtTransferSwitch functionality has been merged into GuiMods
	ExtTransferSwitch is now obsolete and will be uninstalled by GuiMods

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


This package provides the following modifications to the VenusOS GUI:
	A "dark mode" for all overviews and menu pages
		A toggle in the Display & Languages menu switches between light mode and dark mode
		In addition, a touch area is available in the tool bar for the same switch.
		Note that this can not be accessed via the CCGX hard buttons or those on the remote console.

	A simple "flow" overview:
		This overview provides the tiles for AC in and out, inverter, battery, Solar (PV) charger
			and in some cases PV inverters.

	A flow overview that displays more AC system components:
		This overview is useful when ac-coupled PV inverters are present in the system.
		Tiles have been reduced in size to make room for the additional components.
		Except for the battery, only a gauge and a total power number are displayed

	A flow overview that displays more DC system components:
		This overview is useful when an alternator or other DC components are present in the system.
		Tiles have been reduced in size to make room for the additional components.
		Except for the battery, only a gauge and a total power number are displayed

	For all three overviews, additional details are displayed on full screens devoted to that part of the system.
		Tapping the center of the tile 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"

	In the Victron 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 three flow overview versions.

	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
		Alarm indicaiton: The temp tile alternates between its normal color and red if an alarm condition exists
			Note that the alarm condition must be assigned to a relay for the display to show the alarm

	Move Settings and Notifications
		Moves thise items to the top of the Device List page
			Normally, they are displayed at the bottom

	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 temperature sensors to tanks column
			The tanks column is split into separate columns for tanks and temperature sensors
			A common tile height is set for both columns, then each column is filled in separately
			Any tank that appears 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

	Uses 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 replace "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 available 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.
		Generator 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.

	Adds a an Overview page that shows tanks, temperature sensors and digital inputs.
		This provides a larger view than is available elsewhere
		and uses separate columns for tanks, temps and digital inputs

	Generator overview:
		now includes a button that enables and disables auto run functionality.
			It functions exactly like the manual start/stop button.
			Because two buttons share the hard buttons, up and down buttons are used to select
				which function will be controlled by the center button.
		In the Manual Start popup, scrolling down from Start manually selects a mode which
			will start the generator manually and stop it when all auto stop conditions are satisfied

		Status and test run tiles have been combined and now includes current run time as well as
			time until a timed manual run expires.
		A new Run Times tile has been included which shows times for Today, total accuulated time and
			a count-down to the next required servive
			The service interval is set in the generator settings menu
			as well as a button to reset the count-down timer to the service interval.
			If the service interval is 0 the service number will not be shonw in the Generator overview
		Run times previously used days/hours, hours/minutes, or minutes/seconds formatting. This has been changed
			to show minutes (if less than 1 hour) or hours to be more consistent with generator total run time and service intervals.
		Note: a button in the generator settings menu already exists to set the total accumulate time
			to match the run time meter on the generator itself.
		
		A digital input configured for generator run/stop integrates with the generator manual start/stop logic.

		When the digial input changes to the running state,
		Venus Manual Start is changed to true if there are no automatic run conditions

		When the digital input changes to the not running,
			Venus Manual Start is changed to false

		The Generator overview includes "Running" or "Stopped" in the generator icon if a digital input
			has been configured for generator run status input.

each of these enhancements/modifications can be selected individually any time
    (while system is running) via the Settings Display GuiMods menu

The hard buttons available on the CCGX or other UIs without touch capability can now access the details pages
	UP and DOWN buttons cycle through the available selection.
	The active selection is indicated either by showing the touch target area
	In the details pages, selected button is indicated by a black border
	Pressing the "space" button while the selection is active simulates touching the region
	The active selection times out after 5 seconds.


Power Gauges

The power gauges provide an indication 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 relative 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 its 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 relative 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.
    Charger priority: Grid / Renewable
        When enavled in the Multi/Quattro, the charger priority buttons appear in the Inverter detail page.
        Renewable allows solar and wind power to charge the batteries, essentially ignoring the grid
          until a low battery voltage threshold is reached. The grid is then used to bring the battery to 100% SOC.
        If Grid is pressed, batteries are charged immediately via the grid (and other charging sources).
            When 100% SOC is reached, the system returns to Renewable priority

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 AC input detal page shows information for the active source: per-leg power, current and volage,
	as well as frequency and input current limit.
	In addition, voltage and frequency for grid/shore and generator AC inputs is shown
	to allow monitoring of a generator's voltage and frequency even when on grid power or visa-versa
	AC meters will populate this information for an input if present.
	Quattros may report information for both inputs (what information is reported by Quattro is unknown to me)
	Multis only have one input so only that input will be shown unless AC meters are present.
	

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
    
    Flow Overview selection - refer to the discriptioun above for what is shown in each flow version
		Victron stock
			This disables the GuiMods flow overviews so the ones supplied in by Victron are displayed
		GuiMods simple
		GuiMods DC Coupled
		GuiMods AC Coupled

	Show more devices on flow overview
        Selects between a simpler and more complete overviews (described above).
        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.

	Tank bar format
		displays tank level percentage, actual remaining level (in units), or both

	Show battery temperature on flow overviews
		This preference controls whether battery temperature(s) are shown or hidden on the flow overviews
		Due to space constraints, users may or may not wish to display battery temperature(s)
		Battery temperature(s) are always shown on the Mobile and tanks/temperature/digital inputs overview

    Combine AC input/output loads
        The enhanced flow overview displays two load tiles: Loads on Input and Loads on Output.
        Confusion is likely 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.
    
	DC System tile name
		Renames the DC System tile. This may be useful if for example the system only has DC loads.
		In that case, the tile can be renamed to something like "DC Loads".
		If this paremeter is blank, "DC System" is used for that tile's name

    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.
    
	Replace AC in if inactive
		Some systems do not have an AC generator but do have an alternator connected as a battery charger.
		In these systems, the alternator information is displayed as if it were the system's generator.			

		When this option is on, a DC alternator is displayed as a secondary "generator", replacing the
			AC generator information when the AC input is not present.
		The AC input tile on the GuiMods Simple Overview page is replaced
			with an Alternator tile if this option is on, an alternator exist
				and the AC input is not present.
		The GENERATOR POWER tile on the enhanced Generator Overview is replaced
			with an ALTERNATOR POWER tile if this option is on, an alternator exists
				and the AC input type is not generator or the generator is not producing power.

    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.

	Watts / Killowatts threshold
		Controls the switch between showing values as W, A, V and KW, KA, KV
		The spinner range is from 1000 to 10000
		The default is to switch at 1000
        
    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 installed 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 temperature.
    
    Inverter max continuous power is the power the inverter can produce indefinitely.
        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 temperature.
            
    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
            experimentation 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 of all DC charging sources such as a DC-DC converter from the starter battery
        or a wind generator. Set this parameter to the expected maximum for all charging sources.

	Max Alternator power is the maximum power expected from all alternators in the system

	Max Wind Generator power is the maximum power expected from all wind generators in the system

	Max Fuel Cell power is the maximum power expected from all fuel cells in the system

	Max Motor Drive load power is the maximum power expected from all motor drives when they are consuming power

	Max Motor Drive charge power is the maximum power expected from all motor drives when they are generating power

Generator enhancements:
	A digital may be programmed to communicate generator running state to the GX device
	Pulling that digital input low signals the generator is running.
	Releasing the input so it floats high signals the generator is not running.

	If no digital input is programmed, the AC input for the generator 
		will be used to deternine generator running state

	A Quattro has two AC inputs with one typically connected to a generator.

	A MultiPlus has only one AC input and it will typically be switched between grid/Shore and generator.
	If this is the case, there will be no generator running state available when on grid/shore power.
	In this case, it is best to use the digital input to signal generator is running.
	An alternative would be to install an energy meter on the generator output.
	This will provide generator AC status at all times even if the Multi is fed by grid power.
	
	Running / Stopped status appears in the generator icon in the Generator Overview screen if
		the GX device can detect it. Otherwise, nothing is added to the icon.
		Note that this differs from the Running and stopped indication in the Status tile.
		That information shows whath the GX device told the generator to do (run or stop),
		not what it is actually doing.

	If "Link to external state" in / Settings / Generator start/stop / Settings is on,
		a change in the running state received FROM the generator will synchoniize the Manual Start state
		to the status from the generator.
		This accommodates a situation where the generator might be started from somewhere else.
		
		Note: Link to external state is off by default. Previous versions of GuiMods (and GeneratorConnetor)
			did not have this switch and the digital input was always incorporated in the generator logic.

		If an auto run condtion exists but the generator reports it is not running, "External Override"
		is shown in the status area of the Generator Overview. This might happen if the generator fails
		to start or if the generator control is switched to local and not responding to the GX device's
		generator start relay.

	Link to external state should not be confused with "Detect generator at AC input".
	The latter enables a generator is not running alarm visible on VRM (and other places possibly).

	Manual start / auto stop
		It is possible to start the generator manually, but allow the auto start/stop logic
		to stop the generator when all stop conditions are satisfied.
		For example, of the SOC is programmed to start the generator an say 30% and stop at 90%,
			and if the current SOC is 60%, the generator will not start if auto start/stop is enabled.
			If the manual start/auto stop mode is triggered, the generator WILL start and run until
			the battery reaches 90%.
		
		Manual start/auto stop is initiated by first enabling auto start,
		then selecting Manual Start and scrolling DOWN below Start manually.
		"Run until: all auto stop conditions are met" is shown in the tile.
		Accepting this stop condition will trigger the event.
		
		Note that if all automatic stop conditions are currently satisfied, the generat will not be started.
		That is, if the battery is at 95% in the above example, the generator will NOT start.

External transfer switch:
	This supports an external transfer switch ahead of a MultiPlus AC input
	changing the AC input current limit and and AC source type based on on grid/on generator

	ExtTransferSwitch includes support for "renewable energy" prioritizaiton added in Venus OS 3.10.
		This also requires Multi firmware 506.
	Renewable energy priority shuts down the Multi/Quattro charger allowing solar, wind and other charging sources
		to charge the battery. Grid power is reneabled at a low SOC (battery voltage) set in the Multi configuration.
	In addition, switching the AC source to generator reenables Multi AC input charging.
		
	Note: changes added in Venus OS v3.00 and changes added to Multi/Quattro in fimware 502,
		support a generator on AC 2 in.
		These are required for this package to work on a Quattro's AC 2 input

	A GX device digital input is connected to the external transfer switch to indicate
		if the grid or generator is routed to the Multi's AC input
		This service then makes changed to the AC input current limit and AC source(type)
		grid/shore or generator

	External transfer switch configuration:

		Program a digital input for External transfer switch

		For Quattros, select if the transfer switch is connected to AC 1 in or AC 2 in.
			(for Multis, this selection does not exist since there is only one AC input.)

		Connect an output from the transfer switch to the GX device digital input to indicate
			if the grid or generator source is being routed to the AC 1 input of the Multi.

			The best signal to use is a grid power detection circuit.
				A simle relay across the grid is probably fine for this.
				This same signal would typically switch the transfer switch to the grid position.

			The transfer switch may change state based on generator power being present.
				If this is the case, the generator might not ever start when using this to feed the digital input.
				Install a separate grid power detection circuit to insure proper behavior.

			Verify that the On Grid / On Generator state shown in the Device List tracks the actual state
				of the transfer switch. If it is backwards, change Inverted swich in the device's setup menu.

		While On grid, set the grid input current limit and grid type (grid or shore).

		Cause the transfer switch to change state and while On Generator, set the input current limit again,
			this time for the generator values.

		Now the input current limit will switch between the grid and generator settings.

		If you make changes to the input current limit, those changes will be remembered and restored when the transfer switch
		returns to that position again.

		If you wish to prevent the generator from running when On Grid, make sure the system is not On Generator and
			turn on the Do not run generator when AC1 is in use in:
				Device List / Settings / Generator start/stop settings /Settings / Conditions
			The transfer switch logic will turn this off when switching to On Generator and restore it when switching to On Grid.

Installation:

GuiMods requires that SetupHelper is installed first.

The easiest way to install GuiMods is to do a "blind install" of SetupHelper
	and then add the GuiMods package via the PackageManager menus.

Refer to the SetupHelper ReadMe for instructions and for other install options:
	https://github.com/kwindrem/SetupHelper


Note that installing GuiMods will uninstall GuiMods2.
Installing GuiMods2 after installing GuiMods will uninstall GuiMods.
You should not use GuiMods2 !!!