Troubleshooting
When writing show control scripts, there’s a lot of small details that have to work just right for it to perform the way you want it to. An event out of time or some small bit of syntax that isn’t right will cause the symphony to sound out of tune. To prevent this and help recover from it once it does happen, WinScript offers a number of tools.
The built-in error checker is meant to make sure that your syntax is valid. That doesn’t mean it’s going to work flawlessly (again, the processor is VERY literal) – but it does mean that you don’t have any obvious missing elements (an If without an End If, missing parameters, duplicate IP addresses, etc.) Ideally, your program will compile without any errors or warnings, but if it doesn’t, WinScript will help you try to resolve the issues by pointing out the most likely cause of the issue. Let’s look at an example.
To run the Error Checker, I can either go to File/Save and Error Check or I can open the Errors tab from the View menu, and click Refresh.
This first example has two errors in it. The first is in Sequence “Reset Lights”, on Event #17, where we have an invalid parameter. If I highlight the row and click “Goto Error”, I’m taken directly to the Event row that has an issue, and it’s highlighted in red text. I’m apparently trying to turn OFF an input. That’s not going to work. I clearly meant output16 here, in context. I’ll correct that from the dropdown.
If we click back on errors, we can hit refresh and see that error drop off the list. Our one remaining error is in Sequence “Snow Plow”, on Event #1. Instead of clicking Go To Error, I can also just double click on the row and be taken to it. Here, I have an empty Parameter 2, which apparently is required for this event to work (it’s a conditional logic statement, so it has to compare V16X.Seconds to something!). If I’m not clear what the error is, I can hover over the field and it will tell me what’s supposed to be there. We’re using the “End If” variation, so I need to either put in a variable or a literal here, and then I’m golden. I’m going to put in 0 seconds so that the snowplow runs every time the V16 goes to a new minute on the clock. I can click back on Errors and see what every programmer always hopes for – a clean compile and NO ERRORS. W00t!
Once you get your script to compile without errors (or there are errors in that you are willing to accept for the time being), it’s time to push the show file to the controller and run it. This gives you a chance to test it, ideally with the full show equipment set connected, to see how everything works together. That’s where the next set of tools will come in handy.
Let’s start with the Log Message event. This allows you to write a message and push it out to the log from any sequence and any location in your code. You can put it inside conditional statements to make sure that the condition is evaluated the way you expected when it received certain input values. You can output variables with the Log Message so you can see what the values were when they passed through a particular sequence. You can send informational messages to the user about the state of the system or button presses in case there’s ever a dispute whether an event occurred or not (as the system powered on this morning? Yes, it was at 7:02 a.m.).
The logs show up in the Live Log. These logs are only visible while the system is powered on and are not stored anywhere other than operating memory. As soon as the controller is rebooted, all the live logs will disappear and be restarted. Only a certain number of events can be recorded and displayed onscreen.
Live Log is helpful with tracking sequences starting and stopping, watching your Log Messages come through, and watching for variables to change or device communication to pass by. You can actually see the raw messages passed back and forth between devices using the Live Log and a feature called the Watch List.
The Watch List is where you configure what variables and devices you want to trace the values of. On the Watches page, you will see the current value of those variables, and on the Live Log page, you’ll see those Variables values when they change post live into the log. For Devices, instead of a value, you’ll see the incoming and outgoing messages to that device in their raw state. This is very powerful for troubleshooting because you can see if there’s any delay in getting messages or if a product file may need to be updated because the incoming or outgoing messages don’t match what the device on the other end is expecting or sending. When firmware changes, often, so do the ways those devices communicate. Sometimes, it’s a very small change (adding an additional status or changing the way data is reported). Sometimes it’s a complete change to the style or structure of a message, or new messages have been added that need to be supported.
Let’s take a look at a few examples so this isn’t all theoretical. I’ve got a simple sequence written here that has errors in it. I’m going to run the error checker on it – it highlights that I need to fix this event – turns out I forgot a variable in one of the parameter fields. No problem. We add it back in and we hit Refresh on our Error log – and voila, it’s gone. Now I can push this file to the show controller and we can watch what happens when we run it.
For some reason, the logic in my sequence isn’t running the way I expect – these events aren’t firing. I have variables in my logic, but no way to know what their values are as it runs. If I add them to the watch list, though, I can know exactly what their values are. Since 0 is not greater than 5, this logic isn’t ever going to run. I think I must have gotten the sign wrong – I meant If < instead. Now, we can see the logic runs correctly on the next attempt. Now, these events are firing off as expected.
That said, my QSys Core still isn’t playing my file. Let’s look at the Live Log to see why not. I’m telling it to play “PinkFlood” not “PinkFloyd” – I must have a typo in my command somewhere. There it is – we watch the sequence run again and we hear the familiar refrains playing behind us. Lovely. We can check the Live Log just to make sure it went out as expected and there it is – “PinkFloyd”.
Troubleshooting is one of the hardest things to teach and to master because it requires learning how to recover from failure – and often the only way to do that is to fail a few (or a few hundred) times and have to figure out what went wrong. Thomas Edison once sagely said that he hadn’t failed – he’d simply found 2000 ways not to make a light bulb. In show control, we often find ways NOT to make our show run perfectly – and then we tweak, test, and adjust and we get it to working flawlessly – and there’s no better feeling than to watch it the first time it runs exactly the way you expect. And then again. And again. And again. Knowing that the hardware is rock steady is great – but knowing that you built code to match is a great feeling, and knowing that once you’re done, it’ll run for years without needing much care and feeding is even better.
There are a few Troubleshooting labs you can play with to see if you can find the errors and fix them. Some will be more challenging if you don’t have a controller handy, and others are simple tests of your reasoning skills. If you run into questions while looking at them, don’t hesitate to reach out!