The Development Process

Introduction

---

There have been many calls on the NetStreams Forums site for more detail surrounding the How-To’s of developing custom DigiLinX drivers. As one of the early advocates of better documentation, more robust sample drivers, and enhanced developer support, I’ve decided to invest some of my own time trying to fill these gaps for the NetStreams community. I will put together what I have found on my own to be the basics of “Deving Digi” on this site. 

First, let’s discuss what it means to develop for the DigiLinX platform. At present, NetStreams offers no way to develop custom user interface screens. This restriction means that the user will have to interact with your driver through one of the existing screens. At this point, I have only seen third party driver examples that work with the generic, HVAC, and lighting interfaces.  The lighting and generic drivers are very similar. They provide buttons with text labels on them that the user presses to initiate events. The HVAC interface is a bit more advanced. It displays heating and cooling data, and allows for the adjustment of cooling and heating setback points and the manipulation of system and fan modes.

The ControlLinX

The DigiLinX suite has a device called ControlLinX which serves as a gateway for communication with external systems. The ControlLinX has an RS-232 port, an Ethernet port, voltage sensor inputs, and IR control. Third party automation, audio, and otherwise “smart” systems can be hooked up through RS-232 (or TCP/IP, theoretically), allowing the Digi system to issue commands to the device. A number of devices [PDF] are already supported by the system. However, the Digi infrastructure also allows one to write custom drivers and load them onto a ControlLinX to enable interaction with a system that is not already supported. These custom drivers for non-natively supported systems are the core focus of a series of posts I plan to write.

Getting Started

---

The first step in creating drivers for DigiLinX is to understand the process of writing, loading, and debugging your scripts. You will need three pieces of software to do this. The first is a piece of software built by NetStreams that is used to configure a DigiLinX system. As a developer, you’ll use the Dealer Setup Program to direct a ControlLinX to load and execute the code in your driver, and to configure that driver according to your particular installation. The download for this piece of software can be found in the dealer area of the NetStreams site. (Please don’t email asking me to send it to you – it’s a proprietary piece of software, and you have to be a dealer to access it.) The Dealer Setup Program installation package also provides a debugger that listens for trace messages that you can embed in your script. More on that later.

The next piece of software that you will need is the Lua interpreter. Grab the 5.1 interpreter for the Win32 platform. I assume that you’re developing on XP, since Dealer Setup only runs on that platform at this time. Extract the files into the folder of your choice, and make note of it’s location for use later on.

The final piece of software that you’ll need is a text editor. I recently made the move from TextPad to UltraEdit, and have been quite happy with the change. UltraEdit is a powerful editor with a number of advanced features for coders, and it also supports Lua syntax highlighting.  There are Lua-specific editors out there, but I personally feel more at home with UltraEdit.

UltraEdit Configuration

One nice feature of UltraEdit is that you can configure it to run the Lua interpreter against the Lua script that you’re currently working on. Doing so helps you validate that your code doesn’t contain syntax errors, though it won’t let you actually ensure that your script will work within the DigiLinX environment.

Under the Advanced menu choose Tool Configuration. Click Insert, then use the following information:
- Menu Item Name: Lua Interpreter
- Command Line: F:\ThirdParty\Lua\lua5.1.exe -l %n (adjust the path to your Lua interpreter)
- Working Directory: %p (this uses the path of the Lua script that you are working on) Under the Options tab, choose Dos Program and Save Active File. Under the Output tab choose Output to List Box and Capture Output

And that’s it! Now you can use Control + Shift +0 (assuming that was the first tool you installed in UltraEdit) to run your active Lua script through the Lua interpreter!

Load, Debug, Repeat

---

I will cover how to write Lua scripts for Digi in future articles. But first, let me identify how to load and debug your driver script. This process is what I have found works for me. There may be a better way of doing it – one that doesn’t involve restarting the ControlLinX with every new version of the script – but but I haven’t figured out how to do that yet.

Initial Setup

Ok, so you’ve got your script all polished and pretty, and you’re ready to load it into the ControlLinX to see if it actually works. The first step is to copy it to the magic directory where Dealer Setup can see it: C:\Program Files\DigiLinX Dealer Setup\drivers\. If you haven’t gone through this process before, you’ll have to create the drivers directory. Any *.lua files found in this folder can assigned as the driver file for the UI you assign to the ControlLinX. Let’s call ours MyDriver.lua. I’d suggest that you work on your MyDriver.lua file in a different location on your hard drive until you feel it’s ready to be loaded, then copy it to the magic drivers folder. This, along with a good source control system, will help eliminate those “oh crap, I just lost all my work” moments that can happen at the most inopportune times.

Load

Now that MyDriver.lua is in the magic drivers folder, click on the ControlLinX in Dealer Setup that will host your script. On the IR/RS232 Settings tab, you’ll see your driver file available in the Driver File drop down. 

Select it, click Apply, and you’re ready to load the file. Use Dealer Setup to send the new configuration to all devices, and after a reboot your driver will be running the interface assigned to the ControlLinX. As you make minor changes to your driver file, you’ll only need to push the configuration down to the ControlLinX, not all devices.

Ok, your driver is loaded. What do you mean it’s not doing working correctly? Time to debug.

Debug

As an experienced developer, you’ve anticipated the possibility that you might need to debug a problematic piece of code. Because of this, you’ve sprinkled appropriate debug() statements throughout your script. But how do you see them?  There is a debugging tool located at C:\Program Files\DigiLinX Dealer Setup\tools\ called NetDebugLogViewer.exe. This tool watches the network for Multicast data being sent from DigiLinX devices. The MyDriver.lua file has the following code:

setDebug(“all”, “off”) –Turns off all debug messages
setDebug(“WiredRight”, “on”) –turns on WiredRight debug category
for i=1, 5 do
    os.sleep(250) –introduce delay (1/4 second)
    debug(“WiredRight”, “Counting “..i)
end

A couple of quick tips on debugging/tracing. First of all, DigiLinX is very chatty, so when developing a driver for a specific device, I suggest setting the Message Level Minimum to “4 – Driver” and choosing a specific sender. This will restrict the messages to only those generated by your code on a specific device (with a few system level driver messages sprinkled in).

Have a look at the trace output from MyDriver:

Another item of note – it is possible that some of your trace messages might not make it to your trace window. This can be frustrating, especially since the process of loading a new version of the driver file involves some waiting while the ControlLinX reboots. Having your debugging messages disappear into the ether after waiting 15-20 seconds for your code tweak to be loaded can drive you nuts. I’ve found that introducing a delay into the execution of the code (as I did above with os.sleep(250)) will help, but you have to remember to remove these speed bumps before releasing your final code. I think this points to a problem in the StreamNet debugging libraries, but I’m not 100% sure. 

And Repeat

Ok, those are the basic steps involved in loading and debugging your DigiLinX drivers. Now you can repeat the cycle of edit code, push down configuration using Dealer Setup, and debug using NetDebugLogViewer. I haven’t mentioned it yet, but one obvious downside to all this is that you need at least a ControlLinX (and, in reality, a TouchLinX) in order to do any of this. That can be a good chunk of change to invest in a programming experiment. Hopefully some day NetStreams will release a virtual Digi emulator that developers can run on development machine that emulates a running DigiLinX environment.