Scripting Reference Manual

DE-4000 Series Configurable Safety Shutdown and Control System

Form DE-4000 SRM 4-20

DE-4000 OCM 9-19

All rights reserved © ALTRONIC, LLC 2019 1
DE-4000 Scripting Reference Manual

One overarching capability that allows a bridge to gap the standard needs of everyday
systems and the customer needs of innovation is scripting. A scripting language,
cleverly named Lua, is embedded into the DE-4000 system. It operates as a script
mainly meaning that it does not need additional tools to convert the “code” into
machine language. It also is looked at and corrected for errors every time the script
runs. Therefore it is an “interpreted” language and runs all of the time when you ask it.
Lua comes with a background of being robust, fast, and geared towards embedded
applications, with a proven track record in the gaming industry. For the DE-4000
system it is small and fits in the memory we have available, holds a lot of power, and
keeps it simple for writing in the language.
All information regarding the Lua scripting language is located at https://Lua.org
Using the Lua engine as an embedded tool allows for taking advantage of a full
architecture and standard at your fingertips. Within the language there are all of
the normal attributes to programming such as functions, variables, statements,
expressions etc. All of this reference material can be found at https://lua.org/
manual/5.3/
For getting started and using a guided reference, there are several editions of
“Programming in Lua” available. Most recent editions are a paid for product that
come in paper back or ebook form. While testing out Lua and becoming familiar, a
free first edition is available and covers a lot of learning needs to get comfortable with
the language. It can be located at https://www.lua.org/pil/contents.html.
A major advantage to using Lua is its inherent ability to allow custom functions. While
all normal functions and calls are published, there is the ability to add new functions
in the DE-4000 firmware. Once new functions are defined and have calls to their
internal properties, they then can be published for the user. This includes functions
such as our flexible Modbus table and talking with various terminal boards linked in
the system. Below is the start to the list of Altronic based functions. As functionality
and features come to life through new ideas, this document will continually get
updated with the latest scripts that we make available.

GETTING STARTED WITH DE- 4000 SCRIPTS

Basic Scripting on DE4000

1. Begin on Dashboard on DE4000 system environment

DE-4000 SRM 4-20

All rights reserved © ALTRONIC, LLC 2020 2
2. Choose “Global” from menu on left side of screen

3. In the Sub-Menu on the Left side select “Scripts”

DE-4000 SRM 4-20

All rights reserved © ALTRONIC, LLC 2020 3
4. Select one of the page icons under one of the 4 script options to open editor

5. Scripting can be entered into the editor.

DE-4000 SRM 4-20

All rights reserved © ALTRONIC, LLC 2020 4
Scripting Windows and examples

• Master Script
The Master Script section is the Primary scripting environment.
Primary scripting functions can be written in this section.
Example:
local suction = get_channel_val(1,1) :This line gets the channel value from Terminal
board 1 Input 1 and stores it in local variable names suction
local discharge1 = get_channel_val(1,3) :This line gets the channel value from
Terminal board 1 Input 3 and stores it in local variable names discharge1
diff = discharge1 - suction : This line takes the discharge1 pressure and subtracts the
suction pressure and stores it in the global variable named diff (NOTE: Any value that
you want to access from another scripting section must be stored in a global variable.
This is used most in calling values into Modbus registers as explained below)
set_sVirt(“Difference”, diff) :This line copies the value from diff and stores it into
the Virtual status channel named “Difference” This channel can be displayed on the
Dashboard

• Control Script
The Control Script section is primarily used for valve control scripting.

• Modbus Script
The Modbus Script section is used to move data into and out of
Modbus registers

defaultModbus() This line pulls in the factory set Modbus mapping

set_modbus(300,diff) This line moves the value from the global variable named diff
into the 40300 Modbus Register

DE-4000 SRM 4-20

All rights reserved © ALTRONIC, LLC 2020 5
CUSTOM FUNCTIONS FOR SCRIPTING

create_param(“index”,default,”category”,”description”)
Create a user configurable parameter
Parameter is stored as “index”
Default value (if not changed by user) is default
Parameters will be grouped on the Global/Params page by category
Description is text to describe the parameter to the user
Example:
create_param(“NumEngCyl”,8,”Engine Params”,”Num. of Engine Cylinders”)
Related function(s): get_param()

get_channel_label(terminal,channel)
Return the label for the input channel defined by terminal, channel
Example:
-- Read channel label for terminal 1, channel 7
local chanLabel = get_channel_label(1,7)

get_channel_long_label(terminal,channel)
Return the channel label, but leave off the short label if defined
Note: A channel can be assigned a short label in the DE4000 channel configuration page. The short label is defined at the
end of the channel label and is enclosed in parentheses.
For a suction pressure channel you would define the channel label as: Suction Pressure (SP)
In this case the channel short label is SP
This function will return the long label defined above as Suction Pressure

Example:
-- Read channel long label for terminal 1, channel 7
local shortLabel = get_channel_short_label(1,7)
-- Returns “Suction Pressure”

get_channel_short_label(terminal,channel)
Return the short label for a channel if defined, otherwise return the channel hash
Note: A channel can be assigned a short label in the DE4000 channel configuration page. The short label is defined at the
end of the channel label and is enclosed in parentheses.
For a suction pressure channel you would define the channel label as: Suction Pressure (SP)
In this case the channel short label is SP
If the channel short label is not defined the channel hash will be returned. For example, the channel hash for Terminal 1,
Input channel 12 is T1:IN12

Example:
-- Read channel short label for terminal 1, channel 7
local shortLabel = get_channel_short_label(1,7)
-- Returns “SP”

DE-4000 SRM 4-20

All rights reserved © ALTRONIC, LLC 2020 6
get_channel_val(terminal,channel)
Returns current value of analog input channel on terminal module terminal
Return value type is numeric
Example: (reads value of Suction Pressure from terminal module #1, IN5)
local sp = get_channel_val(1,5)

get_gbl(“index”,default)
Return global config setting stored under index or return default if not defined
Note: get_gbl is used to retrieve global CONFIGURATION settings that are typically set when the system is configured and
do not change as the system is running.
If you want to set and retrieve global STATUS variables use the get_sGbl() and set_sGbl() functions. If you want to create
and read virtual channels use the set_sVirt() and get_sVirt() functions.
Example: (get the number of terminal boards installed in the system)
local nt = get_gbl(“NumTerm”,1)

get_modbus(register)
Return the value stored in a 40000 block Modbus register
Note: This function returns values from the 40000 block of registers. In other words, passing the value of 250 into this
function will return the value stored at Modbus register 40250
Example:
local regVal = get_modbus(250)
set_sVirt(“Reg40250”,regVal) --create virtual channel with
--value from register 40250
Related function(s): set_modbus()

get_param(“index”)
Return either the default value or the user configured value of the parameter index
Example: (get the configured parameter for number of engine cylinders)
get_param(“NumEngCyl”)
Related function(s): create_param()

get_rpm(channel)
Reads the RPM input channel in units of revolutions per minute
Note: valid channel numbers are 1 – 10 (2 channels each per 5 possible Terminal Modules)
Each Terminal Module has 2 RPM inputs (RPM1 and RPM2)
Terminal Module #1 RPM channels are 1,2
Terminal Module #2 RPM channels are 3,4
Terminal Module #3 RPM channels are 5,6
Terminal Module #4 RPM channels are 7,8
Terminal Module #5 RPM channels are 9,10
Example: (read RPM1 channel on Terminal Module #1
and RPM2 channel on Terminal Module #3)
local engineRPM = get_rpm(1)
local turbuRPM = get_rpm(6)

DE-4000 SRM 4-20

All rights reserved © ALTRONIC, LLC 2020 7
get_sGbl(“index”,{default})
If “index” is defined in the global status table, returns the value associated with “index”
If “index” is not defined and optional {default} is provided then returns {default}
Note: It is recommended to always provide a default value when using this function
Example: (get the previously stored value “calculatedPressure”, return 0 if not found)
local cp = get_sGbl(“calculatedPressure”,0)
Related function(s): set_sGbl()

get_state()
Return the current engine state (possible values are currently 0 - 10)
Example:
local engineState = get_state()
if engineState > 7 then
set_timer(“WarmupTimer”,1000)
end

get_sVirt(“index”,default)
Returns the value of virtual channel index or returns default if the virtual channel does not exist
Example: (get the value of the virtual channel ElapsedTime and set value of status global “timeExceeded” if ElapsedTime
is greater then status global “timeLimit”)
local tl = get_sGbl(“timeLimit”)
local et = get_sVirt(“ElapsedTime”,0)
if et > tl then
set_sGbl(“timeExceeded”,true)
else
set_sGbl(“timeExceeded”,false)
end
Related function(s): set_sVirt()

get_time()
Return the Unix “epoch” time (defined as number of seconds elapsed since Jan 1, 1970)
Note: you can measure elapsed time by storing a get_time() value at one event and later reading the current get_time() and
then subtract the first time from the second time
Example: (store current time if first time through, otherwise calculate elapsed time)
local startTime = get_sGbl(“startTime”,0)
if startTime == 0 then
local currentTime = get_time()
startTime = currentTime
set_sGbl(“startTime”,currentTime)
end
local et = get_time() - startTime
set_sVirt(“ElapsedTime”,et)

DE-4000 SRM 4-20

All rights reserved © ALTRONIC, LLC 2020 8
get_timer(“index”)
Returns 1 or 2 values
First return value (boolean) is true if timer is active(counting down) or false if timer is expired or false if time has not been set
Second return value is number of seconds remaining or -1 if timer is not active or -1 if timer has not been set
Example: (if timer is expired, then set global status “timedOut” to true)
if not get_timer(“myTimer”) then
set_sGbl(“timedOut”,true)
else
set_sGbl(“timedOut”,false)
end
Example: (set virtual channel to show number of remaining seconds)
local active,remaining = get_timer(“myTimer”)
if not active then
set_sVirt(“timeRemaining”,”Expired”)
else
set_sGbl(“timeRemaining”,remaining)
end

Related function(s): set_timer()

RandomVariable(length)
Create a string composed of random alpha/numeric text. The length of the returned string is passed in as length

Example:
-- get a random string 10 characters long
local randomText = RandomVariable(10)
-- returns a random string such as “AIqbFfzQ68”

set_modbus(register,value)
Set a value into a 40000 block Modbus register
Note: This function sets values into the 40000 block of registers. In other words, passing the register parameter of 250 into
this function will set the value stored at Modbus register 40250
Example:
-- Read channel value at Terminal 1, channel 5 and write
-- to Modbus register 40250
local chanVal = get_channel_val(1,5)
set_modbus(250,chanVal)

Related function(s): get_modbus()

DE-4000 SRM 4-20

All rights reserved © ALTRONIC, LLC 2020 9
set_sGbl(“index”,value)
Store value in the global status table under “index”
Value can be a number or a string but if storing a boolean, use tostring()
Example: (store boolean value “minPressureExceeded”)
local mpe = false
local sp = get_channel_val(1,5)
if sp > 15 then
mpe = true
end
set_sGbl(“minPressureExceeded”,tostring(mpe))

Related function(s): get_sGbl()

set_sVirt(“index”,value)
Sets a virtual status channel with channel name index
Note: once you create a virtual channel, you can add that channel to the dashboard using the channel name index
Example: (calculate differential between suction and discharge pressure and assign to virtual channel)
local sp = get_channel_val(1,5) --suction pressure
local dp = get_channel_val(1,6) --discharge pressure
local diffPress = dp - sp
set_sVirt(“SuctDischDiff”,diffPress)

Related function(s): get_sVirt()

set_timer(“index”,secs)
Activate timer “index” and set countdown time to secs
Example: (create timer “myTimer” and start countdown time at 300 seconds)
set_timer(“myTimer”,300)

Related function(s): get_timer()

DE-4000 SRM 4-20

All rights reserved © ALTRONIC, LLC 2020 10