Ping

Use the Ping library in Lua to check whether a device is reachable on the network.

Note: The Lua Ping library requires that you run Q-SYS Designer as administrator ("Run as administrator" option in Windows) when emulating your design. If you see a non-terminating "Socket failed to open" error message in the debug window, re-launch Designer as administrator.

Create a new ping object.

Syntax

Ping.New("target_host")

Arguments

target_host : The hostname to ping.

Example

Copy 
ping_object = Ping.New("www.qsys.com")

Begin the ping session.

Syntax

start(single_shot)

Arguments

single_shot : Bool. Set to true if you want only a single ping attempt.

Example

Copy 
ping_object:start(false)

Stop the ping session.

Syntax

stop()

Example

Copy 
ping_object:stop()

Set the timeout for waiting for a ping response.

Syntax

setTimeoutInterval(interval)

Arguments

interval : Double. The timeout duration, in seconds.

Example

Copy 
ping_object:setTimeoutInterval(10.0)

Set the interval for retrying after a ping request.

Syntax

setPingInterval(interval)

Arguments

interval : Double. The interval duration, in seconds.

Example

Copy 
ping_object:setPingInterval(10.0)

Assign a Lua callback for successful ping events.

Responses

ElapsedTime : Long. The amount of time for the ping to occur, in microseconds.

HostName : String. The hostname that was pinged.

Example

Copy 
ping_object.EventHandler = function(response)
    print(response.HostName)
    print(response.ElapsedTime)
end

Assign a Lua callback for unsuccessful ping events.

Responses

Error : String. The description of the error.

HostName : String. The hostname that was pinged.

Example

Copy 
ping_object.ErrorHandler = function(response)
    print(response.HostName)
    print(response.Error)
end

In this simple example, a ping request is sent to a live host every 5 seconds until the script is stopped. The response includes the host name that was pinged, as well as the amount of time for the ping to occur (in microseconds).

Copy 
myping = Ping.New("www.qsys.com")
myping:start(false)
myping:setPingInterval(5.0)
myping.EventHandler = function(response)
  print(response.HostName)
  print(response.ElapsedTime)
end
myping.ErrorHandler = function(response)
  print(response.HostName)
  print(response.Error)
end

Debug Output

2020-03-24T23:32:08.679	Starting Script
2020-03-24T23:32:08.781	www.qsys.com
2020-03-24T23:32:08.781	25
2020-03-24T23:32:13.892	www.qsys.com
2020-03-24T23:32:13.892	27
2020-03-24T23:32:18.993	www.qsys.com
2020-03-24T23:32:18.994	25
2020-03-24T23:32:24.089	www.qsys.com
2020-03-24T23:32:24.089	23
2020-03-24T23:32:29.184	www.qsys.com
2020-03-24T23:32:29.184	23
2020-03-24T23:32:34.280	www.qsys.com
2020-03-24T23:32:34.280	23
2020-03-24T23:32:39.377	www.qsys.com
2020-03-24T23:32:39.377	24

In this example, the start() function is set to 'true', meaning that the ping request only runs a single time. The request is made to a bad host name, so the response includes the returned error.

Copy 
myping = Ping.New("www.qsc.c")
myping:start(true)
myping:setPingInterval(5.0)
myping.EventHandler = function(response)
  print(response.HostName)
  print(response.ElapsedTime)
end
myping.ErrorHandler = function(response)
  print(response.HostName)
  print(response.Error)
end

Debug Output

2020-03-24T23:22:29.895	Starting Script
2020-03-24T23:22:29.897	www.qsc.c
2020-03-24T23:22:29.897	Send echo failed.