Introduction

This article answers common questions about Lua scripting on [person] devices. It covers script errors, limits, examples and saving script outputs.

Scripting is based on Lua 5.4. The Lua VM runs together with the main device firmware (FW).

⚠️ Warning: Customers are solely responsible for creating, testing and validating their scripts. This includes scripts generated with the Scripting Assistant. Scripting Assistant does not review or guarantee user-created or AI-generated scripts.

1 My script does not work

Start with the checks below. They cover the most common reasons a script does not run.

1.1 The script does not start

Go through these checks in order:

Make sure your device is compatible: HCV5 Lite/Pro5 Lite, Smart5 or Eco5, with the newest firmware.
In the Advanced configurator, open the Scripting group element and tick Enable. The default state is Disabled.
Update the device configuration after enabling Scripting.
Check that the compiled *.lc file is uploaded. Compare Script timestamp and Script CRC in the configurator with your build.
Restart the script with the SMS command luarestart.

The Scripting checkbox is a master switch. If it is disabled, the script does not run, whatever else you send to the device. If it is enabled, the script starts automatically at every device initialization.

1.2 The script stops or shows an error

Send the SMS command lualasterr to get the last recorded script error. You can also run the USB debug log and watch the script output.

If compilation fails in the Advanced configurator, the error is shown in an additional dialog box. Fix the error and build again.

Common causes documented for script termination:

Calling io.get(ioID) for an I/O parameter that does not exist terminates the script.
Using a function outside the allowed basic library list (see 2.3 Available Lua libraries).

💡 Tip: Some I/O parameters must be enabled in the device configuration to return valid values. Enable every I/O parameter your script uses.

1.3 Only part of the script works, or it reacts with delays

Critical processes on the device affect how your script runs. Throttling keeps the script from disturbing the main firmware.

Script execution on average cannot take more than 10 % of device runtime. For example, no more than 100 ms in 1 second.
The end of the main loop MUST contain a pause. This returns control to the main device program.
Use a higher pause value to avoid throttling.
Track time since the last loop with a timer, so the code tolerates delays.

2 Limits and restrictions

2.1 Limits at a glance

Item	Value
Lua version	Lua 5.4
Maximum compiled script size	10 kB
Script share of device runtime	10 % on average (about 100 ms per second)
Dedicated output I/O parameters	10 per size, for sizes 1 B, 2 B, 4 B and 8 B
Scripting default state	Disabled

2.2 Compatible devices

HCV5 Lite/Pro5 Lite
Smart5
Eco5

Use the newest firmware version on these devices.

2.3 Available Lua libraries

These libraries can be used: basic (adjusted), math, package (only require), string and table.

Only these basic library functions are available:

assert, collectgarbage, error, getmetatable, ipairs, next, print, warn, rawequal, rawlen, rawget, rawset, select, tonumber, tostring, type

2.4 Examples

2.4.1 Read an I/O parameter

Include the IO library with require. It replaces the standard Lua library with the same name. io.get returns the size and the value of the I/O parameter.

local io = require("io") local size, value = io.get(29) -- Power supply voltage print("The current PSV is " .. value .. " mV")

2.4.2 Compile a script outside the Advanced configurator

Export the compiler in the Advanced configurator: Tools > Script compilation > Export compiler. Then compile with this command:

luac.exe -s -o out.lc in.lua

2.4.3 Try a ready example

The Advanced configurator includes the example Hello_world.lua. Use it for a first test with Build and Upload Script.

2.5 SMS and USB commands for script control

Command	Action
`luastop`	Stops the script if it is running.
`luastart`	Starts a stopped script.
`luarestart`	Runs `luastop`, then `luastart`.
`lualasterr`	Returns the last recorded script error.
`info luadt`	Returns the build datetime of the script on the device.
`info luacrc`	Returns the CRC of the script in device memory.

luastop, luastart and luarestart also work over USB in a terminal.

3 Saving script outputs

3.1 How can a script output a value?

Use io.set(size, slotNum, valueH, valueL). It writes a value to a dedicated I/O parameter of 1 B, 2 B, 4 B or 8 B. There are 10 independent I/O parameters for each size.

For values larger than 4 bytes, the value is split into high and low words. valueH carries the high bytes.

You can watch these I/O parameters with the Live IO function in the Tools section of the Advanced configurator.

3.2 Are variables or outputs kept after a device restart?

[TO BE CONFIRMED: whether script variables or written I/O values persist after reboot or script restart, and how they are stored or sent to the server.]

The script starts again at every device initialization.

4 Uploading and managing scripts

4.1 Upload with a USB connection

Connect the device to a PC by USB and update it to the latest FW.
In the Advanced configurator, click Options in the Scripting group element.
Click Build and Upload Script and select the *.lua file.
Enter the configuration password when prompted.
Tick Enable in the Scripting group element and update the configuration.

The compiled file is saved as inputFileName_UTCtimestamp.lc. Other options are Build Script, Upload Script, Get Script and Delete Script. Without a connected device, only Build is available.

4.2 Upload remotely

The configuration (CFG) file does not contain the Lua script. A script update cannot be done with the LCM config update feature.

Build the script in the Advanced configurator to get the *.lc file (Scripting > Options > Build script).
Make sure the device connects to DMP with the DCS (TCP) method, not MQTT.
Upload the *.lc file in DMP and set it as a configuration update for your devices.

If your device uses MQTT, contact [person] Support with the list of devices to switch to DCS. The uploaded file name is visible in the object's Operation history in DMP.

⚠️ Warning: Switching from MQTT to DCS recreates the device in DMP. Request the change only for devices that need script updates.

5 Support scope

Support helps with questions about the scripting feature itself. Support does not write, debug or review custom scripts.

If your goal is possible with standard device settings, check those first. For example, speeding detection in a geozone with a buzzer can be configured without scripting.

Review any script generated by the [person] Scripting Assistant before use. Test it on your device first.

Ruptela Lua Scripting