Persistent data in the Programmer

When running in User and respectively in Kiosk Mode, an e:cue Programmer show is considered as persistent with unchangeable data. This is for safety reasons, in case that you want to grant users limited control over a lighting installation (in most cases via the Action Pad) but nothing more than that. Nevertheless, there might be the need to save some status information even in User/Kiosk Mode. As an example you control several rooms using Action Pad faders and you want the lighting values to persist after system shutdown/reboot without making changes to the show file itself.

The e:script language features a set of commands to write variables into an XML file for later use. First, you have to use XmlBegin to specify a filename and if you want to read from or write into the particular file. The next step is to use the command XmlExchange to read/write certain variables (this depends on what you specified with XmlBegin). To close the file operation, call XmlEnd. You can use XmlExchange multiple times inside such an XmlBegin-/XmlEnd block to read or write multiple variables from or into one file.
Please note that a write operation will completely erase the previous contents of the given file. So be careful to use the correct filename. If no file with the given name exists, a new file will be created.

As a filename, you can either specify a simple filename (in that case the file will take its place in the Programmer’s main directory) or a complete path along with the name of the file. To use the My Documents folder of the current Windows user you can write $(MyFiles) followed by subfolders and the filename. When specifying a complete path, you must not use single backslashes as a separator because these are interpreted as control characters. You can either use a double backslash or a single slash as a separator.

Masters as XML

Masters as XML

Fader values exist in the file and of course, are already declared inside the macro. In the special case when you read out an array, the array that was declared has also to be of exactly the same size as the array that was saved into the file before.

When you write a variable into a file, the particular variable must exist, of course. The command XmlEnd finishes a read/write operation. Please note that a write operation will only occur when you use XmlEnd.

When saving masters as values, 4096 relates to 100% and indices of masters begin with 0.

Example: Saving and recalling fader values

To save the position of Action Pad faders we have to query the status of the associated Versatile Masters and save the particular values into a file.

Assume that for our purpose it is sufficient to save the values of the first 12 Versatile Masters. The corresponding code is very short and easy:

int vmaster[12];
int i;
for (i = 0; i < 12; i++)
{
   vmaster[i] = GetSpeedMaster(i);
}
XmlBegin(“$(myfiles)\\vmasters.xml”, 1);
XmlExchange(vmaster);
XmlEnd();

As you can see, an array named vmaster is declared in order to hold the values of the Versatile Masters. The values are received using the command GetSpeedMaster inside a for loop. The contents of our array are then all together written into the file vmasters.xml inside the current users My Documents directory. What we have to do now is to write a macro that restores the Fader values from the XML file. This is quite as easy and looks very similar to our previous code snippet:

int vmaster[12];
int i;
XmlBegin(“$(myfiles)/vmasters.xml”, 0);
XmlExchange(vmaster);
XmlEnd();
for (i = 0; i < 12; i++)
{
   SetSpeedMaster(i, vmaster[i]);
}

We first read out the contents of our XML file (note the 0 as parameter for XmlBegin) into the array. These values are then applied to the particular Versatile Masters using the command SetSpeedMaster.

Using a function for complex data exchange

For simple variable storage and restore operations involving only a few variables, the example above works just fine. However, if you want to exchange a big set of variables, maybe even several times, it comes in very handy to write a function for the data exchange operation. This simplifies the code and prevents errors like forgetting a variable in an exchange operation as well. The following macro code shows an example function exchanging some sample variables:

function DataExchange(int do_save)
{
   XmlBegin(“vars.xml”, do_save);
   XmlExchange(int1);
   XmlExchange(int2);
   XmlExchange(int3);
   XmlExchange(array1);
   XmlExchange(string1);
   XmlExchange(string2);
   XmlEnd();
}

The above function DataExchange has one parameter named do_save. This parameter specifies if you want to save or load the particular variables. As for both kinds of operation the same function is used, it can never occur that a variable is forgotten. To save the set of variables specified inside the function, call the function as follows:

DataExchange(1);

To restore a set of saved variables, write:

DataExchange(0);

Email for you

Since early versions of the LAS it is possible to send email via e:script. Up to version 6.0 this email distribution was handled with an e:cue server as gateway. From LAS 6.0 SR1 on a direct SMTP interface is available to send mail. Sending an email is helpful when systems run unattended or headless, so there is no way to alert somebody if something strange is going on. You could, for example, combine the script for RDM checking with this  email function to notify somebody about problems with some fixtures.

In any case you need access to an SMTP server as a MTA.

Programmer SMTP configuration

Programmer SMTP configuration

First of all  set the necessary parameters in the Application Options of the Programmer:

  • Name: Set the sender’s name for the FROM field.
  • Email address: The sender’s email address, the FROM address.
  • Server name: The address of the SMTP server
  • Port: The mail port of the server, depends on connection type and is set to values when the connection type is defined. Most servers accept  port 25 („smtp“), newer servers also port 587.
  • Connection security: The security type of the connection. If only notifying about something basic connection security should do.
  • Authentication method: The encryption level for the connection.
  • User name: The user name used to login to the SMTP server.
  • Password: The password for the SMTP server login.

After configuring your SMTP connection you can send email from e:script:

// Generate mail content
int hMailObject = CreateMail(“user@example.com”, 
          “Hello World!”, 
          “The quick brown fox jumps over the lazy dog.”);
AddMailTo(hMailObject, “user@example.com”);
// Schedule mail and remember the message queue ID
int nMessageQueueID = SendMail(hMailObject);
DestroyMail(hMailObject);
// Wait for message being processed
RegisterEvent(Frame, OnFrame);
Suspend();

function OnFrame()
{
   if (MailIsValidID(nMessageQueueID) == 0)
   {
      alert(Unknown mail ID!\n”);
      exit; // shutdown suspended macro event
   }
   // Is message being processed?
   if (MailIsProcessed(nMessageQueueID) == 0)
   {
      printf(“Waiting for message being processed ... \n”);
   }
   else
   {
      printf(“Message was processed.\n”);
      // Is a response available?
      if (MailIsResponseAvailable(nMessageQueueID))
      {
         // Check if sending was successful
         if (MailIsTransmissionSuccessful(nMessageQueueID) == 1)
            printf(“Sending mail successful.\n”);
         else
            alert(“Sending message failed!\n”);
      }
      exit; // Shutdown suspended macro event
   }
}

More MIDI, please

There are some other new features in the LAS 6.1, one is an addition in two places to simplify the use of MIDI sources for Masters and Triggers in the Programmer. It is a learning function which listens to a MIDI channel and recognizes channels and channel values. Not that complex, but very helpful.

MIDI for Masters

MIDI control for Masters

MIDI control for Masters

Either in the Master’s context menu (right mouse click) or in the Master’s properties dialog (Grand and Versatile Masters) there is a Learn entry or button. For Masters, only MIDI Control Changes are recognized, and they are only possible for Masters, not for Faders. Simply click the Learn button or select Learn from the context menu, move or turn the control knob or fader on a MIDI keyboard or MIDI console and the right channel  parameters get inserted as MIDI source for this Master.

There is an additional checkbox in the dialog for feedback. Feedback means that in case of a change of this Master in the Programmer (and even in the Action Pad!) the Programmer sends out MIDI control changes to the physical MIDI source to reflect the change on the fader. Perfect for MIDI consoles with motor faders.

Now MIDI for Triggers

MIDI Learn for Triggers

MIDI Learn for Triggers

Using MIDI notes from a keyboard as Triggers in the Programmer is not new. But this gets much easier with the MIDI Learn button in the definition dialog for the Trigger. Open the Trigger list, add a trigger and press MIDI Learn. Now use a key on the connected MIDI keyboard or a button on a MIDI keypad and the note will be used as MIDI value to trigger the Action. Define the proper Action and you’re done.

Famous last words

When ever using MIDI sources, do not forget to insert a MIDI driver in the Device Manager of the Programmer. Open the Device Manager, choose to add a driver and use the Generic MIDI driver for MIDI cards or USB-to-MIDI adapters. The configuration of the MIDI device usually gets done by an automatic Windows driver update.

Autotext and RDM

One of the most helpful features in the Programmer is Autotext. But what is Autotext?

An ancient feature

Autotext was implemented in a rather early version of the Programmer and realizes access to internal data and parameters of the Programmer. This can be system time and date, astronomical times like sunset or twilight, even network parameters, cuelist parameters or Versatile Master names and values. The most prominent use of Autotext  is in the Action Pad. In a textfield, for example, use the expression <nicetime %X> and the Programmer will substitute this expression with the systemtime. <master 1 name> will show the name of the Versatile Master #1. A complete list of Autotext parameters can be found in the LAS Advanced System Manual, for free download from the Traxon or e:cue website.

The next big step

With LAS 6.1 it is possible now to access the RDM subsystem of the Programmer as Autotext. In this way you can show fixture data like lamp lifetime, up-time and all other RDM values and parameters in the Action Pad. And these are not static values, but updated all the time while the fixture runs RDM communication. The best way to see this is to watch the RDM timestamp of a fixture. To insert RDM Autotext in a textfield is very simple, because there is an interactive method to do this. You can, but you must not create the Autotext by hand.

Autotext sources

Autotext sources

In the Action Pad create a textfield. Double-click the created field or select Properties from the element’s context menu (right mouse button). The properties dialog has a button for Autotext. Clicking the button, a subselection gets displayed where you can choose the Autotext source. Here you can see the many sources to Autotext. For RDM select RDM and Create RDM Autotext. The RDM Autotext dialog opens.

RDM parameter dialog

RDM parameter dialog

In the RDM dialog you now can select the fixture and subdevice, as well as what sensor or parameter will be used. Click the varoius areas in the dialog to define the Autotext source from the RDM vaue stream, the click OK.

This will insert the proper Autotext definition in the textfield of the Action Pad.

Do not forget to enable Autotext substitution for the field in the element properties of the field. Otherwise you will only see the Autotext definition instead of the real value.

Action Pad and RDM

Action Pad and RDM

That’s all. You now have dynamic, realtime RDM data in your Action Pad page.

A complete description of RDM and Autotext is in the LAS Advanced System Manual for the LAS 6.1, available in the product page for the LAS in the Traxon website, and a complete description of the LAS as LAS System Manual (after release of LAS 6.1, of course).

Reading RDM with e:script

RDM (Remote Device Management) is a remote management protocol on top of DMX and allows bidirectional communication with fixtures. You can read system values and status, and depending on the type of fixture you can set DMX addresses and other parameters. The Programmer of the Lighting Application Suite has a complete implementation of ANSI E1.20, Remote Device Management on board. With the coming LAS 6.1 you can read RDM values in fixtures and use them as Autotext (similar to time, astronomical times, system parameters) in the Action Pad.

You can also use the RDM API in the Programmer in e:script, which allows very flexible and custom-specific functions. Here is an example script how the RDM API can be used to check fixture temperatures.

// --------------------------------
// checkTemperature script comment
// --------------------------------

int sensorId = 7; // id of temperature sensor
int temperatureMax = 80000; 
              // commonly given in m°C so 80000 is 80°C
string deviceId;
int li = CreateRdmDeviceList();
int deviceCount = GetRdmDeviceCount(li);

// iterate all rdm devices
int i;
for (i = 0; i < deviceCount; i++)
{
     deviceId = GetRdmDeviceId(li, i);
     printf("deviceId = %s\n", deviceId);
     checkTemperature(deviceId);
}
DestroyRdmDeviceList(li);

// checks if temperature value from sensor 
// is within allowed range
function checkTemperature(string deviceId)
{
     int t = GetRdmSensorValue(deviceId, sensorId);
     printf(" %s %d\n", deviceId, t);
     if (t > temperatureMax)
     {
          // do something if temperature too high
          alert("Warning: temperature of device %s is > %d!\n", 
                                   deviceId, temperatureMax);
     }
}

Getting DMX engines online

The DMX engines Butler S2 or Butler XT2 sometimes seem to cause trouble when trying to connect them to the LAS (Lighting Application Suite) server. In nearly all cases the connection between Butler and server is not correct, IP addresses are duplicated or wrong cable used. For this reason here a more detailed description.

Use the right cables and switches

System diagram

System diagram

Do not connect server and engine with an Ethernet cable directly. Use an Ethernet switch in any case, like shown in this picture. The Ethernet switch may have DHCP enabled or not, as nobody sends DHCP requests, it does not matter.

Even an Ethernet cross cable will not work in any case, in general avoid cross cables as they may cause damages, e. g. in networks with Power-over-Ethernet. Be sure not to use any cross cable at all, they are devil’s work.

RJ45 pairing

RJ45 pairing

You can recognize a cross cable when laying the two plugs together. A cross cable reverses the pinning on the two sites, the standard RJ45 cable does not, like in this picture. This is a general RJ45 CAT5 Ethernet cable without crossing. The red wires are on the same side, the pinning is identical on both sides.

Connect all Butlers over this switch to the server running the Programmer or Patchelor.

Do not mix networks

Programmer - Appl Options

Programmer – Appl Options

Use a separated, closed network segment for your lighting control. Do not use enterprise or open networks. The best way is to use a dedicated Ethernet card in the server, a switch and the Butlers. Be sure to assign the right network card in the Programmer in the Application Options, if there are more than one in the server.

Use the network IP range 192.168.123.*, assign a unique IP address to the server network interface, like 192.168.123.10 or similar, this is done with the Windows Control Panel in the network section. Be sure that the server IP address is really unique and does not conflict with any UMTS USB/WLAN sticks or WLAN adapters. Build a clear address structure in your network, this makes it easier to separate address ranges, like

  • 192.168.123.1 = do not use, reserved for factory state engines!
  • 192.168.123.10 – 192.168.123.20 = servers
  • 192.168.123.100 – 192.168.123.199 = engines
  • 192.168.123.200 – 192.168.123.255 = any other network devices

The hidden enemy

Be sure that all firewalls are switched off. As the e:net system is a closed network, no firewall is necessary, neither in hardware nor in software. Firewalls in Windows 7 get switched off via the Control Panel.

Set proper IP addresses

When arriving from the factory, the Butlers have an assigned IP address 192.168.123.1, always. To connect more than one Butler be sure to have only one of them connected to the network, otherwise more than one system will try to communicate over 192.168.123.1, which will not work. Never connect more than one factory-state Butler to the network.

Programmer - Network

Programmer – Network

If all is well, the Butler should become visible in the Network tab of the Programmer now. If this happens, the Butler is recognized and the network seams to work properly.

Now assign a unique and new IP address to this engine, to do so, click on the device in the network tab line, here “Butler XT2” and the device configuration dialogue opens. In this dialogue a new IP address can be given to the Butler.

Device configuration

Device configuration

Enter a new IP address for this engine, click OK and the new configuration will be transferred to the Butler. Now you may connect the next Butler to the network and continue to set up all addresses.

Be sure that every engine has a unique IP address, also the server!

Even better with the Butler XT2

Butler XT2 standalone config

Butler XT2 standalone config

The Butler XT2 has a build-in webserver, connect a PC with a webbrowser instead of a server with the Programmer. Or use a WLAN router to be connected with the Butler XT2 and access the Butler XT2 with PC or mobile devices with a webbrowser.

 

 

 

butler_xt2_webconfig_mainStart the web browser and enter the IP address of the Butler XT2 in the address field of the browser, in factory state 192.168.123.1 (if the Butler was configured differently before and you do not know the IP address, perform a Reset to factory settings).

Butler XT2 password

Butler XT2 password

You can now see the current settings and  parameters.To change the configuration, click the upper Configure button and enter the password.
The default password is “ecue”, it can be changed during configuration.

Set the parameters and click Submit to save the changes. This makes the basic configuration of several Butler XT2s much easier.

Code examples from the Advanced System Manual

LASM

LASM

The e:script coding examples from the Advanced System Manual für the Lighting Application Suite cannot be copied via Copy/Paste from a PDF file. PDF files are coded in UTF-8 code format, while the macro editor of the Programmer only understands ASCII. For this reason we have made the files available as standard text files with a .cpp extension here:

www.traxontechnologies.com | Downloads | e:cue Software | Support Files