™ ™ NetStreams DigiLinX ™ Writing StreamNet Device Drivers
Copyright Title: Writing StreamNet Device Drivers Document Number: 020014A Original Publication Date: August 14, 2006 Revision Date: February 27, 2007 All rights reserved. Copyright © 2007 by NetStreams. All brand names, product names, and trademarks are properties of their respective owners. 3600 W. Parmer Lane, Suite 100 Austin, TX 78727 USA Phone: +1 512.977.9393 Fax: +1 512.977.
Contents Chapter 1: Introduction ................................................................................................................ 1-1 Introduction to Lua .................................................................................................................. 1-2 Chapter 2: Activating Drivers within DigiLinX Dealer Setup .................................................... 2-1 Chapter 3: Handling Commands ........................................................................
Writing Streamnet Device Drivers aString = command.toNode .................................................................................................. 9-5 aString = command.toSubNode ............................................................................................ 9-5 aString = command.from ...................................................................................................... 9-5 aString = command.fromNode ....................................................................
Chapter 1 Introduction NetStreams® ships drivers for a variety of third party systems with the DigiLinX™ system. These drivers include Lutron® for lighting, Aprilaire® for HVAC, and GE Concord® for security. Custom installers can use these included drivers with a ControLinX™ to enable DigiLinX control of external systems. Sometimes, the specific needs of a job require DigiLinX to control different third party systems.
Writing StreamNet Device Drivers enables DigiLinX to control and be controlled by third party systems using a driver (seeFigure 1-2 ). Figure 1-2 Connecting 3rd Party Systems to DigiLinX Device drivers allow two-way interaction with third party hardware devices over a communications subsystem, such as RS-232. The ControLinX device includes the hardware needed to control external systems. The DigiLinX API is written in a programming language called Lua.
Introduction portion of the control system can be written in C/C++ while a minimum of device specific code is written in interpreted Lua. Minimal System Interface and Dependence – The Lua virtual machine and its associated parser/compiler are written in ANSI-standard C with a minimum system interface. There is no operating system (OS) interface defined at the script level.
Writing StreamNet Device Drivers 1-4 All specifications subject to change without notification. All rights reserved. Copyright © 2007 NetStreams Main +1 512.977-9393 / fax +1 512.977.9398 / Toll Free Technical Support +1 866-353-3496 3600 W. Parmer Lane, Suite 100; Austin, TX 78727 / www.netstreams.com.
Chapter 2 Activating Drivers within DigiLinX Dealer Setup Starting with version 1.70, DigiLinX Dealer Setup uses an intelligent lookup to determine if there are custom written drivers present in the system. In order to load custom written drivers through DigiLinX Dealer Setup, you must first create a new folder called “drivers” under your DigiLinX Dealer Setup install directory and copy the .lua driver file to this directory.
Writing StreamNet Device Drivers 2-2 All specifications subject to change without notification. All rights reserved. Copyright © 2006 NetStreams Main +1 512.977-9393 / fax +1 512.977.9398 / Toll Free Technical Support +1 866-353-3496 3600 W. Parmer Lane, Suite 100; Austin, TX 78727 / www.netstreams.com.
Chapter 3 Handling Commands The generation and processing of ASCII-formatted commands is central to the interaction between various StreamNet devices and hence, the heart of a device driver is how it receives and process ASCII commands. Figure 3-1 shows how the StreamNet commands flow.
Writing StreamNet Device Drivers Streamnet command is routed to the appropriate section of the Lua driver code Start No Is there a Control specific command handler? No Call Control default command handler Yes Yes Is the command addressed to a subnode? Call Control specific command handler No Is there a Control specific command handler? Yes Is there a subnode default command handler? Yes No Yes Is there a subnode specific command handler? Call subnode specific command handler Call subnode
Handling Commands if(cmd.command == “debug”) then … handle the #debug command end end If the command is specific to a particular subNode of the driver, it should be defined as an element in the subNode. It will be passed the subNode itself as its only argument. subNode.handle_set = function(self, cmd) if(cmd.params[1] == “heat”) then … handle the #set heat… command end end subNode.default_command_handler = function(self, cmd) if(cmd.
Writing StreamNet Device Drivers 3-4 All specifications subject to change without notification. All rights reserved. Copyright © 2007 NetStreams Main +1 512.977-9393 / fax +1 512.977.9398 / Toll Free Technical Support +1 866-353-3496 3600 W. Parmer Lane, Suite 100; Austin, TX 78727 / www.netstreams.com.
Chapter 4 Handling Communications Most device drivers will need some mechanism for talking to a controlled device. In the StreamNet system, that capability is provided by a generalized I/O Stream mechanism. A stream can be created using a string-based configuration string, the precise format of which depends on the details of the connection. Once the stream is created, the details of the underlying transport mechanism (such as RS-232, TCP/IP, or some other mechanism) is identical for all streams.
Writing StreamNet Device Drivers 4-2 All specifications subject to change without notification. All rights reserved. Copyright © 2007 NetStreams Main +1 512.977-9393 / fax +1 512.977.9398 / Toll Free Technical Support +1 866-353-3496 3600 W. Parmer Lane, Suite 100; Austin, TX 78727 / www.netstreams.com.
Chapter 5 Configuration As for any other StreamNet service, a StreamNet service with a Lua driver is configured by including an appropriate service tag within the config_current.xml file. In the case of standard StreamNet device types, the clause will be automatically generated, but in the case of custom device types, the clause may need to be manually generated.
