TRIKLITS Software Driver

The driver software is available as a ZIP file.

Download the driver software (v1.3 2006-10-24)
added SD Controller support
v1.2 2006-09-27
added MAC USB4 support (OS 10.4.7 seems to work, older might not)

File Summary

The driver software ZIP archive contains a number of files. These files and programs were compiled under the Cygwin package on Windows XP. The programs are all standard C code and should be easily portable to other environments.

In the top directory you will find some sample effects named flash, wheel, sequence, and off. Flash turns all the lights on red, then blue, then green, then white, then off, and repeats for 15 seconds. Off just turns off all the lights.

In the CONF subdirectory you will find a few more files. Main.c, config.h, Common.c and common.h are some common subroutines you might want to use when writing effects. However, the most important file is out_file.c.

The out_file.c module contains code that takes an array of RGB values and sends them to the Triklits. It is a bit complex as it knows how to talk to Triklits through various devices such as the USB and Ethernet interfaces.

Configuring the driver

Connect to the CONF subdirectory.

First, edit config.h, and set SX to the number of Triklit strings you have (or the number of possible strings on the interface). This file is mostly used by the demo pattern generating code. It configures the size of a global array called v that is used as the RGB "frame buffer".

Now edit the driver code out_file.c. The driver comes mostly configured for the USB-4 interface, but you will probably need to modify a few settings. These are all configured with "#define" statements near the top of the file.

The driver can talk to a file (or COM port), or to an ethernet interface. This is selected by picking one of the lines "#define OUT_FILE" or "#define OUT_NET" and commenting out the other.

If you are using the USB4 interface pick OUT_FILE. After you have attached it to your system you will need to look at the Hardware Manager and find out what COM port it was assigned to. Then you will need to set the "#define OUT_NAME_FORMAT" to the appropriate COM port name. For example, for COM10 you would set:

#define OUT_NAME_FORMAT "/dev/com10"        // define this to be COM port of USB4 interface

A little farther down you will find this set of #defines:

//maximum number of light strings
#define OUTPUT_STRINGS            4    // must be <= (OUTPUT_DEVICES * OUTPUT_INTERLEAVE * 8)
#define OUTPUT_DEVICES            1    // number of controllers
#define OUTPUT_INTERLEAVE         1    // number of driver boards per controller
#define SLOTS                     24   // number of lights on a string
//uncomment the line below for 4-port USB interface
#define OUTPUT_4BITS                 // pack 4-bit nibbles into bytes

For the USB4 interface, leave all these settings alone. You are always sending data for 4 strings at a time, whether or not they are actually attached to the interface.

For the ethernet interface, set OUT_NET instead of OUT_FILE.
Set OUTPUT_STRINGS to 8 times the number of driver boards you have.
Set OUTPUT_DEVICES to the number of ethernet controllers you have.
Set OUTPUT_INTERLEAVE to the number of driver boards attached to the controller. For the ethernet interface, this number must be rounded up to the nearest power of 2 (so set it to 1, 2, 4 or 8).
Make sure you comment out the OUTPUT_4BITS definition

Once you have modified this file, run the "make clean" and then "make" to compile it and produce an out_file.o module. You will then link this into your program so you can call the output functions.

Running the demo effects

After compile the driver code above, connect to the main directory where the effects are located. Do a "make clean" and then a "make" command. This will recompile the effects with the reconfigured driver. Now you can run any of the .EXE files that were generated, such as flash, wheel, sequence and off.

Using the driver

Call TL_init() to initialize the driver
Call TL_open() to open the output device
Call TL_frame(array,time) to send data to the lights
Call TL_close() when done

The output driver works like a graphics frame buffer. You generate a frame of RGB data for every single light, then ask TL_frame() to update all the lights with the new frame. You also tell TL_frame() how long to display that frame, it will round up to the closest available frame time (about 19 milliseconds) and return the number of milliseconds the frame was actually displayed for. If you ask for a display time under 19msec, the frame is displayed once. If you ask for say 190msecs, the frame is sent 10 times.

TL_frame() takes a 3-dimensional array of RGB values to display. How it maps the values from that array to which physical light on which string is done by the function ssmap(). By default ssmap() is a simple mapping into the array. For example an array v[X][Y][Z] of RGB values is assumed to have X strings of lights, Y number of lights per string (24), and Z always equal to 0 (1 dimension).

The reason for this mapping function is to let you build more complicated lighting displays. For example, you could build a 3D cube and have the RGB values stored in an array v[8][8][8]. You can then modify the ssmap() function to figure out where in the cube a particular string/light is located. For example, v[0][0][0] might map to string 0, light 0. But v[0][1][0] might map to string 2, light 15.

Hopefully, the included examples will be enough to get you started.

This is also a good place to tell you about RGB values. The RGB values used by the Triklits are not the same as that used on a computer system. Please read the info about Colors and Power back on the main web page. For the most saturated colors we suggest only turning on 2 of the 3 LEDs at a time. Also pay attention to the maximum recommended power level for each light. A simple rule would be to keep the total of the 3 RGB values under 512.

HOME