Read past values of a global with GH#

A global normally holds one value, the current one. Every time the preset is saved Kustom also keeps the old value in a small history, and $gh()$ is how you read it back. This is what you use to show a trend, a delta, or a small chart of how a value moved over time.

$gv(name)$ gives you the value now, $gh(name, 0)$ gives you the same thing, and $gh(name, 1)$ gives you the value before that.

How the history moves#

Think of the history as a list where index 0 is always the newest. Each new saved value pushes everything one step down.

So with a global called level sitting at 88, this formula

now $gh(level,0)$   prev $gh(level,1)$   before $gh(level,2)$

renders as

now 88.0   prev 62.0   before 45.0

Number globals keep a decimal part, so they print as 88.0 and not 88. Wrap the call in $mu()$ if you want a whole number, for example $mu(floor, gh(level,0))$ gives you 88.

One thing to know while you are editing. The new entry is written as part of the save, so right after you press Save the big preview on top still shows the previous values, while the item list below already shows the new ones. The stored history is correct in both cases. The preview picks it up when the preset is loaded again, so if the two do not match, trust the list.

History only exists after a save#

This is the part that trips most people up. $gh()$ only reads, it never writes. The history row is written when the preset is saved, so a global you just created has no past values yet and every $gh()$ returns empty. Set the value, save, set it again, save again, and the history starts to fill.

You can also change how often it stores. Go to Advanced Settings and look for “Global persistence”. “If changed” is the default and stores a value only when it is different from the last one, “Always” stores on every save, and “Never” disables history completely. If $gh()$ is always empty, check that setting first.

Using an index or a time#

The second argument works in two ways. Anything from 0 to 999 is treated as an index, so $gh(level, 5)$ means five values back. Anything from 1000 up is treated as a unix timestamp in seconds, and Kustom returns the value that was current at that moment.

To ask for “the value 30 minutes ago” you build the timestamp with $df()$ using the S specifier, which is seconds since epoch.

$gh(level, df(S, r30m))$

Show the whole series with one formula#

Because the index is just a number you can loop over it with $fl()$ instead of writing one formula per value. The loop variable is i, so you feed it straight into $gh()$.

$fl(0, 2, "i + 1", "gh(level, i)", " | ")$

With the same history as above that renders

88.0 | 62.0 | 45.0

Change the second argument to go further back, and change the separator to whatever you like. This is the quickest way to print a small trend line in a single text item.

If you want real bars instead of numbers, put a Progress or a Shape item inside a Stack Group and use the same idea, one item per index, with the value set to $gh(level, 0)$, $gh(level, 1)$ and so on.

Notes#

• Index 0 and $gv()$ are the same value, both are the current one
• A missing history entry returns empty, not zero, so wrap it if you need a number
• Deltas work normally, $gh(level,0)-gh(level,2)$ gives you the change over two steps