Ssh

The Ssh object allows Q-SYS cores to make secure client connections to devices on the network. It is very similar to TcpSocket, but requires additional connection arguments (host, port, user, password). Unlike TcpSocket, a standard, unified event handler function is not supported. Additionally, compared to TcpSocket, there is a LoginFailed event handler that is called if login credentials are incorrect.

Creates a new SSH instance.

Syntax

Ssh.New()

Attempts to connect using the specified host address, port, and credentials.

Syntax

:Connect("host", port, "user", "password")

Arguments

host : String. The IP Address or FQDN (fully qualified domain name) which represents the remote host.

port : Integer, 0 - 65535. The connection port number on the remote host.

user : String. The connection user name, in quotes.

password : String. The connection password, in quotes.

Disconnects the socket.

Syntax

:Disconnect()

Writes specified data to the socket. Raises error if socket is not connected.

Syntax

:Write(data)

Arguments

data : String. The data to write to the socket.

Attempts to read up to 'length' bytes from socket. These bytes are removed from the buffer, leaving any remaining bytes beyond the 'length' specified.

Syntax

:Read(length)

Arguments

length : Positive integer. The number of bytes of data to read from the socket buffer.

Return Value

Returns a string containing the number of bytes requested or the number of bytes available, whichever comes first. Returns Nil if the buffer is empty.

Attempts to read a 'line' from the socket buffer.

Syntax

:ReadLine(TcpSocket.EOL.keyword, <custom>)

Arguments

TcpSocket.EOL.keyword : The EOL keyword can be any of the types shown in the EOL table below.

custom : Used only if the EOL keyword is Custom. A string literal containing the custom end of line character combination to search for.

TcpSocket.EOL Keywords

Description

Any

The end of line is any sequence of any number of carriage return and/or linefeed characters. This is the appropriate choice if the protocol uses simply a carriage return as the end of message.

CrLf

The end of the line is an optional carriage return, followed by a linefeed. (In other words, it is either a "\r\n" or a "\n".) This format is useful in parsing text-based Internet protocols, since the standards generally prescribe a "\r\n" line-terminator, but nonconformant clients sometimes use just "\n".

CrLfStrict

The end of a line is a single carriage return, followed by a single linefeed. (This is also known as "\r\n". The ASCII values are 0x0D 0x0A).

Lf

The end of a line is a single linefeed character. (This is also known as "\n". It is ASCII value is 0x0A.)

Null

The end of line is a single byte with the value 0 — an ASCII NUL.

Custom

The end of line is defined by the string passed into the ReadLine() method.

Return Value

Nil if the EOL was not found, otherwise returns the string up to the EOL sequence.

Searches the socket buffer for string 'str' (starting at integer 'start_pos') and returns the index of where 'str' is found. 'start_pos' defaults to 1.

Syntax

:Search(str, [start_pos])

Arguments

str : The string to search for.

start_pos : Integer. Optional. The index of where to start in the socket buffer. Default is index 1.

Return Value

Nil if the search string was not found, otherwise returns the integer index of where the search string was found.

Name

Function Signature

Description

.LoginFailed

function( tcpTable )

Assign a function which is called upon a failed login.

.Connected

function( tcpTable )

Assign a function which is called upon connection to remote host

.Reconnect

function( tcpTable )

Assign a function which is called when socket is attempting to reconnect to the remote host

.Data

function( tcpTable, data )

Assign a function which is called when there is new data available in the socket buffer

.Closed

function( tcpTable )

Assign a function which is called when the socket is closed by the remote host

.Error

function( tcpTable, err )

Assign a function which is called when the socket is closed due to error. The error argument in the function will contain more information, which can be displayed if a variable was created to catch the error message.

.Timeout

function( tcpTable, err)

Assign a function which is called when a read or write timeout is triggered and the socket was closed.

Name

Description

Connected

 The socket has connected to the remote host.

Reconnect

 The socket is attempting to reconnect to the remote host

Data

 There is new data available in the socket buffer

Closed

The socket was closed by the remote host

Error

The socket was closed due to error. The error argument to the EventHandler will have more information, which can be displayed if a variable was created to catch the error message.

Timeout

A read or write timeout was triggered and the socket was closed.

Name

Notes

Description

.ReadTimeout

Optional; Default is 0 ( disabled )

Time, in seconds, to wait for data to be available on socket before raising an error.

.WriteTimeout

Optional; Default is 0 ( disabled )

Time, in seconds, to wait for data write to complete before raising an error.

.ReconnectTimeout

Optional; Default is 5 seconds

Time in seconds to wait before attempting to reconnect. 0 disables automatic reconnect.

.IsConnected

Read-Only

Returns true if socket is connected.

.BufferLength

Read-Only

Amount of data in buffer, in bytes.

In this example script, a new SSH connection is created. Multiple event handlers are included to print connection status. Upon connection:

  • The date is written.
  • Data from the socket buffer is read and printed.
  • The buffer length is printed.
ssh = Ssh.New()
address = "192.0.2.199"
port = 22
user = "myusername"
pass = "mypassword"

timer = Timer.New()
timer.EventHandler = function()
  ssh:Write("date\n")
end

ssh.Connected = function()
  print("ssh connected")
  timer:Start(10)
end

ssh.Reconnect = function()
  print("ssh reconnect")
end

ssh.Data = function()
  print("ssh data")
  line = ssh:ReadLine(TcpSocket.EOL.Any)
  while line do
    print(line)
    print(ssh.BufferLength)
    line = ssh:ReadLine(TcpSocket.EOL.Any)
  end
end

ssh.Closed = function()
  print("ssh closed")
  timer:Stop()
end

ssh.Error = function(s, err)
  print("ssh error", err)
end

ssh.Timeout = function()
  print("ssh timeout")
end

ssh.LoginFailed = function()
  print("ssh LoginFailed")
end

ssh:Connect(address, port, user, pass)