SatVUE Portal LUA Documentation

Lua Documentation

This documentation will describe the variables and functions made available by SatVUE Lua engine. This documentation will not describe how to program in Lua, for this information please see Lua 5.1 Documentation.

The Lua extensions on the SatVUE Portal allow you create just about any type of calculation you require, or can be used to generate a custom report tailored to meet your exact needs.

When using Lua as the calculation method for your device's fields, you must return a numeric value. This value be used as the value for your field's value. If you return a nil value, that field value will be dropped and not logged.

When using Lua to generate a custom report, print() statements are used to output the content you wish to have in your report.


Variables

  • message_data[] This variable contains all the data from the SatVUE device as well as calculated fields.
  • report_data[] This variable contains all the data from the SatVUE device required to generate the report

Functions

Lua/SatVUE Variables

SatVUE defines some variables in the Lua Engine which are made available to the user. These variables expose some information which can be used in your calculations or your Lua defined actions.

Name Description
message_data[] When using the Lua engine for calculating a device field value, the message_data variable is defined. This variable contains all the raw data from the SatVUE device, as well as all fields that have been calculated prior to this field.

For more information on message payload structure see Return Message Documentation .

Example
local epoch = getEpochUTC(message_data['_timestamp_'])
local ydoc_system_message = message_data['_message_']
local dayofweek = formatDateTime(message_data['_timestamp_'], 'N')
local analogInput = message_data['Port1Value']
report_data[] When using the Lua engine for generating a report, the report_data variable is defined. This variable contains all the data from the SatVUE device, required to create this report and has the format:

report_data = {
    start = '2016-12-12 12:12:12',
    end = '2016-12-12 13:12:12',
    data = {
        {
            _timestamp_ = '2016-12-12 12:12:12', -- as defined by report's date format
            field1      = 123,
            field2      = 999
        },
        {
            _timestamp_ => '2016-12-12 13:12:12',
            field1      => 100,
            field2      => 900
        },
        ...
    }
}
								


Example
for key, row in ipairs(report_data['data']) do
    print('Recorded At: '..row['_timestamp_']..' Battery Voltage: '..row['BatteryVoltage']..'\r\n');
end
									
Example Output:
Recorded At: 2017-12-12 09:00:00

Lua/SatVUE Functions

SatVUE defines some functions in the Lua Engine which are made available to the user. These variables expose some information and actions which can be used in your calculations or your Lua defined actions.

Name Description
getEpochUTC(string)

Returns the UTC time in epoch format.

Parameters
string: [Optional] The date/time to format in a string representation to convert. Or current time if this is not set.
Return Value

Returns an integer representing the number of seconds since midnight January 1, 1970.

Example
local epoch = getEpochUTC();
print 'Epoch: '..epoch
Example Output:
Epoch: 1507615068
formatDateTime(string, format)

Takes a date/time in string representation and converts it to the specified format.

Parameters
string: The date/time to format in a string representation
format: The format to return the date/time in. See here for details.

Return Value

Returns a string representation of the specified time in the specified format.

Example
local formatted_time = formatDateTime('2017-11-01 09:12:00 +10', 'H:i:sP, jS F, Y')
print 'Time: '..formatted_time
Example Output:
Time: 09:12:00+10:00, 1st November, 2017
formatEpoch(epoch, format)

Takes a date/time in epoch representation and converts it to the specified format.

Parameters
epoch: The date/time to format in Epoch format
format: The format to return the date/time in. See here for details.

Return Value

Returns a string representation of the specified time in the specified format.

Example
local formatted_time = formatEpoch(1509527520, 'H:i:sP, jS F, Y')
print 'Time: '..formatted_time
Example Output:
Time: 09:12:00+10:00, 1st November, 2017
getAlarmConfig(field) Parameters
field: The name of the device field to fetch the alarm configuration for.

Return Value

A table of the following format is returned

{
    enabled = true,                  -- True if the alarm is enabled, false otherwise
    active  = false,                 -- True if the alarm is currently active, false otherwise
    high    = 5.99                   -- The alarm's high threshold
    low     = 1.23                   -- The alarm's low threshold
}

Fetch the alarm configuration for the specified device field.

Example
local signal_alarm = getAlarmConfig('Signal Strength')
print 'Signal Strength Alarm: '..signal_alarm['low']..' dB'
Example Output:
Signal Strength Alarm: 42 dB
getAlarmConfigFromDevice(device, field) Parameters
device: The name of the device to lookup the device field on.
field: The name of the device field to fetch the alarm configuration for.

Return Value

A table of the following format is returned

{
    enabled = true,                  -- True if the alarm is enabled, false otherwise
    active  = false,                 -- True if the alarm is currently active, false otherwise
    high    = 5.99                   -- The alarm's high threshold
    low     = 1.23                   -- The alarm's low threshold
}

Fetch the alarm configuration for the specified device field.

Example
local signal_alarm = getAlarmConfig('Signal Strength')
print 'Signal Strength Alarm: '..signal_alarm['low']..' dB'
Example Output:
Signal Strength Alarm: 42 dB
getGpsLocation()

Request this SatVUE to aquire its GPS location and transmit it immediately.

Example
getGpsLocation()
getGpsLocationFromDevice(device) Request a SatVUE to aquire its GPS location and transmit it immediately.

Parameters
device: The name of the SatVUE device

Return Value

Returns FALSE if the device name could not be found, or TRUE if the message was sent.

Example
if getGpsLocationFromDevice('AnotherSatVUE') then
  print 'Message has been sent'
end
Example Output:
Message has been sent
getLatestValueFromDevice(device, field) Gets a field value from another SatVUE device.

Parameters
device: The name of the SatVUE device
field: The name of the field to get

Return Value

Returns the field's latest value from the specified device, or nil if there is no previous value.

Example
local barometric = getLatestValueFromDevice('AnotherSatVUE', 'Barometric')
print 'Barometric Pressure: '..barometric..' KPa'
Example Output:
Barometric Pressure: 101.1 KPa
getPreviousValues(field, count) Gets multiple previous values of a field value from this SatVUE device.
Only the previous four months will be searched.

Parameters
field: The name of the field to get
count: The number of samples to fetch

Return Value

A table of the following format is returned

{
  {
    timestamp = 1509527520,                  -- Timestamp is in Epoch format
    datetime = '2017-11-01 19:12:00 +10',    -- Timestamp is in String format
    value = 1.23                             -- Numeric Field value
  },
  {
    timestamp = 1509527580,
    datetime = '2017-11-01 19:13:00 +10',
    value = 2.12
  },
  ...
  ...
}

Example
local values = getPreviousValues('Water Level', 5)
for i,record in ipairs(values) do
  local epochTimestamp = record.timestamp
  local waterLevel = record.value
  print 'Timestamp: '..formatEpoch(epochTimestamp, 'Y-m-d H:i:s')..' Value: '..
end
Example Output:
...
getLatestValue(field) Gets a field value from this device.

Parameters
field: The name of the field to get

Return Value

Returns the field's latest value from the specified device, or nil if there is no previous value.

Example
local barometric = getLatestValue('Barometric')
print 'Barometric Pressure: '..barometric..' KPa'
Example Output:
Barometric Pressure: 101.1 KPa
pollDevice(device) Request a SatVUE to sample its ports and transmit its data immediately.

Parameters
device: The name of the SatVUE device

Return Value

Returns FALSE if the device name could not be found, or TRUE if the message was sent.

Example
if pollDevice('AnotherSatVUE') then
  print 'Poll message has been sent'
end
Example Output:
Poll message has been sent
requestLoggedData(start, end, count)

If the SatVUE is logging data to a local file, this function can be used to request that logged data from the unit.

Parameters
start: The start date/time in UTC/Epoch format
end: The end date/time in UTC/Epoch format
count: The max number of samples to return

Return Value

Returns FALSE if the parameters are invalid, or TRUE if the message was sent.

Example
if requestLoggedData(1509527520, 1509529000, 100) then
  print 'Up to 100 records has been requested'
end
Example Output:
Up to 100 records has been requested
setEioOutput(port, value) Sets a digital output to either high or low on this device.

Parameters
port: The digital output port to set, 1 - 4.
value: True to set the output high, or False to set it low

Return Value

Returns FALSE if the port parameter is invalid, or TRUE if the message was sent.

Example
if setEioOutput(1, true) then
  print 'Message has been sent'
end
Example Output:
Message has been sent
setEioOutputOnDevice(device, port, value) Sets a digital output to either high or low on another device.

Parameters
device: The name of the SatVUE device
port: The digital output port to set, 1 - 4.
value: True to set the output high, or False to set it low

Return Value

Returns FALSE if the port parameter or the device name is invalid, or TRUE if the message was sent.

Example
if setEioOutputOnDevice('AnotherSatVUE', 2, false) then
  print 'Message has been sent'
end
Example Output:
Message has been sent
setDigitalOutput(slave, output, value) Sets/clears an output on an IO expansion board within the SatVUE.

Parameters
slave: The modbus slave the IO exapander is on, 1 - 6.
output: The digital output port to set, 1 - 2.
value: True to set the output, or False to clear the output

Return Value

Returns FALSE if the slave parameter is invalid, or TRUE if the message was sent.

Example
if setDigitalOutput(1, 1, true) then
  print 'Message has been sent'
end
Example Output:
Message has been sent
setDigitalOutputOnDevice(slave, output, value) Sets/clears an output on an IO expansion board within another SatVUE.

Parameters
device: The name of the SatVUE device
slave: The modbus slave the IO exapander is on, 1 - 6.
output: The digital output port to set, 1 - 2.
value: True to set the output, or False to clear the output

Return Value

Returns FALSE if the slave parameter is invalid, or TRUE if the message was sent.

Example
if setDigitalOutputOnDevice('AnotherSatVUE', 1, 1, true) then
  print 'Message has been sent'
end
Example Output:
Message has been sent
sendModbusCmd(command) Perform a Modbus request on this SatVUE.

Parameters
command: A table containing the following data:
command = {
  FunctionCode    = 6,     -- The function code
  SlaveAddress    = 240,   -- The slave address
  RegisterAddress = 34,    -- The register address
  Length          = 1,     -- The register count
  Values          = {1},   -- The register data to write as a binary string
  Timeout         = 1000,  -- The slave timeout
  Retries         = 3,     -- Number of times to retry the modbus request
}

Return Value

Returns FALSE if the a parameter is invalid, or TRUE if the message was sent.

Example
if sendModbusCmd({
  FunctionCode    = 6,     -- The function code
  SlaveAddress    = 240,   -- The slave address
  RegisterAddress = 34,    -- The register address
  Length          = 1,     -- The register count
  ValueString     = 1,     -- The register data to write as a binary string
  Timeout         = 1000,  -- The slave timeout
  Retries         = 3,     -- Number of times to retry the modbus request
}) then
  print 'Message has been sent'
end
Example Output:
Message has been sent
sendModbusCmdToDevice(device, command) Perform a Modbus request on another SatVUE.

Parameters
device: The name of the SatVUE device
command: See sendModbusCmd() for description.

Return Value

Returns FALSE if the a parameter is invalid, or TRUE if the message was sent.

Example
local command = { ... }
if sendModbusCmd('AnotherSatVUE', command) then
  print 'Message has been sent'
end
Example Output:
Message has been sent
getAlarmConfig(field_name) Returns a table containing the alarm configuration from a field on the current device.

Parameters
field_name: The name of the field to fetch the alarm configration from.

Return Value

A table containing the following information:

result = {
  enabled  = 1,     -- Is the alarm enabled
  active   = 1,     -- Is the alarm currently active
  high     = 34,    -- The alarm's high threshold
  low      = 1,     -- The alarm's low threshold
}
Example
local alarm_config = getAlarmConfig('Water Depth')
if alarm_config['active'] then
  print 'The alarm is active'
end
Example Output:
The alarm is active
getAlarmConfigFromDevice(field_name) Returns a table containing the alarm configuration from a field on another device.

Parameters
device: The name of the device to lookup the field on
field_name: The name of the field to fetch the alarm configration from.

Return Value

A table containing the following information:

result = {
  enabled  = 1,     -- Is the alarm enabled
  active   = 1,     -- Is the alarm currently active
  high     = 34,    -- The alarm's high threshold
  low      = 1,     -- The alarm's low threshold
}
Example
local alarm_config = getAlarmConfigFromDevice('Tank 1', 'Water Depth')
if alarm_config['active'] then
  print 'The alarm is active'
end
Example Output:
The alarm is active
insertValue(timestamp, field_name, value) Inserts a value into a Device Field, if the field does not exist it will be created.

Parameters
timestamp: The timestamp for the value to be inserted for the Device Field.
field_name: The name of the device field to insert the value for.
value: The value to insert
decimals: [Optional] If the field is created, it will get defined to use this many decimal places.
units: [Optional] If the field is created, it will get defined to use this as it units.

Return Value

Returns FALSE if the insert failed, or TRUE if it was successful.

Example
if insertValue('2021-01-01 12:00:00', 'field-name', 1.23) then
  print 'Value has been inserted'
end
Example Output:
Value has been inserted
emailSend(to, subject, text, html) Send a custom email to an email address.

Parameters
to: The email address to send the message to. Comma seperate multiple addresses.
subject: The subject of the email.
text: The text body of the email message.
html: [Optional] The HTML body of the email message.

Return Value

Returns FALSE if the email failed to send, or TRUE if it was successful.

Example
local to = 'person@example.com'
local subject = 'This is an email'
local text = 'This is the text part of the email'
local html = 'This is the HTML part of the email'
emailSend(to, subject, text, html)

Date/Time Format Characters

The following characters are recognized in the format parameter string
format character Description Example returned values
Day
d Day of the month, 2 digits with leading zeros 01 to 31
D A textual representation of a day, three letters Mon through Sun
j Day of the month without leading zeros 1 to 31
l (lowercase 'L') A full textual representation of the day of the week Sunday through Saturday
N ISO-8601 numeric representation of the day of the week (added in PHP 5.1.0) 1 (for Monday) through 7 (for Sunday)
S English ordinal suffix for the day of the month, 2 characters st, nd, rd or th. Works well with j
w Numeric representation of the day of the week 0 (for Sunday) through 6 (for Saturday)
z The day of the year (starting from 0) 0 through 365
Week
W ISO-8601 week number of year, weeks starting on Monday Example: 42 (the 42nd week in the year)
Month
F A full textual representation of a month, such as January or March January through December
m Numeric representation of a month, with leading zeros 01 through 12
M A short textual representation of a month, three letters Jan through Dec
n Numeric representation of a month, without leading zeros 1 through 12
t Number of days in the given month 28 through 31
Year
L Whether it's a leap year 1 if it is a leap year, 0 otherwise.
o ISO-8601 week-numbering year. This has the same value as Y, except that if the ISO week number (W) belongs to the previous or next year, that year is used instead. (added in PHP 5.1.0) Examples: 1999 or 2003
Y A full numeric representation of a year, 4 digits Examples: 1999 or 2003
y A two digit representation of a year Examples: 99 or 03
Time
a Lowercase Ante meridiem and Post meridiem am or pm
A Uppercase Ante meridiem and Post meridiem AM or PM
B Swatch Internet time 000 through 999
g 12-hour format of an hour without leading zeros 1 through 12
G 24-hour format of an hour without leading zeros 0 through 23
h 12-hour format of an hour with leading zeros 01 through 12
H 24-hour format of an hour with leading zeros 00 through 23
i Minutes with leading zeros 00 to 59
s Seconds with leading zeros 00 through 59
v Milliseconds (added in PHP 7.0.0). Same note applies as for u. Example: 654
Timezone
e Timezone identifier (added in PHP 5.1.0) Examples: UTC, GMT, Atlantic/Azores
I (capital i) Whether or not the date is in daylight saving time 1 if Daylight Saving Time, 0 otherwise.
O Difference to Greenwich time (GMT) in hours Example: +0200
P Difference to Greenwich time (GMT) with colon between hours and minutes (added in PHP 5.1.3) Example: +02:00
T Timezone abbreviation Examples: EST, MDT ...
Z Timezone offset in seconds. The offset for timezones west of UTC is always negative, and for those east of UTC is always positive. -43200 through 50400
Full Date/Time
c ISO 8601 date (added in PHP 5) 2004-02-12T15:19:21+00:00
r ยป RFC 2822 formatted date Example: Thu, 21 Dec 2000 16:01:07 +0200
U Seconds since the Unix Epoch (January 1 1970 00:00:00 GMT) Example: 1567379368