Control4 Driver Works SDK - Driver Works API Reference Guide

March 29, 2018 | Author: nopenoway | Category: Application Programming Interface, Port (Computer Networking), Device Driver, Variable (Computer Science), Parameter (Computer Programming)
Share
Report this link


Comments



Description

Control4 DriverWorks Software Development KitDriverWorks API Reference Guide 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 Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation, All Rights Reserved Page 2 Version 1.7.3 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  Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation, All Rights Reserved Page 3 Version 1.7.3 ............24  1...............................36  DisableRemoteDebugging ......................... 27  DebugLog ..................................................................................... All Rights Reserved Page 4 Version 1..................................................................................................................31  Base64Decode ...................................................................................25  OnPropertyChanged ..................25  DriverWorks Properties Table ............................................................................................................32  XMLEscapeString ......................................24  SendIRStop ......................11 Debug Interface Section ........................24  SendIRStart ....................................7........................................................................................29  AddDynamicBinding ......................................................................33  TEAEncrypt .............................................................................................................................................................28  GetCapability ...................................34  GetProxyDevices ............................................................................................36  hexdump ................25  1....................................................33  ntoh_l ................................................................................31  OnPoll ...............28  GetDeviceID ............................................................37  Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation....................................................................................................3 ..35  tohex ...............31  Base64Encode .....................27  ErrorLog ...........................................................................................6 IR Interface ......................................................................................................................................................................................37  Attach ...........................................................28  1....................................................................................................................................................................................................................................................... 24  SendIR .......... 28  DriverWorks PersistData Table ...................................................35  1.. 36  EnableRemoteDebugging ...................................................................28  OnBindingChanged ..........................9 Miscellaneous ......7 Properties Interface ....................................................................................................................8 Log Interface ................................................10 Helper Functions ...................................................................................32  CRC32 .....................................................................................1............................33  TEADecrypt...............................................................................................................................5 Event Interface................................................34  hton_l ..................................................................................29  RemoveDynamicBinding ................................................................26  1...........................................................................36  1................................................................................................................................................................................................ 35  Print .............. 25  UpdateProperty ................................................. 24  FireEvent ................................................................................................................................. ......................Generic ............7.................. 38  MediaRemoveAllMedia . 45  MediaGetSongInfo ................................51  ListIsInNavigation ...............................................................51  ListNewList ...................51  ListGoToRoot ......43  MediaGetAlbumInfo..40  MediaRemoveAllMovies .......................................38  1................................................................................43  MediaGetAllAlbums ........................46  MediaModifySongInfo ..........45  1........................................ 39  MediaAddMovieInfo .................................................................................................50  ListGetRoomID .........................40  MediaRemoveMovie..44  MediaRemoveAllAlbums ....................................38  MediaGetDeviceContext ....................................................................................................................13 Media Management – Movies ...................................49  ListGetItems ................................................................................................................................45  MediaGetSongLocation .............12 Media Management ........................................37  1............................46  MediaGetSongsforAlbum .......39  MediaGetMovieInfo ..................................................................................................................................................................................................................................................46  MediaLinkSongToAlbum .................................................................................................................................................53  ListNewControl ............. 48  ListSetCapabilities......................................................................45  MediaRemoveSong..................................................................................................50  ListSendCommand ....44  MediaModifyAlbumInfo ........ 42  MediaAddAlbumInfo ..............................................................................................................................................................................................49  ListStop ..........................................................................................................................................................................................................................................................................................................................53  ListMIBReceived .....................40  MediaGetAllMovies .......................................................................................................................................................14 Media Management – Albums .........................15 Media Management – Songs .............51  ListIsStarted .46  1........................38  MediaSetDeviceContext ...........................................................................................................................................40  MediaModifyMovieInfo .....................................................................................................................16 List Navigator Functionality .............39  MediaGetMovieLocation ..........................................................OnEndDebugSession .................................................................................................................................................................................43  MediaGetAlbumLocation............41  1..............................................3 ..........................................................48  ListStart ...................................... All Rights Reserved Page 5 Version 1.............................54  Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation..........................................................................................44  MediaRemoveAlbum ................................................................................................................................................................................................................................................................................ ........................62  OnReflashLockRevoked ..............62  ReleaseReflashLock .............7......................62  Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation.................57  OnZigbeePacketIn........c4i file ........................58  OnZigbeePacketSuccess ...............................................................................................60  Encoded BLOB data in the ..............60  Updating Zigbee Device firmware Using DriverWorks ............................................................ 57  Send/Receive Data from Zigbee ...............................................................ListEvent ..59  OnZigbeeOnlineStatusChanged ....................................................................................................................61  RequestReflashLock ...............................................................................................................................................................................62  OnReflashLockGranted ...........................................................................................59  OnZigbeePacketFailed ...............................................................................................................................................................................................................................55  Encoded Item Values ......................3 .............................................................................................................................................60  GetBlobByName .................62  KeepReflashLock ....................................... 56  DriverWorks and Zigbee Functionality ..............57  SendZigbeePacket ............... All Rights Reserved Page 6 Version 1......................................................... lua.3 .7. This is not an exhaustive reference document but is intended to teach you what you need to know to get started.org/wiki/LuaComparison Lua Testimonials http://www.org Official Lua Website Lua FAQ http://lua-users. Getting Started with DriverWorks explains the basic concepts and how to get started with the development of a DriverWorks driver. 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. Other Languages http://lua-users. This is required reference material for driver creators. for example: C4:SendToProxy. http://www. do not. All Rights Reserved Page 7 Version 1.lua.lua.org/wiki/LuaFaq Programming In Lua (online version) http://www. 2. you may benefit from referencing material on In addition to this source material. DriverWorks Reference Guide (this document) – this guide documents all APIs available through DriverWorks.html Note: Some of the functions used in the samples found in this section use “C4:”as a prefix. for example ReceivedFromProxy.org/wiki/Lua 1996 DDJ article on Lua goals and purposes: http://www. Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation.c4i file that is not compiled by the driver creator before it is used by the Control4 system.1 Reference Manual http://www.c4i file.lua. Functions that DriverWorks drivers call utilize the “C4:” Functions that are called by Director. An embedded Lua interpreter exists on the Control4 Controller that executes the Lua code found within the .org/manual/5.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.wikipedia.org/ddj.org/pil/ Lua 5. A DriverWorks driver is completely defined by a . Other functions do not use the “C4:” prefix.html Lua Wikipedia Entry http://en. you may benefit from referencing material on Lua. In addition to this source material.lua.org/quotes.1/ Lua vs. 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. This version sends a single parameter to the Proxy.Command to send to the proxy strParam . "DISPLAY_TEXT".String containing single parameter to the command. strCommand. strCommand.0 Proxy Interface SendToProxy C4:SendToProxy(idBinding. Returns None Parameters idBinding . strParam) Function called from DriverWorks driver to send a Control4 BindMessage to the proxy bound to the specified binding. All Rights Reserved Page 8 Version 1. "CLOSED".Binding ID for the proxy you wish to send to strCommand . Examples C4:SendToProxy(11. "TEMPERATURE_CHANGED". Strmessage . C4:SendToProxy(5001. strCommand. tParams. or: C4:SendToProxy(idBinding. "DISPLAY_TEXT". which are auto-converted. {TEMPERATURE = 76}) Notify the attached thermostat binding that the temperature is now 76. Note that tParams is required.1. {}) Notify the attached contact binding that the contact has closed. Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation. Examples C4:SendToProxy(5001. C4:SendToProxy(5001.Binding ID for the proxy you wish to send to strCommand . not a set of Key/Value pairs of parameters.Lua table containing parameters to the command. Returns None Parameters idBinding . "<text>SYSTEM ARMED</text>") Send the ‘System Armed’ text to the attached security proxy Display Text.7. if there are no parameters.COMMAND or NOTIFY – Overrides the default message type that SendToProxy will send by default.3 . strmessage) or C4:SendToProxy(idBinding. TBD: Show how to send things other than strings or numbers. strParam) Function called from DriverWorks driver to send a Control4 BindMessage to the proxy bound to the specified binding.Command to send to the proxy tParams . send an empty Lua table. "<text>SYSTEM ARMED</text>") Send the ‘System Armed’ text to the attached security proxy Display Text. "]: " . strCommand .. Returns None Parameters idBinding . proxy) cmd = CMDS[strCommand] if (cmd ~= nill) then print( "Received from Proxy: " . All Rights Reserved Page 9 Version 1.5.Lua table of received command parameters Example Print all commands received from the proxy...c4i] function ReceivedFromProxy(idBinding.. tParams) proxy = "Undefined" if idBinding == 5001 then proxy = "Receiver" elseif idBinding == 5002 then proxy = "Tuner" end print("ReceivedFromProxy [" . ". Send to Device: " . " for " . ParamValue in pairs(tParams) do print(ParamName.ReceivedFromProxy ReceivedFromProxy(idBinding.Binding ID of the proxy that sent a BindMessage to the DriverWorks driver. idBinding .3 . cmd) emit(cmd) else CommandInterpreter(strCommand.7. ParamValue) end end end Map the idBinding to a variable for proxy. "]: " .. strCommand. strCommand .. evaluate the command coming in – if it’s a simple command. idBinding . including all parameters: function ReceivedFromProxy(idBinding. strCommand. The following example comes from: [DriverWorks_232_sample_receiver_Integra_dtr-4... strCommand.. otherwise call a function to process the command. strCommand .. tParams) print("ReceivedFromProxy [" . tParams) Function called by Director when a proxy bound to the specified binding sends a BindMessage to the DriverWorks driver.Command that was sent tParams . strCommand) if (tParams ~= nil) then for ParamName.. tParams) end end Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation. get the command equivalent out of the CMDS table. " Value: " .. All Rights Reserved Page 10 Version 1. which are sent from Composer’s Actions tab and processes them. cmd .Undefined Command") print("Key: " .1. tParams) print("ExecuteCommand: " .c4i] function ExecuteCommand(strCommand. " Value: " .3 .Lua table of parameters for the sent command Example Print all commands received for this protocol driver.. cmdv) end end Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation.7.cmdv) if cmd == "ACTION" then if cmdv == "Reset Security System" then ResetSecuritySystem() else print("From ExecuteCommand Function . This includes commands created in Composer programming. Parameters strCommand ..Undefined Action") print("Key: " .Command to be sent tParams .. strCommand) if (tParams ~= nil) then for ParamName. cmd . tParams) print("ExecuteCommand function called with : " .. including all parameters: function ExecuteCommand (strCommand. strCommand) if (tParams == nil) then if (strCommand =="GET_PROPERTIES") then GET_PROPERTIES() else print ("From ExecuteCommand Function .. ParamValue in pairs(tParams) do print(ParamName.cmdv in pairs(tParams) do print (cmd. tParams) Function called by Director when a command is received for this DriverWorks driver.. strCommand) end end if (strCommand == "LUA_ACTION") then if tParams ~= nil then for cmd. It also looks for LUA_ACTION commands.Unutilized command: " .. cmdv) end else print("From ExecuteCommand Function . ParamValue) end end end This sample function evaluates the commands received from Director and calls the correct function. The following example comes from: [DriverWorks_232_Template_Security..1 Director Command Interface ExecuteCommand ExecuteCommand(strCommand. rev. You are currently running version " . Return   buildtime  13:35:13    builddate  Sep 29 2008    version  1. major .2 Serial/Network/Device Interface SendToSerial C4:SendToSerial(idBinding. build) if (tonumber(major) < 2) then if (tonumber(minor) < 8) then print("This Code requires at least version 1... "(%d+)\. minor ..7.Returns 000fff665FDE 1.7. " Minor: " .. minor.match(strVers.. rev .(%d+)\. " Rev: " . 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 Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation.0.(%d+)\.222    buildtype  DEBUG  Parameters None Example local tVers = C4:GetVersionInfo() local strVers = tVers["version"] local major. All Rights Reserved Page 11 Version 1..3 ..8 to operate properly. " Build: " .(%d+)") print("Major: " .GetVersionInfo C4:GetVersionInfo() GerVersionInfo returns the version of Director currently running.. build = string. strVers) end end GetUniqueMAC C4:GetUniqueMAC() Returns the unique MAC address of the controller running Director Returns String Parameters None Example print(C4:GetUniqueMAC()) -. .3 . It then evaluates the response for specific delimiters and extracts the necessary components which are then used to do something.Binding ID of the serial interface to send on. NULL (‘\0’) is a valid character and Lua strings handle embedded NULL characters.. All Rights Reserved Page 12 Version 1.5..Parameters idBinding . strCommand) C4:SendToSerial("1". It is the driver’s responsibility to re-constitute and parse the commands received from the device. strCommand .c4i] function ReceivedFromSerial(idBinding.7.c4i] function emit(strCommand) print("Emit: " .Binding ID of the serial interface the data was received on strData . strData) print("Received something from serial on binding " . idBinding) hexdump(strData) responseCount=0 l_string = strData for w in string.sub(l_string.5.6.find(l_string. Serial data received may only include part of a protocol command from the connected device.Data to send out the specified serial interface Remarks Serial data to be sent can contain NULL characters.gmatch(strData. strData) Function which dumps the data received from serial (hex format) for inspection via print.sub(l_string. strData . "\r") end ReceivedFromSerial ReceivedFromSerial(idBinding.delimPos+1) sendNotify() end end Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation.)") do retType = w responseCount=responseCount +1 delimPos = string. Parameters idBinding .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. Example The following example comes from: [DriverWorks_232_sample_receiver_Integra_dtr-4. tonumber(delimPos)-1) l_string = string.. Example The following example comes from: [DriverWorks_232_sample_receiver_Integra_dtr-4. "!1(..tohex("1A")) retValue = string. c4i] function ReceivedFromNetwork(idBinding. Example The following example comes from [weatherbug. g_URLPacket) ReceivedFromNetwork ReceivedFromNetwork(idBinding.SendToNetwork C4:SendToNetwork(idBinding.Send 'queued' HTTP request to WeatherBug: C4:SendToNetwork(6001.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.7. All Rights Reserved Page 13 Version 1.. Returns None Parameters idBinding .Binding ID of the network interface to send on nPort .Binding ID of the interface the data was received from nPort . Network data received may only include part of a protocol command from the connected device. nPort.. nPort.Network data from the specified binding and port Remarks Network data received may contain NULL characters. strData) Function which sends an HTTP request to a network binding / port. strData) Function which combines the data received from the network into a variable for processing when the connection status changes.Network port to send on strDat .3 . Example The following example comes from [weatherbug. nPort. g_Receivebuffer = g_Receivebuffer .Save up things coming back on HTTP port. NULL (‘\0’) is a valid character and Lua strings handle embedded NULL characters. strData end Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation. It is the driver’s responsibility to re-constitute and parse the commands received from the device.Network Port the data was received on strData .. strData) -. 80. process when done sending to us. Returns None Parameters idBinding .c4i] -. Once it's connected. nPort.Binding ID of the network interface to disconnect from nPort . nPort) Function called from DriverWorks driver to disconnect from a specific idBinding and nPort. strStatus) if (idBinding == 6001) then if (strStatus == "ONLINE") then -.“OFFLINE” or “ONLINE” Example The following example comes from: [weatherbug.Connect was successful.7. the g_URLPacket will be sent.3 . All Rights Reserved Page 14 Version 1. An established connection can be validated through OnConnectionStatusChanged.Send 'queued' HTTP request to WeatherBug: Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation. Returns None Parameters idBinding .c4i]: -. C4:NetConnect(6001.Binding ID of the network interface nPort .Network port to connect to Example The following example comes from: [weatherbug. port 80. 80) NetDisconnect C4:NetDisconnect(idBinding.Network port Example The following example disconnects the current connection on binding 5001.Connect to WeatherBug HTTP server.Port number whose status has changed strStatus . strStatus) Function based on the return from the system used by weatherbug driver to process the communication.NetConnect C4:NetConnect(idBinding. -. nPort. C4:NetDisconnect(5001. Retrurns None Parameters idBinding .ID of the network binding whose status has changed nPort . Send URL packet.c4i] function OnConnectionStatusChanged(idBinding. nPort) Function used to tell the system to make a connection.Other actions… -. Returns None Parameters idBinding . 80) OnConnectionStatusChanged OnConnectionStatusChanged(idBinding. {}) Ramps the Light registered with the system as device 41 to 60% over 3 seconds: C4:SendToDevice(41. "TOGGLE". TIME = 3000}) Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation. idBinding .ID of the network binding whose addressing status has changed bIsBound .Command to be sent tParams . bIsBound) Function called by Director when a network connection has been addressed (‘identified’ on Network Connections Page) or unaddressed (‘disconnect’).. strCommand. Returns None Parameters idDevice .. This means the receive buffer is full and ready to process.. "RAMP_TO_LEVEL".Lua table of parameters to the command Example Toggles the Light registered with the system as device 41: C4:SendToDevice(41. 80.") if (bIsBound) then print("Binding is bound.. g_URLPacket) else -.Whether the network binding has a bound address Example function OnNetworkBindingChanged(idBinding. bIsBound) print("Network Binding " .Device ID of the driver you wish to send the command to strCommand . Returns None Parameters idBinding ..OFFLINE. All Rights Reserved Page 15 Version 1.Other actions… end end end OnNetworkBindingChanged OnNetworkBindingChanged(idBinding. {LEVEL = 60.") else print("Binding is not bound.7.3 .") end end SendToDevice C4:SendToDevice(idDevice. -. " Changed. tParams) Function called from DriverWorks driver to send a Control4 CommandMessage to the specified Control4 device driver.C4:SendToNetwork(6001.. 7.Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation. All Rights Reserved Page 16 Version 1.3 . Value to set variable Example Sets the value of the device variable named “Driver Variable” to 90: C4:SetVariable("Driver Variable". Returns None Parameters strName . LEVEL. The following example comes from:[weatherbug.c4i]: C4:SetVariable("FORECAST_SUMMARY". All Rights Reserved Page 17 Version 1. strValue) Function called from a DriverWorks driver to set the value of a Control4 variable for the driver. strVarType. Determines if the variable can be seen in Composer. Example C4:AddVariable("Driver Variable". [bReadOnly].3 Variable Interface AddVariable C4:AddVariable(strName. strSummary) Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation. BOOL bReadOnly .Variable Type.Value of Control4 variable strVarType .Optional.Name of Control4 variable strValue . defaults to false.Name of variable to set strValue . Composer programming will be incorrect. Valid types: STRING.Optional.1.7. SetVariable C4:SetVariable(strName. Remarks Variables should always be added in the same order. strValue. "NUMBER") Creates the device variable named “Driver Variable” within the Control4 system. defaults to false. In other words. 0.3 . 90) Sets the device variable named “FORECAST_SUMMARY” to the value indicated by strSummary for use within the Control4 system. bHidden . which are allocated in order during AddVariable calls. if you add a set of variables then later delete them and re-add different variables or in a different order. [bHidden]) Function called from a DriverWorks driver to create a Control4 variable for the driver. NUMBER. Determines if the variable can be modified externally. Control4 Composer programming is based on VariableID’s. Returns None Parameters strName . . Examples Use Variables in a comparison: if (Variables["Power State"] == "OFF") then C4:SendToSerial(idSerialBinding. Returns None Parameters strName .. "__ON__") C4:SetVariable("Power State". Variables[strName]) end DriverWorks Variables Table Variables[strName] The Lua Table ‘Variables’ contains the current value of this driver’s variables.Name of variable that has changed. you should use C4:SetVariable(strName. to change the value of a device variable. strName) print(" . Returns None Parameters strName – Variable name..DeleteVariable C4:DeleteVariable(strName) Function called from a DriverWorks driver to delete a Control4 variable for the driver. Parameters strName .3 .variable named: " . Although you can read directly from this table. new value is: " . function OnVariableChanged(strName) print("Variable value changed .Name of variable to delete Example Deletes the device variable named "Driver Variable" from the Control4 system. "ON") end Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation. strValue).. 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.7. All Rights Reserved Page 18 Version 1. C4:DeleteVariable("Driver Variable") OnVariableChanged OnVariableChanged(strName) Function called by Director when one of this driver’s variables’ values is changed. The value of the variable that has changed can be found with: Variables[strName]. Remarks OnVariableChanged is NOT called on a driver when it changes its own variable’s value. 1003)) Gets and prints the User Variable registered with the project as variable 209: print(C4:GetDeviceVariable(100001. idVariable.String Value of the requested variable. 70) Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation. nil if not found. 1004. Returns strValue . 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. idVariable) This function has been deprecated and should not be used for future driver development. idVariable) Function called by a DriverWorks driver to get the value of another device’s variable. 1000)) print(C4:GetDeviceVariable(84. All Rights Reserved Page 19 Version 1. with a DeviceID of 100001. strValue) Sets the Device Variable specified to the value passed to the function. Remarks User Variables belong to the Variable Agent. 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.7.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.Variable ID of the specified variable strValue .Value of the variable to set. Parameters idDevice .Device ID of the device that owns the specified variable idVariable . VariableValue) end GetVariable C4:GetVariable(idDevice. 209)) SetDeviceVariable C4:SetDeviceVariable(idDevice.3 . VariableValue in pairs(Variables) do print(VariableName. Returns None Parameters idDevice . GetDeviceVariable C4:GetDeviceVariable(idDevice. It was replaced by ‘GetDeviceVariable’ since it is used to get variables on different devices other than the DriverWorks driver.Print out all Variables: for VariableName. with a Device ID of 100001. the Lua OnWatchedVariableChanged call is called. idVariable. 1000) LIGHT_STATE (1000) Changes.Register for function StopMonitoring() -..3 ..RegisterVariableListener C4:RegisterVariableListener(idDevice.") print(" device: " . you MUST call UnregisterVariableListener when the driver is destroyed (in the OnDriverDestroyed function). 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.. 1001) LIGHT_LEVEL (1001) Changes. C4:UnregisterVariableListener(devid. The OnWatchedVariableChanged function will be called immediately after the listener is successfully set.. 1000) C4:UnregisterVariableListener(84. strValue) print("Variable changed.. All Rights Reserved Page 20 Version 1. idDevice) print(" variable: " . idVariable) print(" value: " . When a listener is set on a variable..Unregister Variable Listeners.7. idVariable) Function called from a DriverWorks driver to set a listener on a particular device’s variable. 1003) C4:RegisterVariableListener(100001.Device ID of the device that owns the requested variable idVariable . 1003) C4:UnregisterVariableListener(100001. whenever the variable changes. 1000) C4:UnregisterVariableListener(devid... Returns None Parameters idDevice . C4:RegisterVariableListener(devid. 1001) end Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation. strValue) print("-----------") end WARNING When registering variable listeners with this function.Register for -. Example: function StartMonitoring() C4:RegisterVariableListener(devid. Failure to do this may cause Director to crash when the variable changes value. end -. 209) C4:RegisterVariableListener(84.. 209) function OnWatchedVariableChanged(idDevice.. 1000) C4:RegisterVariableListener(84. with a DeviceID of 100001.Variable ID of the requested variable Remarks User Variables belong to the Variable Agent.. Variable ID of the changed variable strValue .") print(" device: " . strValue) print("-----------") end Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation. Variable changes for the particular Device’s Variable will no longer be reported.function OnDeviceDestroyed() -.Called when the driver is about to go away. not variables that necessarily belong to a DriverWorks driver. idVariable.Device ID of the device that owns the requested variable idVariable . idVariable) print(" value: " . idVariable) Function called from DriverWorks driver to remove a listener on a particular device’s variable... 209) OnWatchedVariableChanged OnWatchedVariableChanged(idDevice.. strValue) Function called by Director when a Control4 variable changes value.New value of variable that has changed Remarks Watched variables are variables that belong to other devices in the system. 1003) C4:RegisterVariableListener(100001. 1000) C4:UnregisterVariableListener(84. Example This stops the system from reporting variable value changes for the specified device and variables: C4:UnregisterVariableListener(84. variable ID. Parameters idDevice ...7.Device ID of the device that owns the changed variable idVariable .. idVariable. All Rights Reserved Page 21 Version 1.3 . StopMonitoring() end UnregisterVariableListener C4:UnregisterVariableListener(idDevice. Returns None Parameters idDevice . strValue) print("Variable changed.Variable ID of the requested variable Remarks User Variables belong to the Variable Agent. idDevice) print(" variable: " . and variable value when any watched variable changes: function OnWatchedVariableChanged(idDevice. Example This example function prints the value of the device ID. with a DeviceID of 100001.. 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 Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation, All Rights Reserved Page 22 Version 1.7.3 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) Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation, All Rights Reserved Page 23 Version 1.7.3 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 Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation, All Rights Reserved Page 24 Version 1.7.3 22) SendIRStop C4:SendIRStop(idBinding. strValue) Function called from DriverWorks driver to update driver properties.c4i Remarks The IR code to send must be declared as an <ircode> in the <irsection> of the driver’s .Name of property to update strValue .Id of the IR Code to start sending from the . idIRCode. 22) 1. This is typically used on button release events.armMode) C4:UpdateProperty("Security State". All Rights Reserved Page 25 Version 1. The IR code to send must be declared as an <ircode> in the <irsection> of the driver’s ."Armed ".c4i] C4:UpdateProperty("Security State".IR Binding ID to send the IR Code. Returns None Parameters strName . Returns None Parameters idBinding ."Disarmed") OnPropertyChanged OnPropertyChanged(strName) Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation. idIRCode) Causes Director to stop sending the specified IR Code out the specified binding. Example This example stops sending the specified IR Code out the specified IR Binding: C4:SendIRStop(1. Example This example starts sending the specified IR Code out the specified IR Binding: C4:SendIRStart(1..New value of property Example Various examples of how the properties are updated by the driver.c4i file.c4i file.3 . This example can be found in: [DriverWorks_232_template_security. which (in the case of volume ramps) could be catastrophic to equipment.Remarks Failure to call the SendIRStop function will cause the IR code to be sent continually.7.7 Properties Interface UpdateProperty C4:UpdateProperty(strName. you should use C4: UpdateProperty.. This example can be found in: [DriverWorks_232_template_security.do stuff end elseif (string. Returns None Parameters strName .find(strProperty.do stuff elseif propertyValue == "Armed Away" then -. All Rights Reserved Page 26 Version 1.do stuff else print("No action performed for " .c4i] function OnPropertyChanged(strProperty) propertyValue = Properties[strProperty] print("strProperty = " . only when the Property is changed by the user from the Properties Page. propertyValue) if (strProperty == "Security State") then if propertyValue == "Disarmed" then -.Name of property that has changed. " changed to: " . strProperty .do stuff elseif propertyValue == "Alarm Activated" then -. strProperty . Returns None Parameters strName – Desired device Property Examples Use of Properties in a comparison: Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation.Function called by Director when a property changes value. and change properties’ values on the devices’ Properties page.do stuff elseif propertyValue == "Armed Stay" then -.3 .. to change the value of a device property programmatically. 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. Remarks The value of the property that has changed can be found with: Properties[strName].7.. " which has been set to: " ... Note that OnPropertyChanged is not called when the Property has been changed by the driver calling the UpdateProperty command. Example An example function used to process property value changes."Zone") ~= nil) then -. PropertyValue in pairs(Properties) do print(PropertyName.8 Log Interface DebugLog C4:DebugLog(strLogText) Function called from DriverWorks driver to send messages to Control4’s debug log.3 . PropertyValue) end 1.7.c4i] C4:DebugLog("Log This Text") Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation. Returns None Parameters strLogText . All Rights Reserved Page 27 Version 1.if (Properties[“CalculateWindShear”] == “true”) then CalculateWindShear() end Print out all Properties: for PropertyName.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. Returns Driver Device ID Parameters None Example local myid = C4:GetDeviceID() print("My Device's ID is: " .7.The value of the capability retrieved from the .c4i file. 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.ErrorLog C4:ErrorLog(strLogText) Function called from DriverWorks driver to send messages to Control4’s error log. GetDeviceID C4:GetDeviceID() Function called from DriverWorks driver to get this driver’s Device ID. Returns strCapability .c4i file Parameters strName .9 Miscellaneous DriverWorks PersistData Table PersistData = {} The Lua Table ‘PersistData’ is available for drivers to keep persistent data across director restarts. myid) GetCapability C4:GetCapability(strName) Function called from DriverWorks driver to get a capability from the driver’s .The name of the capability to retrieve Examples Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation..3 . Any values placed into the PersistData table will exist in the PersistData table when the driver is loaded after a director restart. All Rights Reserved Page 28 Version 1.c4i] function dbg(strDebugText) if (g_debugprint) then print(strDebugText) end if (g_debuglog) then C4:ErrorLog(strDebugText) end end 1. strClass .. STEREO.Whether the binding has been bound or unbound. to the now-connected device. strClass. strType. Example function OnBindingChanged(idBinding.Class of binding that has changed. " (Class " .. bIsBound) Function called by Director when a binding changes state (bound or unbound). only *control*-type bindings (Serial. send discrete volume.") if (bIsBound) then print("Binding is bound.3 . It is intended to be used specifically for when serial bindings are made.. All Rights Reserved Page 29 Version 1. so the driver knows it can send initialization.7. strName. etc. This indicates which has been bound or unbound. etc. bHidden. Returns None Parameters IdBinding .). ") Changed. Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation.. 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. the AddDynamicBinding does not work for audio and Video bindings.") end end AddDynamicBinding C4:AddDynamicBinding(idBinding.If this device supports discrete volume control. idBinding . bIsProvider. strClass.ID of the binding whose state has changed StrClass . Remarks Protocol drivers do not get OnBindingChanged notifications for AV and Room bindings being bound. IR. strClass. bIsBound) print("Binding " . otherwise. etc. A single binding can have multiple classes: COMPONENT. BIsBound . bAutoBind) Note: Currently.") else print("Binding is not bound. 3 . 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. false. StrType . false) PersistData["zonebindings"][102] = "Zone 2" C4:AddDynamicBinding(102. BAutoBind .ID of the dynamic binding. "CONTROL". Returns None Parameters IdBinding .Whether the dynamic binding is hidden. "CONTROL". "CONTACT_SENSOR". VIDEO.Whether the binding is a Provider or a Consumer binding. Examples Dynamically create 4 Zone Contact Bindings for a Security Driver: C4:AddDynamicBinding(101. true. and ROOM_CONTROL bIsProvider . "CONTROL". false. BHidden . "CONTROL".Class of dynamic binding that is being created. If dynamic bindings have been connected in Composer. if they are properly restored by the DriverWorks driver. false. "Zone 3". "Zone 1". false. Should typically be false. "CONTACT_SENSOR". All Rights Reserved Page 30 Version 1.Function called by a DriverWorks driver to add a dynamic binding (a binding added at runtime). "Zone 1". "CONTROL". true. true. "CONTROL".Whether the dynamic binding should be auto-bound. "CONTACT_SENSOR". "Zone 3". false) PersistData["zonebindings"][103] = "Zone 3" C4:AddDynamicBinding(103. the connections made between the bindings will be automatically restored. false) C4:AddDynamicBinding(102. false. "CONTACT_SENSOR". PROXY.Type of dynamic binding. true. Valid types include: CONTROL. "Zone 2". "CONTACT_SENSOR". This is typically done by security panels or other devices whose number of bindings are unknown when the driver is created. "CONTACT_SENSOR". the bindings will not be available after a Director restart. false) Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation. "Zone 2". Should typically be false.7.Name of binding that will appear in Composer’s connections page. AUDIO. true. StrClass . false) C4:AddDynamicBinding(103. If this is not done. true. 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. false. StrName . All Rights Reserved Page 31 Version 1.3 .String to be encoded in Base64 encoding Example Example Base64 encodes a string. true. dec) Base64Decode C4:Base64Decode(strToDecode) Function called in a DriverWorks driver to decode the specified string from a Base64encoded string. "CONTROL"... false.ID of the dynamic binding to remove. false) end end RemoveDynamicBinding RemoveDynamicBinding(idBinding) Function called by a DriverWorks driver to remove a dynamically-created binding. str) local enc = C4:Base64Encode(str) print("Encoded: " . not within any declared function: if (PersistData ~= nil) then for key. value.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. Returns String encoded in Base64 encoding. and then decodes it: local str = "Control4 DriverWorks SDK" print("Original String: " . Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation.7.. Returns None Parameters IdBinding . "CONTACT_SENSOR". enc) local dec = C4:Base64Decode(enc) print("Decoded: " . Parameters StrToEncode .value in pairs(PersistData["zonebindings"]) do C4:AddDynamicBinding(key. 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 Base64encoded string. Serial polling C4:SendToSerial(1.String to be decoded from Base64 encoding Example Example Base64 encodes a string. Remarks You must escape all strings that are put into XML.Returns String decoded from Base64 encoding. Parameters StrToDecode .The passed in string. Parameters strRawInput . dec) OnPoll OnPoll() Function called by Director when Director’s internal Poll timer expires. with possibly invalid characters for an XML value.c4i files. C4:XMLEscapeString . Returns strEscaped . "STATUS\r\n") end XMLEscapeString C4:XMLEscapeString(strRawInput) ‘Escapes’ the passed in string.. This only occurs in drivers that have requested polling within their . All Rights Reserved Page 32 Version 1. Parameters None Returns None Remarks You can also implement polling yourself within your driver by using DriverWorks system timers.. and then decodes it: local str = "Control4 DriverWorks SDK" print("Original String: " ..3 . enc) local dec = C4:Base64Decode(enc) print("Decoded: " .. "</text>" Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation. Examples Builds an XML string with a string that could have invalid XML characters in it: strXmlListItem = "<text>" . with all XML characters properly escaped. Example function OnPoll() -. otherwise invalid characters could cause the XML to be invalid. str) local enc = C4:Base64Encode(str) print("Encoded: " .. by setting the <can_poll_serial> capability to “True”.7.Raw input string. rendering any XML characters in the string as characters that are valid in an XML value. format("%x". Returns strDecrypted . Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation. strKey .format("%x". encoded as a string (128-bit). print(string. using the specified key. The input string (strBuf) must be padded to a 4-byte boundary.org/wiki/XXTEA Examples Encrypt then Decrypt a string.wikipedia. C4:CRC32(""))) -.should print "0" print(string. 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. using the specified key.should print "c877f61" TEAEncrypt C4:TEAEncrypt(strBuf. strKey) Encrypt the input string with Corrected Block TEA (XXTEA) Algorithm. key)) -. Returns nCRC32 . Example Calculate and print the CRC32 value of some common valid CRC32 test vectors. key) print(C4:TEADecrypt(e.3 . Parameters strBuf .The calculated CRC32 value of the input string (a number). C4:CRC32("Test vector from febooti.com"))) -. then print the original string out: local key = "1234567887654321abcdefabcabcdefa" e = C4:TEAEncrypt("Control4 Rocks! ".Key to use for encryption.CRC32 C4:CRC32(strInput) Calculates the CRC32 value for the input string. strKey) Decrypt the input string with Corrected Block TEA (XXTEA) Algorithm.TEA Encrypted version of input string.String to be encrypted. Parameters strInput .Decrypted version of input string. Keys are 32 hex digits. Returns strEncrypted . All Rights Reserved Page 33 Version 1.prints "Control4 Rocks! " TEADecrypt C4:TEADecrypt(strBuf. Remarks Key must be the same for encryption / decryption to function properly.7.String of data to calculate the CRC32 of. key)) -. Remarks Key must be the same for encryption / decryption to function properly. Returns Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation. when the byte order of the two ends is unknown or may be different from each other.Parameters strBuf .The input unsigned long value.Key to use for decryption. encoded as a string (128-bit). 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. The input string (strBuf) must be padded to a 4-byte boundary.3 .String to be decrypted.7. strKey . Remarks This function is typically used to convert numeric values received over a network.wikipedia. All Rights Reserved Page 34 Version 1. This way.org/wiki/XXTEA Examples Encrypt then Decrypt a string.prints "Control4 Rocks! " ntoh_l C4:ntoh_l(nVal) Converts the numeric value passed in to host byte order. key) print(C4:TEADecrypt(e.The nVal parameter converted to host byte order Parameters nVal . then print the original string out: local key = "1234567887654321abcdefabcabcdefa" e = C4:TEAEncrypt("Control4 Rocks! ". Keys are 32 hex digits. ‘Host’ byte order is the byte order of values on the local machine. Example i_network = 0x1234ABCD i_native = C4:ntoh_l(i_network ) print("native order = " . and ‘Network’ byte order is the standard byte order on Ethernet networks.. Returns nHostVal . ‘little-endian’ and ‘big-endian’ machines can communicate without confusion. 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. . and ‘Network’ byte order is the standard byte order on Ethernet networks. ‘little-endian’ and ‘big-endian’ machines can communicate without confusion. Example i_native = 0x1234ABCD i_network = C4:hton_l(i_native) print("netowrk order = " . Parameters None Returns proxy id. when the byte order of the two ends is unknown or may be different from each other. the print function can be called without prefacing with C4: Example Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation. Returns None Parameters strPrintText .Text to print Remarks Note that for convenience..3 . 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. Parameters paramName paramText Remarks This function is typically used to convert numeric values to be passed over a network.The nVal parameter converted to network byte order. ‘Host’ byte order is the byte order of values on the local machine. … Example local proxyId = C4:GetProxyDevices() print("proxy is: " . All Rights Reserved Page 35 Version 1.7.nNetVal . This way. proxy id. 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. Te 00000008 73 74 20 54 65 78 74 st. Returns None Parameters strHex . "Test Text") Prints out the following: 00000000 00 FF DE AD BE EF 54 65 . Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation. 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 ") ..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. All Rights Reserved Page 36 Version 1. Full instructions on use of remote debugging of DriverWorks drivers may be found in the “Control4 DriverWorks SDK – Getting Started Guide”.7..11 Debug Interface Section EnableRemoteDebugging C4:EnableRemoteDebugging(strHostAndPort) Enables remote debugging of DriverWorks Lua scripts through an external IDE with a debugger.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.. Typically used when a protocol sends commands that are hex values. All characters that are not ‘A-Z’ or ‘0-9’ are printed as a ‘.3 ..’ In the ascii representation.Text 1. 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. Returns None Parameters None Example function Attach() -. All Rights Reserved Page 37 Version 1. Returns None Parameters None Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation.0. Returns None Parameters None Example C4:DisableRemoteDebugging() Attach Attach() Function called by Director when remote debugging of the DriverWorks script has started.168.118:8888") DisableRemoteDebugging C4:DisableRemoteDebugging() Disables remote debugging of DriverWorks Lua scripts.7.3 .Initial debug setup bDebug = true end OnEndDebugSession OnEndDebugSession() Function called by Director when remote debugging of the DriverWorks script has ended. Parameters None Returns Driver Device ID Example local contextId = C4:MediaGetDeviceContext() print("context is: " ..3 .7.Example function OnEndDebugSession() bDebug = false end 1. Returns None Parameters None Example MediaSetDeviceContext C4:MediaSetDeviceContext() Function that sets a device id to be used for media related call. Parameters New device id to be associated with media related api’s. 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.Generic MediaRemoveAllMedia Removes all albums songs and movies from the device. modifying.12 Media Management . If set to any value other than “0” then adding. All Rights Reserved Page 38 Version 1. retrieving or removing functionality will use the supplied device id. If set to “0” then the media related api’s will use the current driver’s device id. contextId) prints: context is: 391 Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation. 0.1/movies/shrek1". rating = "". description = "In this fully computer-animated fantasy".1. shrekMovie) MediaGetMovieInfo C4:MediaGetMovieInfo(mediaId) Function that returns movie properties. Eddie Murphy.13 Media Management – Movies The examples used in the Movies section of this document will reference the following movie: shrekMovie = { directors = "Andrew Adamson.0.0. cast = "Mike Myers. "shrek1".3 Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation.1/movies/shrek1". John Lithgow".0. cover_art = "/9j/4AAQSkZJRgABAQEBLAEsAAD/" } MediaAddMovieInfo C4:MediaAddMovieInfo("http://127. Returns Table • • • • • • • • • • • • • • information. Vicky Jenson". release_company = "DreamWorks". shrekMovie) Returns Number – The new Media ID for the movie Parameters string location string title table information Example mediaId1 = C4:MediaAddMovieInfo("http://127. Page 39 Version 1. 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. All Rights Reserved . genre = "Children's/Family". "shrek1".7. release_date = "2001". Returns Table containing Media IDs and locations.7. All Rights Reserved Page 40 Version 1.key. Parameters number – The Media ID of the movie..Parameters Number – Media ID – This is the Media ID of the movie. Example C4:MediaRemoveMovie(mediaId3) MediaRemoveAllMovies C4:MediaRemoveAllMovies() Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation..3 . " location is ". Example myMovieInfo = C4:MediaGetMovieInfo(mediaId1) print(myMovieInfo[“title”]) MediaGetMovieLocation C4:MediaGetMovieLocation(mediaId) Function that returns the movie location. Parameters None Example allMovies = C4:MediaGetAllMovies() for key.. 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.value in pairs(allMovies) do print("mediaId 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. shrekMovie) Remarks A modify call does not change the media’s ID number where a delete or add call will.Removes all movies Example C4:MediaRemoveAllMovies() MediaModifyMovieInfo Function to modify the data associated with an existing media id. "shrek1". if a button push has is programmed to play the media. All Rights Reserved Page 41 Version 1. Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation. Returns None Parameters None . "http://127. For example. the media’s current ID is maintained and programming is not impacted.7.1/movies/shrek1Modified".0. Returns None Parameters Media ID Location Name Movie table information .Function to remove all movies from the database.movie information is required. Modify calls are useful if programming relies on the current Media ID. and a modify call is used.3 . None Example shrekMovie["genre"] = "Horror" C4:MediaModifyMovieInfo(mediaId1.0. release_date = "1992". } SomeSong3 = { title="Test Song Number 3". location=songLocation1. genre = "Blues & Browns". release_date="15 Jun 2222".1/music/song2.0.7. release_label = "Grass and Cash". } SomeSong2 = { title="Test Song Number 2".1/music/song1.mp3" songLocation2="http://127. artist = "C4 Music Factory".1/music/Album1".0.0.mp3" songLocation3="http://127. artist = "C4 Music Factory". --optional fields name = "Name Test Song Number 1". songs = {SomeSong1. artist = "C4 Music Factory".0.mp3" SomeSong1 = { --required fields title="Title Test Song Number 1".3 . record_label="Dos Record Label". record_label="Island".1/music/song3. Album1) songLocation1="http://127.0. release_date="3 Dec 2002". SomeSong2. "Funky Music".0. description = "Worst episode ever". location=songLocation2. name = "Name Test Song Number 3". All Rights Reserved Page 42 Version 1.0. release_date="15 Jun 2004". track_no="7". record_label="Boat".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. } Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation. } Album1 = { artist = "Jimmy Joe". name = "Name Test Song Number 2".0. location=songLocation3. track_no="6". track_no="1".1. SomeSong3}. 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 The new Media ID Parameters string location string title album table info . 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. Returns string location string title table information.3 . Each song is a table.1/music/Album1". song table info . "Funky Music". Table must contain the songs you want added to the album. location and track_no – unique for that able Example mediaId = C4:MediaAddAlbumInfo("http://127. All Rights Reserved Page 43 Version 1. Parameters Number – The Media ID for the album.songs information is required.7. Album1) MediaGetAlbumInfo C4:MediaGetAlbumInfo() Function that returns album information based on Media ID.0. Returns string – the location of this media stored in the database Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation.0.MediaAddAlbumInfo C4:MediaAddAlbumInfo Function that passes album info and returns a Media Id that for the album.data from MediaGetSongInfo: required fields are title. songs – an array of songs. value in pairs(allAlbums) do print("mediaId is ". Note. all songs associated with this album will be removed as well.key.Parameters number – the Media ID desired Example print(C4:MediaGetAlbumLocation(mediaId1)) MediaGetAllAlbums C4:MediaGetAllAlbums() Function that returns all albums and their Media IDs... Returns None Parameters number – The Media ID for the album. All Rights Reserved Page 44 Version 1.. " location is ".value) end MediaRemoveAlbum C4:MediaRemoveAlbum(mediaId) Function that will remove an album based on its media ID. Returns A table of each album’s Media ID as well as location.7.3 . Parameters None Example allAlbums = C4:MediaGetAllAlbums() for key. Returns Deletes all albums and songs for the device Parameters None Example C4:MediaRemoveAllAlbums() Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation. Example C4:MediaRemoveAlbum(mediaId1) MediaRemoveAllAlbums C4:MediaRemoveAllAlbums() Function that removes all albums. "NewLocation". Album1) Remarks A modify call does not change the media’s ID number where a delete or add call will. required fields are title. Example mySongInfo = C4:MediaGetSongInfo(mediaId1) print(mySongInfo["name"]) MediaGetSongLocation Parameters number – The Media ID of the song.15 Media Management – Songs MediaGetSongInfo C4:MediaGetSongLocation(mediaId) Function that returns song information based on its Media ID.3 . Returns string – The location of this media as stored in the data base Example print(C4:MediaGetSongLocation(mediaId1)) Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation. The information table will have entries for: string location string title Parameters Number – the Media ID for this song.7.0.1/music/Album1Modified".0. "http://127. Returns Table information. All Rights Reserved Page 45 Version 1. For example.MediaModifyAlbumInfo C4:MediaModifyAlbumInfo() Parameters media Id location name album table info song information is required. if a button push has is programmed to play the media. and a modify call is used. song table info data from MediaGetSongInfo. location and track_no – unique for that table Returns None Example Album1["release_label"] = "modded label" C4:MediaModifyAlbumInfo(mediaId1. 1. the media’s current ID is maintained and programming is not impacted. Modify calls are useful if programming relies on the current Media ID. Table must contain the songs you want added to the album. Name of the song. Returns Table of values including Media ID and location of each song. mediaIdSong. " location is ". 1) MediaGetSongsforAlbum C4:MediaGetSongsForAlbum() Function that returns songs associated with an album.7.MediaRemoveSong C4:MediaRemoveSong() Function that removes a song based on its Media ID.3 . Example C4:MediaRemoveSong(mediaId1) MediaLinkSongToAlbum C4:MediaLinkSongToAlbum() Function that associates a song to an album..key.. 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. Example Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation. Example AllSongs= C4:MediaGetSongsForAlbum(mediaIdAlbum) for key. All Rights Reserved Page 46 Version 1.value in pairs(AllSongs) do print("mediaId is ". Returns None Parameters number – the Media ID of the song..value) end MediaModifySongInfo C4:MediaModifySongInfo() Function that updates the location and name of a song Returns None Parameters Media ID of the song. Parameters Media ID of an album containing desired songs. Location of the song. the media’s current ID is maintained and programming is not impacted.7. Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation. Modify calls are useful if programming relies on the current Media ID. and a modify call is used.C4:MediaModifySongInfo(mediaId1.3 .0. All Rights Reserved Page 47 Version 1. if a button push has is programmed to play the media.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. For example.0. "http://127. All Rights Reserved Page 48 Version 1. The DriverWorks driver presents the list to the physical device. You should not request all list items. This mainly affects getting initial driver Room ID and initializing List Navigator. DriverWorks drivers have the ability to access Control4’s List Navigator functionality.16 List Navigator Functionality Beginning with the Control4 1. 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. and anytime *after* driver initialization. Typically. The DriverWorks driver handles button presses from the physical device. nControl(s)…) ListSetCapabilities must be called before starting a list with C4:ListStart. 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. 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. You may call List Navigator calls within functions in your Lua code. the DriverWorks driver will need to perform the following functions: • • • • • • The DriverWorks driver Initializes List Navigator When the device requires a menu. as well as on the 10-button LCD Keypad. Doing so can result in the driver not being loaded by Director and/or crashing Director.1. and requests additional items as needed.3 .Determines how many list items you wish to receive at a time. WARNING – You CAN NOT call List Navigator functions in the initialization portion of your DriverWorks code (in the main Lua body of the driver). Control4 uses List Navigator to provide the list interface on Control4’s System Remotes. Your driver should handle paging of the items and requesting Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation. using the phone keypad for navigation. Returns None Parameters nMaxListCacheSize . nMaxListItemLen. This tells Director how many items you wish to retrieve at once. but only as many as you wish to hold locally. or a portion of the list if there are many items using calls ListNewList and ListMIBReceived. the DriverWorks driver calls C4:ListStart The DriverWorks driver receives a list from Director.7. how wide to make the items. ListSetCapabilities C4:ListSetCapabilities(nMaxListCacheSize.2 system software release.7. These two functions are performed in a function that is triggered by a timer in the body of the <script> section of the driver. and what controls you wish to implement. info:watch. or the Browse Videos by Director: C4:ListStart('audio') C4:ListStart('videos:browse:director') ListStop C4:ListStop() Stop the current DriverWorks List Navigator session. videos:browse:director. info:listen. Examples This sets the list capabilities to allow 30 items at a time.7. Requesting all items at once will slow down your driver and Director.You can request which controls you will implement. 20. lights. audio. Returns None Parameters None Example C4:ListStop() Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation. It is recommended that you pass 0x0d. comfort. nMaxListItemLen. comfort:thermostat. no wider than 20 characters. videos:browse. info:help. tv:channels. info. house:relays.3 . All Rights Reserved Page 49 Version 1. 0x0e for your controls. 0x0d. tv.Container (page) you wish to start the list on. info:about Examples Start a List Navigator session on the main menu: C4:ListStart() Start a List Navigator session on the ‘audio’ menu. videos:browse:all. No parameter equals starting at the main list menu.Maximum length of items in your display. radio:stations. videos:browse:rating. comfort:contacts. locations. nControls . video. house:contacts. 0x0e) ListStart DescriptionText C4:ListStart(strContainer) Returns None Parameters strContainer. Valid Containers include: house. radio.more items when needed. comfort:blinds. videos:browse:genre. and will implement the standard controls: C4:ListSetCapabilities(30. videos:browse:actor. Director will cut off any items longer than this length. comfort:relays. Param2: 0) Other MIB Commands (no additional info available): c4. Examples Select Item number 3 in the current list indicated by g_ListID C4:ListSendCommand("c4. 3)) Go back in the list a level (triggered by left button.Number of records to retrieve.ise – Item Select c4. nCount . nStartIndex. Parameters nListID . Not required. nCount) Requests nCount list items.cn – Cancel c4. All Rights Reserved Page 50 Version 1.is". the list items are returned in a call to ListMIBReceived. g_ListID).ln. 20) ListSendCommand C4:ListSendCommand(strCommand. 0 is the first record in a list.Parameters to the command. nStartIndex . g_ListID).This is the List ID received in the ListNewList call from Director. typically) C4:ListSendCommand("c4.7.ii – Item Info c4.cc – Control Change c4.Starting index of the records to receive. This is an asynchronous call.ln.format("%04x".ln. Param2…) Send a List MIB command to Director. you may pass as many parameters as needed.lb – List Back (Param1: ListID. Returns None Parameters StrCommand .List MIB Command Param1 .format("%04x". starting at StartIndex Returns None.format("%04x".ish. Examples Retrieve the first 20 items of the current list in g_List: C4:ListGetItems(g_List. string. this quoting must be performed by the DriverWorks driver. 0) Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation.ln. string. it will not be performed by the ListSendCommand itself. string.ListGetItems C4:ListGetItems(nListID.ln. c4. Param2: Selected Item Number – 0based) c4.lb".ln. 0. for the ListID passed in.as – Alphanumeric Select Remarks If string parameters are required to be quoted by List Navigator. Useful MIB Commands: c4.ln.ln.3 .ln.is – Item Select (Param1: ListID. Param1.ln. ListGetRoomID will initially return the Device ID of the room the device driver is placed into in the project.List is started.DeviceID of the current List Navigator room device. Parameters None Remarks .3 . Returns None Parameters None Example C4:ListGoToRoot() ListIsStarted C4:ListIsStarted() Returns a Boolean of whether the list is started or not. All Rights Reserved Page 51 Version 1.ListGetRoomID C4:ListGetRoomID() Gets the DeviceID of the current ListNavigator room. Returns bIsStarted . true or false Parameters None Example Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation. Returns bIsInNavigation .List is in navigation. Returns NRoomID .7. 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. Examples Print the current Room Device ID: print(C4:ListGetRoomID()) ListGoToRoot C4:ListGoToRoot() Reset the current list back to the main menu. 3 . All Rights Reserved Page 52 Version 1.7.if (C4:ListIsInNavigation()) then print("List is in Navigation") end Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation. ‘house’. This includes things like ‘audio’. etc. nIndex . strNavID) Function called by Director when a new List Navigator List has been requested by the DriverWorks driver and successfully opened by Director. strName.MIB Command that was received. strNavID) print("New List: ID: " .. This is typically displayed on the top line of the display. nCount. nItemCount. and can be used to determine where the user is in the list. end. Not typically used.Selected index in the list.Category of the list. They are described in more detail in the Remarks section.is).. To retrieve the list items themselves. All Rights Reserved Page 53 Version 1.si”.. C4:GetListItems must be called.3 .ln. and when you select an item in the list. tParams) Function called by Director when List items or List MIB Commands are received... and is initially the name of the Room. For lists that are received from a ‘list back (c4.ItemCount is the number of items in this list. strContainer. nItemCount. Typical MIB Commands include: “c4. “c4. " Name: " . strContainer . strCategory . It is required to request more items from the list. Remarks ListNewList is received when the list is opened. strCategory. " Index: " . Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation.le”. along with the currently selected item number (1/5) strName . ‘locations’. nIndex. strContainer . nIndex. strNavID) -. it will be the list index that was selected. strName. nItemCount .ln.7. " Category: " .. etc. strName .Name of this list...ln. For lists that are being selected. It is called in response to: • C4:ListStart • C4:ListSendCommand (Item Select – c4.ListNewList ListNewList(nListID. Returns None Parameters nListID .This is really too complicated for a ‘real’ example… end ListMIBReceived ListMIBReceived(strCommand.ln.Container is similar to Category. strNavID . " Count: " .gi”. but no list items are returned. nListID . strContainer. strCategory.Navigator ID of this list. Parameters strCommand . " Container: " .. " NavID: " . to decide when to pop up a control..lb)’ command..ListID is a number used by List Navigator to track which list you are currently viewing.ln. and updated items.Count of the items in the tParams table. and “c4. nIndex . Example function ListNewList(nListID. may be ‘Unknown’. nItemCount . this will typically be 0.. This is typically displayed on the top line of the display. nCount . strCategory .. List MIBs are how Director communicates lists. Parameters of the device.Container this control resides in. Example function ListNewControl(strContainer. This MIB indicates that the list has ended..v) end end end ListNewControl ListNewControl(strContainer. for a light being selected.le – List End.Table of values for the MIB Command that was received. or if you call C4:ListStop. tParams) Function called by Director when you have selected a ‘Control’. toggle it when selected if ((strContainer == "comfort") and (strNavID == "NIRelay")) then C4:SendToDevice(idDevice.. All Rights Reserved Page 54 Version 1. "TOGGLE". They are indexed on a zerobased index in the table. strNavID .v in pairs(tParams) do print(k. tParams) -.Navigator ID of the control. For example. tParams) print("List MIB Received: " .3 . Used to determine what action to take or what control to display when ListNewControl is called. strCommand) print(nCount . Remarks MIB Descriptions: c4. and this is the list of items that you requested. Any items that need updating are encoded the same as items in c4.gi above. Example function ListMIBReceived(strCommand. The items in the list are encoded with specific key values preceding the item name. 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. idDevice. Controls are pages used on a List Navigator to control a specific item. idDevice . " Params:") if (nil ~= tParams) then for k. tParams .ln. In the tParams table. nCount. {}) end Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation.Device ID of the device that should be controlled. Used to determine what action to take or what control to display when ListNewControl is called.1). and one of them was switched on or off.7.tParams .If this is a relay. Parameters strContainer .ln. This MIB indicates that you called C4:ListGetItems. c4. there will be a set of list items. Typically you will receive this MIB when the user has backed all the way out of the menu. strNavID. This could happen if you were looking at a list of lights. idDevice.ln.si – Updated Item. c4. or if your music queue changed while looking at the music queue. Encoded values are listed below. like a light level or the volume of an audio zone. This MIB indicates that an item in your current list has been updated. 0 to (nCount .ln.gi – GetItems return. strNavID. "TOGGLE". Param1. " (" . Common List Events are described below: VolumeChanged . Depends on the event. Param1. etc..Second Parameter to the event. If your driver is in a menu.-. Param1 is the new light value. Media Changing.. RoomChanged . and request it’s room ID again. {}) else gInControl = true gControlType = "light" gControlName = tParams["NAME"] gControlLightValue = tonumber(tParams["LEVEL"]) gControlDeviceID = idDevice DisplayControl(true) end end ListEvent ListEvent(strEvent. ProjectChanged . ")") Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation. Remarks List Events happen on things like the room Volume changing. Param1 . LightValueChanged . Param1 end if (nil ~= Param2) then outstr = outstr . Param2 .First Parameter to the event. Param2) Function called by Director when an event happens on which a List Navigator client should operate.. Param2) local outstr = "" if (nil ~= Param1) then outstr = outstr .This event indicates that the Media playing in the currently selected room has changed. Param2 is the name of the new room. Depends on the event. Returns None Parameters strEvent . MediaChanged ... it should exit the menu..This event indicates that a light’s brightness has changed value.If a switch." .This event indicates that the currently selected device has changed.This event indicates that the currently selected room’s volume has changed.This event indicates that the currently selected room has changed. outstr .3 . strEvent . Example function ListEvent(strEvent. toggle.7.Name of the List Event. " -. Param1 is a string representation of the current volume. All Rights Reserved Page 55 Version 1. Param1 is the DeviceID of the new room. if a dimmer.. start Light Control Dialog if ((strContainer == "lights") and (strNavID == "NILight")) then if (tParams["IS_DIMMER"] == "FALSE") then C4:SendToDevice(idDevice.This event indicates that the project has changed and a ‘Refresh Navigators’ has been issued. Param1 is an XML string that indicates the changed media. SelectedDeviceChanged . Param2 end print("List Event: " . Room Changing. 0 1 2 3 4 5 6 7 – – – – – – – – Check Icon Light On Icon Light Off Icon Motion Icon Music Icon Relay Closed Icon Relay Opened Icon Selectable Icon Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation. If your device can display icons.3 .7. \0 – \7 – these are “icons”. \> – Indicates the item can be selected. you should show the icon. All Rights Reserved Page 56 Version 1. Can usually be ignored. Different types of lists use icons to indicate whether lights are on. similar to how the Control4 System Remotes. or contacts / relays are open or closed. so you should indicate this on the display somehow.end Encoded Item Values \c – Indicates a Container. 1 transports. SendZigbeePacket C4:SendZigbeePacket (strPacket. but define their own ID strings. Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation. Returns None Parameters strPacket .7. 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. ndestinationEndpoint) This function sends a raw Zigbee packet to a Zigbee Binding. nDestinationEndpoint .Source Cluster library included within the Profile nGroupID . Packet data is still sent in the strPacket parameter. All Rights Reserved Page 57 Version 1.3 .1. Remarks The following parameters are ignored when using the Control 4 (Embernet) Zigbee stack: nProfileID nClusterID nGroupID nSouceEndpoint nDestinationEndpoint. nClusterID.Zigbee device group identification nSouceEndpoint . This functionality supports both the current Control 4 (EmberNet) as well as ZigBee Pro 1. This information will support the development of DriverWorks Zigbee functionality so that partners using the Zigbee SDK can integrate into the Control 4 system. Send/Receive Data from Zigbee The ability to Send and Receive data from ZigBee devices is supported in DriverWorks. If using ZigBee Pro. nProfileID .DriverWorks and Zigbee Functionality DriverWorks support for Zigbee functionality will be delivered in release 1. all data (including strPacket) must conform to ZigBee Pro format.ZigBee supported command containing user data.6. This section has been included to provide information to Control 4 partners already using the Zigbee SDK. nGroupID.Endpoint designated as the recipient of the data packet delivery.Profile associated with the data packet nClusterID .Endpoint designated as the source of the data packet delivery. Allow ZigBee SDK developers the ability to utilize the Control4 identification mechanism.nProfileID. nSourceEndpoint. nProfileID .0. strPacket) end Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation.ZigBee supported user data received from the ZigBee device.lv 100" C4: SendZigbeePacket(strPacket. all data (including strPacket) must conform to ZigBee Pro format. idGroupID.7.format(%04x". nDestinationEndpoint . idProfileID. nSourceEndpoint. Packet data is still sent in the strPacket parameter.0) OnZigbeePacketIn OnZigbeepacketIn(strPacket. nClusterID. Example function OnZigbeePacketIn (strPacket. Returns None Parameters strPacket .Endpoint designated as the recipient of the data packet delivery." . string. nGroupID.3 . idClusterID. If using ZigBee Pro.dm.0. " c4.0.g_SequenceNumber) .Source Cluster library included within the Profile nGroupID .Profile associated with the data packet nClusterID . ndestinationEndpoint) Receives an unsolicited zigbee packet from the device or a response to a command that was sent.. All Rights Reserved Page 58 Version 1. Chartype .Example g_SequenceNumber=g_sequenceNumber + 1 strPacket = "0" .. Remarks The following parameters are ignored when using the Control 4 (Embernet) Zigbee stack: nProfileID nClusterID nGroupID nSouceEndpoint nDestinationEndpoint.0.Endpoint designated as the source of the data packet delivery.nProfileID.destinationEndpoint) print("OnZigbeePacketIn..Zigbee device group identification nSouceEndpoint . sourceEndpoint.. OnZigbeePacketSuccess OnZigbeePacketSuccess(strPacket. nClusterID. nSourceEndpoint.Profile associated with the data packet nClusterID .destinationEndpoint) print("OnZigbeePacketSuccess.Endpoint designated as the source of the data packet delivery.Zigbee device group identification nSouceEndpoint .Profile associated with the data packet nClusterID .strPacket) end OnZigbeePacketFailed OnZigbeePacketFailed (strPacket. nClusterID. idProfileID. If using ZigBee Pro. nProfileID .Source Cluster library included within the Profile nGroupID . All Rights Reserved Page 59 Version 1. Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation. idGroupID. all data (including strPacket) must conform to ZigBee Pro format. nDestinationEndpoint .ZigBee supported user data received from the ZigBee device.ZigBee supported user data received from the ZigBee device.3 .7. Packet data is still sent in the strPacket parameter. nProfileID . nSourceEndpoint. idClusterID.Endpoint designated as the recipient of the data packet delivery. nDestinationEndpoint . sourceEndpoint. Returns None Parameters strPacket ..Source Cluster library included within the Profile nGroupID .". nGroupID. Example function OnZigbeePacketSuccess (strPacket.Endpoint designated as the source of the data packet delivery. Remarks The following parameters are ignored when using the Control 4 (Embernet) Zigbee stack: nProfileID nClusterID nGroupID nSouceEndpoint nDestinationEndpoint. Returns None Parameters strPacket . ndestinationEndpoint) Return function upon the successful delivery of a data packet.Endpoint designated as the recipient of the data packet delivery. nGroupID. nProfileID.Zigbee device group identification nSouceEndpoint . ndestinationEndpoint) Return function upon the unsuccessful delivery of a data packet.nProfileID. c4i file as seen in the example below: Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation. all data (including strPacket) must conform to ZigBee Pro format. The encoded firmware data string information should reside at the beginning of the .Remarks The following parameters are ignored when using the Control 4 (Embernet) Zigbee stack: nProfileID nClusterID nGroupID nSouceEndpoint nDestinationEndpoint. Encoded BLOB data in the . UNKNOWN strVersion strSkew Remarks This gets called when the Online status of a Zigbee node changes. sourceEndpoint. strVersion. REBOOT. strSkew) print("Zigbee Status Changed: " . idProfileID.destinationEndpoint) print("OnZigbeePacketFailed. idGroupID. ONLINE.c4i file DriverWorks supports the ability to store binary firmware data within the . If using ZigBee Pro. strStatus) gZigbeeStatus = strStatus end Updating Zigbee Device firmware Using DriverWorks Note: Zigbee functions will not be applicable until system software release 1. strSkew) Parameters strStatus OFFLINE.. This data must be Base64 encoded. strPacket) end OnZigbeeOnlineStatusChanged OnZigbeeOnlineStatusChanged (strStatus. Example function OnZigbeePacketFailed (strPacket. strVersion.3 .c4i file Functions to handle device requests and delivery of the firmware data.0. idClusterID. Packet data is still sent in the strPacket parameter.8. All Rights Reserved Page 60 Version 1. Example function OnZigbeeOnlineStatusChanged (strStatus. This functionality has been implemented using two new features: • • Support of encoded BLOB data (firmware) within the ." .c4i file..7. The ability to use DriverWorks drivers to update firmware on ZigBee devices is now supported. 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 rights reserved.<devicedata> <copyright>Copyright 2008 Control4 Corporation. This allows the driver to ensure that it is the only driver updating a device at any time. The OnReflashLockGranted function is called by Director when the driver has permission to update the firmware on the device. This ensures that device firmware updates don't overload the zigbee network.7. Example C4:GetBlobByName("Blob1") Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation.</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. Returns Binary data from . This is required so that Director can manage multiple Zigbee drivers so that only one driver will be allowed to update at a time. For example. this requires a copy of the firmware data within every loaded driver used by the device. The functions delivered in this SDK support this. All Rights Reserved Page 61 Version 1. the data is sent accordingly to the device. Firmware request Functions . if 15 devices use the driver. Drivers that wish to update their device’s firmware should do it in a sequential manner. Parameters strName – Name of the Binary Large Object to retrieve from the .c4i file. It is possible to place the BLOB data in the Lua section of the driver.c4i file. it will be necessary to maintain 15 copies of the firmware update data loaded in memory. If an update is available.3 . However.When a device requests a firmware update (the version of the firmware on the device is older than the firmware the driver has). All reflash traffic is sent to the device using standard SendZigbeePacket and OnZigbeePacketIn commands/functions as described above. the driver should request a 'reflash lock' via RequestRefreshLock. 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). KeepReflashLock C4:KeepReflashLock() If a driver takes longer than a minute to upload the firmware data to the device. Control4 DriverWorks SDK – API Reference Guide Copyright 2009 Control4 Corporation. Ensures that the driver is the only one currently granted permission to update the device.3 . This request will maintain the reflash lock while updating. If a driver does not call KeepReflashLock. OnReflashLockRevoked OnReflashLockRevoked() Function called by Director when a driver loses permission to perform a device update. The driver receives permission when it receives the OnReflashLockGranted call. the Reflash Lock will be revoked after approximately one minute. it should call C4:KeepReflashLock.7. ReleaseReflashLock C4:ReleaseReflashLock() Function to terminate the request for firmware data upon completion of update. All Rights Reserved Page 62 Version 1. OnReflashLockGranted OnReflashLockGranted() Function called by Director when a Zigbee device grants communication access.RequestReflashLock C4:RequestReflashLock() Function that requests permission of Director to update the device.
Copyright © 2024 DOKUMEN.SITE Inc.