Lua Scripts in Helm 4.4

Helm 4.4 introduces some new concepts and capabilities for Lua script support. All existing Lua scripts should work unchanged but use of these new powerful features will require Helm 4.4 or later. This post gives an overview of the new features but does not list the Helm functions where these new features can be used. Functions shown here are for illustration only.

Return values from Helm functions

Previously, any ‘standard’ Helm functions called from Lua could not return values to the Lua script. A common pattern to work around this involves the Helm function updating a property, which can then be read by Lua:

H.MyDevice.UpdateSpecialProperty(param1, param2,...)
if H.MyDevice.SpecialProperty = "1234" then ...

Instead, new functions will allow you to write this:

if H.MyDevice.ReadSpecialProperty(param1, param2,...) = "1234" then ...

Passing Lua Tables to Helm functions

Previously, only simple Lua types like numbers, strings and booleans could be passed to Helm functions.

H.MyDevice.DoSomething(123, "Hello", false)

Now certain functions can take any Lua table as a parameter, allowing arbitrarily complex data to be passed in. Tables are also supported as return values. Helm’s new Facebook support uses this for sending and receiving data via the Facebook API.

local myTable = {)
myTable.name = "Joe Bloggs"
myTable.country = "UK"
myTable.age = 42

H.MyDevice.AddUser(myTable)

Functions can also return complex data as tables

if H.MyDevice.GetUser("Joe Bloggs").country = "UK" then ...

JSON Support

When tables are passed to a Helm function, they are encoded using JSON. So if you pass a table to a function expecting a string it will receive a JSON representation of the object. Also, if you print a table for debugging, you’ll now get the JSON representation.

--lua

local foo = {name= "Joe"}
print(foo)

A side-effect of this is that Helm panels don’t need to explicitly require the JSON library. This now happens automatically, so the line

JSON = require("JSON")

.. can be omitted from script startup.