Software Documentation

Exporting a firing system scriptDocumentation

IntegrationIntermediate Last updated: September 30, 2019

9 Pyrodigital

In the past, scripting software including our own Finale Business required that you download your script to the Pyrodigital controller using the software application itself.  That was at times inconvenient for people when they needed to download a script from a computer that didn’t have the software program installed on it or didn’t have a software license.  Finale 3D attempts to solve this problem by splitting the download process into two steps: 1) export the file to be downloaded, and 2) download the file.

The two steps can occur at different times, by different people, on different computers.  A show designer can make a last minute change to a script, export the file, and email it to the show operator on site to download from his own PC using a terminal program or a downloader that doesn’t require a software license.   The file to download to the controller is a simple text file, with the file extension PDM.

This section provides basic instructions to create a PDM file, and for those who are interested this section also provides the technical specifications of the file format.  To create and export a script to a Pyrodigital controller, please follow these steps:

  1. Choose module type.  After you select Pyrodigital as the “Controller Type” in Finale 3D, you have the option of selecting the “Module Type“. The module type options include (1) a choice for “Standard Script” (entire script plays as one piece) or “Manual Script” (script consists of short sections or individual cues that you can step through), (2) the specification of the time base (30fps, 29.97 SMPTE DF, 25fps, or 24fps), and (3) for your convenience an option to use only 15 of the 16 pins (some companies use 15 pins to make it easier for the addressing to align with rack configurations).  You can select any of the module types for the full show in “Show > Set show information…” or in “Addressing > Addres show…”, or you can choose different module types per-position by right clicking positions and doing “Edit position properties” from the context menu.  The only requirements are that you use the same time base and same standard/manual script choice for all module types in the show.
  2. Address show.  (“Addressing > Address show…“).  Finale 3D provides a variety of addresssing methods, including all-at-once, or blueprints, or fill-down.  The easiest method is the function, “Addressing > Address show…” which asks the order of assignment and presents some other options and then addresses the show all at one.  For explanation of the other options, see Addressing basic instructions).
  3. Export script. (“File > Export > Export firing script(s)…“).  Having addressed the show, use the export function to create a PDM file to transfer to your Pyrodigital controller.  The export function is separate from the download function in Finale 3D to allow you export and download at different times, or by different people.  For example, a show designer can export the PDM file and give the file to an operator to load onto the controller at a later time.
  4. Download to controller (“File > Download > Download firing system script file to Pyrodigital…“).  Having created the PDM file and saved on your computer, you can download the PDM file to your Pyrodigital controller at any time, using Finale 3D, or using a Pyrodigital downloader program, or using a terminal program.  The PDM file is just a text file, so any terminal program that can transfer files with a standard serial protocol will suffice.

Step 3 creates the PDM file.   Although this file is just a text file, the format of the file is not at all easy for a human to read.  To give you the ability to look over the actual file contents before downloading to the controller, if you feel so inclined, Finale 3D provides the function “File > Tools > Open firing system script as generic table…” to view the contents of the PDM file in a table window.  You can select all in the table window (control-A), then copy (control-C), then paste into an Excel file if you prefer viewing it in Excel.  This function doesn’t provide editing capabilities, but it does enable you to see exactly what the file contains.  If you really just want to do a quick check to make sure the file is valid, and don’t want to look over its rows, you can do the function, “File > Tools > Verify PDM file…”, which verifies the file is in the proper format and shows a quick summary of its contents.

Figure 1 – Pyrodigital FC-A controller

 

Table 1 – PDM file format and encoding

File format Extension Text encoding Field delimiter End-of-line
Text file .PDM ASCII None Carriage return  + linefeed (0x0D0A)

The PDM script is a text file that you can inspect and edit in a text editor, but it is in a format that is difficult to read.  The format consists of a list of rows, followed by a file checksum.  Each row is a list of fields formatted as hexadecimal, with a “start of message” indicator at the beginning of the row and a checksum and end-of-line (CR LF) sequence at the end.  The fields are all fixed width numbers of characters, with no delimiter in between them.  There are 11 fields in the row comprising 28 characters, making the output look like this:

N30000000005001E0010000100CB

As you can see, these rows are a little difficult to read.  The function “File > Tools > Open firing system script as generic table…” splits out the fields and converts them from hexadecimal to decimal format to make them more readable (except leaving the address field in hexadecimal).

Figure 2 – The PDM file shown in a table window.

 

You will notice even in the table window, there aren’t any notes or effect names.  No angles, or any of the other properties of the script as you see it in the scripting software.  That’s because those extra properties are not downloaded to the Pyrodigital controller.  The only fields that are ever downloaded to the Pyrodigital controller are the fields in the PDM file, as shown in Figure 2.

If you are familiar with the field names at the top of Figure 2, and if you have no need for the technical specifications of this file format, then you can stop reading at this juncture.  If you have a need for an example file, the downloads are at the bottom of the section.

 

Table 2 – Special characteristics of the PDM file

Special characteristics Description
Time representation Effect times are represented in a frame based time format (HH, MM, SS, FF).  Event times (the times of the ignitions) are  the effect time minus the prefire time.  The prefire time is represented in tenths of a second.  Frame based time formats include 30fps, 29.97fps SMPTE DF, 25fps, and 24fps.  The PDM file does not contain a specification of its own frame based time format, so it is impossible to interpret the time representation without knowing, a priori, what the time format is.  Obviously if the file contains frame numbers 25 or higher, then it’s not 25fps or 24fps.
Manual script (macro fire) The manual script mode provides for stepping through a show in short sections or individual cues instead of playing the entire script all at once or synchronized to time code. Finale 3D will export a standard script or a manual script based on your choice in the Module Type selector. The two script formats are different — standard script rows contain effect times and prefires that the controller subtracts from the effect times to determine the ignition times; manual script rows contain effect times that merely identify groups of rows that are part of the same “Macro” (short section or individual cue), and prefires that represent the offsets of those rows’ ignition times relative to the time at which the macro is triggered, beginning with zero and in chronological order.

In Finale 3D, please use the “Track” field of the script rows to identify groups of rows that are part of the same macro. The Track field can be blank, or it can have any integer value from 0 to 9999. Rows that have a blank Track field will automatically be grouped into individual cue macros. An individual cue macro consists of all the rows having the same effect time. Thus individual cue macros may contain one or more than one row.

The exported PDM script does not actually contain the track numbers. Pyrodigital controllers use the effect time field to identify the rows that are part of the same macro. The kind of macros that originate in Finale 3D from having the same track numbers, and the kind of macros that originate in Finale 3D from having a blank track field and being at the same effect time are both represented the same way in the exported PDM script — as rows that have the same effect time.

Since the Track field is essentially optional, you can create manual scripts conveniently in Finale 3D by leaving the Track field blank for those macros that are just individual cue macros, and filling in the Track field for sequences of effects not all shot at the same time. The Track field numbers themselves are immaterial and do not need to be in order; they are simply identifiers to group the effects.

Zipper fire “fix” for macros Older Pyrodigital controllers including the FC-3 have a hardware limitation that macros cannot begin with multiple rows having prefire = 0 if the macros contains any rows with prefire  > 0.  In other words, either all the rows in the macro must have prefire = 0 (so called “zipper” fire in Pyrodigital terminology) or only one one row in the macro can have prefire = 0.  Finale 3D works around this limitation by inserting a “Dummy Cue” at the beginning of any macro that would otherwise not work. The dummy cue has a module and pin address of 000 and a prefire of zero. The remaining rows in the macro will have their prefires increased by 0.1 seconds. Thus a macro previously beginning with two or more shots at the same time will now begin with a single dummy cue shot, followed by the original two or more shots a tenth of a second later.

The downside of dummy cues is that they assume the module and pin address 000 does nothing; and they introduce a 1/10th second delay in the macro response to being triggered. If you want to disable this “fix” in Finale 3D, please set the per-show setting pyrodigitalDisableMacroZipperFix to true in the per-show settings window before exporting.  Please see the “Zipper fire ‘fix’ for macros” section below.

Sort order of rows Rows sorted ascending by effect time.
What rows represent Each firing row represents the electrification of a pin at the row’s event time, calculated from the effect time and prefire time.
Checksum function The file contains checksums for each row and at the end of the file. The checksum function is defined by this procedure:

Start with variable SUM = 0.
Loop over the ASCII characters of the data being checksummed, in pairs.
   Read each pair of characters as a hexadecimal number ("00" - "FF"), producing an integer in the range 0-255. 
   Add the integer to SUM.
Return 255 - ( SUM & 255 ).
End-of-file checksum (six characters) The file concludes with a checksum in the format: “N9” + the first two characters of the last row in the file + two character checksum of the first two characters of the last row in the file.
Download protocol If you are using a terminal program to download the PDM program to the controller, or if you are writing a program to do it, use these settings:

COM port = whatever port connects to the controller.
Data rate = 9600 baud.
Hardware control flow = CTS control flow.
Parity = none.
Bits per byte = 8.
Stop bits = 1.

 

The script rows consist of the 11 fields described in Table 3.  All fields except the SOM field at the beginning are formatted as hexadecimal numbers with two or four digits.  The total number of ASCII characters per row is 28.

 

Table 3 – Specifications of script fields

Field name Description
SOM (two characters) A “Start of message” delimiter consisting of the two characters “N3”.
LINE (hexadecimal int,  formatted with four digits) A counting number that begins with “0000” and increments sequentially with each row.  The maximum value is “270F” (9999 decimal).
HH (hexadecimal int, formatted with two digits) The hours component of the effect time.  For standard scripts, the effect time minus the prefire time determines the ignition time.  For manual fire scripts, the effect time merely identifies rows that are part of the same macro.
MM (hexadecimal int, formatted with two digits) The minutes component of the effect time.
SS (hexadecimal int, formatted with two digits) The seconds component of the effect time.
FF (hexadecimal int, formatted with two digits) The frames component of the effect time, starting with zero.  The maximum value is “17” or “18” or “1D” (decimal 23, 24, or 29) depending on the time format of the file (see Time representation, in Table 1).
PREFIRE (hexadecimal int, formatted with two digits) For standard scripts, this field is the prefire time in tenths of a second.  For manual fire scripts, this field is the offset of the row’s ignition time from time at which the macro is triggered, in tenths of a second.  Sequences of rows that are part of the same macro in manual fire scripts must have non-decreasing prefire times.
ADDR (hexadecimal int,  formatted with four digits) The module number * 16 plus the pin number.  The module number is limited to 127; the pin number is limited to 15.  Thus the first digit of the ADDR field is always zero, and the maximum value is “07FF”.
SHOT (hexadecimal int,  formatted with four digits) A counting number that begins with “0001” and increments sequentially with each new effect time.  The maximum value is “270F” (9999 decimal).
CGHZ (hexadecimal int, formatted with two digits) The lockout / hazard class.  The minimum (and default value) is “00”; the maximum value is “10” (16 decimal).
CHECKSUM (hexadecimal int, formatted with two digits) A checksum value for the characters in the row beginning with LINE and ending with CGHZ (24 characters in total).  See the definition of the checksum function in Table 2.

An example script is shown below as Figure 3.  This is the same script as shown in the table of Figure 2, and included in the downloads in Table 4.

N30000000005001E0010000100CB
N30001000005001E0020000100BA
N30002000005001E0030000100A9
N30003000005001E004000010098
N30004000005001E005000010087
N30005000005001E006000010076
N30006000005001E007000010362
N3000700000C071E0011000204B0
N300080000110B1E0012000304A4
N300090000110B1E0013000304A2
N3000A00001D1A16001400040090
N3000B00002C1A1600150005007E
N900FF

Figure 3 – Example PDM file

 

Zipper fire “fix” for macros

As described above, Finale 3D works around the macro limitation in early Pyrodigital controllers including the FC-3 by introducing a dummy cue at the beginning of any macro that begins with two or more shots at the same time and also contains other shots at a later time.  The circumstances requiring this workaround are not hard to construct.  Imagine a center-to-outside chase of simultaneous mine/shell combinations across nine positions, with the center position (call it position 5) triggering first, followed by the pair of positions immediately before and after (position 4 and 6) together, followed by positions 3 and 7 together, then 2 and 8 together, and finally 1 and 9 together.  Except for the center position shots, all the other shots of this sequence are in pairs of positions.  If you want to shoot this sequence with a manual fire script, advancing the cues step-by-step, you will run into the circumstance requiring the zipper fire fix.

Figure 4 shows the PDM file generated from this example.  There are nine positions, each with a pair of shots (one mine and one shell) at the same effect time, 18 shots total.  The center position yields a macro with one shot at prefire = 0 and a second shot at prefire = the lift time of the shell.  The other positions, firing in pairs, yield four more macros, each beginning with two shots at prefire = 0, and two shots at prefire = the lift time of the shells.

Without the zipper fire fix these macros will not fire correctly on FC-3 controllers.  The zipper fire fix adds four dummy cues to correct the problem, which you can see circled in Figure 4.    Notice that the dummy cues have prefire = 0, and they are each followed by the pair of shots that would otherwise have begun the macro with zipper fire.  The fixed script file contains 22 rows total, comprising the original 18 shots and 4 dummy cues.

Figure 4 – “Dummy cues” fixing macros that would otherwise begin with zipper fire

 

To avoid any confusion about dummy cues, Finale 3D displays a warning during the export operation whenever it detects a macro requiring the dummy cue fix.  If you see the warning shown in Figure 5, that means dummy cues were added to make the script fire correctly.

Figure 5Finale 3D displays a warning whenever “dummy cues” are required.

 

Table 4 – Example files

Download link Explanation
test_pyrodigital.fin Example show file addressed for Pyrodigital
test_pyrodigital.pdm Example exported PDM file