84531515 Control4 Driver Works SDK Driver Works API Reference Guide

Control4 DriverWorks Software Development Kit

DriverWorks API Reference Guide

Control4 DriverWorks SDK – API Reference Guide Page 2 Copyright 2009 Control4 Corporation, All Rights Reserved Version 1.7.3

The information contained in this document is the intellectual property of Control4 Technologies. The holder of this document shall keep all information contained herein confidential and shall protect this information in whole or in part from disclosure to any and all third parties except as specifically authorized in writing by Control4 Technologies. Disclaimer Control4® makes no representations or warranties with respect to this publication, and specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose. Control4 reserves the right to make changes to any and all parts of this publication at any time, without any obligation to notify any person or entity of such changes. Trademarks Control4 and the Control4 logo and DriverWorks are trademarks or registered trademarks of Control4 Corporation. Other product and company names mentioned in this document may be the trademarks or registered trademarks of their respective owners. Copyright Copyright © 2004-2009 Control4. All rights reserved. No part of this publication may be reproduced, photocopied, stored on a retrieval system, or transmitted without the express written consent of the publisher. Contact Us Control4 Corporation 11734 S. Election Road Salt Lake City, UT 84020 USA http://www.control4.com


Table of Contents

Table of Contents ..................................................................... 3

1.0 Proxy Interface .................................................................. 8

SendToProxy .............................................................................................. 8 ReceivedFromProxy ..................................................................................... 9

1.1 Director Command Interface ............................................ 10

ExecuteCommand ...................................................................................... 10 GetVersionInfo .......................................................................................... 11 GetUniqueMAC .......................................................................................... 11

1.2 Serial/Network/Device Interface ..................................... 11

SendToSerial............................................................................................. 11 ReceivedFromSerial ................................................................................... 12 SendToNetwork ......................................................................................... 13 ReceivedFromNetwork ................................................................................ 13 NetConnect ............................................................................................... 14 NetDisconnect ........................................................................................... 14 OnConnectionStatusChanged ....................................................................... 14 OnNetworkBindingChanged ......................................................................... 15 SendToDevice ........................................................................................... 15

1.3 Variable Interface ............................................................ 17

AddVariable .............................................................................................. 17 SetVariable ............................................................................................... 17 DeleteVariable ........................................................................................... 18 OnVariableChanged .................................................................................... 18 DriverWorks Variables Table ........................................................................ 18 GetVariable ............................................................................................... 19 GetDeviceVariable ..................................................................................... 19 SetDeviceVariable ...................................................................................... 19 RegisterVariableListener ............................................................................. 20 UnregisterVariableListener .......................................................................... 21 OnWatchedVariableChanged ........................................................................ 21

1.4 Timer Interface ................................................................ 22

AddTimer ................................................................................................. 22 KillTimer ................................................................................................... 22 OnTimerExpired......................................................................................... 23 OnDriverDestroyed .................................................................................... 23


1.5 Event Interface ................................................................. 24

FireEvent .................................................................................................. 24

1.6 IR Interface ...................................................................... 24

SendIR ..................................................................................................... 24 SendIRStart .............................................................................................. 24 SendIRStop .............................................................................................. 25

1.7 Properties Interface ......................................................... 25

UpdateProperty ......................................................................................... 25 OnPropertyChanged ................................................................................... 25 DriverWorks Properties Table ...................................................................... 26

1.8 Log Interface .................................................................... 27

DebugLog ................................................................................................. 27 ErrorLog ................................................................................................... 28

1.9 Miscellaneous ................................................................... 28

DriverWorks PersistData Table ..................................................................... 28 GetDeviceID ............................................................................................. 28 GetCapability ............................................................................................ 28 OnBindingChanged .................................................................................... 29 AddDynamicBinding ................................................................................... 29 RemoveDynamicBinding ............................................................................. 31 Base64Encode ........................................................................................... 31 Base64Decode .......................................................................................... 31 OnPoll ...................................................................................................... 32 XMLEscapeString ....................................................................................... 32 CRC32 ..................................................................................................... 33 TEAEncrypt ............................................................................................... 33 TEADecrypt ............................................................................................... 33 ntoh_l ...................................................................................................... 34 hton_l ...................................................................................................... 34 GetProxyDevices ....................................................................................... 35

1.10 Helper Functions ............................................................ 35

Print ........................................................................................................ 35 tohex ....................................................................................................... 36 hexdump .................................................................................................. 36

1.11 Debug Interface Section ................................................. 36

EnableRemoteDebugging ............................................................................ 36 DisableRemoteDebugging ........................................................................... 37 Attach ...................................................................................................... 37


OnEndDebugSession .................................................................................. 37

1.12 Media Management - Generic ......................................... 38

MediaRemoveAllMedia ................................................................................ 38 MediaSetDeviceContext .............................................................................. 38 MediaGetDeviceContext .............................................................................. 38

1.13 Media Management – Movies .......................................... 39

MediaAddMovieInfo .................................................................................... 39 MediaGetMovieInfo .................................................................................... 39 MediaGetMovieLocation .............................................................................. 40 MediaGetAllMovies ..................................................................................... 40 MediaRemoveMovie.................................................................................... 40 MediaRemoveAllMovies ............................................................................... 40 MediaModifyMovieInfo ................................................................................ 41

1.14 Media Management – Albums ......................................... 42

MediaAddAlbumInfo ................................................................................... 43 MediaGetAlbumInfo .................................................................................... 43 MediaGetAlbumLocation .............................................................................. 43 MediaGetAllAlbums .................................................................................... 44 MediaRemoveAlbum ................................................................................... 44 MediaRemoveAllAlbums .............................................................................. 44 MediaModifyAlbumInfo ............................................................................... 45

1.15 Media Management – Songs ........................................... 45

MediaGetSongInfo ..................................................................................... 45 MediaGetSongLocation ............................................................................... 45 MediaRemoveSong..................................................................................... 46 MediaLinkSongToAlbum .............................................................................. 46 MediaGetSongsforAlbum ............................................................................. 46 MediaModifySongInfo ................................................................................. 46

1.16 List Navigator Functionality ............................................ 48

ListSetCapabilities...................................................................................... 48 ListStart ................................................................................................... 49 ListStop ................................................................................................... 49 ListGetItems ............................................................................................. 50 ListSendCommand ..................................................................................... 50 ListGetRoomID .......................................................................................... 51 ListGoToRoot ............................................................................................ 51 ListIsStarted ............................................................................................. 51 ListIsInNavigation ...................................................................................... 51 ListNewList ............................................................................................... 53 ListMIBReceived ........................................................................................ 53 ListNewControl .......................................................................................... 54


ListEvent .................................................................................................. 55

Encoded Item Values .............................................................. 56

DriverWorks and Zigbee Functionality .................................... 57

Send/Receive Data from Zigbee ................................................................... 57 SendZigbeePacket ..................................................................................... 57 OnZigbeePacketIn...................................................................................... 58 OnZigbeePacketSuccess ............................................................................. 59 OnZigbeePacketFailed ................................................................................ 59 OnZigbeeOnlineStatusChanged .................................................................... 60 Updating Zigbee Device firmware Using DriverWorks ...................................... 60 Encoded BLOB data in the .c4i file ................................................................ 60 GetBlobByName ........................................................................................ 61 RequestReflashLock ................................................................................... 62 KeepReflashLock ....................................................................................... 62 ReleaseReflashLock .................................................................................... 62 OnReflashLockGranted ............................................................................... 62 OnReflashLockRevoked ............................................................................... 62


Control4 DriverWorks SDK Reference Guide Description The Control4 DriverWorks SDK can be used to create two-way serial and network drivers for third party devices. A DriverWorks driver is completely defined by a .c4i file that is not compiled by the driver creator before it is used by the Control4 system. An embedded Lua interpreter exists on the Control4 Controller that executes the Lua code found within the .c4i file. How do I learn about DriverWorks in order to write a driver? There are two reference materials from Control4 that you will find useful: 1. Getting Started with DriverWorks explains the basic concepts and how to get started with the development of a DriverWorks driver. This is not an exhaustive reference document but is intended to teach you what you need to know to get started. 2. DriverWorks Reference Guide (this document) – this guide documents all APIs available through DriverWorks. This is required reference material for driver creators. In addition to this source material, you may benefit from referencing material on

In addition to this source material, you may benefit from referencing material on Lua. Official Lua Website http://www.lua.org Lua FAQ http://lua-users.org/wiki/LuaFaq Programming In Lua (online version) http://www.lua.org/pil/ Lua 5.1 Reference Manual http://www.lua.org/manual/5.1/ Lua vs. Other Languages http://lua-users.org/wiki/LuaComparison Lua Testimonials http://www.lua.org/quotes.html Lua Wikipedia Entry http://en.wikipedia.org/wiki/Lua 1996 DDJ article on Lua goals and purposes: http://www.lua.org/ddj.html Note: Some of the functions used in the samples found in this section use “C4:”as a prefix, for example: C4:SendToProxy. Other functions do not use the “C4:” prefix, for example ReceivedFromProxy. Functions that DriverWorks drivers call utilize the “C4:” Functions that are called by Director, do not.

http://www.lua.org/

http://lua-users.org/wiki/LuaFaq

http://www.lua.org/pil/

http://www.lua.org/manual/5.1/

http://lua-users.org/wiki/LuaComparison

http://www.lua.org/quotes.html

http://en.wikipedia.org/wiki/Lua

http://www.lua.org/ddj.html


1.0 Proxy Interface

SendToProxy C4:SendToProxy(idBinding, strCommand, tParams, strmessage) or C4:SendToProxy(idBinding, strCommand, strParam) Function called from DriverWorks driver to send a Control4 BindMessage to the proxy bound to the specified binding.

Returns

None Parameters

idBinding - Binding ID for the proxy you wish to send to strCommand - Command to send to the proxy tParams - Lua table containing parameters to the command.

TBD: Show how to send things other than strings or numbers, which are auto-converted.

Strmessage - COMMAND or NOTIFY – Overrides the default message type that SendToProxy will send by default. SendToProxy will send a NOTIFY if it is equal to or more than a 1000 and a Command if it is less than a 1000. Examples C4:SendToProxy(11, "CLOSED", {}) Notify the attached contact binding that the contact has closed. Note that tParams is required, if there are no parameters, send an empty Lua table. C4:SendToProxy(5001, "TEMPERATURE_CHANGED", {TEMPERATURE = 76}) Notify the attached thermostat binding that the temperature is now 76. C4:SendToProxy(5001, "DISPLAY_TEXT", "<text>SYSTEM ARMED</text>") Send the ‘System Armed’ text to the attached security proxy Display Text. or: C4:SendToProxy(idBinding, strCommand, strParam) Function called from DriverWorks driver to send a Control4 BindMessage to the proxy bound to the specified binding. This version sends a single parameter to the Proxy, not a set of Key/Value pairs of parameters. Returns

None Parameters

idBinding - Binding ID for the proxy you wish to send to strCommand - Command to send to the proxy strParam - String containing single parameter to the command.

Examples C4:SendToProxy(5001, "DISPLAY_TEXT", "<text>SYSTEM ARMED</text>") Send the ‘System Armed’ text to the attached security proxy Display Text.


ReceivedFromProxy ReceivedFromProxy(idBinding, strCommand, tParams) Function called by Director when a proxy bound to the specified binding sends a BindMessage to the DriverWorks driver. Returns None Parameters

idBinding - Binding ID of the proxy that sent a BindMessage to the DriverWorks driver.

strCommand - Command that was sent tParams - Lua table of received command parameters

Example Print all commands received from the proxy, including all parameters:

function ReceivedFromProxy(idBinding, strCommand, tParams) print("ReceivedFromProxy [" .. idBinding .. "]: " .. strCommand) if (tParams ~= nil) then for ParamName, ParamValue in pairs(tParams) do print(ParamName, ParamValue) end end end

Map the idBinding to a variable for proxy; evaluate the command coming in – if it’s a simple command, get the command equivalent out of the CMDS table, otherwise call a function to process the command. The following example comes from: [DriverWorks_232_sample_receiver_Integra_dtr-4.5.c4i]

function ReceivedFromProxy(idBinding, strCommand, tParams) proxy = "Undefined" if idBinding == 5001 then proxy = "Receiver" elseif idBinding == 5002 then proxy = "Tuner" end print("ReceivedFromProxy [" .. idBinding .. "]: " .. strCommand .. " for " .. proxy) cmd = CMDS[strCommand] if (cmd ~= nill) then print( "Received from Proxy: " .. strCommand .. "; Send to Device: " .. cmd) emit(cmd) else CommandInterpreter(strCommand, tParams) end end


1.1 Director Command Interface

ExecuteCommand ExecuteCommand(strCommand, tParams) Function called by Director when a command is received for this DriverWorks driver. This includes commands created in Composer programming. Parameters

strCommand - Command to be sent tParams - Lua table of parameters for the sent command

Example 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. The following example comes from: [DriverWorks_232_Template_Security.c4i]

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


GetVersionInfo C4:GetVersionInfo() GerVersionInfo returns the version of Director currently running. Return buildtime 13:35:13 builddate Sep 29 2008 version 1.7.0.222 buildtype DEBUG Parameters None 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

GetUniqueMAC C4:GetUniqueMAC() Returns the unique MAC address of the controller running Director Returns String Parameters None Example print(C4:GetUniqueMAC()) -- Returns 000fff665FDE

1.2 Serial/Network/Device Interface

SendToSerial C4:SendToSerial(idBinding, strData) Simple function which sends the command out serial port on binding 1 and adds the \r terminator to the end of the command being sent Returns

None


Parameters idBinding - Binding ID of the serial interface to send on. strData - Data to send out the specified serial interface

Remarks Serial data to be sent can contain NULL characters. NULL (‘\0’) is a valid character and Lua strings handle embedded NULL characters. Example The following example comes from: [DriverWorks_232_sample_receiver_Integra_dtr-4.5.c4i]

function emit(strCommand) print("Emit: " .. strCommand) C4:SendToSerial("1", strCommand .. "\r") end

ReceivedFromSerial ReceivedFromSerial(idBinding, strData) Function which dumps the data received from serial (hex format) for inspection via print. It then evaluates the response for specific delimiters and extracts the necessary components which are then used to do something. Parameters

idBinding - Binding ID of the serial interface the data was received on strData - Data received from the serial interface

Remarks Serial data received may contain NULL characters. NULL (‘\0’) is a valid character and Lua strings handle embedded NULL characters. Serial data received may only include part of a protocol command from the connected device. It is the driver’s responsibility to re-constitute and parse the commands received from the device. Example The following example comes from: [DriverWorks_232_sample_receiver_Integra_dtr-4.5.c4i]

function ReceivedFromSerial(idBinding, strData) print("Received something from serial on binding " .. idBinding) hexdump(strData) responseCount=0 l_string = strData for w in string.gmatch(strData, "!1(...)") do retType = w responseCount=responseCount +1 delimPos = string.find(l_string,tohex("1A")) retValue = string.sub(l_string,6, tonumber(delimPos)-1) l_string = string.sub(l_string,delimPos+1) sendNotify() end end


SendToNetwork C4:SendToNetwork(idBinding, nPort, strData) Function which sends an HTTP request to a network binding / port. Returns

None Parameters

idBinding - Binding ID of the network interface to send on nPort - Network port to send on strDat - Data to send out specified network interface

Remarks Data to be sent can contain NULL characters. NULL (‘\0’) is a valid character and Lua strings handle embedded NULL characters. Example The following example comes from [weatherbug.c4i] -- Send 'queued' HTTP request to WeatherBug: C4:SendToNetwork(6001, 80, g_URLPacket)

ReceivedFromNetwork ReceivedFromNetwork(idBinding, nPort, strData) Function which combines the data received from the network into a variable for processing when the connection status changes. Returns None Parameters

idBinding - Binding ID of the interface the data was received from nPort - Network Port the data was received on strData - Network data from the specified binding and port

Remarks Network data received may contain NULL characters. NULL (‘\0’) is a valid character and Lua strings handle embedded NULL characters. Network data received may only include part of a protocol command from the connected device. It is the driver’s responsibility to re-constitute and parse the commands received from the device. Example The following example comes from [weatherbug.c4i]

function ReceivedFromNetwork(idBinding, nPort, strData) -- Save up things coming back on HTTP port, process when done

sending to us... g_Receivebuffer = g_Receivebuffer .. strData end


NetConnect C4:NetConnect(idBinding, nPort) Function used to tell the system to make a connection. An established connection can be validated through OnConnectionStatusChanged. Returns

None Parameters

idBinding - Binding ID of the network interface nPort - Network port to connect to

Example The following example comes from: [weatherbug.c4i]:

-- Connect to WeatherBug HTTP server. Once it's connected, the g_URLPacket will be sent. C4:NetConnect(6001, 80)

NetDisconnect C4:NetDisconnect(idBinding, nPort) Function called from DriverWorks driver to disconnect from a specific idBinding and nPort. Returns

None Parameters

idBinding - Binding ID of the network interface to disconnect from nPort - Network port

Example The following example disconnects the current connection on binding 5001, port 80. C4:NetDisconnect(5001, 80)

OnConnectionStatusChanged OnConnectionStatusChanged(idBinding, nPort, strStatus) Function based on the return from the system used by weatherbug driver to process the communication. Retrurns None Parameters

idBinding - ID of the network binding whose status has changed nPort - Port number whose status has changed strStatus - “OFFLINE” or “ONLINE”

Example The following example comes from: [weatherbug.c4i] function OnConnectionStatusChanged(idBinding, nPort, strStatus) if (idBinding == 6001) then if (strStatus == "ONLINE") then -- Connect was successful. Send URL packet. -- Other actions… -- Send 'queued' HTTP request to WeatherBug:


C4:SendToNetwork(6001, 80, g_URLPacket) else -- OFFLINE... This means the receive buffer is full and ready to process... -- Other actions… end end end

OnNetworkBindingChanged OnNetworkBindingChanged(idBinding, bIsBound) Function called by Director when a network connection has been addressed (‘identified’ on Network Connections Page) or unaddressed (‘disconnect’). Returns None Parameters

idBinding - ID of the network binding whose addressing status has changed bIsBound - Whether the network binding has a bound address

Example function OnNetworkBindingChanged(idBinding, bIsBound) print("Network Binding " .. idBinding .. " Changed.") if (bIsBound) then print("Binding is bound.") else print("Binding is not bound.") end end

SendToDevice C4:SendToDevice(idDevice, strCommand, tParams) Function called from DriverWorks driver to send a Control4 CommandMessage to the specified Control4 device driver. Returns

None Parameters

idDevice - Device ID of the driver you wish to send the command to strCommand - Command to be sent tParams - Lua table of parameters to the command

Example Toggles the Light registered with the system as device 41: C4:SendToDevice(41, "TOGGLE", {})

Ramps the Light registered with the system as device 41 to 60% over 3 seconds: C4:SendToDevice(41, "RAMP_TO_LEVEL", {LEVEL = 60, TIME = 3000})



1.3 Variable Interface

AddVariable C4:AddVariable(strName, strValue, strVarType, [bReadOnly], [bHidden]) Function called from a DriverWorks driver to create a Control4 variable for the driver. Returns

None Parameters

strName - Name of Control4 variable strValue - Value of Control4 variable strVarType - Variable Type. Valid types: STRING, NUMBER, LEVEL, BOOL bReadOnly - Optional, defaults to false. Determines if the variable can be

modified externally. bHidden - Optional, defaults to false. Determines if the variable can be seen

in Composer. Remarks Variables should always be added in the same order. Control4 Composer programming is based on VariableID’s, which are allocated in order during AddVariable calls. In other words, if you add a set of variables then later delete them and re-add different variables or in a different order, Composer programming will be incorrect. Example C4:AddVariable("Driver Variable", 0, "NUMBER") Creates the device variable named “Driver Variable” within the Control4 system.

SetVariable C4:SetVariable(strName, strValue) Function called from a DriverWorks driver to set the value of a Control4 variable for the driver.

Returns

None Parameters

strName - Name of variable to set strValue - Value to set variable

Example Sets the value of the device variable named “Driver Variable” to 90: C4:SetVariable("Driver Variable", 90) Sets the device variable named “FORECAST_SUMMARY” to the value indicated by strSummary for use within the Control4 system. The following example comes from:[weatherbug.c4i]: C4:SetVariable("FORECAST_SUMMARY", strSummary)


DeleteVariable C4:DeleteVariable(strName) Function called from a DriverWorks driver to delete a Control4 variable for the driver. Returns

None Parameters

strName - Name of variable to delete Example Deletes the device variable named "Driver Variable" from the Control4 system. C4:DeleteVariable("Driver Variable")

OnVariableChanged OnVariableChanged(strName) Function called by Director when one of this driver’s variables’ values is changed. Parameters

strName - Name of variable that has changed. Remarks OnVariableChanged is NOT called on a driver when it changes its own variable’s value. The value of the variable that has changed can be found with: Variables[strName]. Example This simple function prints to the Lua Output window in Composer when any variable on that device changes and includes the variable name and value.

function OnVariableChanged(strName) print("Variable value changed - variable named: " .. strName) print(" ... new value is: " .. Variables[strName]) end

DriverWorks Variables Table Variables[strName] The Lua Table ‘Variables’ contains the current value of this driver’s variables. Although you can read directly from this table, to change the value of a device variable, you should use C4:SetVariable(strName, strValue). Returns None Parameters strName – Variable name. Examples Use Variables in a comparison:

if (Variables["Power State"] == "OFF") then C4:SendToSerial(idSerialBinding, "__ON__") C4:SetVariable("Power State", "ON") end


Print out all Variables: for VariableName, VariableValue in pairs(Variables) do print(VariableName, VariableValue) end

GetVariable C4:GetVariable(idDevice, idVariable) This function has been deprecated and should not be used for future driver development. It was replaced by ‘GetDeviceVariable’ since it is used to get variables on different devices other than the DriverWorks driver.

GetDeviceVariable C4:GetDeviceVariable(idDevice, idVariable) Function called by a DriverWorks driver to get the value of another device’s variable. Returns strValue - String Value of the requested variable, nil if not found. Parameters idDevice - Device ID of the device that owns the specified variable idVariable - Variable ID of the specified variable Remarks User Variables belong to the Variable Agent, with a DeviceID of 100001. Examples Gets and prints the value of the HVAC mode and temperature variables of a Control4 Thermostat registered in the project as Device ID 84: print(C4:GetDeviceVariable(84, 1000)) print(C4:GetDeviceVariable(84, 1003)) Gets and prints the User Variable registered with the project as variable 209: print(C4:GetDeviceVariable(100001, 209))

SetDeviceVariable C4:SetDeviceVariable(idDevice, idVariable, strValue) Sets the Device Variable specified to the value passed to the function. Returns None Parameters idDevice - Device ID of the Device that owns the specified variable idVariable - Variable ID of the specified variable strValue - Value of the variable to set. Remarks User Variables belong to the Variable Agent, with a Device ID of 100001. Examples Sets the value of the Heat Setpoint on a Control4 Thermostat registered with the project as Device ID 84 to 70 degrees: C4:SetDeviceVariable(84, 1004, 70)


RegisterVariableListener C4:RegisterVariableListener(idDevice, idVariable) Function called from a DriverWorks driver to set a listener on a particular device’s variable. When a listener is set on a variable, whenever the variable changes, the Lua OnWatchedVariableChanged call is called.

Returns

None Parameters

idDevice - Device ID of the device that owns the requested variable idVariable - Variable ID of the requested variable

Remarks User Variables belong to the Variable Agent, with a DeviceID of 100001. The OnWatchedVariableChanged function will be called immediately after the listener is successfully set. Example This example watches the value of the temperature and HVAC mode variables on a Control4 Thermostat registered with the system as device 84. It also registers to watch for changes to the user variable 209:

C4:UnregisterVariableListener(84, 1000) C4:UnregisterVariableListener(84, 1003) C4:UnregisterVariableListener(100001, 209) C4:RegisterVariableListener(84, 1000) C4:RegisterVariableListener(84, 1003) C4:RegisterVariableListener(100001, 209) function OnWatchedVariableChanged(idDevice, idVariable, strValue) print("Variable changed...") print(" device: " .. idDevice) print(" variable: " .. idVariable) print(" value: " .. strValue) print("-----------") end

WARNING When registering variable listeners with this function, you MUST call UnregisterVariableListener when the driver is destroyed (in the OnDriverDestroyed function). Failure to do this may cause Director to crash when the variable changes value. Example: function StartMonitoring() C4:RegisterVariableListener(devid, 1000) -- Register for LIGHT_STATE (1000) Changes... C4:RegisterVariableListener(devid, 1001) -- Register for LIGHT_LEVEL (1001) Changes... end function StopMonitoring() -- Unregister Variable Listeners... C4:UnregisterVariableListener(devid, 1000) C4:UnregisterVariableListener(devid, 1001) end


function OnDeviceDestroyed() -- Called when the driver is about to go away... StopMonitoring() end

UnregisterVariableListener C4:UnregisterVariableListener(idDevice, idVariable) Function called from DriverWorks driver to remove a listener on a particular device’s variable. Variable changes for the particular Device’s Variable will no longer be reported.

Returns

None Parameters

idDevice - Device ID of the device that owns the requested variable idVariable - Variable ID of the requested variable

Remarks User Variables belong to the Variable Agent, with a DeviceID of 100001. Example This stops the system from reporting variable value changes for the specified device and variables:

C4:UnregisterVariableListener(84, 1000) C4:UnregisterVariableListener(84, 1003) C4:RegisterVariableListener(100001, 209)

OnWatchedVariableChanged OnWatchedVariableChanged(idDevice, idVariable, strValue) Function called by Director when a Control4 variable changes value. Parameters

idDevice - Device ID of the device that owns the changed variable idVariable - Variable ID of the changed variable strValue - New value of variable that has changed

Remarks Watched variables are variables that belong to other devices in the system, not variables that necessarily belong to a DriverWorks driver. Example This example function prints the value of the device ID, variable ID, and variable value when any watched variable changes:

function OnWatchedVariableChanged(idDevice, idVariable, strValue) print("Variable changed...") print(" device: " .. idDevice) print(" variable: " .. idVariable) print(" value: " .. strValue) print("-----------") end


1.4 Timer Interface

AddTimer C4:AddTimer(nInterval,[strUnits],[bRepeat]) Function called from DriverWorks driver to create a C4 timer.

Returns

idTimer - Timer ID of the newly added timer. Can be used to KillTimer or to know which timer has expired in OnTimerExpired. Parameters

nInterval - Number of seconds/milliseconds/hours/minutes before the timer expires

strUnits - Optional, defaults to SECONDS. Units of timer measurement. Valid units include: MILLISECONDS, SECONDS, MINUTES and HOURS.

bRepeat - Optional, defaults to FALSE. Is the timer a repeating timer? Repeating timers will expire continually, until killed. Example This example starts a repeating timer to use for a countdown function. It can be found in: [DriverWorks_232_Template_Security.c4i]

exitTimer = C4:AddTimer(1,"SECONDS",true)

This example starts a non-repeating timer to use for a delay before checking device status. It can be found in: [DriverWorks_232_sample_receiver_Integra_dtr-4.5.c4i] tunerqDelay = C4:AddTimer(100, "MILLISECONDS")

KillTimer C4:KillTimer(idTimer) Function called from DriverWorks driver to kill a C4 timer. Returns

None Parameters

idTimer - Timer ID to kill Remarks This call stops the timer, and removes it from Control4’s list of valid timers. Note that C4: KillTimer does NOT change the value of idTimer, since Lua doesn’t support passing parameters by reference, but KillTimer does return 0, so it can be used to set the value of the timer to 0 in the same call:

idSendTimer = C4:KillTimer(idSendTimer) Example


This example stops a repeating timer used for a countdown function. It can be found in: [DriverWorks_232_Template_Security.c4i]

if exitDelay == 0 then C4:KillTimer(exitTimer) -- do stuff here

end

OnTimerExpired OnTimerExpired(idTimer) Function called by Director when the specified Control4 timer expires. Returns None Parameters

idTimer - Timer ID of expired timer. Example

This function is called by Director when a timer expires. Based on the idTimer passed in, you program what you want to do. This example is used for handling several timers. It can be found in: [DriverWorks_232_sample_receiver_Integra_dtr-4.5.c4i]:

function OnTimerExpired(idTimer) if idTimer == tunerqDelay then emit("!1TUNQSTN") -- Query Channel after a short delay elseif idTimer == volrampTimer then -- do stuff elseif idTimer == channelrampTimer then -- do stuff end end

OnDriverDestroyed OnDriverDestroyed() OnDriverDestroyed is called by Director when the DriverWorks driver has been deleted from the system and/or Director is shutting down. It is a good idea to use this function to kill any running DriverWorks timers created by your driver. Failure to do so may cause your driver to crash Director. Returns None Parameters None Example This OnDriverDestroyed kills any timers that are in use:

function OnDriverDestroyed() if (g_dbgTimer ~= nil) then C4:KillTimer(g_dbgTimer) end if (gPopupTimer ~= nil) then C4:KillTimer(gPopupTimer)


end end

1.5 Event Interface

FireEvent C4:FireEvent(strEvent) Function called from DriverWorks driver to Fire the specified event on this driver. Returns None Parameters strEvent – Desired event. Example Fires the "Forecast Received" event for use by the system. This example can be found in: [weatherbug.c4i]:

C4:FireEvent("Forecast Received")

1.6 IR Interface

SendIR C4:SendIR(idBinding, idIRCode) Function called from DriverWorks driver to send an IR Code. Returns

None Parameters

idBinding - IR Binding ID to send the IR Code idIRCode - ID of the IR Code to send from .c4i

Remarks The IR code to send must be declared as an <ircode> in the <irsection> of the driver’s .c4i file. Example

This example sends the specified IR Code out the specified IR Binding: C4:SendIR(1, 22)

SendIRStart C4:SendIRStart(idBinding, idIRCode) Causes Director to start sending the specified IR Code out the specified binding. This is typically used on button press events. Returns

None Parameters idBindingIR - Binding ID to send the IR Code idIRCode – Id of the IR Code to start sending from the .c4i


Remarks

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’s .c4i file.

Example This example starts sending the specified IR Code out the specified IR Binding: C4:SendIRStart(1, 22)

SendIRStop C4:SendIRStop(idBinding, idIRCode) Causes Director to stop sending the specified IR Code out the specified binding. This is typically used on button release events. Returns

None

Parameters idBinding - IR Binding ID to send the IR Code. idIRCode- Id of the IR Code to start sending from the .c4i

Remarks The IR code to send must be declared as an <ircode> in the <irsection> of the driver’s .c4i file.

Example This example stops sending the specified IR Code out the specified IR Binding: C4:SendIRStop(1, 22)

1.7 Properties Interface

UpdateProperty C4:UpdateProperty(strName, strValue) Function called from DriverWorks driver to update driver properties. Returns

None Parameters

strName - Name of property to update strValue - New value of property

Example Various examples of how the properties are updated by the driver. This example can be found in: [DriverWorks_232_template_security.c4i]

C4:UpdateProperty("Security State","Armed "..armMode) C4:UpdateProperty("Security State","Disarmed")

OnPropertyChanged OnPropertyChanged(strName)


Function called by Director when a property changes value. Returns None Parameters

strName - Name of property that has changed. Remarks The value of the property that has changed can be found with: Properties[strName]. Note that OnPropertyChanged is not called when the Property has been changed by the driver calling the UpdateProperty command, only when the Property is changed by the user from the Properties Page. Example An example function used to process property value changes. This example can be found in: [DriverWorks_232_template_security.c4i]

function OnPropertyChanged(strProperty) propertyValue = Properties[strProperty] print("strProperty = " .. strProperty .. " changed to: " .. propertyValue) if (strProperty == "Security State") then if propertyValue == "Disarmed" then -- do stuff elseif propertyValue == "Armed Stay" then -- do stuff elseif propertyValue == "Armed Away" then -- do stuff elseif propertyValue == "Alarm Activated" then -- do stuff end elseif (string.find(strProperty,"Zone") ~= nil) then -- do stuff else print("No action performed for " .. strProperty .. " which has been set to: " .. Properties[strProperty]) end

end

DriverWorks Properties Table Properties[strName] The Lua Table ‘Properties’ contains the current value of this driver’s properties. Although you can read from this table, and change properties’ values on the devices’ Properties page, to change the value of a device property programmatically, you should use C4: UpdateProperty. Returns None Parameters strName – Desired device Property Examples Use of Properties in a comparison:


if (Properties[“CalculateWindShear”] == “true”) then CalculateWindShear() end

Print out all Properties:

for PropertyName, PropertyValue in pairs(Properties) do print(PropertyName, PropertyValue) end

1.8 Log Interface

DebugLog C4:DebugLog(strLogText) Function called from DriverWorks driver to send messages to Control4’s debug log. Returns

None Parameters

strLogText - Text to log Example Here is an example from the weatherbug driver of using a Property to set an error logging mode: This example can be found in: [weatherbug.c4i]

C4:DebugLog("Log This Text")


ErrorLog C4:ErrorLog(strLogText) Function called from DriverWorks driver to send messages to Control4’s error log. Returns None Parameters strLogText - Example Here is an example from the weatherbug driver of using a Property to set an error logging mode: This example can be found in: [weatherbug.c4i]

function dbg(strDebugText) if (g_debugprint) then print(strDebugText) end if (g_debuglog) then C4:ErrorLog(strDebugText) end end

1.9 Miscellaneous

DriverWorks PersistData Table PersistData = {} The Lua Table ‘PersistData’ is available for drivers to keep persistent data across director restarts. Any values placed into the PersistData table will exist in the PersistData table when the driver is loaded after a director restart.

GetDeviceID C4:GetDeviceID() Function called from DriverWorks driver to get this driver’s Device ID. Returns Driver Device ID Parameters None Example

local myid = C4:GetDeviceID() print("My Device's ID is: " .. myid)

GetCapability C4:GetCapability(strName) Function called from DriverWorks driver to get a capability from the driver’s .c4i file. Returns

strCapability - The value of the capability retrieved from the .c4i file Parameters

strName - The name of the capability to retrieve Examples


If this device supports discrete volume control, send discrete volume, otherwise, send a Volume Up or Volume Down command:

if (C4:GetCapability("has_discrete_volume_control") == "False") then if (VolumeValue > CurVolumeValue) then SendVolumeUp() else SendVolumeDown() end else SendVolumeDiscrete(VolumeValue) end

OnBindingChanged OnBindingChanged(idBinding, strClass, bIsBound) Function called by Director when a binding changes state (bound or unbound).

Returns None Parameters

IdBinding - ID of the binding whose state has changed StrClass - Class of binding that has changed. A single binding can have

multiple classes: COMPONENT, STEREO, etc. This indicates which has been bound or unbound.

BIsBound - Whether the binding has been bound or unbound. Remarks 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. Example

function OnBindingChanged(idBinding, strClass, bIsBound) print("Binding " .. idBinding .. " (Class " .. strClass .. ") Changed.") if (bIsBound) then print("Binding is bound.") else print("Binding is not bound.") end end

AddDynamicBinding C4:AddDynamicBinding(idBinding, strType, bIsProvider, strName, strClass, bHidden, bAutoBind) Note: Currently, the AddDynamicBinding does not work for audio and Video bindings.


Function called by a DriverWorks driver to add a dynamic binding (a binding added at runtime). This is typically done by security panels or other devices whose number of bindings are unknown when the driver is created. Returns None Parameters

IdBinding - ID of the dynamic binding. StrType - Type of dynamic binding. Valid types include: CONTROL, PROXY,

VIDEO, AUDIO, and ROOM_CONTROL bIsProvider - Whether the binding is a Provider or a Consumer binding. StrName - Name of binding that will appear in Composer’s connections page. StrClass - Class of dynamic binding that is being created. BHidden - Whether the dynamic binding is hidden. Should typically be false. BAutoBind - Whether the dynamic binding should be auto-bound. Should

typically be false. Examples Dynamically create 4 Zone Contact Bindings for a Security Driver:

C4:AddDynamicBinding(101, "CONTROL", true, "Zone 1", "CONTACT_SENSOR", false, false) C4:AddDynamicBinding(102, "CONTROL", true, "Zone 2", "CONTACT_SENSOR", false, false) C4:AddDynamicBinding(103, "CONTROL", true, "Zone 3", "CONTACT_SENSOR", false, false)

Remarks It is the responsibility of the DriverWorks driver to maintain the Dynamic bindings and to restore them from persistent data upon the driver being initialized. If this is not done, the bindings will not be available after a Director restart. If dynamic bindings have been connected in Composer, if they are properly restored by the DriverWorks driver, the connections made between the bindings will be automatically restored. Below is an example of how to create and save bindings for three security contacts:

if (nil == PersistData) then PersistData = {} end PersistData["zonebindings"] = {} PersistData["zonebindings"][101] = "Zone 1" C4:AddDynamicBinding(101, "CONTROL", true, "Zone 1", "CONTACT_SENSOR", false, false) PersistData["zonebindings"][102] = "Zone 2" C4:AddDynamicBinding(102, "CONTROL", true, "Zone 2", "CONTACT_SENSOR", false, false) PersistData["zonebindings"][103] = "Zone 3" C4:AddDynamicBinding(103, "CONTROL", true, "Zone 3", "CONTACT_SENSOR", false, false)


The following is an example of how to restore saved bindings This code should be in the main body of the script section of the driver, not within any declared function:

if (PersistData ~= nil) then for key,value in pairs(PersistData["zonebindings"]) do C4:AddDynamicBinding(key, "CONTROL", true, value, "CONTACT_SENSOR", false, false) end end

RemoveDynamicBinding RemoveDynamicBinding(idBinding) Function called by a DriverWorks driver to remove a dynamically-created binding. Returns None Parameters IdBinding - ID of the dynamic binding to remove. Example

Removes dynamic binding created with AddDynamicBinding above: C4:RemoveDynamicBinding(103)

Base64Encode Base64Encode(strToEncode) Function called in a DriverWorks driver to encode the specified string as a Base64-encoded string. Returns

String encoded in Base64 encoding. Parameters

StrToEncode - String to be encoded in Base64 encoding Example

Example Base64 encodes a string, and then decodes it: local str = "Control4 DriverWorks SDK" print("Original String: " .. str) local enc = C4:Base64Encode(str) print("Encoded: " .. enc) local dec = C4:Base64Decode(enc) print("Decoded: " .. dec)

Base64Decode C4:Base64Decode(strToDecode) Function called in a DriverWorks driver to decode the specified string from a Base64-encoded string.


Returns String decoded from Base64 encoding.

Parameters StrToDecode - String to be decoded from Base64 encoding

Example Example Base64 encodes a string, and then decodes it: local str = "Control4 DriverWorks SDK" print("Original String: " .. str) local enc = C4:Base64Encode(str) print("Encoded: " .. enc) local dec = C4:Base64Decode(enc) print("Decoded: " .. dec)

OnPoll OnPoll() Function called by Director when Director’s internal Poll timer expires. This only occurs in drivers that have requested polling within their .c4i files, by setting the <can_poll_serial> capability to “True”. Parameters None Returns None Remarks You can also implement polling yourself within your driver by using DriverWorks system timers. Example

function OnPoll() -- Serial polling C4:SendToSerial(1, "STATUS\r\n") end

XMLEscapeString C4:XMLEscapeString(strRawInput) ‘Escapes’ the passed in string, rendering any XML characters in the string as characters that are valid in an XML value. Returns strEscaped - The passed in string, with all XML characters properly escaped. Parameters strRawInput - Raw input string, with possibly invalid characters for an XML value. Remarks You must escape all strings that are put into XML, otherwise invalid characters could cause the XML to be invalid. Examples Builds an XML string with a string that could have invalid XML characters in it: strXmlListItem = "<text>" .. C4:XMLEscapeString .. "</text>"


CRC32 C4:CRC32(strInput) Calculates the CRC32 value for the input string. Returns nCRC32 - The calculated CRC32 value of the input string (a number). Parameters strInput - String of data to calculate the CRC32 of. Example Calculate and print the CRC32 value of some common valid CRC32 test vectors. print(string.format("%x", C4:CRC32(""))) -- should print "0" print(string.format("%x", C4:CRC32("Test vector from febooti.com"))) -- should print "c877f61"

TEAEncrypt C4:TEAEncrypt(strBuf, strKey) Encrypt the input string with Corrected Block TEA (XXTEA) Algorithm, using the specified key. Returns strEncrypted - TEA Encrypted version of input string. Parameters strBuf - String to be encrypted. strKey - Key to use for encryption. Keys are 32 hex digits, encoded as a string (128-bit). Remarks Key must be the same for encryption / decryption to function properly. The input string (strBuf) must be padded to a 4-byte boundary. More information about the Corrected Block TEA algorithm (XXTEA) as well as a compatible C implementation of XXTEA may be found at Wikipedia: http://en.wikipedia.org/wiki/XXTEA Examples Encrypt then Decrypt a string, then print the original string out: local key = "1234567887654321abcdefabcabcdefa" e = C4:TEAEncrypt("Control4 Rocks! ", key) print(C4:TEADecrypt(e, key)) -- prints "Control4 Rocks! "

TEADecrypt C4:TEADecrypt(strBuf, strKey) Decrypt the input string with Corrected Block TEA (XXTEA) Algorithm, using the specified key. Returns strDecrypted - Decrypted version of input string.


Parameters strBuf - String to be decrypted. strKey - Key to use for decryption. Keys are 32 hex digits, encoded as a string (128-bit). Remarks Key must be the same for encryption / decryption to function properly. The input string (strBuf) must be padded to a 4-byte boundary. More information about the Corrected Block TEA algorithm (XXTEA) as well as a compatible C implementation of XXTEA may be found at Wikipedia: http://en.wikipedia.org/wiki/XXTEA Examples Encrypt then Decrypt a string, then print the original string out: local key = "1234567887654321abcdefabcabcdefa" e = C4:TEAEncrypt("Control4 Rocks! ", key) print(C4:TEADecrypt(e, key)) -- prints "Control4 Rocks! "

ntoh_l C4:ntoh_l(nVal) Converts the numeric value passed in to host byte order. Returns nHostVal - The nVal parameter converted to host byte order Parameters nVal - The input unsigned long value. Remarks This function is typically used to convert numeric values received over a network, when the byte order of the two ends is unknown or may be different from each other. This way, ‘little-endian’ and ‘big-endian’ machines can communicate without confusion. ‘Host’ byte order is the byte order of values on the local machine, and ‘Network’ byte order is the standard byte order on Ethernet networks. Example i_network = 0x1234ABCD i_native = C4:ntoh_l(i_network ) print("native order = " .. i_native) little endian machine prints: native order = cdab3412

hton_l C4:hton_l(nVal) Converts the numeric value passed in to network byte order. Returns


nNetVal - The nVal parameter converted to network byte order. Parameters paramName paramText Remarks This function is typically used to convert numeric values to be passed over a network, when the byte order of the two ends is unknown or may be different from each other. This way, ‘little-endian’ and ‘big-endian’ machines can communicate without confusion. ‘Host’ byte order is the byte order of values on the local machine, and ‘Network’ byte order is the standard byte order on Ethernet networks. Example i_native = 0x1234ABCD i_network = C4:hton_l(i_native) print("netowrk order = " .. i_network) little endian machine prints: netowrk order = cdab3412

GetProxyDevices C4:GetProxyDevices() Function that returns the proxy device id(ids if device has multiple proxies) associated with the current driver. Parameters None Returns proxy id, proxy id, … Example

local proxyId = C4:GetProxyDevices() print("proxy is: " .. proxyId)

prints: proxy is: 393

1.10 Helper Functions

Print print(strPrintText) Function called from DriverWorks driver to prints items out the drivers’ properties page console. Returns

None Parameters

strPrintText - Text to print Remarks Note that for convenience, the print function can be called without prefacing with C4: Example


print("Test Stuff")

tohex tohex(strHex) 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. Returns

None Parameters

strHex - Text to convert to binary hex 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")

hexdump hexdump(strDump) 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. Returns

None Parameters

strDump - Text to print out in a hexdump 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

1.11 Debug Interface Section

EnableRemoteDebugging C4:EnableRemoteDebugging(strHostAndPort) Enables remote debugging of DriverWorks Lua scripts through an external IDE with a debugger. Full instructions on use of remote debugging of DriverWorks drivers may be found in the “Control4 DriverWorks SDK – Getting Started Guide”.


Returns None

Parameters strHostAndPort – paramText

Example C4:EnableRemoteDebugging("192.168.0.118:8888")

DisableRemoteDebugging C4:DisableRemoteDebugging() Disables remote debugging of DriverWorks Lua scripts. Full instructions on use of remote debugging of DriverWorks drivers may be found in the “Control4 DriverWorks SDK – Getting Started Guide”. Returns None Parameters None Example C4:DisableRemoteDebugging()

Attach Attach() Function called by Director when remote debugging of the DriverWorks script has started. Returns None Parameters None Example

function Attach() -- Initial debug setup bDebug = true end

OnEndDebugSession OnEndDebugSession() Function called by Director when remote debugging of the DriverWorks script has ended. Returns None Parameters None


Example function OnEndDebugSession() bDebug = false end

1.12 Media Management - Generic

MediaRemoveAllMedia

Removes all albums songs and movies from the device. Returns None Parameters None Example

MediaSetDeviceContext C4:MediaSetDeviceContext() Function that sets a device id to be used for media related call. If set to any value other than “0” then adding, modifying, retrieving or removing functionality will use the supplied device id. Parameters New device id to be associated with media related api’s. If set to “0” then the media related api’s will use the current driver’s device id. Returns None Example C4:MediaSetDeviceContext(391)

MediaGetDeviceContext C4:MediaGetDeviceContext() Function that returns the what the device context is currently set to. If “0” then all media api’s are using the current driver’s device id. Parameters None Returns Driver Device ID Example

local contextId = C4:MediaGetDeviceContext() print("context is: " .. contextId)

prints: context is: 391


1.13 Media Management – Movies The examples used in the Movies section of this document will reference the following movie: shrekMovie = { directors = "Andrew Adamson; Vicky Jenson", description = "In this fully computer-animated fantasy", cast = "Mike Myers; Eddie Murphy; John Lithgow", rating = "", genre = "Children's/Family", release_date = "2001", release_company = "DreamWorks", cover_art = "/9j/4AAQSkZJRgABAQEBLAEsAAD/" }

MediaAddMovieInfo C4:MediaAddMovieInfo("http://127.0.0.1/movies/shrek1", "shrek1",

shrekMovie) Returns Number – The new Media ID for the movie Parameters

string location string title table information

Example mediaId1 = C4:MediaAddMovieInfo("http://127.0.0.1/movies/shrek1",

"shrek1", shrekMovie)

MediaGetMovieInfo C4:MediaGetMovieInfo(mediaId) Function that returns movie properties. Returns

Table information. The table may have entries for: • string location • string title • string directors – comma separated • string description • string cast – comma separated • string rating • string rating_reason • string reviews • string genre • string aspect_ratio • string release_date • string release_company • string length – time span in minutes • string cover_art – this is a base64 encoded JPEG file of the cover art.


Parameters Number – Media ID – This is the Media ID of the movie.

Example myMovieInfo = C4:MediaGetMovieInfo(mediaId1) print(myMovieInfo[“title”])

MediaGetMovieLocation C4:MediaGetMovieLocation(mediaId) Function that returns the movie location. Parameters number – The Media ID of the movie. Returns string – The location of this media as stored in the database. Example myLocation = C4:MediaGetMovieLocation(mediaId1)

MediaGetAllMovies C4:MediaGetAllMovies() Function that returns a table of all movies. Returns Table containing Media IDs and locations. Parameters None Example

allMovies = C4:MediaGetAllMovies() for key,value in pairs(allMovies) do print("mediaId is "..key.. " location is "..value) end

MediaRemoveMovie C4:MediaRemoveMovie(mediaId) Removes a movie based on media ID Returns None Parameters Number – the Media ID of the movie being removed. Example C4:MediaRemoveMovie(mediaId3)

MediaRemoveAllMovies C4:MediaRemoveAllMovies()


Function to remove all movies from the database. Returns None Parameters None - Removes all movies Example C4:MediaRemoveAllMovies()

MediaModifyMovieInfo Function to modify the data associated with an existing media id. Returns None Parameters Media ID Location Name

Movie table information - movie information is required. None Example shrekMovie["genre"] = "Horror" C4:MediaModifyMovieInfo(mediaId1, "http://127.0.0.1/movies/shrek1Modified", "shrek1", shrekMovie) Remarks A modify call does not change the media’s ID number where a delete or add call will. Modify calls are useful if programming relies on the current Media ID. For example, if a button push has is programmed to play the media, and a modify call is used, the media’s current ID is maintained and programming is not impacted.


1.14 Media Management – Albums The examples used in the Albums section of this document will reference the following album/songs: mediaId1 = C4:MediaAddAlbumInfo("http://127.0.0.1/music/Album1", "Funky Music", Album1) songLocation1="http://127.0.0.1/music/song1.mp3" songLocation2="http://127.0.0.1/music/song2.mp3" songLocation3="http://127.0.0.1/music/song3.mp3" SomeSong1 = { --required fields title="Title Test Song Number 1", location=songLocation1, track_no="6", --optional fields name = "Name Test Song Number 1", artist = "C4 Music Factory", record_label="Island", release_date="15 Jun 2004", } SomeSong2 = { title="Test Song Number 2", location=songLocation2, track_no="1", name = "Name Test Song Number 2", artist = "C4 Music Factory", record_label="Dos Record Label", release_date="15 Jun 2222", } SomeSong3 = { title="Test Song Number 3", track_no="7", location=songLocation3, name = "Name Test Song Number 3", artist = "C4 Music Factory", record_label="Boat", release_date="3 Dec 2002", } Album1 = { artist = "Jimmy Joe", description = "Worst episode ever", genre = "Blues & Browns", release_date = "1992", release_label = "Grass and Cash", songs = {SomeSong1, SomeSong2, SomeSong3}, }

http://127.0.0.1/music/song1.mp3




MediaAddAlbumInfo C4:MediaAddAlbumInfo Function that passes album info and returns a Media Id that for the album. Returns

The new Media ID Parameters

string location string title album table info - songs information is required. Table must contain the songs you want added to the album. song table info - data from MediaGetSongInfo: required fields are title, location and track_no – unique for that able Example

mediaId = C4:MediaAddAlbumInfo("http://127.0.0.1/music/Album1", "Funky Music", Album1)

MediaGetAlbumInfo C4:MediaGetAlbumInfo() Function that returns album information based on Media ID. Parameters

Number – The Media ID for the album. Returns

string location string title

table information. The information table may have entries for: artist record_label release_date description genre cover_art – this is a base64 encoded JPEG file of the cover art. songs – an array of songs.

Each song is a table, and must contain entries for name track_no location

Example MyAlbumInfo= C4:MediaGetAlbumInfo(mediaId1) print(MyAlbumInfo["name"])

MediaGetAlbumLocation C4:MediaGetAlbumLocation (mediaId) Function that returns an album’s loctation. Returns

string – the location of this media stored in the database


Parameters

number – the Media ID desired Example print(C4:MediaGetAlbumLocation(mediaId1))

MediaGetAllAlbums C4:MediaGetAllAlbums() Function that returns all albums and their Media IDs. Returns A table of each album’s Media ID as well as location. Parameters None Example

allAlbums = C4:MediaGetAllAlbums() for key,value in pairs(allAlbums) do print("mediaId is "..key.. " location is "..value) end

MediaRemoveAlbum C4:MediaRemoveAlbum(mediaId) Function that will remove an album based on its media ID. Returns None Parameters number – The Media ID for the album. Note, all songs associated with this album will be removed as well. Example C4:MediaRemoveAlbum(mediaId1)

MediaRemoveAllAlbums C4:MediaRemoveAllAlbums() Function that removes all albums. Returns Deletes all albums and songs for the device Parameters None Example C4:MediaRemoveAllAlbums()


MediaModifyAlbumInfo C4:MediaModifyAlbumInfo() Parameters media Id location name

album table info song information is required. Table must contain the songs you want added to the album. song table info data from MediaGetSongInfo. required fields are title, location and track_no – unique for that table

Returns None Example Album1["release_label"] = "modded label" C4:MediaModifyAlbumInfo(mediaId1, "http://127.0.0.1/music/Album1Modified", "NewLocation", Album1) Remarks A modify call does not change the media’s ID number where a delete or add call will. Modify calls are useful if programming relies on the current Media ID. For example, if a button push has is programmed to play the media, and a modify call is used, the media’s current ID is maintained and programming is not impacted.

1.15 Media Management – Songs

MediaGetSongInfo C4:MediaGetSongLocation(mediaId) Function that returns song information based on its Media ID. Returns Table information. The information table will have entries for: string location string title Parameters Number – the Media ID for this song. Example mySongInfo = C4:MediaGetSongInfo(mediaId1) print(mySongInfo["name"])

MediaGetSongLocation

Parameters number – The Media ID of the song. Returns string – The location of this media as stored in the data base Example print(C4:MediaGetSongLocation(mediaId1))


MediaRemoveSong C4:MediaRemoveSong() Function that removes a song based on its Media ID. Returns None Parameters number – the Media ID of the song. Example C4:MediaRemoveSong(mediaId1)

MediaLinkSongToAlbum C4:MediaLinkSongToAlbum() Function that associates a song to an album. Returns None Parameters number – the Media ID of the Album number – the Media ID of the Song number – track-based sequence that this song belongs within the album Example C4:MediaLinkSongToAlbum(mediaIdAlbum, mediaIdSong, 1)

MediaGetSongsforAlbum C4:MediaGetSongsForAlbum() Function that returns songs associated with an album. Returns Table of values including Media ID and location of each song. Parameters Media ID of an album containing desired songs. Example

AllSongs= C4:MediaGetSongsForAlbum(mediaIdAlbum) for key,value in pairs(AllSongs) do print("mediaId is "..key.. " location is "..value) end

MediaModifySongInfo C4:MediaModifySongInfo() Function that updates the location and name of a song Returns None Parameters Media ID of the song. Location of the song. Name of the song. Example


C4:MediaModifySongInfo(mediaId1, "http://127.0.0.1/music/songtest","Test of modified song")

Remarks A modify call does not change the media’s ID number where a delete or add call will. Modify calls are useful if programming relies on the current Media ID. For example, if a button push has is programmed to play the media, and a modify call is used, the media’s current ID is maintained and programming is not impacted.


1.16 List Navigator Functionality Beginning with the Control4 1.7.2 system software release, DriverWorks drivers have the ability to access Control4’s List Navigator functionality. Control4 uses List Navigator to provide the list interface on Control4’s System Remotes, as well as on the 10-button LCD Keypad. This functionality can now be supported in drivers created for devices that have hardware to display a list and buttons to navigate through the list. A 3rd-party example of this functionality is the ability to use Panasonic PBX-attached phones to access a Control4 menu through the phone’s display, using the phone keypad for navigation. Typically, the DriverWorks driver will need to perform the following functions:

• The DriverWorks driver Initializes List Navigator • When the device requires a menu, the DriverWorks driver calls C4:ListStart • The DriverWorks driver receives a list from Director, or a portion of the list if

there are many items using calls ListNewList and ListMIBReceived. • The DriverWorks driver presents the list to the physical device, and requests

additional items as needed. • The DriverWorks driver handles button presses from the physical device,

navigates the list with those presses and sends List Select calls when an item in the list is selected

• The DriverWorks driver can end the list and/or the list may be ended by the user backing out of the list.

WARNING – You CAN NOT call List Navigator functions in the initialization portion of your DriverWorks code (in the main Lua body of the driver). Doing so can result in the driver not being loaded by Director and/or crashing Director. You may call List Navigator calls within functions in your Lua code, and anytime *after* driver initialization. This mainly affects getting initial driver Room ID and initializing List Navigator. These two functions are performed in a function that is triggered by a timer in the body of the <script> section of the driver.

ListSetCapabilities C4:ListSetCapabilities(nMaxListCacheSize, nMaxListItemLen, nControl(s)…) ListSetCapabilities must be called before starting a list with C4:ListStart. This tells Director how many items you wish to retrieve at once, how wide to make the items, and what controls you wish to implement. Returns None Parameters nMaxListCacheSize - Determines how many list items you wish to receive at a time. You should not request all list items, but only as many as you wish to hold locally. Your driver should handle paging of the items and requesting


more items when needed. Requesting all items at once will slow down your driver and Director. nMaxListItemLen- Maximum length of items in your display. Director will cut off any items longer than this length. nControls - You can request which controls you will implement. It is recommended that you pass 0x0d, 0x0e for your controls. Examples This sets the list capabilities to allow 30 items at a time, no wider than 20 characters, and will implement the standard controls: C4:ListSetCapabilities(30, 20, 0x0d, 0x0e)

ListStart

DescriptionText C4:ListStart(strContainer) Returns None Parameters strContainer- Container (page) you wish to start the list on. No parameter equals starting at the main list menu. Valid Containers include: house, locations, house:contacts, house:relays, lights, audio, video, videos:browse, videos:browse:all, videos:browse:genre, videos:browse:director, videos:browse:actor, videos:browse:rating, tv, tv:channels, radio, radio:stations, comfort, comfort:thermostat, comfort:blinds, comfort:contacts, comfort:relays, info, info:watch, info:listen, info:help, info:about Examples Start a List Navigator session on the main menu: C4:ListStart() Start a List Navigator session on the ‘audio’ menu, or the Browse Videos by Director: C4:ListStart('audio') C4:ListStart('videos:browse:director')

ListStop C4:ListStop() Stop the current DriverWorks List Navigator session. Returns None Parameters None Example C4:ListStop()


ListGetItems C4:ListGetItems(nListID, nStartIndex, nCount) Requests nCount list items, for the ListID passed in, starting at StartIndex Returns None. This is an asynchronous call, the list items are returned in a call to ListMIBReceived. Parameters nListID - This is the List ID received in the ListNewList call from Director. nStartIndex - Starting index of the records to receive. 0 is the first record in a list. nCount - Number of records to retrieve. Examples Retrieve the first 20 items of the current list in g_List: C4:ListGetItems(g_List, 0, 20)

ListSendCommand C4:ListSendCommand(strCommand, Param1, Param2…) Send a List MIB command to Director. Returns None Parameters StrCommand - List MIB Command Param1 - Parameters to the command. Not required, you may pass as many parameters as needed. Useful MIB Commands: c4.ln.is – Item Select (Param1: ListID, Param2: Selected Item Number – 0- based) c4.ln.lb – List Back (Param1: ListID, Param2: 0) Other MIB Commands (no additional info available): c4.ln.ii – Item Info c4.ln.ish, c4.ln.ise – Item Select c4.ln.cn – Cancel c4.ln.cc – Control Change c4.ln.as – Alphanumeric Select Remarks If string parameters are required to be quoted by List Navigator, this quoting must be performed by the DriverWorks driver, it will not be performed by the ListSendCommand itself. Examples Select Item number 3 in the current list indicated by g_ListID C4:ListSendCommand("c4.ln.is", string.format("%04x", g_ListID), string.format("%04x", 3)) Go back in the list a level (triggered by left button, typically) C4:ListSendCommand("c4.ln.lb", string.format("%04x", g_ListID), 0)


ListGetRoomID C4:ListGetRoomID() Gets the DeviceID of the current ListNavigator room. Returns NRoomID - DeviceID of the current List Navigator room device. Parameters None Remarks - ListGetRoomID will initially return the Device ID of the room the device driver is placed into in the project. Examples Print the current Room Device ID: print(C4:ListGetRoomID())

ListGoToRoot C4:ListGoToRoot() Reset the current list back to the main menu. Returns None Parameters None Example C4:ListGoToRoot()

ListIsStarted C4:ListIsStarted() Returns a Boolean of whether the list is started or not. Returns bIsStarted - List is started, true or false Parameters None Example

if (C4:ListIsStarted()) then print("List is Started") end

ListIsInNavigation C4:ListIsInNavigation() Returns a Boolean of whether the list is in navigation or not. Returns bIsInNavigation - List is in navigation, true or false Parameters None Example


if (C4:ListIsInNavigation()) then print("List is in Navigation") end


ListNewList ListNewList(nListID, nItemCount, strName, nIndex, strContainer, strCategory, strNavID) Function called by Director when a new List Navigator List has been requested by the DriverWorks driver and successfully opened by Director. It is called in response to:

• C4:ListStart • C4:ListSendCommand (Item Select – c4.ln.is), etc.

Returns None Parameters nListID - ListID is a number used by List Navigator to track which list you are currently viewing. It is required to request more items from the list, and when you select an item in the list. nItemCount - ItemCount is the number of items in this list. This is typically displayed on the top line of the display, along with the currently selected item number (1/5) strName - Name of this list. This is typically displayed on the top line of the display, and is initially the name of the Room. nIndex - Selected index in the list. For lists that are being selected, this will typically be 0. For lists that are received from a ‘list back (c4.ln.lb)’ command, it will be the list index that was selected. strContainer - Container is similar to Category, and can be used to determine where the user is in the list, to decide when to pop up a control. strCategory - Category of the list. This includes things like ‘audio’, ‘house’, ‘locations’, etc. strNavID - Navigator ID of this list. Not typically used, may be ‘Unknown’. Remarks ListNewList is received when the list is opened, but no list items are returned. To retrieve the list items themselves, C4:GetListItems must be called. Example

function ListNewList(nListID, nItemCount, strName, nIndex, strContainer, strCategory, strNavID) print("New List: ID: " .. nListID .. " Count: " .. nItemCount .. " Name: " .. strName .. " Index: " .. nIndex .. " Container: " .. strContainer .. " Category: " .. strCategory .. " NavID: " .. strNavID) -- This is really too complicated for a ‘real’ example… end

ListMIBReceived ListMIBReceived(strCommand, nCount, tParams) Function called by Director when List items or List MIB Commands are received. List MIBs are how Director communicates lists, end, and updated items. Parameters strCommand - MIB Command that was received. Typical MIB Commands include: “c4.ln.gi”, “c4.ln.le”, and “c4.ln.si”. They are described in more detail in the Remarks section. nCount - Count of the items in the tParams table.


tParams - Table of values for the MIB Command that was received. Remarks MIB Descriptions: c4.ln.gi – GetItems return. This MIB indicates that you called C4:ListGetItems, and this is the list of items that you requested. In the tParams table, there will be a set of list items. They are indexed on a zero- based index in the table, 0 to (nCount - 1). The items in the list are encoded with specific key values preceding the item name. Encoded values are listed below. c4.ln.si – Updated Item. This MIB indicates that an item in your current list has been updated. This could happen if you were looking at a list of lights, and one of them was switched on or off, or if your music queue changed while looking at the music queue. Any items that need updating are encoded the same as items in c4.ln.gi above. c4.ln.le – List End. This MIB indicates that the list has ended. Typically you will receive this MIB when the user has backed all the way out of the menu, or if you call C4:ListStop. Example

function ListMIBReceived(strCommand, nCount, tParams) print("List MIB Received: " .. strCommand) print(nCount .. " Params:") if (nil ~= tParams) then for k,v in pairs(tParams) do print(k,v) end end end

ListNewControl ListNewControl(strContainer, strNavID, idDevice, tParams) Function called by Director when you have selected a ‘Control’. Controls are pages used on a List Navigator to control a specific item, like a light level or the volume of an audio zone. Parameters strContainer - Container this control resides in. Used to determine what action to take or what control to display when ListNewControl is called. strNavID - Navigator ID of the control. Used to determine what action to take or what control to display when ListNewControl is called. idDevice - Device ID of the device that should be controlled. tParams - Parameters of the device. For example, for a light being selected, a call to ListNewControl is sent with the following parameters: LEVEL – The light’s current level NAME – The name of the light IS_DIMMER – to know whether it can be dimmed or not. Example

function ListNewControl(strContainer, strNavID, idDevice, tParams) -- If this is a relay, toggle it when selected if ((strContainer == "comfort") and (strNavID == "NIRelay")) then C4:SendToDevice(idDevice, "TOGGLE", {}) end


-- If a switch, toggle, if a dimmer, start Light Control Dialog if ((strContainer == "lights") and (strNavID == "NILight")) then if (tParams["IS_DIMMER"] == "FALSE") then C4:SendToDevice(idDevice, "TOGGLE", {}) else gInControl = true gControlType = "light" gControlName = tParams["NAME"] gControlLightValue = tonumber(tParams["LEVEL"]) gControlDeviceID = idDevice DisplayControl(true) end end

ListEvent ListEvent(strEvent, Param1, Param2) Function called by Director when an event happens on which a List Navigator client should operate. Returns None Parameters strEvent - Name of the List Event. Param1 - First Parameter to the event. Depends on the event. Param2 - Second Parameter to the event. Depends on the event. Remarks List Events happen on things like the room Volume changing, Media Changing, Room Changing, etc. Common List Events are described below: VolumeChanged - This event indicates that the currently selected room’s volume has changed. Param1 is a string representation of the current volume. MediaChanged - This event indicates that the Media playing in the currently selected room has changed. Param1 is an XML string that indicates the changed media. RoomChanged - This event indicates that the currently selected room has changed. Param1 is the DeviceID of the new room, Param2 is the name of the new room. LightValueChanged - This event indicates that a light’s brightness has changed value. Param1 is the new light value. SelectedDeviceChanged - This event indicates that the currently selected device has changed. ProjectChanged - This event indicates that the project has changed and a ‘Refresh Navigators’ has been issued. If your driver is in a menu, it should exit the menu, and request it’s room ID again. Example

function ListEvent(strEvent, Param1, Param2) local outstr = "" if (nil ~= Param1) then outstr = outstr .. Param1 end if (nil ~= Param2) then outstr = outstr .. " -- " .. Param2 end print("List Event: " .. strEvent .. " (" .. outstr .. ")")


end

Encoded Item Values \c – Indicates a Container. Can usually be ignored. \> – Indicates the item can be selected, so you should indicate this on the display somehow. \0 – \7 – these are “icons”. Different types of lists use icons to indicate whether lights are on, or contacts / relays are open or closed. If your device can display icons, you should show the icon, similar to how the Control4 System Remotes. 0 – Check Icon 1 – Light On Icon 2 – Light Off Icon 3 – Motion Icon 4 – Music Icon 5 – Relay Closed Icon 6 – Relay Opened Icon 7 – Selectable Icon


DriverWorks and Zigbee Functionality DriverWorks support for Zigbee functionality will be delivered in release 1.6.1. This section has been included to provide information to Control 4 partners already using the Zigbee SDK. This information will support the development of DriverWorks Zigbee functionality so that partners using the Zigbee SDK can integrate into the Control 4 system. Functionality provided in support of Zigbee functionality currently includes:

• Allowing DriverWorks driver developers to send data to and receive data from ZigBee devices using either EmberNet or ZigBee Pro

• Allow ZigBee SDK developers the ability to update their ZigBee devices using DriverWorks.

• Allow ZigBee SDK developers the ability to utilize the Control4 identification mechanism, but define their own ID strings.

Send/Receive Data from Zigbee

The ability to Send and Receive data from ZigBee devices is supported in DriverWorks. This functionality supports both the current Control 4 (EmberNet) as well as ZigBee Pro 1.1 transports.

SendZigbeePacket C4:SendZigbeePacket (strPacket,nProfileID, nClusterID, nGroupID, nSourceEndpoint, ndestinationEndpoint) This function sends a raw Zigbee packet to a Zigbee Binding. Returns None Parameters strPacket - ZigBee supported command containing user data. nProfileID - Profile associated with the data packet nClusterID - Source Cluster library included within the Profile nGroupID - Zigbee device group identification nSouceEndpoint - Endpoint designated as the source of the data packet delivery. nDestinationEndpoint - Endpoint designated as the recipient of the data packet delivery. Remarks The following parameters are ignored when using the Control 4 (Embernet) Zigbee stack:

nProfileID nClusterID nGroupID nSouceEndpoint nDestinationEndpoint.

Packet data is still sent in the strPacket parameter. If using ZigBee Pro, all data (including strPacket) must conform to ZigBee Pro format.


Example g_SequenceNumber=g_sequenceNumber + 1 strPacket = "0" .. Chartype .. string.format(%04x",g_SequenceNumber) .. " c4.dm.lv 100" C4: SendZigbeePacket(strPacket,0,0,0,0,0)

OnZigbeePacketIn OnZigbeepacketIn(strPacket,nProfileID, nClusterID, nGroupID, nSourceEndpoint, ndestinationEndpoint) Receives an unsolicited zigbee packet from the device or a response to a command that was sent. Returns None Parameters strPacket - ZigBee supported user data received from the ZigBee device. nProfileID - Profile associated with the data packet nClusterID - Source Cluster library included within the Profile nGroupID - Zigbee device group identification nSouceEndpoint - Endpoint designated as the source of the data packet delivery. nDestinationEndpoint - Endpoint designated as the recipient of the data packet delivery. Remarks The following parameters are ignored when using the Control 4 (Embernet) Zigbee stack:


Packet data is still sent in the strPacket parameter. If using ZigBee Pro, all data (including strPacket) must conform to ZigBee Pro format. Example function OnZigbeePacketIn (strPacket, idProfileID, idClusterID, idGroupID, sourceEndpoint,destinationEndpoint) print("OnZigbeePacketIn;" .. strPacket) end


OnZigbeePacketSuccess OnZigbeePacketSuccess(strPacket,nProfileID, nClusterID, nGroupID, nSourceEndpoint, ndestinationEndpoint) Return function upon the successful delivery of a data packet. Returns None Parameters strPacket - ZigBee supported user data received from the ZigBee device. nProfileID - Profile associated with the data packet nClusterID - Source Cluster library included within the Profile nGroupID - Zigbee device group identification nSouceEndpoint - Endpoint designated as the source of the data packet delivery. nDestinationEndpoint - Endpoint designated as the recipient of the data packet delivery. Remarks The following parameters are ignored when using the Control 4 (Embernet) Zigbee stack:


Packet data is still sent in the strPacket parameter. If using ZigBee Pro, all data (including strPacket) must conform to ZigBee Pro format. Example

function OnZigbeePacketSuccess (strPacket, idProfileID, idClusterID, idGroupID, sourceEndpoint,destinationEndpoint) print("OnZigbeePacketSuccess;"..strPacket) end

OnZigbeePacketFailed OnZigbeePacketFailed (strPacket, nProfileID, nClusterID, nGroupID, nSourceEndpoint, ndestinationEndpoint) Return function upon the unsuccessful delivery of a data packet. Returns None Parameters strPacket - ZigBee supported user data received from the ZigBee device. nProfileID - Profile associated with the data packet nClusterID - Source Cluster library included within the Profile nGroupID - Zigbee device group identification nSouceEndpoint - Endpoint designated as the source of the data packet delivery. nDestinationEndpoint - Endpoint designated as the recipient of the data packet delivery.


Remarks The following parameters are ignored when using the Control 4 (Embernet) Zigbee stack:


Packet data is still sent in the strPacket parameter. If using ZigBee Pro, all data (including strPacket) must conform to ZigBee Pro format. Example

function OnZigbeePacketFailed (strPacket, idProfileID, idClusterID, idGroupID, sourceEndpoint,destinationEndpoint) print("OnZigbeePacketFailed;" .. strPacket) end

OnZigbeeOnlineStatusChanged OnZigbeeOnlineStatusChanged (strStatus, strVersion, strSkew) Parameters strStatus OFFLINE, ONLINE, REBOOT, UNKNOWN strVersion strSkew Remarks

This gets called when the Online status of a Zigbee node changes. Example

function OnZigbeeOnlineStatusChanged (strStatus, strVersion, strSkew) print("Zigbee Status Changed: " .. strStatus) gZigbeeStatus = strStatus end

Updating Zigbee Device firmware Using DriverWorks Note: Zigbee functions will not be applicable until system software release 1.8.0. The ability to use DriverWorks drivers to update firmware on ZigBee devices is now supported. This functionality has been implemented using two new features:

• Support of encoded BLOB data (firmware) within the .c4i file

• Functions to handle device requests and delivery of the firmware data.

Encoded BLOB data in the .c4i file DriverWorks supports the ability to store binary firmware data within the .c4i file. This data must be Base64 encoded. The encoded firmware data string information should reside at the beginning of the .c4i file as seen in the example below:


<devicedata> <copyright>Copyright 2008 Control4 Corporation. All rights reserved.</copyright>

<largeblobs> <largeblob name="Blob1">VGhpcyBpcyBOaGUgRmlyc3QgQkxPQiENCg==</largeblob>

<largeblobname="Blob2">AAECAwQFBgclCQoLDA0ODwABAgMEBQYHCAkKCwwNDg8=</largeblob>

</largeblobs> <config> When ZigBee devices come on-line they can validate firmware versions with Director. If an update is available, the data is sent accordingly to the device. Drivers that wish to update their device’s firmware should do it in a sequential manner. The functions delivered in this SDK support this. It is possible to place the BLOB data in the Lua section of the driver. However, this requires a copy of the firmware data within every loaded driver used by the device. For example, if 15 devices use the driver, it will be necessary to maintain 15 copies of the firmware update data loaded in memory. Firmware request Functions - When a device requests a firmware update (the version of the firmware on the device is older than the firmware the driver has), the driver should request a 'reflash lock' via RequestRefreshLock. This allows the driver to ensure that it is the only driver updating a device at any time. This is required so that Director can manage multiple Zigbee drivers so that only one driver will be allowed to update at a time. This ensures that device firmware updates don't overload the zigbee network. The OnReflashLockGranted function is called by Director when the driver has permission to update the firmware on the device. This function ensures that the driver is the only device using the zigbee network to flash a device. This ensures that the delivery of the firmware update won’t be slowed down due to other firmware updates from other devices. All reflash traffic is sent to the device using standard SendZigbeePacket and OnZigbeePacketIn commands/functions as described above. The following functions can be used to handle firmware data updates to Zigbee devices:

GetBlobByName C4:GetBlobByName(strName) Returns the un-encoded string containing the firmware update data of the specified BLOB (Binary Large Object). Returns Binary data from .c4i file. Parameters strName – Name of the Binary Large Object to retrieve from the .c4i file. Example C4:GetBlobByName("Blob1")


RequestReflashLock C4:RequestReflashLock() Function that requests permission of Director to update the device. The driver receives permission when it receives the OnReflashLockGranted call.

KeepReflashLock C4:KeepReflashLock() If a driver takes longer than a minute to upload the firmware data to the device, it should call C4:KeepReflashLock. This request will maintain the reflash lock while updating. If a driver does not call KeepReflashLock, the Reflash Lock will be revoked after approximately one minute.

ReleaseReflashLock C4:ReleaseReflashLock() Function to terminate the request for firmware data upon completion of update.

OnReflashLockGranted OnReflashLockGranted() Function called by Director when a Zigbee device grants communication access. Ensures that the driver is the only one currently granted permission to update the device.

OnReflashLockRevoked OnReflashLockRevoked() Function called by Director when a driver loses permission to perform a device update.

84531515 Control4 Driver Works SDK Driver Works API Reference Guide

Documents

84531515 Control4 Driver Works SDK Driver Works API Reference Guide