# Creating and Using Lua scripts

<p class="callout warning">
  Lua scripting is an advanced topic. eGauge Support has limited support for
  troubleshooting Lua scripts and cannot review Lua code.
</p>

<p class="callout danger">
  Use caution and test extensively when using Lua scripts for automated
  control of remote devices to prevent unexpected operation or damage to
  connected equipment.
</p>

<p class="callout info">
  <b>Use the latest firmware</b>: Lua support was added in eGauge meter
  <a href="https://www.egauge.net/revs/#4.1">firmware version 4.1</a>. However,
  bug fixes and new features this article refers to may have been added in
  newer firmware versions.
  <a href="https://kb.egauge.net/books/egauge-meter-ui/page/checking-and-upgrading-firmware">
    Click here</a>
  for information about checking and updating a meter's firmware. 
</p>

### Introduction

eGage meters have a <a href="https://www.lua.org/about.html" target="_blank">Lua</a>
scripting environment that allows for creation of advanced formula register and alert
functions, as well as automated control of supported devices such as the
[eGauge PRM3 Power Relay Module](https://www.egauge.net/support/m/prm3).

Refer to the
[Lua Scripting Overview](https://kb.egauge.net/books/advanced-egauge-operation/page/lua-scripting-overview)
article for a general Lua primer and additional modules provided by the eGauge
firmware.


### Lua scripting interface

[![](https://kb.egauge.net/uploads/images/gallery/2024-04/scaled-1680-/image-1714160404297.png)](https://kb.egauge.net/uploads/images/gallery/2024-04/image-1714160404297.png)

Several keyboard shortcuts are displayed when the interface is loaded:
- `F1`: Open the keyboard shortcuts menu
- `F2`: Toggle the sidebar on the right
- `Ctrl-␣`: Toggle auto-complete
- `Ctrl-,`: Open the GUI settings menu

When using Mac, use the ⌘ key instead of Ctrl.

The eGauge web interface has a built-in Lua script editor with 3 panes as shown in the above screenshot.

- **Editor** (_top left_)— The Lua code editor. There are 4 buttons for this pane:
  - [1] Save: This saves the functions and makes them available for use by the meter.
  - [2] Search: This allows to search for and replace text in the code.
  - [3] Upload: This replaces the current script on the meter with a file upload.
  - [4] Download: This downloads the current script from the meter as a file
- **Output log** (_bottom left_)— Below the editor, the Lua log is displayed.
  This will include any script errors or print statements. If there are no
  custom Lua functions for the script loaded, there may be an error such as
  "Lua error: cannot open xxx.lua: No such file or directory", and this error may be
  ignored. There are 4 buttons available for this pane:
  - [5] Filter: Apply a filter to only output log lines containing certain text
  - [6] Autoscroll: Toggles auto-scrolling to the most recent log output
  - [7] Download: Downloads the log file
  - [8] Maximize Window: Maximizes the log output window
- **Sidebar** (_right_)— the sidebar on the right-hand side provides a method explorer
  to find and describe all available eGauge-provided functions and modules. The function
  or module may be clikced on to automatically insert it into the Editor pane to the left.
  The sidebar has a search bar [9] to conveniently search through methods, functions and
  documentation


#### Accessing the Lua scripting environment

1. If using the classic interface, click on View &rarr; Modern user-interface:
<div style="text-align: center">
  <img style="width: 50%; height: auto" src="https://kb.egauge.net/uploads/images/gallery/2024-04/image.png"/>
</div>

2. Navigate to Setup &rarr; Lua and choose the appropriate script type:
<div style="text-align: center">

  <img style="width: 50%; height: auto" src="https://kb.egauge.net/uploads/images/gallery/2024-04/scaled-1680-/image-1714168394310.png" />
</div>

#### Script Types

Click to expand information for the script type:

<details>
  <summary>Formulas script (formula registers)</summary>
  Creating lua functions in the Formulas script editor will allow the functions
  to be used in a formula register.
  
  For example, here are two functions made in the Lua Formulas script editor
  that will return the min or max of two numbers:
  ```lua
-- function returning the larger of two numbers
function lua_max(num1, num2)
   if (num1 > num2) then
      result = num1;
   else
      result = num2;
   end
   return result;
end

--function returning the lesser of two numbers
function lua_min(num1, num2)
   if (num1 < num2) then
      result = num1;
   else
      result = num2;
   end
   return result;
end
```

  They may then be used in a formula register:

  [![](https://kb.egauge.net/uploads/images/gallery/2023-02/scaled-1680-/image-1676407153301.png)](https://kb.egauge.net/uploads/images/gallery/2023-02/image-1676407153301.png)

  And we may see the registers work as defined by the script functions:

  [![](https://kb.egauge.net/uploads/images/gallery/2023-02/scaled-1680-/image-1676407218019.png)](https://kb.egauge.net/uploads/images/gallery/2023-02/image-1676407218019.png)
</details>

<details>
  <summary>Tariff script (Advanced time-of-use and tiered billing)</summary>
  Advanced time-of-use and tiered billing may be performed in this Lua scrript.
  <br/><br/>
  

  A tariff script should provide (at least) a
  <span style="font-family: monospace;">
    cost(<i>register</i>, <i>negate</i>, <i>schedule</i>)
  </span>
  function which calculates the incremental cost based on the energy-use
  recorded by register.   _negate_ can be set to true if the register's value
  counts down for power consumption.   _schedule_ is optional and can be set to
  the (non-default) name of the schedule to use when calculating the cost.
  
  A formula register of type "monetary" would be used with the `cost()`
  function.
  
  For an example billing script, from the classic interface:
  1. Navigate to Settings &rarr; Billing.
  2. Choose Xcel Colorado as the tariff provider.
  3. Click "OK" to save and go back to the main settings page.
  4. Go back to Settings &rarr; Billing.
  5. Change the tariff providert to "custom"
  6. Click the "Customize tariff script" button, which will open a copy of
  the Xcel Colorado billing tariff in the Lua script editor.
</details>

<details>
  <summary>Alert script</summary>
  Alerts scripts work the same as Formula scripts, but are used in eGauge meter
  alerts, configured in Settings &rarr; Alerts.
</details>

<details>
  <summary>Control scripts</summary>
  <span id="bkmrk-lua-control-script">
  <p class="callout info">
    See the main
    <a href="https://kb.egauge.net/link/321#bkmrk-lua-environment-for-" target="_blank">
      Lua Scripting Overview</a>
      Control Scripts section for additional Lua Control environment
      information.
  </p>

  <p class="callout warning">
    There is risk of damaging external equipment using control scripts.
    Only skilled Lua developers familiar with the eGauge meter and software
    should attempt to use Lua control scripts.
  </p>

  Control scripts can be used to confrol supported equipment such as the eGauge
  Power Relay Module (PRM3).

  For example, the following script reads the instantaneous value of a register
  called "Temperature" and controls a PRM3 relay contact. If the temperature is
  lower than 21 C, relay number 0 of the PRM3 is closed (activated), otherwise
  opens (turns off) relay number 0. It then sleeps for 15 minutes before checking
  again.

  In the real world, the control script should be more advanced 
    
  <pre><code class="language-lua">dev = ctrl:dev({interface='relay'})
  relay = dev:interface('relay')

  while true do
    print("Temperature is currently: " .. __r("Temperature"))
    if __r("Temperature") &lt; 21 then
        relay:close(0)
    else
        relay:open(0)
    end
    sleep(60*15)
  end</code></pre>
  </span>
</details>

<details>
  <summary>Persistent variables</summary>

  See the main [Lua Scripting Overview](https://kb.egauge.net/link/321#bkmrk-module-persistent) section on Persistent variables.

  Persistent variables are variables that are preserved between reboots or power cycles.
  
  The following Formula script creates and updates a peristent variables with a given name
  and number passed to it in a formula register, and prints debug to the output log:
  
  <pre><code class="language-lua">function persistent_variable_example(name, number)
  
     obj = persistent:new(name, number, "Variable stored by formula function persistent_variable_example")
  
     current_value = obj:get()
     print(name .. " currently has value " .. current_value)
  
     print("updating " .. name .. "to new value " .. number)
  
     obj:set(number)
  end
  </code></pre>
  
  A register is configured to run the formula script:
  
  [![](https://kb.egauge.net/uploads/images/gallery/2023-02/scaled-1680-/image-1676411385422.png)](https://kb.egauge.net/uploads/images/gallery/2023-02/image-1676411385422.png)
  
  This creates or updates a persistent variable called "variable test 1" with the current time.
  
  The Formula script editor shows the print debug as the variable is updated once a second
  as the formula register is run:
  
  ```
  15:26:28.168 variable test 1 currently has value 22.043333333333
  15:26:28.168 updating variable test 1 to new value 22.043611111111
  15:26:29.171 variable test 1 currently has value 22.043611111111
  15:26:29.172 updating variable test 1 to new value 22.043888888889
  15:26:30.168 variable test 1 currently has value 22.043888888889
  15:26:30.168 updating variable test 1 to new value 22.044166666667
  15:26:31.168 variable test 1 currently has value 22.044166666667
  15:26:31.168 updating variable test 1 to new value 22.044444444444
  ```
  
  While this particular example is rather pointless, persistent variables may be used in any Lua scripts.
  Control scripts are executed continuously, and a formula register would not need to be created to run it.
</details>