Variables

So far we’ve learned about how the show controller organizes sequences and events to make cool stuff happen (light shows, virtual snow, etc.). We saw how to configure our device and get connected to it to run a script. We ran a few examples in Live Mode and saw the output from the devices in RealTime, which is neat.

In order to take our scripts to the next level, we often will need to store data for use either in another event, another sequence, or by another device. Like all other programming systems, WinScript and the controllers support variables – and there are two different types. Let’s take a look at WHY that is.

The first type of variables are “Script” variables that are specific to the script that’s running. They are available for me to use anywhere that their particular data type is supported in the script. The data types can be any of the following:

Boolean
Date/Time
Decimal
Device*
Integer
LCDString
Percent
String
Timecode

Most of these will be familiar if you’ve programmed in other environments or languages before, but we’ll go over them quickly.

Boolean is a binary data type – either on or off, 1 or 0, etc.
Date/Time is exactly what it sounds like, in the format MM/DD/YYYY 12:34:56 in 24-hour format (no frames on Date/Time data types)
Decimal is a numeric value with the ability to support fractional numbers (parts after the decimal point)
Device is a reference to a device from the list of Devices. This is most commonly used with Device Arrays, which we’ll get into later in the course.
Integer is a numeric value for whole numbers only.
LCDString is a specially formatted string for display on the front LCD panel.
Percent is an integer value that automatically includes support for the formatting with the percent symbol. Useful for relative things like volume, panning left/right, light intensities, etc.
Strings are any Unicode text characters, wrapped in double-quotes.
Timecode is for tracking sequence time, SMPTE timecode, or other relative time values with frame-level accuracy. The number of frames depends on the setting in the controller’s device configuration.

Variables are incredibly useful and powerful storage for data that we need to use elsewhere in our systems. They can be passed from device to device, they can be set in multiple places and read back in multiple places (though that should be carefully planned so you don’t change a value unexpectedly!).

SO you may be asking yourself, “Self, why are their Variables and Device Variables.”

Well, I’m glad you asked, Self. Device Variables are just variables that are specific to a particular device. They are the resources that device uses to keep track of things like status, errors, MAC addresses, lamp hours, motor homing status, and many many more. Every device has SOME number of device variables that are available to use. Some require that you poll the device to populate them, and others are populated automatically. Looking at the list of V16X device variables, we see things like “Date” which is the current date and time on the show controller, DeviceName, LTC (if you’re using SMPTE/EBU), broken down elements of the date-time and time, Sunrise and Sunset (very useful if you’re running lighting control for exterior illumination) and more. If I were to look at the device variables for an A/V Binloop Uncompressed, they are completely different and appropriate for that device type. Same with a QSys Core, a Weigl ProCommander AX or a Christie Boxer 4K30. The device variables are defined by the product file and made available via methods that either automatically or manually populate those values. Some devices allow you to add Device Variables and populate them dynamically like the Allen-Bradley PLC integration – I can add Tags that will be read/written to the PLC automatically on a recurring basis.

Defining script-level variables is easy – choose Variables from the Resources menu and click Add. Choose your variable name, data type, and initial value, and you’re all set. You can use the wizard if you prefer – this is particularly helpful if you want to build arrays of variables. Let’s say that you need to keep track of 50 strings that reference 50 different ride vehicles’ statuses. In the wizard, I choose Array, type in my Array size, and choose whether or not it’s zero-indexed. In this example, zero-indexed means that the numbers that track which member of the array you’re looking at either start with 0 and run through 49 or start with 1 and run through 50. For local variables, you can do it, however, makes the most sense for your application. For some integrations (PLCs in particular), they will nearly always be zero-indexed. Check with your device’s manufacturer to see how they handle arrays of variables.

A word on naming conventions – like standards, there are so many great ones to choose from. Pick one you like and stick with it. It’s helpful to identify the datatype in your variable name so that you aren’t fumbling around for it later (did I call this integer FuzzyNumber or NumberFuzzy? If it’s called i_FuzzyNumber or intFuzzyNumber, you’ll find it a lot faster).

Variables will show up in your script where they are appropriate to be used. Some events limit the types of data types for various parameters – so if a parameter can only accept a string, you’ll only see strings in the dropdown list of available options. If it only supports integers, you’ll only see those. You’ll notice that in the parameters on Events, I can either choose from values that are available as Variables or Device Variables or I can type in values that I want to use. If I type in values, those are called Literals – a fixed value. Literals are often okay, but it’s good practice to avoid Literals if you might ever need to change a value programmatically and switch it out for a variable instead. As an example, if we wanted to allow the user to configure the delay in our snow sequence, we could have two variables that can be changed from a user interface via ShowTouch. Literals will limit your flexibility but are occasionally appropriate. In computing, we often call unexplained literals “Magic Numbers” – because when we go back to look at it, we have no idea why we (or a programmer who preceded us) chose a particular number – why did I choose 9 frames as the maximum instead of 10? Or 15? It just sounded good at the time, I guess. MAGIC!

This lesson seems shorter than many of the rest, but don’t be fooled. Variables and Device Variables are the magic that lies underneath all of the most powerful show control programs that are running out there today. Between the variables and the use of LOGIC, which is what we’ll tackle next, you can handle nearly any creative challenge that comes your way.