57.4. LUA SCRIPT Abilis extensions
Prev Chapter 57. LUA scripts Next

57.4. LUA SCRIPT Abilis extensions

In addition to functions in the standard LUA library, there are several functions specific for Abilis. All such functions are collected in the “abilis” name space that must be activated by this command:

local abilis = require "abilis"

57.4.1. Abilis CPX extensions (general purpose functions)

The functions in the “abilis.cpx” namespace allow to make various general purpose operations related to various parts of the Abilis system.

To use this extension add the following code into your Lua script

local abilis = require "abilis"
abilis.cpx.sleep
abilis.cpx.sleep(sec)

This function suspends the script execution for sec seconds. Decimal fractions are allowed, so the value 1.5 means 1500 milliseconds. The value is internally converted to whole number of ticks, where the tick period is 10 ms. This function doesn't have any negative impact on CPX performance, as it doesn't consume any CPU time.

Input parameters:

  • sec - time in seconds to sleep running script.

Return value:

  • No return value.

Example:

abilis.cpx.sleep(2.5) -- makes 2.5 second delay during current script
abilis.cpx.sendmail
retval = abilis.cpx.sendmail(from, to, subject, message, [filename], [mimetype])

This function sends mail via SMTP resource of the Abilis.

Input parameters:

  • from - mail message sender;

  • to - mail message target;

  • subject - mail subject;

  • message - mail message itself (body);

  • filename [optional] - filename of the file to attach to the mail;

  • mimetype [optional] - mail mimetype of the attachment, by default the ASCII encoded is used.

Return value:

  • retval - return error code of the Abilis SendMail(...) function, if success the 0 is returned; nil or true is never returned.

Example:

local mail_retval = abilis.cpx.sendmail(
	"lua@test.lan"
	,"test@test.lan"
	,"Lua report mail"
	,"Configuration of the Abilis"
	,"drivers.cfg"
	)
abilis.cpx.cls
retval = abilis.cpx.cls()

This function clear the Lua console of the Abilis web interface for Lua scripts.

Input parameters:

  • No input parameters.

Return value:

  • retval - true if cleared successfully, false when failed.

Example:

local retval = abilis.cpx.cls()

57.4.2. Abilis IOHUB extensions

The functions in the “abilis.iohub” namespace allow to obtain data from general purpose digital and analogue inputs, and to send data to general purpose digital and analogue outputs.

To use this extension add the following code into your Lua script

local abilis = require "abilis"
abilis.iohub.get_device_handle
device = abilis.iohub.get_device_handle(res, num)

This function takes the CPX resource name ("GPIO" or "MFIO" etc.) in the res parameter, and the resource number (i.e. 1 for GPIO-1, etc.) in the num parameter.

Input parameters:

  • res - device name, could be one of the following strings - "GPIO", "MFIO", "RIO" or "RVS";

  • num - device number, 1, 2, etc. (e.g. 1 for GPIO-1, 2 for GPIO-2, etc.).

Return value:

  • device - device handle that is used in subsequent functions.

abilis.iohub.get_digital_input
ok, value = abilis.gio.get_digital_input(device, line)

This function returns a value from the digital input of the specified device and line.

Input parameters:

  • device - device handle returned by previously called abilis.gio.get_device_handle function;

  • line - line index counted from 1 (e.g. 1, 2, 3 etc.);

Return value:

  • ok - boolean true if the operation succeeds (e.g. device is available) or false if the operation fails;

  • value - boolean true if the line is ON or false if the line is OFF.

abilis.iohub.get_digital_input_events
ok, events = abilis.gio.get_digital_input_events(device, line)

This function returns a number of state changes on the digital input of the specified device and line.

Input parameters:

  • device - device handle returned by previously called abilis.gio.get_device_handle function;

  • line - line index counted from 1 (e.g. 1, 2, 3 etc.).

Return value:

  • ok - boolean true if the operation succeeds (e.g. device is available) or false if the operation fails;

  • events - number of events on the line from the system start.

abilis.iohub.set_digital_output
ok = abilis.iohub.set_digital_output(device, line, value)

This function writes a value to the digital output of the specified device and line.

Input parameters:

  • device - device handle returned by previously called abilis.gio.get_device_handle function;

  • line - line index counted from 1 (e.g. 1, 2, 3 etc.);

  • value - requested value of the output line, boolean true or false.

Return value:

  • ok - boolean true if the operation succeeds (e.g. device is available) or false if the operation fails.

abilis.iohub.get_digital_output
ok, value = abilis.iohub.get_digital_output(device, line)

This function returns a value from the digital output of the specified device and line.

Input parameters:

  • device - device handle returned by previously called abilis.gio.get_device_handle function;

  • line - line index counted from 1 (e.g. 1, 2, 3 etc.).

Return value:

  • ok - boolean true if the operation succeeds (e.g. device is available) or false if the operation fails;

  • value - boolean true if the line is ON or false if the line is OFF.

abilis.iohub.get_digital_output_events
ok, events = abilis.gio.get_digital_output_events(device, line)

This function returns a number of state changes on the digital output of the specified device and line.

Input parameters:

  • device - device handle returned by previously called abilis.gio.get_device_handle function;

  • line - line index counted from 1 (e.g. 1, 2, 3 etc.).

Return value:

  • ok - boolean true if the operation succeeds (e.g. device is available) or false if the operation fails;

  • events - number of events on the line from the system start.

abilis.iohub.get_analog_input
ok, value = abilis.iohub.get_analog_input(device, index)

This function returns a value from the analogue input of the specified device and line.

Input parameters:

  • device - device handle returned by previously called abilis.gio.get_device_handle function;

  • line - line index counted from 1 (e.g. 1, 2, 3 etc.).

Return value:

  • ok - boolean true if the operation succeeds (e.g. device is available) or false if the operation fails;

  • value - number containing value (e.g. 1.56) of the line.

abilis.iohub.set_analog_output
ok = abilis.iohub.set_analog_output(device, index, value)

This function writes a value to the analogue output of the specified device and line.

Input parameters:

  • device - device handle returned by previously called abilis.gio.get_device_handle function;

  • line - line index counted from 1 (e.g. 1, 2, 3 etc.);

  • value - requested value of the output line in a number form (e.g. 1.56).

Return value:

  • ok - boolean true if the operation succeeds (e.g. device is available) or false if the operation fails.

abilis.iohub.get_analog_output
ok, value = abilis.iohub.get_analog_output(device, index)

This function returns a value from the analogue output of the specified device and line.

Input parameters:

  • device - device handle returned by previously called abilis.gio.get_device_handle function;

  • line - line index counted from 1 (e.g. 1, 2, 3 etc.).

Return value:

  • ok - boolean true if the operation succeeds (e.g. device is available) or false if the operation fails;

  • value - number containing value (e.g. 1.56) of the line.

57.4.3. Abilis DISA extensions

The functions of the “abilis.disa” namespace cooperate with the DISA driver and its services configured in the APP mode. These functions allow to make outgoing phone call, wait for incoming call, obtain information about the call, play sounds to the call, etc.

To use this extension add the following code into your Lua script

local abilis = require "abilis"
abilis.disa.dial
handle = abilis.disa.dial(service, cd, cg, sd, sg, rg)

This asynchronous function makes an outgoing call with the specified parameters: DISA service identifier, called number, calling number, called subaddress, calling subaddress, redirecting number. Only the first two parameters are mandatory.

This function returns a call handle, which is used as the first parameter of the other functions. The call handle must be closed by the abilis.disa.close function.

This function returns nil on failure.

abilis.disa.listen
handle = abilis.disa.listen(service)

This asynchronous function sets the selected DISA service into a listening mode, allowing its to accept incoming calls.

This function returns a call handle, which is used as the first parameter of the other functions. The call handle must be closed by the abilis.disa.close function.

This function returns nil on failure.

abilis.disa.close
ok = abilis.disa.close(handle)

This function closes an existing handle.

This function returns either true on success or false on failure.

abilis.disa.get_state
state = abilis.disa.get_state(handle)

This function returns the call state for the provided call handle. The call state is identified by a number: 0 ≡ closed, 1 ≡ calling, 2 ≡ alerting, 3 ≡ active, 4 ≡ closing, 5 ≡ listening. The value could be converted to a string by the abilis.disa.state_str function.

abilis.disa.state_str
text = abilis.disa.state_str(state)

This function converts the call state provided by the abilis.disa.get_state function into a readable text string.

abilis.disa.get_info
cg, cd, sg, sd, rg = abilis.disa.get_info(handle)

This function returns the call data for the provided call handle: Calling number, called number, calling subaddress, called subaddress, redirecting number. If some of those values is unavailable then nil is returned instead.

abilis.disa.get_dtmf
text = abilis.disa.get_dtmf(handle)

This function returns a string with all DMTF codes collected from the last call of this function.

This function returns nil on failure.

abilis.disa.play_file
ok = abilis.disa.play_file(handle, filename)

This function starts playback of the CPM file whose absolute path must be specified. The play process can be monitored with the abilis.disa.get_play_state function. The CPM file can be created from the WAV file by the abilis.disa.convert_wav function.

This function returns either true on success or false on failure.

abilis.disa.get_play_state
state = abilis.disa.get_play_state(handle)

This function returns the play state for the provided call handle. The play state is identified by a number: 0 ≡ silent, 1 ≡ playing. The value could be converted to a string by the abilis.disa.play_state_str function.

abilis.disa.play_state_str
text = abilis.disa.play_state_str(state)

This function converts the play state provided by the abilis.disa.get_play_state function into a readable text string.

abilis.disa.convert_wav
ok = abilis.convert_wav(filename)

This function converts a WAV file into the CPM file, which is used by the abilis.disa.play_file function. The full path to the CPM file must be provided.

This function returns either true on success or false on failure.

57.4.4. Abilis CP extensions

The functions in the “abilis.cp” namespace allow to obtain/send character streams from/to CP (control port) part of the Abilis. This provides possibility to make any of control/check commands available also via Telnet/SSH connection into the Abilis.

To use this extension add the following code into your Lua script

local abilis = require "abilis"
abilis.cp.open
CpStream = abilis.cp.open()

This function opens the CP stream of the Abilis and provides to make operation on this CP stream like write and read.

Input parameters:

  • No input parameters.

Return values:

  • CpStream - table of write/read/close functions related to CP stream to be used for handling, nil if double open is called in the same script.

Example:

 local CpStream = abilis.cp.open()
 CpStream:write("D PCIDEV")
CpStream:close
CpStream:close()

This function closes the opened CpStream

Input parameters:

  • No input parameters.

Return value:

  • No output parameters.

Example:

CpStream:write("D PCIDEV")
CpStream:write
Success = CpStream:write(CpString)

This function sends the given CpString into the opened CP stream of the Abilis

Input parameters:

  • CpString - string to sent into the Abilis CP interface.

Return value:

  • Success - result of the operation, nil if failed.

Example:

CpStream:write("D PCIDEV")
CpStream:read
InputString = CpStream:read(Param)

This function reads the given CpString into the opened CP stream of the Abilis. The

Input parameters:

  • Param - If Param is number, the given number of characters is read from CP stream. If Param = "l" the string of the complete line is returned, the line end is detected when \r\n sequence is there and concurrently this character pair (\r\n) is removed from the line string.

Return value:

  • InputString - string received from the CP of the Abilis, nil if there are no other data.

Example:

InStr = CpStream:read(5)
print("Read string is: "..InStr)
Read string is: PCI S
InStr = CpStream:read("l")
print("Read string is: "..InStr)
Read string is: PCI Server Overview:
Prev Up Next
57.3. LUA SCRIPT diagnostics and statistics Home 57.5. LUA SCRIPT examples