License, Copyright, and Trademark

The content contained in this repository is the intellectual property of Snap One, LLC, (formerly known as Wirepath Home Systems, LLC), and use without a valid license from Snap One is strictly prohibited. The user of this repository shall keep all content contained herein confidential and shall protect this content in whole or in part from disclosure to any and all third parties except as specifically authorized in writing by Snap One.

License and Intellectual Property Disclaimer

The content in this repository is provided in connection with Snap One products. No license, express or implied, by estoppal or otherwise, to any intellectual property rights is granted by this document or in this repository. Except as provided in Snap Oneʼs terms and conditions for the license of such products, Snap One and its affiliates assume no liability whatsoever and disclaim any express or implied warranty, relating to the sale and/or use of Snap One products including liability or warranties relating to fitness for a particular purpose, merchantability, or infringement of any patent, copyright or other intellectual property right. Snap One products are not intended for use in medical, lifesaving, or life sustaining applications.

Information regarding third-party products is provided solely for educational purposes. Snap One is not responsible for the performance or support of third-party products and does not make any representations or warranties whatsoever regarding the quality, reliability, functionality or compatibility of these products. The reader is advised that third parties can have intellectual property rights that can be relevant to this repository and the technologies discussed herein, and is advised to seek the advice of competent legal counsel regarding the intellectual property rights of third parties, without obligation of Snap One.

Snap One retains the right to make changes to this repository or related product specifications and descriptions in this repository, at any time, without notice. Snap One makes no warranty for the use of this repository and assumes no responsibility for any errors that can appear in the repository nor does it make a commitment to update the content contained herein.

Copyright

Copyright 2022 Snap One, LLC. All rights reserved.

The above copyright notice applies to all content in this repository unless otherwise stated explicitly herein that a third-party’s copyright applies.

No part of this publication may be reproduced, photocopied, stored on a retrieval system, or transmitted without the express written consent of the publisher.

Trademarks

Snap One and Snap One Logo, Control4 and the Control4 logo, and DriverWorks are trademarks or registered trademarks of Snap One, LLC. Other product and company names mentioned in this repository may be the trademarks or registered trademarks of their respective owners.

 Derivative Works

To the extent that you create any “Derivative Work” (meaning any work that is based upon one or more preexisting versions of the work provided to you in this repository, such as an enhancement or modification, revision, translation, abridgement, condensation, expansion, collection, compilation or any other form in which such preexisting works may be recast, modified, transformed or adapted, explicitly including without limitation, any updates or changes to Snap One, LLC’s software code or intellectual property) such Derivative Work shall be owned by Snap One, LLC and all right, title and interest in and to each such Derivative Work shall automatically vest in Snap One, LLC. To the extent any Derivative Work does not automatically vest in Snap One, LLC by operation of law, you hereby assign such Derivative Work to Snap One, LLC with full title guarantee. Snap One, LLC shall have no obligation to grant you any right in any such Derivative Work.

Contact Us

Snap One, LLC 11734 S. Election Road Salt Lake City, UT 84020 USA

http://www.control4.com

Introduction

Effective communication between your driver and Control4 System is paramount to a successful end user experience. The API Reference Guide details each of the Interfaces supported through the DriverWorksSDK. These Interfaces include numerous APIs that can be leveraged by your driver to facilitate communication between the driver and the Control4 O.S.

What's New

What’s New in 3.3.0

C4SSH Interface

The DriverWorks API has been expanded with the addition of the new C4SSH API. This API enables Lua drivers to establish an SSH client connection to a remote device and execute a series of commands. A driver creates an instance of a C4SSH object by calling the C4:CreateSSHClient function.

File Interface

As part of Control4’s plan to tighten driver security, the io.popen() call has bee removed. In doing this, driver developers need to use C4:File commands to accomplish what they previously did with io.popen (). The following APIs have been added or modified in support of this effort:

A new API: FileCreateDir has been added. This function has been added to create a new directory.

The FileDelete function has been modified in conjunction with O.S. release 3.3.0.

A new API: FileMove has been added. This function moves files within certain restrictions.

The FileSetDir has been modified In conjunction with O.S. release 3.3.0. This function is being restricted to allowed locations whereas previously it had full root access.

Additionally, a new API: UnZip has been added. This API enables Lua drivers to extract one, or more, files from a .zip archive.

Helper Interface

A new API: GetCodeItems has been added. This function returns Code Items for a specified device and event.

A new API: GetAllCodeItems has been added. This function returns all Code Items within the project.

A new API: GetBootID has been added. This function returns a string that contains an ID which is unique for the current kernel instance. When the controller is re-booted, the ID will change.

A new API: UUID has been added. This function generates a UUID (Universally Unique IDentifier). This function has also been added to tighten driver security and support the removal of the the io.popen() call.

Miscellaneous Interface

A new API: GetDriverFileName has been added. This function returns a string of the driver filename.

What’s New in 3.2.3

Timer Interface

A new API: GetTime has been added to the Timer Interface in this version of the SDK. This API enables Lua drivers to retrieve the number of milliseconds since the epoch.

What’s New in 3.2.2

Variable Interface

A new API: UnRegisterAllVariableListeners has been added to this version of the SDK.

What’s New in 3.2.1

Variable Interface

A new API: UnRegisteredAllVariableListeners has been added to this version of the SDK.

What’s New in 3.2.0

Driver Initialization and Destruction

New parameters have been added to OnDriverInit, OnDriverLateInit and OnDriver Destroyed. These parameters support instances when driver needs to know under what condition or event caused the Initialization or Destroyed functions to be called. OS Release 3.2.0 introduces a new string parameter for these functions to identify the reason for the call. This parameter, driverInitType (DIT) provides this information.

Driver Add Driver

Two new APIs have been delivered with O.S. 3.2.0 to facilitate the ability of driver to add another driver to a project as well as the ability to add a location within the project. See the AddDevice and AddLocation APIs for more information.

What was New in 3.1.0

New APIs that were Added

ToStringLocaleC - A new helper function which converts a number to a string using the ‘C’ locale regardless of the locale setting of the Control4 Operating System.

Interfaces that were Modified

Zigbee Interface

Future Changes to Zigbee Server-Side Cluster Management

Encryption Interface

A new Lua Signing API has been added to the SDK. C4:Sign enables drivers to crypto-graphically sign an arbitrary payload using a specified key. The API currently supports both HMAC & RSA signing. Control4 strongly recommends that driver developers implement this new API as soon as possible.

New Sample Drivers that were Added

A client side websocket driver has been added to the SDK to assist with websocket support. Sample drivers can be found in the Sample Driver folder at the root level of the SDK.zip.

What was New in O.S.3

New Interfaces that were Added

The Notification Interface allows device drivers to include .jpeg files within notifications. These images are displayed as part of the notification. The .jpeg file can be retrieved from a cloud service that supports the device, from the device itself or from a location on a Control4 Controller.

The Scheduler Agent Interface has been added which supports a driver's ability to create scheduled events that can be used in Programming in ComposerPro.

New APIs that were Added

The GetBindingsByDevice API returns all of the Binding information for a device. The GetNetworkBindingsByDevice API return all of the Network Binding information for a device. The GetNetworkConnections API returns connection information based on connection type. The GetProjectProperty API uses a single string parameter from a list of property names and returns the value of that property, if it exists.

Interfaces that were Modified

The Media Management Interface has been enhanced with content supporting Device Level Context and Broadcast Video APIs

The Timer Interface has been updated to identify legacy APIs that, while still valid, are not recommenced for new driver development. Additionally, a sample driver using the (recommended) SetTimer API has been included with the SDK.

The WebService Interface has been updated with a new sample driver that demonstrates how to perform basic C4:url calls.

Interfaces that were Modified

The AddVariable API has been enhanced with additional Parameter Types.

The JsonDecode API has been enhanced with a new optional parameter: decodeNull which indicates how null values are decoded. Additionally, c4json.null has been added. This can can be used to insert a null value into a JSON document or to test for a null value that was encountered in a JSON document.

The OnBindingChanged API has been updated to include missing parameters.

The PersistGetValue API has been updated with an option third parameter: encrypted.

The PersistSetValue API has been updated with an option third parameter: encrypted.

The RenameDevice API has updated content regarding passing a ProxyID or DeviceId value.

The UpdatePropertyList API has been modified with a parameter re-name and an additional, optional parameter.

APIs that were Deprecated

The Debug Interface content has been removed from the DriverWords SDK. The APIs that were defined in the Debug Interface were used in conjunction with an executable that supported remote debugging. Support for the debugging utility was discontinued several years ago. As a result, the following APIs have been removed:

• Attach
• DisableremoteDebugging
• EnableRemoteDebugging
• OnEndDebugSession

C4SSH Interface

CreateSSHClient

The C4SSH API enables Lua drivers to establish an SSH client connection to a remote device and execute a series of commands. A driver creates an instance of a C4SSH object by calling the C4:CreateSSHClient function.

This interface was released in conjunction with O.S. 3.3.0

Signature

C4:CreateSShClient ()

Parameters

None

Returns

An instance of a C4SSH object that can be used to establish an SSH client connection to a remote device. The C4SSH object enables a Lua driver to establish an SSH client connection to a device, and then to interact with that device by executing a series of commands. The C4SSH object API provides the following methods:

• Connect
• Send
• Disconnect
• SetConnectTimeout
• SetOnConnected
• SetOnData
• SetOnDisconnected

These methods are defined below:

Connect

The Connect method attempts to establish a connection to a remote device. There are three methods that set callback functions which enable a driver to receive various notifications about the connection. These are:

SetOnConnected: Provides notification when a connection is established. SetOnData: Provides notification when data is read from the connection. SetOnDisconnected: Provides notification when the connection is disconnected, or has otherwise failed.

Additionally, a driver may control how long the C4SSH object waits before determining that the connection has failed. This is accomplished with: SetConnectTimeout which specifies the amount of time to wait when attempting to connect to an endpoint.

Signature

Connect(endpoint, username, password, string)

Returns

The Connect method may return multiple values. On success, Connect returns the following:

• The instance of the C4SSH object on which Connect was invoked.

On failure, Connect returns the following:

• nil
• A string describing the failure

See Also:

• SetOnConnected
• SetOnData
• SetOnDisconnected
• SetConnectTimeout
• OnConnected
• OnData
• OnDisconnected

Send

Sends a command to a remote device. A driver may set a callback function to receive notification when data has been read from the connection by calling the SetOnData method.

Signature

Send(command)

Returns

The Send method may return multiple values. On success, Send returns the following:

• The instance of the C4SSH object on which the Send method was invoked.

On Failure, Send returns the following:

• nil
• A string describing the failure

Usage Note

Due to the asynchronous nature of the C4SSH API, a driver must wait for a connection to be established before calling Send. A driver can be notified that a connection has been established successfully by calling SetOnConnected to register an OnConnected callback function.

See Also:

• SetOnData
• OnData

Disconnect

Closes the connection. A driver may set a callback function to receive notification when the connection has been disconnected by calling the SetOnDisconnected method.

Signature

Disconnect()

Parameters

None

Returns

The Disconnect method returns a single value which is the instance of the C4SSH object on which the Disconnect method was invoked.

Set Also

• SetOnDisconnected
• OnDisconnected

SetConnectTimeout

Sets the amount of time the C4SSH object waits before determining that an attempt to establish a connection to an endpoint has failed. The C4SSH object notifies a driver that a connection has timed out by invoking the OnDisconnected callback function. A driver may set the OnDisconnected callback function by calling SetOnDisconnected.

Signature

SetConnectTimeout(Timeout)

Returns

The SetConnectTimeout method may return multiple values. On Success, SetConnectTimeout returns the following:

• The instance of the C4SSH object on which SetConnectTimeout was invoked.

On failure, SetConnectTimeout returns the following:

• nil
• A string describing the failure.

See Also

• Connect
• SetOnDisconnected
• OnDisconnected

SetOnConnected

Sets the callback function that is invoked when a client connection has been established. See OnConnected for specific details about the function signature of this callback.

Signature

SetOnConnected(Callback)

Returns

The SetOnConnected method returns a single value which is the instance of the C4SSH object on which SetOnConnected was invoked.

See Also

• OnConnected

SetOnData

Sets the callback function that is invoked when data has been read from a connection. See OnData for specific details about the function signature of this callback.

Signature

SetOnData(Callback)

Returns

The SetOnData method returns a single value which is the instance of the C4SSH object on which the SetOnData method was invoked.

See Also

• OnData

SetOnDisconnected

Sets the callback function that is invoked when a connection is disconnected or has otherwise failed. Note that the C4SSH object invokes the OnDisconnected callback to notify a driver when an error has forced the closure of a connection. See OnDisconnected for specific details about the function signature of this callback.

Signature

SetOnDisconnected(Callback)

Returns

The SetOnDisconnected method returns a single value which is the instance of the C4SSH object on which SetOnDisconnected was invoked.

See Also

• OnDisconnected

C4SSH Callbacks

The C4SSH object provides the following callback functions that enable a driver to receive various notifications about the connection. These include the following:

• OnConnected
• OnData
• OnDisconnected

OnConnected

The OnConnected callback is invoked to notify a driver that a connection has been established.

Signature

OnConnected(client)

Parameters

See Also

• SetOnConnected

Example

function OnData(client, data)
    print(client, "OnData")
    print(data)
    client:Disconnect()
end

function OnConnected(client)
    print(client, "OnConnected")
    client:Send("ls")
end

function OnDisconnected(client, error)
    print(client, "OnDisconnected", error)
end

sshclient = C4:CreateSSHClient()

sshclient:SetOnDisconnected(OnDisconnected)
sshclient:SetOnConnected(OnConnected)
sshclient:SetOnData(OnData)

sshclient:Connect("192.168.1.42", "username", "password")

OnData

The OnData callback is invoked to notify a driver when data has been read from a connection.

Signature

OnData(Client, Data)

See Also

• SetOnData

Example

function OnData(client, data)
    print(client, "OnData")
    print(data)
    client:Disconnect()
end

function OnConnected(client)
    print(client, "OnConnected")
    client:Send("ls")
end

function OnDisconnected(client, error)
    print(client, "OnDisconnected", error)
end

sshclient = C4:CreateSSHClient()

sshclient:SetOnDisconnected(OnDisconnected)
sshclient:SetOnConnected(OnConnected)
sshclient:SetOnData(OnData)

sshclient:Connect("192.168.1.42", "username", "password")

OnDisconnected

The OnDisconnected callback is invoked to notify a driver that a connection has been disconnected. If an error forced the closure of the connection, then the Error argument provides a string describing the error.

Signature

OnDisconnected(client Error)

See Also

• SetOnDisconnected

Example

function OnData(client, data)
    print(client, "OnData")
    print(data)
    client:Disconnect()
end


function OnConnected(client)
    print(client, "OnConnected")
    client:Send("ls")
end

function OnDisconnected(client, error)
    print(client, "OnDisconnected", error)
end

sshclient = C4:CreateSSHClient()

sshclient:SetOnDisconnected(OnDisconnected)
sshclient:SetOnConnected(OnConnected)
sshclient:SetOnData(OnData)

sshclient:Connect("192.168.1.42", "username", "password")

Controller Registry Interface

RegistryDeleteValue

Removes a key/value pair from the Registry.

Available from 2.10.4

Signature

C4:RegistryDeleteValue(key)

Returns

None

RegistryGetValue

Retrieves a value from the Registry.

Available from 2.10.4

Signature

C4:RegistryGetValue(key)' |Parameters | Description| | --- | --- | | num | The key applicable to the value being retrieved. |

Returns

Upon success, the API returns the value that was decoded from the Registry. The value can be any of the following: number, string ,boolean, table. Upon failure, the API returns nil.

RegistrySetValue

Sets the value of a Registry key/value pair. The value is updated if the specified key/value pair exists. A key/value pair is created by the API if it does not exist.

Available from 2.10.4

Signature

C4:RegistrySetValue(key, value)

Returns

Upon success, the API returns the value that was decoded from the Registry. The value can be any of the following: number, string ,boolean, table. Upon failure, the API returns nil.

Director Command Interface

ExecuteCommand

Function called by Director when a command is received for this DriverWorks driver. This includes commands created in Composer programming. This API should not be invoked during OnDriverInit.

Available in 1.6.0.

Signature

ExecuteCommand(strCommand, tParams)

Returns

None

Usage Note

Prior to Operating System 2.10, overuse of C4:InvalidateState()was an issue as persisting extraneous data through a driver had performance implications. Beginning with Operating System 2.10, it is no longer necessary to cause driver data to be persisted. Drivers should use the PersistSetValue and PersistGetValue functions to store data that will be required across system restarts.

Examples:

Print all commands received for this protocol driver, including all parameters:

function ExecuteCommand (strCommand, tParams)
 print("ExecuteCommand: " .. strCommand)
 if (tParams \~= nil) then
   for ParamName, ParamValue in pairs(tParams) do 
     print(ParamName, ParamValue) 
   end
 end
end

This sample function evaluates the commands received from Director and calls the correct function. It also looks for LUA_ACTION commands, which are sent from Composer’s Actions tab and processes them:

function ExecuteCommand(strCommand, tParams)
print("ExecuteCommand function called with : " .. strCommand)
  if (tParams == nil) then
    if (strCommand =="GET\_PROPERTIES") then
      GET\_PROPERTIES()
    else
      print ("From ExecuteCommand Function - Unutilized command: " .. strCommand)
    end
  end
  if (strCommand == "LUA\_ACTION") then
    if tParams \~= nil then
      for cmd,cmdv in pairs(tParams) do 
        print (cmd,cmdv)
        if cmd == "ACTION" then
          if cmdv == "Reset Security System" then
            ResetSecuritySystem()
          else
            print("From ExecuteCommand Function - Undefined Action")
            print("Key: " .. cmd .. "  Value: " .. cmdv)
          end
        else
          print("From ExecuteCommand Function - Undefined Command")
          print("Key: " .. cmd .. "  Value: " .. cmdv)
        end
      end
    end
  end
end

GetVersionInfo

Function that returns the version of Director that is currently running. This API can be invoked during OnDriverInit.

Available in 1.60.

Signature

C4:GetVersionInfo()

Parameters

None

Returns

Example

local tVers = C4:GetVersionInfo()
local strVers = tVers["version"]


local major, minor, rev, build = string.match(strVers, "(%d+).(%d+).(%d+).(%d+)")

print("Major: " .. major .. " Minor: " .. minor .. " Rev: " .. rev .. " Build: " .. build)

if (tonumber(major) < 2) then
  if (tonumber(minor) < 8) then
    print("This Code requires at least version 1.8 to operate properly.  You are currently running version " .. strVers)
  end
end GetVersionInfo

InvalidateState

Function to notify director that data from this driver has been modified and needs to be persisted. This API should not be invoked during OnDriverInit.

Signature

C4:InvalidateState()

Usage Note

Prior to Operating System 2.10, overuse of C4:InvalidateState() was an issue as persisting extraneous data through a driver had performance implications. Beginning with Operating System 2.10, it is no longer necessary to cause driver data to be persisted. Drivers should use the PersistSetValue and PersistGetValue functions to store data that will be required across system restarts.

Encryption Interface

Encode

local data = 'Hello World This Is London Calling'
local data_encoding = 'BASE64'
local encoded_data, err = C4:Encode (data, data_encoding)
print (type (encoded_data), encoded_data)

Output:

string  SGVsbG8gd29ybGQ=

Encodes a given string with the specified data encoding.

Available in 1.6.0.

Signature

C4:Encode (data, data_encoding)

Returns

result, err

A successful operation will return nil for err. If an error occurs, then result will be nil and err will contain the description of the error.

Encrypt

local cipher = 'AES-256-CBC'
local key = 'Super Secret Key'
local iv = 'IV For C4'
local data = 'Hello World, this is London calling'
local options = {
    return_encoding = 'BASE64',
    key_encoding = 'NONE',
    iv_encoding = 'NONE',
    data_encoding = 'NONE',
    padding = true,
}
local encrypted_data, err = C4:Encrypt (cipher, key, iv, data, options)
print (type (encrypted_data), encrypted_data)

Output:

string  HMQ9QXyBFUBnTAXBl2zi6k6abipQYQjpc37B0nA3WaxK9vBNrqKKAEzIglxWkA46

Encrypts a given string with the specified cipher, using the specified key and IV.

Available in 1.6.0.

Signature

C4:Encrypt (cipher, key, iv, data, options)

Valid key/value pairs for options parameter:

Returns

result, err

A successful operation will return nil for err. If an error occurs, then result will be nil and err will contain the description of the error.

Decode

local data = 'SGVsbG8gd29ybGQ='
local data_encoding = 'BASE64'
local decoded_data, err = C4:Decode (data, data_encoding)
print (type (decoded_data), decoded_data)

Output:

string  Hello World

Decodes a given string that was previously encoded with the specified data encoding.

Available in 1.6.0.

Signature

C4:Decode (data, data_encoding)

Returns

result, err

A successful operation will return nil for err. If an error occurs, then result will be nil and err will contain the description of the error.

Decrypt

local cipher = 'AES-256-CBC'
local key = 'Super Secret Key'
local iv = 'IV For C4'
local data = 'HMQ9QXyBFUBnTAXBl2zi6k6abipQYQjpc37B0nA3WaxK9vBNrqKKAEzIglxWkA46'
local options = {
    return_encoding = 'NONE',
    key_encoding = 'NONE',
    iv_encoding = 'NONE',
    data_encoding = 'BASE64',
    padding = true,
}
local decrypted_data, err = C4:Decrypt (cipher, key, iv, data, options)
print (type (decrypted_data), decrypted_data)

Output:

string  Hello World, this is London calling

Encrypts a given string with the specified cipher, using the specified key and IV.

Available in 1.6.0.

Signature

C4:Decrypt (cipher, key, iv, data, options)

Valid key/value pairs for options parameter:

Returns

result, err

A successful operation will return nil for err. If an error occurs, then result will be nil and err will contain the description of the error.

GenerateCSR ECC

This API will generate a certificate signing request (CSR) which, when sent to a certificate authority, will return a digital identity certificate that meets the encryption criteria defined by Elliptic-curve cryptography (ECC) standard. The use of this API assumes a thorough knowledge of public-key cryptosystems and the ECC cryptosystem definition.

Available in 3.1.2.

Signature

C4:GenerateCSP_ECC(digest, curve, subject, tx509_exts) 

Returns

None

Examples

Generate a CSR using ECC requirements:

local csr = C4:GenerateCSR_ECC("SHA256", "secp256k1", "/C=US/ST=Utah/L=Draper/O=Control4/OU=Controller Certificates/CN=foo.bar.com")

The resulting CSR to the right is generated:

 -----BEGIN CERTIFICATE REQUEST-----
MIIB0TCCAXcCAQAweDELMAkGA1UEBhMCVVMxDTALBgNVBAgMBFV0YWgxDzANBgNV
`BAcMBkRyYXBlcjERMA8GA1UECgwIQ29udHJvbDQxIDAeBgNVBAsMF0NvbnRyb2xs`
`ZXIgQ2VydGlmaWNhdGVzMRQwEgYDVQQDDAtmb28uYmFyLmNvbTCB9TCBrgYHKoZI`
zj0CATCBogIBATAsBgcqhkjOPQEBAiEA////////////////////////////////
/////v///C8wBgQBAAQBBwRBBHm+Zn753LusVaBilc6HCwcCm/zbLc4o2VnygVsW
`+BeYSDradyajxGVdpPv8DhEIqP0XtEimhVQZnEfQj/sQ1LgCIQD/////////////`
`///////+uq7c5q9IoDu/0l6M0DZBQQIBAQNCAAQXXbHNU5r5vYzZRYhPZGKFcSBe`
I+D0y0pvyw+tUo8eGO9QjHqmw6A0vm5OyRR3C9qDH8msuDO1ZgieUkCfnfYSoAAw
CgYIKoZIzj0EAwIDSAAwRQIgMvJKuHT2E+um/iXdUNhJK61jSI1ygcjR77lCZM2E
`aRkCIQCcZLJvubYxdGxB0q7ApSBujF/L6/UtL/gjuolLE6JUaw==`
  -----END CERTIFICATE REQUEST----- 

Generate a CSR using ECC requirements with the optional X.509 parameter:

local csr = C4:GenerateCSR_ECC("SHA256", "secp256k1", "/C=US/ST=Utah/L=Draper/O=Control4/OU=Controller Certificates/CN=foo.bar.com", {subjectKeyIdentifier = "hash", subjectAltName = "DNS:acs.qacafe.com, DNS:www.acs.qacafe.com"})

The resulting CSR is generated:

--- X.509 Example

-----BEGIN CERTIFICATE REQUEST-----
MIICIzCCAcgCAQAweDELMAkGA1UEBhMCVVMxDTALBgNVBAgMBFV0YWgxDzANBgNV`
BAcMBkRyYXBlcjERMA8GA1UECgwIQ29udHJvbDQxIDAeBgNVBAsMF0NvbnRyb2xs
ZXIgQ2VydGlmaWNhdGVzMRQwEgYDVQQDDAtmb28uYmFyLmNvbTCB9TCBrgYHKoZI`
zj0CATCBogIBATAsBgcqhkjOPQEBAiEA////////////////////////////////
/////v///C8wBgQBAAQBBwRBBHm+Zn753LusVaBilc6HCwcCm/zbLc4o2VnygVsW
+BeYSDradyajxGVdpPv8DhEIqP0XtEimhVQZnEfQj/sQ1LgCIQD/////////////
///////+uq7c5q9IoDu/0l6M0DZBQQIBAQNCAASu8/6lwqmnPbMLCvXIIU38ZmAo
LjjaMLNhzAgAnWYz/lzg3h8FXcuC/W6jv83inkfgu/4Zutp/GxAQLBqA+lkeoFEw
TwYJKoZIhvcNAQkOMUIwQDALBgNVHQ4EBGhhc2gwMQYDVR0RBCpETlM6YWNzLnFh
Y2FmZS5jb20sIEROUzp3d3cuYWNzLnFhY2FmZS5jb20wCgYIKoZIzj0EAwIDSQAw
RgIhAI78Y9z3cIlRinJVmyx7I+7uA37HEfofzdSktra4Lm5nAiEAxTep97UadRb1
phLqvILbPqe2Lsm8JyCg/yEn5JlfncA=
 -----END CERTIFICATE REQUEST-----

GenerateCSR RSA

This API will generate a certificate signing request (CSR) which, when sent to a certificate authority, will return a digital identity certificate that meets the encryption criteria defined by the Rivest–Shamir–Adleman (RSA) standard. The use of this API assumes a thorough knowledge of public-key cryptosystems and the RSA cryptosystem definition.

Available in 3.1.2.

Signature

C4:GenerateCSP_RSA(digest, sizeCert, subject, tx509_exts)

Returns

None

Examples

Generate a CSR using RSA requirements:

local csr = C4:GenerateCSR_RSA("SHA256", 2048, "/C=US/ST=Utah/L=Draper/O=Control4/OU=Controller Certificates/CN=foo.bar.com")

The resulting CSR to the right is generated:

BEGIN CERTIFICATE REQUEST-----
MIICvTCCAaUCAQAweDELMAkGA1UEBhMCVVMxDTALBgNVBAgMBFV0YWgxDzANBgNV
BAcMBkRyYXBlcjERMA8GA1UECgwIQ29udHJvbDQxIDAeBgNVBAsMF0NvbnRyb2x~~s
ZXIgQ2VydGlmaWNhdGVzMRQwEgYDVQQDDAtmb28uYmFyLmNvbTCCASIwDQYJKoZI
hvcNAQEBBQADggEPADCCAQoCggEBALzSLHvRT8QcVbfFlxCCUkGEL2irn8r6DxBM
+XEK6/xXeAVZ/oWRAiGOHBNeqmdaUz0ib4ANdTHn8jEUB2t38cDVEJ88o4BiE+/D
rpmUphIKXh3Hp57PwyC0EKHQ2POq6e75AxOMouCdtbbLgBDxmD6WWM6ojEwphEQ2
M6JM6ZJA9pDQ/UanbGWruvKFEm9AUdo+hAjoFgObDqhWLLIwXFeSyz6y/0aymBam
jtO/ovOS/5moNy+ENBeOsLC2ayCn4Fquj77Y825Ye9kYPkiVkkcEtawAEEFebZJY
pUE8SwBOYjjHYJoWFDv+vcxWBFlc0ECTFKeB9Bd4vi2TF+IlwpsCAwEAAaAAMA0G
CSqGSIb3DQEBCwUAA4IBAQBv4Z7e1cD1gbNy0PXYyugQpbG19umTcZkQN+BlK5TY
+VcNLKK/56IPaxX7ZeHpe3DQPOXnTmc/+wVremZ6h7TwSxUOBFY9DjVUuh0thWsB
t+xUzWt4Oae0ymP8JF83b9RZl1EGGsAsQopB+Uu4P9VgwjHm9PTXVBheofbZ/yXp
oeom+w0fl+/qCcIjvDAGh8ODz4gfk6Mjl1iiQykOyWeGhZiGyd6G80IAF1pjciVS
O94cvy6o9EAAgujSCmCZFOgx3kwOfLZ/r1rq5jRvyyjK7wzL7bZHHjBJBLpe/tx0
AV+GeKVQe0nHme1tt1n+ZC5mIZ0q7qjKL3wwl4ckwTg/
      -----END CERTIFICATE REQUEST—

Generate a CSR using RSA requirements with the optional X.509 parameter:

local csr = C4:GenerateCSR_RSA("SHA256", 1024, "/C=US/ST=Utah/L=Draper/O=Control4/OU=Controller Certificates/CN=foo.bar.com", {subjectKeyIdentifier = "hash", subjectAltName = "DNS:acs.qacafe.com, DNS:www.acs.qacafe.com"})

The resulting CSR to the right is generated:

— X.509 Example

 -----BEGIN CERTIFICATE REQUEST-----
MIICCTCCAXICAQAweDELMAkGA1UEBhMCVVMxDTALBgNVBAgMBFV0YWgxDzANBgNV
BZXIgQ2VydGlmaWNhdGVzMRQwEgYDVQQDDAtmb28uYmFyLmNvbTCBnzANBgkqhkiG
9w0BAQEFAAOBjQAwgYkCgYEA3djqm4PIBftyev9W0W4U+2XlwKHepq2o+dWPSk5s
/UzNd0TCeYoM02r+sTzQN2lkiGMYoPoKvP6qvQFWBzprtkS40z11S8AYGLqwKvxy
/MC8YcWjgGgvZB0h51TdW1OFdFT+yL68jnO9rGGIlfHx5DMyYypZf3tJKLczLVrh
rY0CAwEAAaBRME8GCSqGSIb3DQEJDjFCMEAwCwYDVR0OBARoYXNoMDEGA1UdEQQq
RE5TOmFjcy5xYWNhZmUuY29tLCBETlM6d3d3LmFjcy5xYWNhZmUuY29tMA0GCSqG
SIb3DQEBCwUAA4GBAA8Rz0fl6ue23HBENNV151uF0mQ9aT6/Z5S+8w8XTXXmf76B
OtTWXwPsxfsfxtZgRyKIGS4evUFN9jQIyEJNDj1+gvN2YFcm7bZFnPgq1m2vA3R1
TI9W6D463RicdNwjO92RYUgSm58Q1tCpyvlQqnedzvihQw1JFRgcIGNhbqI5
 -----END CERTIFICATE REQUEST-----

GetSupportedCiphers

Returns the list of ciphers supported by the Encrypt and Decrypt functions.

Available in 1.6.0.

Signature

C4:GetSupportedCiphers ()

Returns

ciphers

Valid key/value pairs for ciphers element value:

Example

local supportedCiphers = C4:GetSupportedCiphers ()
for k,v in pairs (supportedCiphers ['AES-256-CBC']) do
    print (k, v)
end

> Output:

BlockSize   16
KeyLength   32
IVLength    16

GetSupportedDigests

Returns the list of digests supported by the Hash, HMAC and PBKDF2 functions.

Available in 1.6.0.

Signature

C4:GetSupportedDigests ()

Returns

Valid key/value pairs for digest element value:

Example

local supportedDigests = C4:GetSupportedDigests ()
for k,v in pairs (supportedDigests ['SHA256']) do
    print (k, v)
end

> Output:

Size    32

Hash

Hashes a given string with the specified digest.

Available in 1.6.0.

Signature

C4:Hash (digest, data, options)

Valid key/value pairs for options parameter:

Returns

A successful operation will return nil for err. If an error occurs, then result will be nil and err will contain the description of the error.

Example

local digest = 'SHA256'
local data = 'Hello World, this is London calling'
local options = {
    return_encoding = 'HEX',
    data_encoding = 'NONE',
}
local digest_output, err = C4:Hash (digest, data, options)
print (type (digest_output), digest_output)

> Output:

string  3fa83003c1c41282cac40d71b680d85f981f1517e5ac4941bd871955aeecbfec

HMAC

Computes a hash-based message authentication code (HMAC) for a given string using the specified key.

Available in 1.6.0.

Signature

C4:HMAC (digest, key, data, options)

Valid key/value pairs for options parameter:

Returns

A successful operation will return nil for err. If an error occurs, then result will be nil and err will contain the description of the error.

Example

local digest = 'SHA256'
local key = 'Super Secret Key'
local data = 'Hello World, this is London calling'
local options = {
    return_encoding = 'HEX',
    key_encoding = 'NONE',
    data_encoding = 'NONE',
}
local hmac_output, err = C4:HMAC (digest, key, data, options)
print (type (hmac_output), hmac_output)

> Output:

string  6402b5430d06db90c84e91a3ed605ba12964ff29e7bbd197b54109ac72aa58ce

LoadPKCS12

Load a certificate and private key from a #PKCS12 file.

The Lua PKCS #12 interface enables drivers to manage certificates and private keys using the PKCS #12 file format. These files are encrypted and protected by a password. This ensures that cryptographic assets are secure and are not easily recovered.

Available in 3.1.2.

Signature

C4:LoadPKCS12(filename, password) 

Returns

Success returns multiple values consisting of: true, string, string.

Failure returns multiple values consisting of: false, string

Example

local filename = "Foo.p12"
local password = "PaSsWoRd"

result, cert, key = C4:LoadPKCS12(filename, password)
   if (result) then
   print("Success!")
 else
   print("Something horrible has happened: ", cert)
end

PBKDF2

Performs a Password-Based Key Derivation Function 2 (PKCS#5) (PBKDF2) for a given password using the specified digest, salt, number of iterations and desired output key length.

Available in 1.6.0.

Signature

C4:PBKDF2 (digest, password, salt, iterations, key_length, options)

Valid key/value pairs for options parameter:

Returns

result, err

A successful operation will return nil for err. If an error occurs, then result will be nil and err will contain the description of the error.

Example

local digest = 'SHA256'
local password = 'My Voice Is My Passport'
local salt = 'NaCl is one of many'
local iterations = 100000
local keyLen = 32
local options = {
    return_encoding = 'HEX',
    salt_encoding = 'NONE',
}
local pbkdf2_output, err = C4:PBKDF2 (digest, password, salt, iterations, keyLen, options)
print (type (pbkdf2_output), pbkdf2_output)

> Output:

string  12675672222506b342f05c0406f43e2af944bcb4ba592bf45e1c7cebad0fcdee

Sign

Sign enables drivers to crypto-graphically sign an arbitrary payload using a specified key.  The API currently supports both HMAC & RSA signing. Control4 strongly recommends that driver developers implement this new API beginning with OS Release 3.1.0. This API is the best solution to cryptographically sign a payload. Control4 recommends its use rather than other Lua libraries.

Available in 3.1.0.

Signature

C4:Sign(operation, digest, key, data, [options])

Options:

key_encoding

Identifies the format of the key. Valid values for this option are:

• NONE: The key is not encoded.
• HEX: The key is hex encoded.
• Base64: The key is base64 encoded.
• PEM: The key a PEM encoded private key. -

data_encoding

Identifies the format of the data. Valid values for this option are:

• NONE: The data is not encoded.
• HEX: The data is hex encoded.
• BASE64: The data is base64 encoded. -

return_encoding

Identifies the format of the result (signature). Valid values for this option are:

• NONE: Do not encode the result.
• HEX (default): Hex (lowercase) encoding.
• HEX_UPPER: Hex (uppercase) encoding.
• BASE64: Base64 encoding.

Returns

Success: Returns a string containing the signature.

Failure: Returns the following multiple results:

Examples

options = {}
options["key_encoding"] = "PEM"
options["return_encoding"] = "BASE64"
key = [[-----BEGIN RSA PRIVATE KEY-----
MIICXAIBAAKBgQC8cDObD4DjL3TnUR7JxObq+pwb4XX6UYjXuM1zzl/4gvQ8KzA4
CDl8S5FQeaPe4vdrLHEJudxSJc7JWehMwcS+jP6xO1pRA68SBphq9I5G/itBw5zx
RSGi26NDTiu7XczTRTPGRyBRNxBiln4hWg3ordY5gn0PYe30Fem9vTyZ1QIDAQAB
AoGAPTNfv1uwq5iNKleRXUyjBuwv6Wo3a/4xKIbvy03ao5a8hhIszfX13aWZY36u
N0SVwOwlJliD8vYui/y0UsGYCRCKrBFh5iBlL4bd4bOg/3uD9EXqiZQiT/BeYAD5
TYozqtsBU8DhZytdX3OcmLlKwhX+fzKMC2/UWPkEQ2TlSX0CQQDd/DgdI6WbCn3f
sIJo6yEA98ZivayuoePfRP8CHaIAOVO6KOa1wYwR/nmrUmPSFZDUpvwB7mvel4WN
3VqNO9sXAkEA2VAKopLmgdL+KNZdpg2BB3eVMMDefhXC04tBmUpWX6qaFEVsw+gl
DYnDel3gv43iq3xqszaKEJy+1T+bR9tV8wJAc4ecvK2ctsATGqQGewxENPi/KwyE
Hq7qpXyHK1a4xV0QkkZPLDD68TJ7qApNIT1QDxyI84heY46AV4Doa7DHKQJBAMj0
l6EXL0nGj3m8IgW4XyVElBXthNIb1XpCQHs8nvsAjFNKj/Xp6rnGN5okzfzVfFMQ
TqtDOBF8oYwZscKVNbkCQFolrfE1I7DMTuQNHmF6kMXr/0gjhDTbUOOP3kzCSK14
iSpRAwom9R5BWUMFoRCn0j0TWFsTIBNSuOcMrw5n6NU=
-----END RSA PRIVATE KEY-----]]
signature=C4:Sign("RSA", "SHA256", key, "Walla Walla Washington", options)
print(signature)


options = {}
options["key_encoding"] = "BASE64"
options["return_encoding"] = "HEX"
key = "VGhlIHF1aWNrIGJyb3duIGZveCBqdW1wZWQgb3ZlciB0aGUgbGF6eSBkb2cu"
signature = C4:Sign("HMAC", "SHA256", key, "Walla Walla Washington", options)
print(signature)


options = {}
options["key_encoding"] = "BASE64"
options["return_encoding"] = "HEX"
key = "VGhlIHF1aWNrIGJyb3duIGZveCBqdW1wZWQgb3ZlciB0aGUgbGF6eSBkb2cu"
signature = C4:Sign("HMAC", "SHA256", key, "Walla Walla Washington", options)
print(signature)

WritePKCS12

Writes a certificate and private key to a specified #PKCS12 file.

The Lua PKCS #12 interface enables drivers to manage certificates and private keys using the PKCS #12 file format. These files are encrypted and protected by a password. This ensures that cryptographic assets are secure and are not easily recovered.

Available in 3.1.2.

Signature

C4:WritePKCS12(filename, password, certificate, key, label, options)

Returns

Success returns true.

Failure: Returns multiple values consisting of false and string.

Example

local filename = "Foo.p12"
local password = "PaSsWoRd"
local label = "This is my excellent certificate"


local certificate = [[`
     -----BEGIN CERTIFICATE-----
MIIDLTCCAhUCCQC5eca/KJpLETANBgkqhkiG9w0BAQsFADCBkTEVMBMGA1UEAwwM
Y29udHJvbDQuY29tMQ0wCwYDVQQIDARVdGFoMQswCQYDVQQGEwJVUzEdMBsGA1UE
CgwUQ29udHJvbDQgQ29ycG9yYXRpb24xFDASBgNVBAsMC0VuZ2luZWVyaW5nMScw
JQYJKoZIhvcNAQkBFhhlbmdpbmVlcmluZ0Bjb250cm9sNC5jb20wHhcNMTQwNzA3
MjEzMTA4WhcNNDExMTIyMjEzMTA4WjCBojELMAkGA1UEBhMCVVMxDTALBgNVBAgM
BFV0YWgxDzANBgNVBAcMBkRyYXBlcjEdMBsGA1UECgwUQ29udHJvbDQgQ29ycG9y
YXRpb24xFDASBgNVBAsMC0VuZ2luZWVyaW5nMRUwEwYDVQQDDAxjb250cm9sNC5j
b20xJzAlBgkqhkiG9w0BCQEWGGVuZ2luZWVyaW5nQGNvbnRyb2w0LmNvbTCBnzAN
BgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAvHAzmw+A4y9051EeycTm6vqcG+F1+lGI
17jNc85f+IL0PCswOAg5fEuRUHmj3uL3ayxxCbncUiXOyVnoTMHEvoz+sTtaUQOv
EgaYavSORv4rQcOc8UUhotujQ04ru13M00UzxkcgUTcQYpZ+IVoN6K3WOYJ9D2Ht
9BXpvb08mdUCAwEAATANBgkqhkiG9w0BAQsFAAOCAQEAmMloM/SyJoC4JwZx6o3p
NfRBmtXZNK7GaHUe49d1o68IGzwhEg9lOYC9oD6krRonN80AczSW0igN/gHxYtti
1Rf/YhYH/GW+n4p5tCOVRYhJxuqGSaycK5+t1Bs4BibYN2p7+p1PI2kpEGPCb+tp
HpM2wX1TUrI01VeB94roVAhkhNRO4xsgsgcaQPvBNFHJylbn2vmFEIwlJLB4G+sr
VNTlaC7uANjuBoFjopyQNLhxl/oPahI1k2z8ccGQjRjxKp5T/S8hKVniGr47m9eu
WSFPDl5gqSkPwHE1RGqh2i8axBaJ97Y0MhAbRmNY2sDv7kxhC+qCKn4Xm1yEi1Mn
Lw==
     -----END CERTIFICATE-----

Event Interface

Registering for System Events

The management of registering for notifications which occur when system events are fired is made possible through several APIs and callback functions. The following is an example of how to be notified when the “Refresh Navigator” call is made. When bindings, device names, or device media has changed, a “Refresh Navigator” call is is fired. This event is an alert for the Navigators that any cached data about the project or media may now be invalid.

Specifically the event for “Refresh Navigator” is the “OnPIP” event. To get this event, we make use of the following generic event registration calls:

RegisterSystemEvent

C4:RegisterSystemEvent(eventId, deviceId)

Creates a registration for a notification when a system event fires.

Example

C4:RegisterSystemEvent(C4SystemEvents["OnPIP"], 0)

The C4SystemEvents variable is the array of all event name to ID’s. Use deviceId 0 to register for device specific events for all devices. Some events are system wide and will be sent regardless of the device id that was registered, others use the device id to filter who gets what events.

Additionally, your driver will need to implement the OnSystemEvent method.

Useful System Event ID Values

Note that the OnProjectChanged event was deprecated in 2.10.X due to the architectural change of using a database for persistence. There are specific events available for things such as device add, remove, and rename. These are:

• OnItemAdded
• OnItemRemoved
• OnItemNameChanged

AddEvent

Function called from DriverWorks driver to add a new Event. This API should not be invoked during OnDriverInit.

Available in 2.8.0.

Signature

C4:AddEvent(num,str,str)

Returns

True or False

True on successful addition of the Event

Example

The example below would be displayed in Composer Pro Programming as: "When the Theater->AV Switch TEST DYNAMIC 3 Event Changes" This example assumes a room of Theater and a driver named AV Switch.

C4:AddEvent(3, "TEST_DYNAMIC_3", "When the NAME TEST_DYNAMIC_3 Event Changes")

Usage Note

The AddEvent function will update an event if the event ID passed in the function is already in the driver.

DeleteEvent

Function called from DriverWorks driver to delete an Event. This API should not be invoked during OnDriverInit.

Available in 2.8.0.

Signature

C4:DeleteEvent(num)

Returns

None

Usage Note

The DeleteEvent API should not be used to remove Events which are defined in the driver's XML. Events defined in the XML are intended to be static. If an Event in the XMl needs to be deleted, it should be removed manually from the XML and the driver re-compiled and a new version assigned to it.

Events can be deleted regardless of their location within a set of Events. Empty Event IDs that result from this are acceptable.

FireEvent

Function called from DriverWorks driver to Fire a static or Dynamic Event on the driver. This API should not be invoked during OnDriverInit.

Available in 2.8.0.

Signature

C4:FireEvent(strEvent)

Returns

None

FireEventByID

Function called from DriverWorks driver to Fire a static or Dynamic Event (using the Event's ID Value) on the driver. This API should not be invoked during OnDriverInit.

Available in 2.8.0.

Signature

C4:FireEventByID(num)

Returns

None

OnDeviceEvent

This is a callback function that is sent to a driver when a device event is fired. The function delivers the Device ID for the device that fired the event and the Event's ID value.

Available in 2.9.0.

Signature

OnDeviceEvent(firingDeviceId, eventId) 

Returns

None

Example

OnDeviceEvent(80,2)

OnSystemEvent

This is a callback function that is sent to a driver when a system event is fired. The function delivers Event specific data.

Signature

OnSystemEvent(data)

Example

function OnSystemEvent(data)
   print("System Event occurred - data: " .. data)
end

RegisterDeviceEvent

This API allows for a driver to register for another driver's event. The device ID passed is the ID of the device that is firing the event of interest. This is followed by the event ID.

Available in 2.9.0

Signature

C4:RegisterDeviceEvent(80,15)

Returns

None

Usage Note

Knowledge of device event ID values are required to use this API in a driver. For this reason, the use of this API is intended for event registration between two drivers which have been created in support of one another. For example, this API would be useful in a network driver that wishes to know events fired by one of its module drivers.

RegisterSystemEvent

Creates a registration for a notification when a system event fires.

Signature

C4:RegisterSystemEvent()

Example

C4:RegisterSystemEvent(C4SystemEvents["OnPIP"], 0)

Usage Note

Useful System Event ID Values

UnregisterAllDeviceEvents

This API unregisters all prior event registrations created by the RegisterDeviceEvent API.

Available in 2.9.0

Signature

C4:UnregisterAllDeviceEvents()

Parameter

None

Returns

None

UnregisterAllSystemEvents

Un-registers from all notification of all system events.

Signature

C4:UnregisterAllSystemEvents()

Parameters

None

Example

C4:UnRegisterSystemEvent()

UnregisterSystemEvent

Un-registers a notification when a system event fires.

Signature

C4:UnregisterSystemEvent(eventId, deviceId)

Example

C4:UnregisterSystemEvent()

UnregisterDeviceEvent

This API unregisters prior event registration created by the RegisterDeviceEvent API. The device ID passed is the ID of the device that is firing the registered event. This is followed by the event ID.

Available in 2.9.0

Signature

C4:UnregisterDeviceEvent(deviceId, eventId)

Returns

None

Suppressing System Events

The suppress_connection_events is an optionally used device driver property that dictates whether or not Director will fire the OnDeviceOnline and OnDeviceOffline system events. While these events are not specifically handled within a driver, they can impact system performance. This is especially true when a large amount of media is present or media availability (regardless of a device’s online status) is a requirement. When these events are fired, the Room Driver clears its media cache. The media cache then must be rebuilt when a device comes back online. Unless the exercise of clearing and rebuilding the cache is needed, setting thesuppress_connection_events property to “True” is recommended.

There are two ways to implement suppress_connection_event. First, a driver developer can add the suppress_connection_events tag to the port section in the connections area of their driver. For example, to the right is an entry for an HC-250 that defines Director’s connection to Navigator:

Navigator 5115 True False True True True 0d0a

The second way to use the suppress_connection_events option is in Lua drivers. The NetConnect() function has an optional parameter that specifies whether Director should suppress OnDeviceOnline and OnDeviceOffline events for the connection. By default, Director does suppress events for all connections created this way. The events can be enabled by passing “false” for this parameter.

See the following APIs in the Serial Network Device Interface:

NetConnect

OnConnectionStatusChanged

File Interface

FileClose

Used to close an opened file handle. This API can be invoked during OnDriverInit.

Available from 1.6.0.

Signature

C4:FileClose

FileCreateDir

Function to create a new directory. As part of Control4’s plan to tighten driver security, the io.popen() call has bee removed. In doing this, driver developers need to use C4:File commands to accomplish what they previously did with io.popen (). This API provides the ability to create anew directory as previously done with io.popen.

This API was introduced in O.S. Release 3.3.0

Signature

C4:FileCreateDir()

Note that path aliases are required and cannot be replaced with the actual path.

Example

Assuming that the device id of the driver is 15, the following command will create directory "data" in /lua/sandbox/15/.

C4:FileCreateDir("SANDBOX", "data")

Assuming the device id of the driver is 15, the following command will create directory "backup" in /lua/sandbox/15/data/.

C4:FileCreateDir("SANDBOX", "data/backup")

FileDelete

This function has been modified in conjuction with O.S. release 3.3.0. As part of Control4’s plan to tighten driver security, the io.popen() call ihas been removed. In doing this, driver developers need to use C4:File commands to accomplish what they previously did with io.popen (). Two new parameters have been added to specify an allowed Alias and a sub path and file name to a file to delete.

Signature

C4:FileDelete()

Note that path aliases are required and cannot be replaced with the actual path.

Example

Assuming that the device id of the driver is 15, the following command will delete /lua/sandbox/15/data/datafile.dat.

C4:FileDelete(SANDBOX, "data/datafile.dat")

Example

C4:FileDelete("1.txt")

FileExists

Used to see if a file exists on the file system.  This function takes a file name and returns a bool if the file exists. This API can be invoked during OnDriverInit.

Available from 1.6.0.

Signature

C4:FileExists()

Returns

Example

    bexist = C4:FileExists("1.txt")
    if (bexist) then
    -- the file is already present on the file system
    end

FileFreeSpace

Used to see how much free space exists on the file system in bytes. This API can be invoked during OnDriverInit.

Available from 1.6.0.

Signature

C4:FileFreeSpace

Example

freeSpace = C4:FileFreeSpace()

FileIsValid

Used to see if a file is still valid to be written or read from. This is useful to check before or after reading to see if an end of file condition has been reached. This function returns a bool of the file status. This API can be invoked during OnDriverInit.

Available from 1.6.0.

Signature

C4:FileIsValid

Example

isOkay = C4:FileIsValid(fh)

FileGetName

Used to get the name of an opened file handle.  This function takes a file handle and returns a string of the file name. An empty string is returned if the file handle is not valid. This API can be invoked during OnDriverInit.

Available from 1.6.0.

Signature

C4:FileGetName

Example

name = C4:FileGetName(fh) print(“Name is “ .. name)

FileGetPos

Used to get the current read or write position for the file.  This function takes a file handle and returns the current position. This API can be invoked during OnDriverInit.

Available from 1.6.0.

Signature

C4:FileGetPos

Example

pos = C4:FileGetPos(fh)

FileGetSize

File to get the current size of an opened file handle. This API can be invoked during OnDriverInit.

Available from 1.6.0.

Signature

C4:FileGetSize

Return

Usage Note

Use the c4:FileOpen() call to obtain a valid file handle

Example

fh = C4:FileOpen("test.txt")
    if (fh == -1) then
   -- the file failed to open
  return
end

fileSize = C4:FileGetSize(fh)
print("File size is " .. fileSize)

C4:FileClose(fh)

FileOpen

Used to open (if file exists) or create a new file.  This function takes a file name, returns a handle. A value of -1 is returned if an error.  This API can be invoked during OnDriverInit.

Available from 1.6.0.

Signature

C4:FileOpen

Returns

Example

See example to the right.

fh = C4:FileOpen(“somefile.ext”)
if (fh == -1) then
    -- the file failed to open
end

Usage Note

The C4:FileOpen() function always opens a file so that the position is at end-of-file. For example:

local f = io.open(fullfilePath, "rba")

Opening the file as illustrated above opens the file for read, binary, and append (rba). This means that anything written to the file occurs at the end of the file. This ensures that writes don't overwrite existing data.

However, this also means that attempts to read the file will not return any data because the current read position is at end-of-file.

The example given above can be corrected by using the C4:FileSetPos() function to reset the position to the beginning of the file before reading. See the example to the right.

C4:FileSetDir(parentdir)
local fh = C4:FileOpen(fileName without path)
if (fh ~= -1) then
    C4:FileSetPos(fh, 0)
    local fileSize = C4:FileGetSize(fh)
    local fileContents = C4:FileRead(fh,fileSize)
    C4:FileClose(fh)
end

FileGetOpenedHandles

Used to retrieve a table of all the opened file handles in your sandbox or nil if none are opened. The table is index = file handle and value=file name. This API can be invoked during OnDriverInit.

Available from 1.6.0.

Signature

C4:FileGetOpenedHandles()

Parameters

None

Returns

Example

Closing all opened handles:

  fileHandles = C4:FileGetOpenedHandles()
  if (fileHandles) then
     for index,value in pairs(fileHandles) do
       C4:FileClose(index)
     end
  end

FileList

Used to retrieve a table of all the files that are present or nil if none exist. This API can be invoked during OnDriverInit.

Available from 1.6.0.

Signature

C4:FileList

Example

Deleting all files:

  fileNames = C4:FileList()
  if (fileNames) then
     for index,value in pairs(fileNames) do
       C4:FileDelete(value)
     end
  end

FileMove

Function for or moving files within certain restrictions. As part of Control4’s plan to tighten driver security, the io.popen() call has been removed. In doing this, driver developers need to use C4:File commands to accomplish what they previously did with io.popen () This API provides the ability to move files as previously done with io.popen.

This API was introduced in O.S. Release 3.3.0

Signature

C4:FileMove()

Note that path aliases are required and cannot be replaced with the actual path.

Example

Assuming that the device id of the driver is 15, the following command will move /lua/sandbox/15/tmp/tmpFile.dat to /lua/sandbox/15/data/dataFile.dat

C4:FileMove("SANDBOX", "/tmp/tmpFile.dat", "SANDBOX", "/data/dataFile.dat")

FileRead

Used to read data from a file.  Returns an empty string if no bytes are read. This function takes a file handle and number of bytes to be read. If an end of file is reached with this read operation, a string of what data was read is returned and any subsequent calls to FileRead will return an empty string. Use the FileIsValid call to see if and end of file condition has been reached. This API can be invoked during OnDriverInit.

Available from 1.6.0.

Signature

C4:FileRead

Returns

Example

fileData = C4:FileRead(fh, 10)

FileSetDir

In conjunction with O.S. release 3.3.0, this function is being restricted to allowed locations whereas previously it had full root access. As part of Control4’s plan to tighten driver security, the io.popen() call has been removed. In doing this, driver developers need to use C4:File commands to accomplish what they previously did with io.popen (). Prior to O.S. release 3.3.0, C4:FileSetDir had root access which would allow driver developers to modify anything on the file system.

Signature

C4:FileSetDir()

Examples

C4:FileSetDir(full_path) - Provided for backwards compatibility using allowed paths only.

C4:FileSetDir(PATH_ALIAS) - Specifying alias only.

C4:FileSetDir(PATH_ALIAS, sub_dir) - Specifying alias with a subdirectory of PATH_ALIAS

PATH_ALIAS: The path aliases are defined in the table below. When specifying a PATH_ALIAS, the alias will be replaced by the "Path" as described in the table.

FileSetPos

Used to set the position within the file to read or write from. This function takes a file handle and number for the new position. This API can be invoked during OnDriverInit.

Available from 1.6.0.

Signature

C4:FileSetPos

Example

C4:FileSetPos(fh, 50)

FileWrite

Used to write data to a file.  This function returns the number of bytes written or -1 if file is not valid (example file has been closed). This function takes a file handle, the number of bytes of the string to be written, and a string of data to be written. This API can be invoked during OnDriverInit.

Available from 1.6.0.

Signature

C4:FileWrite

Returns

Example

foo = "\000\001\002\003\004\005\006\007\008\009"
bytesWritten = C4:FileWrite(fh, string.len(foo), foo)

FileWriteString

Function to write a string to an opened file handle.

Available from 1.6.0.

Signature

C4:FileWriteString

Returns

Usage Note

Use the C4:FileOpen() call to obtain a valid file handle.

Example

fh = C4:FileOpen("test.txt")
if (fh == -1) then
   -- the file failed to open
 return
 end

numWritten = C4:FileWriteString(fh, "test1234")
 print("Bytes written " .. numWritten)

C4:FileClose(fh)
Output: Bytes written

UnZip

Function for extracting files from a .zip archive. This API enables Lua drivers to extract one, or more, files from a .zip archive.

This API was introduced in O.S. Release 3.3.0.

Signature

C4:UnZip()

Examples

The examples to the right illustrate the usage of the C4:Unzip function. Note that each sample utilizes a generic Lua function called printTable that dumps the contents of a specified table. This is done to illustrate how to interpret the return values of the function. There are numerous examples of printTable online.

Example 1

result, fileset, errors = C4:Unzip("/opt/control4/var/drivers/c4z/TuneIn.c4z", "*", "/opt/control4/var/drivers/c4z/TuneIn")
print(result)
printTable(fileset)
printTable(errors)

Executing this sample produces the following output.

true
table: 0xa42c380 {
[1] => "driver.xml"
[2] => "driver.lua"
.
.
.
[287] => "www/icons/device/experience_80.png"
[288] => "www/icons/device/experience_90.png"
}
table: 0xa186b60 {
}

The output can be interpreted as follows:
The result is true, indicating that all files were extracted successfully.
The fileset array contains 288 files (truncated for display purposes) that were extracted successfully. Note that the path to each file is relative to the archive.
The errors table is empty because no errors occurred.

Example 2 ```xml result, fileset, errors = C4:Unzip("/opt/control4/var/drivers/c4z/TuneIn.c4z", "*.lua", "/opt/control4/var/drivers/c4z/TuneIn") print(result) printTable(fileset) printTable(errors)

Executing this sample produces the following output.

true table: 0xb68c5e0 { [1] => "driver.lua" } table: 0xb5cc640 { }

The output can be interpreted as follows. The result is true, indicating that all files were extracted successfully. The fileset array contains a single entry because only one file matched the file specification: "*.lua". The errors table is empty because no errors occurred. ```

Example 3

result, fileset, errors = C4:Unzip("/opt/control4/var/drivers/c4z/TuneIn.c4z", "*.gif", "/opt/control4/var/drivers/c4z/TuneIn")
print(result)
printTable(fileset)
printTable(errors)

Executing this sample produces the following output.

false
table: 0xb5cc600 {
}
table: 0xb68ab00 {
[www/composer/ico_16_tunein.gif] => "Could not open file "/opt/control4/var/drivers/c4z/TuneIn/www/composer/ico_16_tunein.gif": Not a directory"
[www/composer/ico_32_tunein.gif] => "Could not open file "/opt/control4/var/drivers/c4z/TuneIn/www/composer/ico_32_tunein.gif": Not a directory"
}

The output can be interpreted as follows.
The result is false, indicating that one, ore more, errors occurred during extraction.
The fileset array is empty because no files were extracted.
The errors table contains two entries, one for each file matching the file specification: "*.gif". Each file is associated with a string describing the error that occurred.

Example 4

result, fileset, errors = C4:Unzip("/opt/control4/var/drivers/c4z/Bogus.c4z", "*", "/opt/control4/var/drivers/c4z/Bogus")
print(result)
printTable(fileset)
printTable(errors)

Executing this sample produces the following output.

false
table: 0xb1285e0 {
}
table: 0xb652200 {
[/opt/control4/var/drivers/c4z/Bogus.c4z] => "The specified zip file does not exist"
}

The output can be interpreted as follows:
• The result is false, indicating that one, ore more, errors occurred during extraction.
• The fileset array is empty because no files were extracted.
• The errors table contains a single entry containing the zip file itself. The associated error message indicates that the specified file does not exist.

Helper Interface

AddDevice

The AddDevice API provides the ability for a driver to add a device driver to a project. The ability to specify the location of the driver within the project as well as naming the device is also supported by the API. Execution of the AddDevice/AddLocation APIs should only be initiated through user interaction from the Dealer or end user. Inadvertent use of these APIs can result in drivers or locations recursively adding themselves to a project.

Available from 3.2.0.

Signature

C4:AddDevice ()

Callback Function Example

function OnDeviceAdded(deviceId, tDeviceInfo)
       LogTrace ("Device Added")
       LogTrace(deviceId)
       LogTrace(tDeviceInfo )
end

Returns

The API itself returns nothing. However, the callback function returns the Device ID value of the driver that was added. It will return a value of 0 upon failure.

Examples

The Inter-Device Comms suite (controller and client) in the sample_drivers directory of the SDK has been updated to show a live usage of AddDevice

1: Adding a Device to a Project without providing a Room ID.

C4:AddDevice("driver_properties.c4z", OnDeviceAdded)

In the example above, the AddDevice API will add the driver named driver_properties.c4z to the project in the same room where the driver exists.

2: Adding a Device to a Room within a Project.

C4:AddDevice("driver_properties.c4z", 38, OnDeviceAdded)

In the example above, the AddDevice API will add the driver named driver_properties to the Room in the project which has an ID value of 38.

3: Adding a Device to a Room within a Project and re-naming the driver:

C4:AddDevice("driver_properties.c4z", 38, “My New Driver”, OnDeviceAdded)

In the example above, the AddDevice API will add the driver named driver_properties to the Room in the project which has an ID value of 38. It will also rename the driver in the project to "My New Driver".

For further reference, the idc_client and idc_controller sample drivers delivered with the SDK both include auto-add functionality in their Driver Actions. See the sample_drivers directory on the SDK landing page for more information.

AddLocation

The AddLocation API provides the ability for a driver to add a location to a project. The locations that can be added are those available in a Control4 project. This includes:

• Site - A new site can be added to a project at the highest level of the project including Home, Work or Corporate.
• Buildings - Buildings can be added to a project including: House, Building or Office.
• Floors - Floors can added to a project including: Main, First, Second and Basement.
• Rooms - Rooms can added to a project including: Theater, Foyer, Living, Dining, Kitchen, Laundry, Bathroom, Master, Bedroom, Front, Garage and Room.

Execution of the AddDevice/AddLocation APIs should only be initiated through user interaction from the Dealer or end user. Inadvertent use of these APIs can result in drivers or locations recursively adding themselves to a project.

Available from 3.2.0.

Signature

C4:AddLocation ()

Returns

The API returns the new Location ID of the location that was added. It will return a value of 0 upon failure.

Examples

1: Adding a Site named Home to a Project:

C4:AddLocation(1, "HOME", "SITE")

In the example above, note that the AddLocation API will add the Site, “HOME” to the project. Note the use of the SITE parameter. This is the highest level available in a Control4 system. In this example, the ParentID must be the ID of the Project, which is always 1

2:  Adding a Building named "Office Building" to the Project.

C4:AddLocation(2, "Office Building", "BUILDING")

In the example above, the ParentID must be the ID of a Site

3: Adding a Floor named First Level to the Project

C4:AddLocation(3, "First Level", "FLOOR")

In the example above, the ParentID must be the ID of a Building

4: Adding a Room named Master Bathroom to the Project while using an image named "Bathroom":

C4:AddLocation(1, "Master Bathroom", "ROOM", "Bathroom")

In the example above, the room named Master Bathroom is not supported by a "Master Bathroom" image in a Control4 project. In this case, the image for Bathroom is used as it most closely matches the room being added.

For further reference, the idc_client and idc_controller sample drivers delivered with the SDK both include auto-add functionality in their Driver Actions. See the sample_drivers directory on the SDK landing page for further information.

Bind

Note the order of the parameters passed in the Bind API. Each has a "Provider" and "Consumer" designation. The Provider designation represents the Device ID value of the device providing the data within the binding. To verify if a device driver is a Provider, go to the driver's <Connections> XML.This API provides the ability to create a binding between two devices: a "Provider Device" and a "Consumer Device." The binding creation through this API is the same as manually creating a binding in ComposerPro's The <consumer> XML tag for this device's driver will be False or: <consumer>False</consumer>. Subsequently, the Provider Binding ID value is the Provider device's binding value.

Available from 2.9.0.

Signature

C4:Bind(idDeviceProvider, idBindingProvider, idDeviceConsumer, idBindingConsumer, strClass)

The Parameters with the Consumer designation represent the device that consumes data from the Provider device. The <consumer> XML tag for this device's driver will be True or: <consumer>True</consumer>. Subsequently, the Consumer Binding ID value is the Consumer device's binding value.

Returns

None

blowfishEcbDecrypt

Function to decrypt using Blowfish in ECB mode. ECB mode operates on exactly 64 bits (8 bytes) of data. This API can be invoked during OnDriverInit.

Available from 1.6.0.

Signature

C4:blowfishEcbEncrypt()

Returns

blowfishEcbEncrypt

Function to encrypt using Blowfish in ECB mode. ECB mode operates on exactly 64 bits (8 bytes) of data. This API can be invoked during OnDriverInit.

Available from 1.6.0.

Signature

C4:blowfishEcbEncrypt()

Returns

CallAsync

API that makes calling functions asynchronously much easier. This API should not be invoked during OnDriverInit.

Available from 1.6.0.

Signature

C4:CallAsync()

Example

print("Calling CallAsync()...")
 C4:CallAsync(function()
       print("Callback was executed.")

print("Called CallAsync().")

-- Example Output:
Calling CallAsync()...
Called CallAsync().
Callback was executed.

EvaluateExpression

EvaluateConditional evaluates the expression and returns a Boolean result. This API has 3 parameters, a logic operator and two operands. ‘value1’ is the left operand and ‘value2’ is the right operand.

Available from 2.10.0

Signature

C4:EvaluateExpression(logic, value1, value2)

Returns

True or False

Example

C4:EvaluateExpression("GREATER_THAN_OR_EQUAL", 50, 0)

In the example above, the expression could be written as “result = (50 >= 0)” and would evaluate to result being equal to “true”.

GetAllCodeItems

This function returns all Code Items within the project.

This API was introduced in O.S. Release 3.3.0

Signature

C4:GetAllCodeItems()

Parameters

None

Example

GetAllCodeItems returns a table with the device ID, the code item, and the event ID for each of the device ID/event ID pairs in the system. The table contains the following key-value pairs:

The table returned by the GetAllCodeItems API (that was stored in codeItems) might look like the table to the right.

{
    ["event_mgr"] = {
        [1] = {
            ["deviceid"] = 1,
            ["codeitem"] = {
                ["enabled"] = true,
                ["cmdcond"] = {
                    ["xml"] = 
                } ,
                ["creator"] = 0,
                ["device"] = 0,
                ["type"] = 1,
                ["display"] = ,
                ["subitems"] = {
                    [1] = {
                        ["enabled"] = true,
                        ["cmdcond"] = {
                            ["xml"] = <devicecommand owneridtype="" owneriditem="-1"><command>ON</command><params/></devicecommand>
                        } ,
                        ["creator"] = 0,
                        ["device"] = 19,
                        ["type"] = 1,
                        ["display"] = Turn on the NAME,
                        ["subitems"] = {} ,
                        ["creatorstate"] = ,
                        ["id"] = 1,
                    } 
                } ,
                ["creatorstate"] = ,
                ["id"] = 0
            } ,
            ["eventid"] = 1,
        } ,
        [2] = {
            ["deviceid"] = 100100,
            ["codeitem"] = {
                ["enabled"] = true,
                ["cmdcond"] = {
                    ["xml"] = 
                } ,
                ["creator"] = 0,
                ["device"] = 0,
                ["type"] = 1,
                ["display"] = ,
                ["subitems"] = {} ,
                ["creatorstate"] = ,
                ["id"] = 0,
            } ,
            ["eventid"] = 2,
        }
    }
}

GetBootID

This function returns a string that contains an ID which is unique for the current kernel instance. When the controller is re-booted, the ID will change. The returned value is the same value as the one stored on Linux at:

/proc/sys/kernel/random/boot_id

This API was introduced in O.S. Release 3.3.0

Signature

C4:GetBootID()

Parameters

None

Example

GetBootID returns a string with the current boot ID for the kernel. An example of the value that can be returned is:

1525a67e-b7bd-4a68-8919-dd65e7f3861a

GetCodeItems

This function returns Code Items for a specified device and event.

This API was introduced in O.S. Release 3.3.0

Signature

C4:GetCodeItems ()

Example

GetCodeItems returns a table with an entry for the device ID and event ID that were provided. The table contains the following key-value pairs :

Code Item Types

The table that is returned by the GetCodeItems command (that was stored in codeItems) would look like the table to the right.

{
    ["codeitems"] = {
        [1] = {
            ["enabled"] = true,
            ["cmdcond"] = {
                ["xml"] =
            } ,
            ["creator"] = 0,
            ["device"] = 0,
            ["type"] = 1,
            ["display"] = ,
            ["subitems"] = {
                [1] = {
                    ["enabled"] = true,
                    ["cmdcond"] = {
                        ["xml"] = <devicecommand owneridtype="" owneriditem="-1"><command>ON</command><params/></devicecommand>
                    } ,
                    ["creator"] = 0,
                    ["device"] = 19,
                    ["type"] = 1,
                    ["display"] = Turn on the NAME,
                    ["subitems"] = {} ,
                    ["creatorstate"] = ,
                    ["id"] = 1,
                }
            } ,
            ["creatorstate"] = ,
            ["id"] = 0
        }
    }
}

GetC4iDir

Function that will return the directory path on the controller where driver.c4i files reside.

Available from 2.10.0

Signature

C4:GetC4iDir()

Parameters

None

Returns

GetC4zDir

Function that will return the directory path on the controller where driver.c4z files reside.

Available from 2.10.0

Signature

C4:GetC4zDir()

Parameters

None

Returns

GetLogDir

Function that will return the directory path on the controller where log files reside.

Available from 2.10.0

Signature

C4:GetLogDir()

Parameters

None

Returns

getPushSettings

A Boolean API that returns the project’s current setting for the “Push Settings from Project” checkbox in Composer Pro’s Project properties screen. True equals a populated checkbox. False equals an un-populated checkbox. This is useful for determining if a driver can push settings to a device (true) or if settings will be sent from the device to the project (false).

Available from 2.7.0.

GetSandboxDir

Returns the directory where the LUA driver will store its files.

Available from 2.9.0

Signature

GetSandboxDir()

Example

print(C4:GetSandboxDir())

Outputs:

/control4/drivers/lua/sandbox/88

Note that the value of 88 in the example above is the Device ID for the driver.

GetTimeZone

Returns the Project's current Time Zone in the form of a LUA string. If there is no Time Zone set for the project, such as in the case of an unidentified controller, an empty string is returned.

Available from 3.0.0

Signature

C4:GetTimeZone ()

Parameters

None

Returns

Examples of return strings are: US/Mountain US/Pacific US/Samoa

Usage Note

The string value returned will be same as the Project value set in: Composer -> Project Settings -> Time Zone field.

hexdump

Prints out the values of a string in both hex and ascii representation. All characters that are not ‘A-Z’ or ‘0-9’ are printed as a ‘.’ in the ascii representation. The print goes to the Lua tab on the properties page of the driver. This API can be invoked during OnDriverInit.

Available from 1.6.0

Signature

hexdump(strDump)

Returns

None

Example

hexdump(tohex("00 ff de ad be ef ") .. "Test Text")

Prints out the following:
00000000  00 FF DE AD BE EF 54 65  ......Te
00000008  73 74 20 54 65 78 74     st.Text

OnBindingChanged

Function called by Director when a binding changes state (bound or unbound).

Available from 2.9.0

Signature

OnBindingChanged (idBinding, strClass, bIsBound, otherDeviceID, otherBindingID)

Returns

None

Usage Note

Protocol drivers do not get OnBindingChanged notifications for AV and Room bindings being bound, only control type bindings (Serial, IR, etc.). It is intended to be used specifically for when serial bindings are made, so the driver knows it can send initialization, etc. to the now-connected device.

ParseXML

Helper function which turns a XML document into a .lua table of parsed XML data. This API can be invoked during OnDriverInit.

Available from 2.7.0

Signature

C4:ParseXml (str)

Returns

Example

     function ParseProxyCommandArgs(tParams)
       local args = {}
       local parsedArgs = C4:ParseXml(tParams["ARGS"])
       for i,v in pairs(parsedArgs.ChildNodes) do
              args[v.Attributes["name"]] = v.Value
       end
       return args
      
end

print

Function called from DriverWorks driver to prints items out the drivers’ properties page console. Note that for convenience, the print function can be called without prefacing with "C4:" This API can be invoked during OnDriverInit.

Available from 1.6.0.

Signature

print(strPrintText)

Returns

None

Usage Note

The Lua output window in ComposerPro does not necessarily display output in the order in which code is actually executed. The print API is a function implemented in Lua which causes the driver to send a DataToUI message.

DataToUI commands are not guaranteed to be in any particular order. ComposerPro simply captures this DATA and displays it. If the order of data appearing in the ComposerPro Lua window is important, Control4 suggests the use of the Director log.

RecordHistory

Helper Function that writes history events to the History Agent database.

Available from 1.6.0.

Signature

C4:RecordHistory(severity, eventType, category, subcategory, description)

Returns

None

Example

C4:RecordHistory(“Critical”,"Disarm”,"Security”,”Front Door”,”The front door was disarmed.")

tohex

Function called from DriverWorks driver to convert a text string of hex into a string with hex values in it. Typically used when a protocol sends commands that are hex values. Note that for convenience, the print function can be called without prefacing with C4: This API can be invoked during OnDriverInit.

Available from 1.6.0.

Signature

C4:tohex(strHex)

Returns

None

Example

Store the HEX code for a discrete Power On command for a Mitsubishi TV:

POWER_ON = tohex("DF 80 70 F8 02 00 00")

tonumberloc

The Lua tonumber() function included in the Lua Library is locale specific. This can cause issues where the Control4 system is set to a locale where the decimal separator is different from what is returned by the target device. For example, if the target device sends the Control4 driver a string of 23.4 (23 decimal 4) but the locale expects this to be 23,4 (23 comma 4) then tonumber("23.4") will fail.  This problem often occurs in drivers where the UI uses decimal values and can occur with any proxy.

Driver writers must ensure that their drivers will not fail in these circumstances. To assist with this, Control4 has provided a function: tonumberloc(). This function is included in the driver templates beginning OS release 2.8.0 and its use ensures this problem does not occur.  Driver writers are advised to usetonumberloc()  in place of tonumber() in their code.

Available from 1.6.0.

Signature

tonumber_loc()

Example

function tonumber_loc(str, base)
        local s
        local num
        if type(str) == "string" then
                s = str:gsub(",", ".") -- Assume US Locale decimal separator
                num = tonumber(s, base)
                if (num == nil) then
                        s = str:gsub("%.", ",") -- Non-US Locale decimal separator
                        num = tonumber(s, base)
                end
        else
                num = tonumber(str, base)
        end
        return num
end

ToStringLocaleC

String helper function to convert a number to a string using the ‘C’ locale regardless of the locale setting of the Control4 Operating System. Some countries use commas instead of decimal points for floating point numbers. Lua ‘tostring’ command and string concatenation (..) with a number variable will convert the decimal value from a decimal point to a comma in some countries (locales). There may be instances where you do not want this conversion to take place and want the floating-point number to always be represented using a decimal point as opposed to a comma. In these cases, the C4:ToStringLocaleC(num) command can be used to convert the number to a string using decimal points.

Available from 1.6.0.

Signature

C4:ToStringLocaleC (num)

Example

The xml schema for extras functionality for thermostat proxy drivers requires that all floating-point numbers be represented using a period for the (decimal point). Using string concatenation to generate the extras xml would produce xml with the comma for the floating-point number if the locale is set to a country that uses commas.   For example, if you have a thermostat that supports an “Auto Temperature” that is not supported by the proxy that you would like displayed under “Extras” in the Thermostat UI you would need to generate the “Extras” xml to send to the UI. If the temperature represented is a floating-point number then when this number is converted to a string with ‘tostring’ or string concatenation (..), it would be converted to a number represented with a comma. In this case you would want to use the C4:ToStringLocaleC() API to convert the floating number appropriately.

unbind

This API provides the ability to unbind bound devices. The unbinding of the devices binding through this API is the same as manually unbinding two devices in ComposerPro's Connections area. Note the parameters passed in the API. Both have "Consumer" designation. These parameters represent the device that consumes data from the Provider device. To verify if a device driver is a Consumer, go to the driver's <Connections> XML. The <consumer> XML tag for this device's driver will be True or: <consumer>True</consumer>. Subsequently, the Consumer Binding ID value is the Consumer device's binding value.

Available from 2.9.0.

Signature

C4:Unbind(idDeviceConsumer, idBindingConsumer)

Returns

None

Example

C4:Unbind(81,1)

UUID

This API generates a UUID (Universally Unique IDentifier) as described in RFC 4122. The type of UUID that is generated depends on the arguments passed into the function.

Available from 3.3.0

Signature

C4:UUID(Type,[Value1,Value2,Value3])

The following section identifies the different types of UUIDs that are supported:

NIL

Required Argument: (”NIL”) A NIL UUID is one in which all bits are zero. It is represented as a string containing all zeros: 00000000-0000-0000-0000-000000000000

String

Required Argument: (”STRING”) A string containing the data to be formatted as a UUID. The String UUID type takes an input string and formats its contents as a UUID. The format of the string must match the following regular expression:

^({)?([0-9a-fA-F]{8})(?-)?([0-9a-fA-F]{4})(?(DASH)-)([0-9a-fA-F]{4})(?(DASH)-)([0-9a-fA-F]{4})(?(DASH)-)([0-9a-fA-F]{12})(?(1)})$

More generally, the following formats are accepted, where h is a valid hexadecimal character:

hhhhhhhh-hhhh-hhhh-hhhh-hhhhhhhhhhhh

{hhhhhhhh-hhhh-hhhh-hhhh-hhhhhhhhhhhh}

hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh

{hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh}

Name

Required Argument: (”NAME”)

Hash: The hashing algorithm to use when generating the UUID. Valid values including the following:

Namespace: A string containing the namespace to be used when generating the UUID. The value must be one of the following as described in Appendix C of RFC 4122:

Name: A string containing the content from which the UUID is derived.

Random

Required Argument: (”RANDOM”) Generates a random version 4 UUID (UUID4). The generator utilizes entropy provided by the operating system. For example: (i.e., /dev/urandom).

Returns

The function may return multiple values. On success, the function returns a string containing the newly generated UUID. On failure, the function returns nil and a string describing the failure.

XmlEscapeString

"Escapes" the passed in string rendering any XML characters (only &, <, and >) in the string as characters that are valid in an XML value. This API should not be invoked during OnDriverInit.

Available from 1.6.0.

Signature

C4:XmlEscapeString(strRawInput)

Returns

Example

Builds an XML string with a string that could have invalid XML characters in it:

strXmlListItem = "<text>" .. C4:XmlEscapeString .. "</text>"

Inbound Driver Interface

InBound Driver Interface

The functions listed below represent Lua functions that are not Control4 APIs but are however included in this documentation. The functions below are implemented within a DriverWorks driver and can be called by an API, Director or another external process.

For example, the Lua function UIRequest isn't a Control4 API. However, it is an InBound Driver Function that needs to be implemented in your driver if you intent to use the Control4 API:SendUIRequest. SendUIRequest sends a request to another driver. It uses the proxy or protocol ID value of the driver as a means to target the driver where the request will be sent. The driver receiving the SendUIRequest must have the InBound Driver Function UIRequest configured, which will contain the return values requested by the SendUIRequest call.

Here is an example of using SendUIRequest in a driver:

C4:SendUIRequest(231, "GET_MY_DRIVER_DATA", tParams)

In this example, the API contains a value of 231. This is the proxy ID value of the driver where the request is being sent. This is followed by a request called GET_MY_DRIVER_DATA. This is an expected request by the driver receiving the SendUIRequest. A table of parameters follows the command.

To the right is an example of the required UIRequest InBound Driver Function found in the driver receiving the SendUIRequest. In this example, when the request is received it takes the values in the tParams table and, if they are not a specified value of 640 or 480, multiplies them by 10. It then formats the values into XML and returns them through retValue to the driver that initiated the SendUIRequest.

function UIRequest(sRequest, tParams)
    tParams = tParams 
    local param_x = tonumber(tParams["PARAM_X"]) or 640
    local param_y = tonumber(tParams["PARAM_Y"]) or 480
               
         local value_x = param_x  10
         local value_y = param_y  10
               
         local retValue = "<driver_data>"
         retValue = retValue .. "<value_x>" .. value_x .. "</value_x>"
         retValue = retValue .. "<value_y>" .. value_y .. "</value_y>"
         retValue = retValue .. "</driver_data>"
               
    return retValue
end


--The XML below is the returned value.
<driver_data>`
    <value_x>10240</value_x>
    <value_y>7680</value_y>
</driver_data>

List of InBound Driver Functions:

• OnBindingChanged
• OnDriverDestroyed
• OnDriverLateInit
• OnDriverInit
• OnPropertyChanged
• SendUIRequest
• ExecuteCommand
• ReceivedFromSerial
• ReceivedFromProxy
• ReceivedFromNetwork
• GetPrivateKeyPassword
• OnVariableChanged
• OnWatchedVariableChanged
• OnConnectionStatusChanged
• OnServerConnectionStatusChanged
• OnServerDataIn
• OnNetworkBindingChanged
• OnZigbeeOnlineStatusChanged
• OnReflashLockGranted
• OnReflashLockRevoked

IR Interface

SendIR

Function called from DriverWorks driver to send an IR Code. This API should not be invoked during OnDriverInit.

Available from 1.6.0

Signature

C4:SendIR(idBinding,idIRCode)

Returns

None

Usage Note

The IR code to send must be declared as an <ircode\> in the <irsection\> section of the driver file.

SendIRStart

Causes Director to start sending the specified IR Code out the specified binding. This is typically used on button press events. This API should not be invoked during OnDriverInit.

Available from 1.6.0

Signature

C4:SendIRStart(idBinding, idBinding, idIRCode)

Returns

None

Usage Note

Failure to call the SendIRStop function will cause the IR code to be sent continually, which (in the case of volume ramps) could be catastrophic to equipment. The IR code to send must be declared as an <ircode\> in the <irsection\> of the driver file.

Example

This example starts sending the specified IR Code out the specified IR Binding:

C4:SendIRStart(1, 22)

SendIRStop

Causes Director to stop sending the specified IR Code out the specified binding. This is typically used on button release events. This API can be invoked during OnDriverInit.

Available from 1.6.0

Signature

C4:SendIRStop(idBinding,idBinding, idIRCode)

Returns

None

Usage Note

Usage Note: The IR code to send must be declared as an <ircode\> in the <irsection\> section of the driver file.

Example

This example stops sending the specified IR Code out the specified IR Binding:

C4:SendIRStop(1, 22)

JSON Interface

c4json.null

c4json is a global object that is used by the JSON encoder/decoder.

null Represents a JSON null value.

c4json.null can be used to insert a null value into a JSON document (encode), or test for a null value that was encountered in a JSON document (decode).

Json:Encode

JSON function that takes the data in the Lua tCommand table and encodes it into a JSON formatted command string representing a Lua object.  On success, this function returns a single value which is as designed. On failure, the function returns two values:

1. nil
2. A string describing the error.

This API should not be invoked during OnDriverInit.

Where necessary, the encoder uses the following fabricated names:

Examples

Primitive
local Foo = "Bar"
local Result = c4:JsonEncode(Foo)

The preceding example yields the following JSON string: {":string:":"Bar"} This occurs because "Foo" is a primitive type (i.e., String). Unfortunately, the name of a single primitive value is unknown to the encoder so it must use a fabricated name that identifies the type. This is necessary because the JSON specification requires that all JSON objects consist of name/value pairs in which the name must be a string (i.e., double quotes).

Note that you'll need to use a Lua table in order to provide a JSON string that includes the name of the value. Consider the following example.

Table
local MyTable = {
    Foo = "Bar"
}

C4:JsonEncode(MyTable)

The preceding example produces the following JSON string: {“Foo”:”Bar”} It is also possible to control whether the resulting JSON string is formatted using newlines and indentations.

Unformatted
local Foo = {
    Biz = "Baz",
    Qux = "Norf"
}

C4:JsonEncode(Foo)

The preceding example yields the following JSON string: {“Biz”:”Baz”,”Qux”:”Norf”}. This might be acceptable when the string is to be used in processes that don't involve humans, such as invoking a REST service. If readability is important, however, provide the formatted (second) parameter.

Formatted
local Foo = {
    Biz = "Baz",
    Qux = "Norf"
}

C4:JsonEncode(Foo, true)

With this example, the resulting JSON string is formatted as:

{
    "Biz" : "Baz"
    "Qux" : "Norf"
} 

The encodeArrays (third) parameter provides control over how tables are encoded. In certain cases it might be necessary to specify that tables are encoded as JSON arrays. Note that a Lua table is considered to be an array when each key is a non-negative integer greater than zero (k > 0). Consider the following code.

Object
local Foo = {
    "One",
    "Two",
    "Three",
    "Four",
}

C4:JsonEncode(Foo, true)

By default, tables are encoded using JSON objects, so the preceding example produces the following formatted JSON string:

{
    "1" : "One"
    "2" : "Two"
    "3" : "Three"
    "4" : "Four"
}

This encoding results for two reasons: First, the table is a Lua array. Each entry corresponds to a numeric key. Second the JSON specification requires that an object consist of name/value pairs in which each name must be a string (i.e., double quotes). As a result, each numeric key is converted to a string. This same table can also be represented as a JSON array.

Array
local Foo = {
    "One",
    "Two",
    "Three",
    "Four",
}

C4:JsonEncode(Foo, true, true)

With the encodeArrays (third) parameter set to true, the encoder yields the following JSON string: [ “One”, “Two”, “Three”, “Four” ]

It is important to note that the encodeArrays parameter affects only tables that are Lua arrays. Consider the following code.

Non-Array
local Foo = {
    Biz = "Baz",
    Quz = "Norf"
}

C4:JsonEncode(Foo, true, true)

Although the encodeArrays parameter was set to true, the resulting JSON string is encoded as JSON object:

{
    "Biz" : "Baz",
    "Qux" : "Norf"

}

This occurs because the Lua table was not an array (i.e., contained at least one non-numeric key). Attempting to encode this table as an array would result in an invalid JSON string.

The symmetric (fourth) parameter specifies whether to use symmetric encoding. When symmetric encoding is enabled, the encoder places certain markers within the resulting JSON string. These markers make it possible to decode a JSON string back into the original (equivalent) object. Symmetric encoding (markers) is necessary due to ambiguities that arise when encoding a Lua object. Consider the following code.

Non-Symmetric
local Foo = {
    "One",
    {
        Two = "Two",
        Three = "Three",
    }
}

C4:JsonEncode(Foo, true, false)

While this accurately represents the Lua object as a JSON string, given the rules of Lua arrays and JSON, it cannot be decoded back into its original (equivalent) table. Rather, decoding this string will produce the following Lua table.

local Bar = {
    ["1"] = "one",
        ["2"] = {
        Two = "Two",
        Three = "Three",
    }
}

Note that the original numeric keys are now strings. Enable symmetric encoding corrects this problem by introducing markers into the resulting JSON string.

Symmetric
local Foo = {
    "One",
    {
        Two = "Two",
        Three = "Three",
    }
}

C4:JsonEncode(Foo, true, false, true)

With the symmetric parameter set to true, the encoder produces the following JSON string:

{
    ":index:1 : "One",
    ":index:2" : "Two" : {
        "Three" : "Three",
        "Two" : "Two"
    }
}

Note the use of the ":index:" markers. These markers specify that the first element, "One", is located at the first numeric index. Similarly, the second element, "Two", is located at the second numeric index. Decoding this JSON string produces the original Lua table. It is important to note that Lua doesn't guarantee any particular order when enumerating the elements of a table. As described in the documentation for the Lua next function. The order in which the indices are enumerated is not specified, even for numeric indices.

Json:Decode

JSON function that takes data from the JSON formatted string message and decodes it into the Lua table. On success, this function returns a single value which is as designed. On failure, the function returns two values:

1. nil
2. A string describing the error.

This API should not be invoked during OnDriverInit.

Signature

C4:JsonDecode(json)

Returns

A value decoded from the specified JSON string.

Examples

Primitive C4:JsonDecode("{":number:":42}")

The preceding example will return a Number with the value: 42. In most cases, however, the decoder will return a table. Consider the following code:

Table
local value  = '{"Contents":["Asia", "Africa", "North America", "South America", "Europe", "Australia"]}'
local Foo = C4:JsonDecode(value)

The preceding example produces the following Lua table:

local Foo = {
    "Continent" = {
        "Asia",
        "Africa", 
        "North America", 
        "South America", 
        "Europe", 
        "Australia"
    }
}

Log Interface

DebugLog

Function called from DriverWorks driver to send messages to the following log files: director.log and driver.log. This API can be invoked during OnDriverInit.

Available from 1.6.0

Signature

C4:DebugLog(strLogText)

Returns

None

Examples

function Log:Alert(strDebugText)
   self:Print(0, strDebugText)
end

function Log:Error(strDebugText)
   self:Print(1, strDebugText)
end

function Log:Warn(strDebugText)
   self:Print(2, strDebugText)
end

function Log:Info(strDebugText)
   self:Print(3, strDebugText)
end

function Log:Trace(strDebugText)
   self:Print(4, strDebugText)
end

function Log:Debug(strDebugText)
   self:Print(5, strDebugText)
end

ErrorLog

Function called from DriverWorks driver to send messages to the following log files: director.log and driver.log.

Available from 1.6.0

Signature

C4:ErrorLog(strLogText)

Example

Here is an example using a variable called "lightLevel" to send an error log when a light level exceeds the value of 100:

If (lightLevel > 100) then
   C4:ErrorLog(“ERROR: light level out of range”)
end

TCPClient Interface

CreateTCPClient

Generally, the class cleans up any resources associated with it.  For example, when the object is no longer referenced, it will cleans it up.  However, there are a few exceptions:  When the class is performing an asynchronous operation, e.g. a connect request, it will remain alive until the appropriate event callback function is called. 

For instance, if you call the Connect() method, the class will remain alive until it either called the OnConnect (and OnResolve) callback function, or the OnError callback function, even if your lua code does not have any reference to the class during that time period.  The same applies to the time period between calling one of the Read() methods and the corresponding OnRead() or OnError() callback, and in between calling the Write() method and the OnWrite() or OnError() callback. This API should not be invoked during OnDriverInit.

Available in 1.6.0

Example

function PullHttpPage(host, path, timeout, done)
 local timer
 local completed = false
 local complete = function(data, errMsg)
  if (not completed) then
   completed = true
   if (timer ~= nil) then
    timer:Cancel()
   end
   done(data, errMsg)
  end
 end
 local readingHeaders, needBytes, response, allReceived
 local cli = C4:CreateTCPClient()
  :OnConnect(function(client)
   local remote = client:GetRemoteAddress()
   print("Connected to " .. remote.ip .. ":" .. remote.port)
   client:Write("GET " .. path .. " HTTP/1.0\r\nHost: " .. host .. "\r\n\r\n"):ReadUntil("\r\n")
   readingHeaders = true
   needBytes = nil
   response = ""
   allReceived = false
  end)
  :OnResolve(function(client, endpoints, choose)
   -- Implementing this callback is optional
   print("Resolved.  Artificially delay choosing endpoint by one second...")
   C4:SetTimer(1000, function(_)
    --choose(1) -- This would choose the first endpoint in the endpoints array
    --choose(0) -- Abort the connection request
    choose() -- Default behavior, this chooses the first endpoint (if available)
   end)
  end)
  :OnDisconnect(function(client, errCode, errMsg)
   if (errCode ~= 0) then
    complete(nil, "Disconnected with error " .. errCode .. ": " .. errMsg)
   elseif (needBytes == nil) then
    complete(nil, "Disconnected and no or invalid response received")
   elseif (needBytes > 0) then
    complete(nil, "Disconnected and received partial response")
   end
  end)
  :OnRead(function(client, data)
   if (readingHeaders) then
    if (data ~= "\r\n") then
     -- Look for the Content-Length header
     local sep = string.find(data, ":", 1, true)
     if (sep ~= nil and sep > 1) then
      local header = string.lower(string.sub(data, 1, sep - 1))
      local value = string.sub(data, sep + 1, -2)
      if (header == "content-length") then
       needBytes = tonumber(value)
      end
     end
     client:ReadUntil("\r\n")
    else
     readingHeaders = false
     if (needBytes ~= nil and needBytes > 0) then
      -- Got all headers, now read the body
      client:ReadUpTo(needBytes)
     else
      -- No body to read
      client:Close()
      if (needBytes == 0) then
       complete("")
      end
     end
    end
   else
    -- Append the body data
    response = response .. data
    needBytes = needBytes - string.len(data)
    if (needBytes > 0) then
     -- We haven't received everything, read more
     client:ReadUpTo(needBytes)
    else
     -- We received the entire body
     client:Close()
     complete(response)
    end
   end
    end)
  :OnError(function(client, errCode, errMsg)
   complete(nil, "Error " .. errCode .. ": " .. errMsg)
  end)
  :Connect(host, 80)
 if (timeout > 0) then
  timer = C4:SetTimer(timeout, function()
   cli:Close()
   complete(nil, "Timed out!")
  end)
 end
end
print("Downloading http://example.com/ ...")
PullHttpPage("example.com", "/", 5000, function(info, err)
 if (info ~= nil) then
  print("GOT: " .. tostring(info))
 else
  print("ERROR: " .. err)
 end
end)

Close

This method closes an established connection, or cancels a pending resolve or connection request. If a resolve or connection request is canceled, the OnError callback function will get called. This API should not be invoked during OnDriverInit. Once you call this method, no more data will be read from the socket and you can no longer write additional data to the socket. Also, the OnWrite callback will not be called anymore, even if the flush argument is set to true.

Available in 1.6.0

Signature

C4:Close(flush)

Connect

This method initiates a connection request to a host and service/port. If a connection request is already in progress, this function returns nil. This API should not be invoked during OnDriverInit.

Available in 1.6.0

Signature

C4:Connect(host, service)

Returns

This method returns a reference to itself, or nil in case of an error.

GetLocalAddress

This method returns a table with the IP address and port of the local endpoint. This API should not be invoked during OnDriverInit.

Available in 1.6.0

Signature

C4:GetLocalAddress()

Parameters

None

Returns

GetRemoteAddress

This method returns a table with the IP address and port of the remote endpoint. This API should not be invoked during OnDriverInit.

Available in 1.6.0

Signature

C4:GetRemoteAddress()

Parameters

None

Returns

OnConnect

This method sets a callback method that will be called once the endpoint has been chosen and the connection is successfully established.

Available in 1.6.0

Signature

C4:OnConnect(func)

Returns

This method returns a reference to itself.

OnDisconnect

This method sets a callback method that will be called when the client gets disconnected.

Available in 1.6.0

Signature

C4:OnDisconnect(func)

Usage Note

• client is this C4LuaTCPClient instance.
• errCode is a number with an error code, if the connection was disconnected due to an error. If the connection was disconnected gracefully, this value will be 0.
• errMsg is a string with a description of the error indicated by errCode.

Returns

This method returns a reference to itself.

OnError

This method sets a callback method that will be called when an error happens during an asynchronous operation.

Available in 1.6.0

Signature

C4:OnError(func)

Usage Note

• server is this C4LuaTCPServer instance
• code is a number with the system error code
• msg is a string with a description of the error

Returns

This method returns a reference to itself.

OnRead

This method sets a callback method that will be called once data has been read on the socket.  If you would like to keep reading more data, you should call one of the Read() methods prior to returning from this callback function.

Available in 1.6.0

Signature

C4:OnRead(func)

Usage Note

• client is this C4LuaTCPClient instance
• data is a string with the data that has been read. This can also be any object if you used the ReadUntil() method with a custom function that returns an object (e.g. pre-parsed data).

Returns

This method returns a reference to itself.

OnResolve

This method sets a callback method that is called once the host/service has been resolved.  If implemented, it allows you to choose a particular endpoint to connect to, or to cancel the connection request.

Available in 1.6.0

Signature

C4:OnResolve(func)

Usage Note

• client is this C4LuaTCPClient instance
• endpoints is an array of endpoint tables, describing all endpoints that the host/service could be resolved to. Each entry has the following fields: ip (string): The IP address to connect to and port (number) - The port number to connect to
• choose is a completion function with this signature:

function([index])

Using this closure is optional and can be used to delay making a choice. The index argument is of type number, and it is optional.  If not provided, default behavior is requested (first endpoint, if available). If the index argument is provided, it should be an index into the endpoints array.  If the index argument is 0, the listen request will be canceled and the OnError callback will be called with an invalid argument error (code 22). func may return a number value that describes the index into the endpoints array, which will be the endpoint that the server should listen on. If this value is 0, the listen request will be canceled and the OnError callback will be called with an invalid argument error (code 22). If the function doesn't return anything, default behavior is chosen unless the choose function is being used to delay making a choice.  Note that if you call the choose function prior to returning from this callback function, that choice will be used rather than whatever the callback may return (if anything). Also, note that modifying the endpoints array (or any table in it) in any way has no effect.|

Returns

This method returns a reference to itself.

Option

This method sets a socket option. This API should not be invoked during OnDriverInit.

Available in 1.6.0

Signature

C4:Option(name, value[, ...])

Returns

This method returns a reference to itself, or nil in case of an error.

ReadAtLeast

This method requests to read at least as many bytes as specified by the min argument. Once at least this amount of data is available, all available data is passed to the OnRead callback. This API should not be invoked during OnDriverInit.

Available in 1.6.0

Signature

C4:ReadAtLeast(min)

Returns

This method returns a reference to itself, or nil in case of an error.

ReadUntil

This method requests to read data until a specific condition is met. This API should not be invoked during OnDriverInit.

Available in 1.6.0

Signature

C4:ReadUntil(arg) 

Returns

ReadUntilOneOf

This method requests to read data until (and including) one of the bytes in the str argument is encountered. This API should not be invoked during OnDriverInit.

Available in 1.6.0

Signature

C4:ReadUntilOneOf(str)

Returns

This method returns a reference to itself, or nil in case of an error.

ReadUntilOneNotOf

This method requests to read data until (and including) any byte that is not in the str argument is encountered. This API should not be invoked during OnDriverInit.

Available in 1.6.0

Signature

C4:ReadUntilOneNotOf(str)

Returns

This method returns a reference to itself, or nil in case of an error.

ReadUpTo

This method requests to read any available data up to (and including) the number of bytes specified by the max argument.  Once data is available, the OnRead callback will be called with whatever data was available, but no more than the limit specified in the max argument. This API should not be invoked during OnDriverInit

Available in 1.6.0

Signature

C4:ReadUpTo(max)

Returns

This method returns a reference to itself, or nil in case of an error.

TCPServer Interface

CreateTCPServer

This class does not in any way manage or keep track of connected clients.  If you explicitly Close() the TCP server or it goes out of scope and gets cleaned up by lua's garbage collector, it does not affect any of the accepted client connections. You can keep track of connected clients by saving them into a map in the OnAccept callback, and setting up a OnDisconnect callback for the connected client connection that removes that client from that map.

Generally, the class cleans up any resources associated with it.  For example, when the object is no longer referenced, it will clean it up.  However, there are a few exceptions:  When the class is performing an asynchronous operation, e.g. a listen request, it will remain alive until the appropriate event callback function is called.  For instance, if you call the Listen() method, the class will remain alive until it either called the OnListen (and OnResolve) callback function, or the OnError callback function, even if your lua code does not have any reference to the class during that time period.  However, once the OnListen callback was called, the class gets cleaned up unless at that point your lua code somehow references this instance. This API should not be invoked during OnDriverInit.

Available in 1.6.0

Example

This is an example of a chat server that accepts a configurable number of clients and shuts the server down after a configurable number of minutes.  It manages all its client connections and shuts them down when the server is being shut down.

local server = {
       clients = {},
       clientsCnt = 0,
       --socket = nil,
       notifyOthers = function(self, client, message)
              for cli,info in pairs(self.clients) do
                     if (cli ~= client and info.name ~= nil) then
                           cli:Write(message .. "\r\n")
                     end
              end
       end,
       broadcast = function(self, client, message)
              local info = self.clients[client]
              print("broadcast for client " .. tostring(client) .. " info: " ..tostring(info))
              if (info ~= nil and info.name ~= nil) then
                     self:notifyOthers(client, info.name .. " wrote: " .. message .. "\r\n")
                     client:Write("You wrote: " .. message .. "\r\n")
              end
       end,
       haveName = function(self, name)
              for _,info in pairs(self.clients) do
                     if (info.name ~= nil and string.lower(info.name) == string.lower(name)) then
                           return true
                     end
              end
              return false
       end,
       stripControlCharacters = function(self, data)
              local ret = ""
              for i in string.gmatch(data, "%C+") do
                     ret = ret .. i
              end
              return ret
       end,
       stop = function(self)
              if (self.socket ~= nil) then
                     self.socket:Close()
                     self.socket = nil


-- Make a copy of all clients and reset the map.
                     -- This ensures that calls to self:broadcast() and self:notifyOthers()
                     -- during the shutdown process get ignored.  All we want the clients to
                     -- see is the shutdown message.
                     local clients = self.clients
                     self.clients = {}
                     self.clientsCnt = 0

for cli,info in pairs(clients) do
                           print("Disconnecting " .. cli:GetRemoteAddress().ip .. ":" .. cli:GetRemoteAddress().port .. ": name: " .. tostring(info.name))
                           cli:Write("Server is shutting down!\r\n"):Close(true)
                     end
              end
       end,
       start = function(self, maxClients, bindAddr, port, done)
              local calledDone = false
              self.socket = C4:CreateTCPServer()
                     :OnResolve(
                           function(srv, endpoints)

print("Server " .. tostring(srv) .. " resolved listening address")
                                  for i = 1, #endpoints do
                                         print("Available endpoints: [" .. i .. "] ip=" .. endpoints[i].ip .. ":" .. endpoints[i].port)
                                  end
                           end
                     )
                     :OnListen(
                            function(srv, endpoint)
                                  -- Handling this callback is optional.  It merely lets you know that the server is now actually listening.
                                  local addr = srv:GetLocalAddress()
                                  print("Server " .. tostring(srv) .. " chose endpoint " .. endpoint.ip .. ":" .. endpoint.port .. ", listening on " .. addr.ip .. ":" .. addr.port)
                                  if (not calledDone) then
                                         calledDone = true
                                         done(true, addr)
                                  end
                           end
                     )
                     :OnError(
                           function(srv, code, msg, op)
                                  -- code is the system error code (as a number)
                                  -- msg is the error message as a string
                                  print("Server " .. tostring(srv) .. " Error " .. code .. " (" .. msg .. ")")
                                  if (not calledDone) then
                                         calledDone = true
                                         done(false, msg)
                                  end
                           end
                     )
                     :OnAccept(
                           function(srv, client)
                                  -- srv is the instance C4:CreateTCPServer() returned
                                  -- client is a C4LuaTcpClient instance of the new connection that was just accepted
                                  print("Connection on server " .. tostring(srv) .. " accepted, client: " .. tostring(client))
                                  if (self.clientsCnt >= maxClients) then
                                         client:Write("Sorry, I only allow " .. maxClients .. " concurrent connections!\r\n"):Close(true)
                                         return
                                   end
                                  local info = {}
                                  self.clients[client] = info
                                  self.clientsCnt = self.clientsCnt + 1
                                  client
                                         :OnRead(
                                                function(cli, data)
                                                       -- cli is the C4LuaTcpClient instance (same as client in the OnAccept handler) that the data was read on
                                                       if (string.sub(data, -2) == "\r\n") then
                                                              -- Need to check if the delimiter exists.  It may not if the client sent data without one and then disconnected!
                                                              data = string.sub(data, 1, -3) -- Cut off \r\n
                                                       end
                                                       data = self:stripControlCharacters(data)
                                                       if (info.name == nil) then
                                                              if (#data > 0) then
                                                                     if (self:haveName(data)) then
                                                                           cli:Write("Choose a different name, please:\r\n")
                                                                     else
                                                                           info.name = data
                                                                           self:notifyOthers(cli, info.name .. " joined!\r\n")
                                                                           cli:Write("Thank you, " .. info.name .. "! Type 'quit' to disconnect.\r\n")
                                                                     end
                                                              else
                                                                     cli:Write("Please enter your name:\r\n")
                                                              end
                                                              cli:ReadUntil("\r\n")
                                                       elseif (data == "quit") then
                                                              cli:Write("Goodbye, " .. info.name .. "!\r\n"):Close(true)
                                                       else
                                                              if (#data > 0) then
                                                                     self:broadcast(cli, data)
                                                              end
                                                              cli:ReadUntil("\r\n")
                                                       end
                                                end
                                         )
                                         :OnWrite(
                                                function(cli)
                                                       -- cli is the C4LuaTcpClient instance (same as client in the OnAccept handler).  This callback is called when
                                                       -- all data was sent.
                                                       print("Server " .. tostring(srv) .. " Client " .. tostring(client) .. " Data was sent.")
                                                end
                                         )
                                         :OnDisconnect(
                                                function(cli, errCode, errMsg)
                                                       -- cli is the C4LuaTcpClient instance (same as client in the OnAccept handler) that the data was read on
                                                       -- errCode is the system error code (as a number).  On a graceful disconnect, this value is 0.
                                                       -- errMsg is the error message as a string.
                                                       if (errCode == 0) then
                                                              print("Server " .. tostring(srv) .. " Client " .. tostring(client) .. " Disconnected gracefully.")
                                                       else
                                                              print("Server " .. tostring(srv) .. " Client " .. tostring(client) .. " Disconnected with error " .. errCode .. " (" .. errMsg .. ")")
                                                       end

if (info.name ~= nil) then
                                                              self:notifyOthers(cli, info.name .. " disconnected!\r\n")
                                                       end
                                                       self.clients[cli] = nil
                                                       self.clientsCnt = self.clientsCnt - 1
                                                end
                                         )
                                         :OnError(
                                                function(cli, code, msg, op)
                                                       -- cli is the C4LuaTcpClient instance (same as client in the OnAccept handler) that the data was read on
                                                       -- code is the system error code (as a number)
                                                       -- msg is the error message as a string
                                                       -- op indicates what type of operation failed: "read", "write"
                                                       print("Server " .. tostring(srv) .. " Client " .. tostring(client) .. " Error " .. code .. " (" .. msg .. ") on " .. op)
                                                end
                                         )
                                         :Write("Welcome! Please enter your name:\r\n")
                                         :ReadUntil("\r\n")
                           end
                     )
                     :Listen(bindAddr, port)
              if (self.socket ~= nil) then
                     return self
              end
       end
}

-- Start the server with a limit of 5 concurrent connections, listen on all interfaces on a randomly available port.  The server will shut down after 10 minutes.
server:start(5, "", 0, function(success, info)
       if (success) then
              local minutes = 10
              print("Server listening on " .. info.ip .. ":" .. info.port .. ". Will stop in " .. minutes .. " minutes!")
              C4:SetTimer(minutes  60 * 1000, function()
                     print("Stopping server and disconnecting clients now.")
                     server:stop()
              end)
       else
              print("Could not start server: " .. info)
       end
end)