What is DriverWorks?

Document created by cdnadmin on Jan 25, 2014
Version 1Show Document
  • View in full screen mode
This document was generated from CDN thread

Created by: Ryan Erickson on 10-08-2012 11:22:01 AM
DriverWorks is the API used by installers / developers to create protocol drivers for 3rd-party devices.
DriverWorks drivers are written in a language called Lua.  Lua is a powerful, fast, lightweight, embeddable scripting language, that Control4 has embedded into it's driver architecture.  The use of Lua allows development of drivers without having to compile drivers within Control4's C++/C# development environment.
DriverWorks drivers are typically Protocol drivers, which translate between proxy drivers and a device's protocol.  In order to do that, drivers typically use functions from the Proxy and Network or Serial interfaces.
A DriverWorks driver sends and receives messages from the proxy through the DriverWorks Proxy interface:
ReceivedFromProxy(idBinding, strCommand, tParams)
C4:SendToProxy(idBinding, strCommand, tParams)
When a proxy sends a message to a DriverWorks protocol driver, the driver's 'ReceivedFromProxy' function gets called.  Passed into ReceivedFromProxy are 3 parameters, a binding ID, which tells which proxy sent the message, a string command, and a Lua table of parameters.  Here's a simple example of a ReceivedFromProxy function declaration:
function ReceivedFromProxy(idBinding, strCommand, tParams)
  print("ReceivedFromProxy[" .. idBinding .. "]: " .. strCommand)
  if (tParams ~= nil) then
    for k,v in pairs(tParams) do print(k,v) end
This example prints out the command and all parameters received from a proxy into the 'Lua Output' window in ComposerPro.
The SendToProxy call is used when the protocol driver has notification information (state change) to send to the proxy.  Here's a simple example of SendToProxy, sending information that the level of a particular light has changed to 33:
C4:SendToProxy(5001, "LIGHT_LEVEL_CHANGED", {LEVEL = 33})
DriverWorks provides a simplified method for sending and receiving network (TCP/UDP) data.  The connection for that data is transparent to the driver.  The driver creates a network binding in the XML portion of the driver, and then uses the following network functions:
ReceivedFromNetwork(idBinding, nPort, strData) -- Data has come in on the network binding / port
C4:SendToNetwork(idBinding, nPort, strData) -- Send data out the network binding / port
Data sent and received through the network interface functions is 8-bit safe, and could be binary data.
DriverWorks also provides a simplified method for sending and receiving data over a serial (RS-232) connection.

Similar to the Network interface, a serial binding is created in the XML portion of the driver, then the driver uses the following serial functions:
ReceivedFromSerial(idBinding, strData) -- Data has come in on the serial binding
C4:SendToSerial(idBinding, strData) -- Send data out the serial binding
Data sent and received through the serial interface functions is 8-bit safe, and could be binary data.
 UI <----> Proxy Driver <----> Protocol Driver <----> Device
(Navigator)      (Light)           (DriverWorks Driver)   (3rd-party light)
* A user presses 'Toggle' for a light on the Navigator UI.
* A 'TOGGLE' Proxy command gets sent to the Light proxy driver
* That command gets sent on to the protocol driver, whose 'ReceivedFromProxy' function gets called.
* Inside the ReceivedFromProxy Lua code, the driver translates the TOGGLE command into the device-specific protocol, and sends it to the device using C4:SendToNetwork.
* The device toggles, which changes it's light's state.  The device sends a message to the protocol driver over the network.
* The Protocol driver's 'ReceivedFromNetwork' function gets called.
* Inside the ReceivedFromNetwork Lua code, the driver parses the protocol driver's message, retrieves the light level, and sends a notify to the proxy, using C4:SendToProxy.
This is the major part of what a typical DriverWorks driver does.  It receives messages from proxies, and sends them on to devices.  It receives messages from devices, and sends them on to proxies, translating the messages each way.
More information about Lua can be found here:
The DriverWorks SDK can be downloaded from the Cisco Automation Solutions 'Getting Started' page: http://developer.cisco.com/web/as/start