Writing Messages Using Regular Expressions
Unlike Outgoing Responses, only the form of a valid Incoming Responses is usually known, not its exact content. For example, you might trigger your Show Controller to send a message to an audio playback device querying the status of a certain track that is currently playing. The Incoming Response from the device might look like any of these:
- “Track 012 – HappyDay3.wav 01:09:59:29; 5m 15s remaining”
- “Track 001 – Song000000001.wav 00:02:14:37; 1h 16m 14s remaining”
- “ERROR 034 - No Track Found”.
You would want your show controller to know that it got a valid Incoming Response if it got either of the first two messages as a response. You might also want it to match enough of the pattern of the message to store some information from it into device variables or data parameters. In order to provide such capabilities and more, regular expression matching is used for incoming messages in the Product File Creator.
Many great introductions and guides on regular expression matching are available on the internet. We could not do justice to all that is possible with regular expressions in this short tutorial, but the Appendix of this document does have some limited information useful to using regular expression with the Product FileCreator and some references to resources. For now, let’s illustrate the use of regular expressions by creating an event to gather the number of hours and minutes that the lamps of our projector have been on.
Create an event called “GetLampHours1” and check the box indicating that there is an Incoming Response:
The correct outgoing message is “(SST+LAMP? 08)”. Add this string in the Outgoing Command tab:
The Incoming Response message is trickier. We’ll use an Example Incoming Response to construct the final regular expression piece by piece. Type “(SST+LAMP!008 "06:45 hh:mm" "Lamp 1 Active Hours")” into the Example Incoming Response box:
“(SST+LAMP!” is always at the beginning of a valid string so let’s highlight that portion of the Example Incoming Response and use it to add the first part of the final message. Click Add Selection and then choose “Constant”.
As you can see, “(SST+LAMP!” is added as one of the substrings comprising the final message and appended into the regexp_format.
After that, the incoming message will have some data we can ignore until we get to the portion that contains the lamp hours. From our Example Incoming Response, this means everything after “LAMP!” and before "06:45 hh:mm". Let’s highlight that portion:
Add it as a wildcard substring. Using a wildcard means that the exact substring does not need to be matched, just something about its form. The Product File Creator tries to decipher what type of text you want to match. Here, because we selected four characters (a space followed by “008”), it defaults to matching any string that is a minimum of 4 characters and a maximum of 4 characters long. That is, the regular expression assumes that the number of characters must be exactly 4 characters.
Since our goal is to ignore all characters until we reach the "06:45" string, let’s erase the values in Min and Max and leave those boxes empty. Removing the Min and Max bounds means that everything that follows “SST+LAMP!” is now part of the wildcard substring we created. You can see in the Response Substrings section that this is more than just the 4 characters we highlighted. It is every character until the end of the message! That’s not quite right, so let’s cut the matching off some.
To do this, note that the next distinct portion of the Example Incoming Response is “"06:45"”. The quotation mark before the 06 lets us know that the data we want (represented by 06 for hours and 45 for minutes) is next in the message. Let’s add this quotation mark to the substring. Highlight it, choose Add Selection, and select Constant as the type.
Next highlight the “06” so that we can store it. Click “Add Selection”. This time we will add it as a variable. By doing so, we are saying that we do not want to literally add the value “06” to the final regular expression, but rather we want to add a placeholder to store whatever would be in that location in a typical Incoming Response.
When you choose to add a substring as a variable, you must choose which Device Variable to store the substring in. If you click the dropdown menu next to “Variable:”, you will see that we have not yet defined a place to store the lamp hours. All you should see in the list are “Error”, which is a default variable, and “TCPStatus”, which was automically created because we earlier specified that this device uses TCP/IP with its Ethernet port.
Click “Edit Variables” to be taken to the Variables screen. This screen is where Device Variables can be defined. Once there, click on the “Add Variable” button. We will call the variable “Lamp1Hours”, define it as an “integer” type, and give it an initial value of 0:
While you are here, go ahead and use the Duplicate button underneath the list of variables to define variables for the “minutes” portion of Lamp 1’s online time, as well as the corresponding variables for Lamp 2’s online time. Device variables can be defined at any time as needed.
We can now go back to the Events tab and use the variables we have just defined to capture part of the Incoming Response. Making sure “06” is selected from the “Response Substrings” section, choose “Lamp1Hours” from the Variable dropdown list. The regexp_format is updated accordingly. Notice that “Character type” now says “digits only” to let the regular expression know to expect 2 integer digits, not just any type of character.
Next, add the “:” as a constant substring. Then, highlight the “45” from the Example Incoming Response and add it as a “variable” substring into the “Lamp1Minutes” variable:
Once we add we have stored the Lamp 1 minutes, nothing else remaining in the Example Incoming Response matters to us. Highlight everything to the right of “45”, and add it as a wildcard substring.
Finally, make sure to erase the Min and Max number of characters for this Wildcard substring and you should end up with a final regular expression of: “(SST+LAMP!."([0-9]{2,2}):([0-9]{2,2}).”
Now you can try it. Add an event for getting Lamp 2’s online time. Use “(SST+LAMP ?38)” as the Outgoing Command and “(SST+LAMP!038 "Stuff to Ignore" "72:23 hh:mm" "Lamp 2 Active Hours")” as the example Incoming Response. Your screen should look similar to the following:
