Type any phrase to search documentation

Software Documentation

Exporting a firing system scriptDocumentation

IntegrationIntermediateLast updated: January 1, 2022

32 Pyrotronix

To create and export a pyro or DMX script for the Pyrotronix firing system, please follow these steps:

  1. Address the show (“Addressing > Address show”) and select one of the PTX2 module types for the PTX C4 controller or the other options for older controllers that imported CSV-style scripts. All PTX2 module types support both pyro and DMX.
  2. Export the script (“File > Export > Export firing scripts…“).

Step 2 creates the script file, which has the “PTX2” extension. The file format details are described in this section.

 

 

Figure 1 – Pyrotronix firing system master

 

DMX overview

The Pyrotronix system supports DMX fixtures by triggering pre-programmed or user-created presets on the controller. Please refer to your PTX C4 instructions for creating presets, and then create effect libraries to match your presets in Finale 3D as described below. The DMX instructions for scripting in Finale 3D ( DMX basic instructions ) do apply but there are two differences for Pyrotronix, since the script exported from Finale 3D will contain only the triggers for pre-programmed presets and not the actual DMX channel data that implement the effects according to the fixture’s DMX personality.

The two differences are: (1) you need to create your own effect libraries in Finale 3D to match your presets (except for the Explo X2 Wave Flamer, for which the effects in Finale 3D‘s pre-defined Generic Effects effect library match the pre-defined presets in the Pyrotronix PTX C4 controller already), and (2) you need to configure DMX fixture positions in Finale 3D as “<Any fixture type>” from the DMX Fixture Type selector after right clicking the positions and doing “Configure position as DMX fixture” from the context menu (except for the Explo X2 Wave Flamer, which you can select instead if desired).

 

Table 1 – File format and encoding

File formatExtensionText encodingField delimiterEnd-of-line
Text.PTX2ASCIISemicolonCRLF

 

Structure of PTX2 script file

The PTX2 script file contains three sections: project, DMX devices, and ignition data, as shown in the example file in Figure 2. As exported from Finale 3D, the first section of the script, the project section, is the text:

[Project]
version=1.0
type=IN

The last line is either “type=IN” for a script with individual events or “type=SQ” for a script with sequences. See the Sequences row in Table 2, below, for further details.

The second section, the DMX devices section, contains a mapping of “Device Name” to “Device Type” and “DMX Channel Base”. The Device Type is defined by the Category field of the DMX effect in Finale 3D, and must match the Device Type of the pre-programmed presets in the Pyrotronix controller exactly. The DMX Channel Base is defined by the DMX Channel Base field of the positions in Finale 3D, once they are configured as DMX fixtures. The Device Name is constructed synthetically from the Device Type and DMX Channel Base trivially by concatenating them together with a space in between.

The syntax of the rows is simply <Device Name>=<Device Type>@<DMX Channel Base>. This DMX devices section is only present if the script contains DMX events.

[DMX devices]
Explo X2 Wave Flamer 1=Explo X2 Wave Flamer@1
Explo X2 Wave Flamer 7=Explo X2 Wave Flamer@7
Explo X2 Wave Flamer 13=Explo X2 Wave Flamer@13

The third section contains the ignition data and DMX preset triggers, intermixed and sorted by event time.

[Ignition data]
1;A;2760;1020;1;1;;Red Chrysanthemum;
2;A;3760;1020;2;1;;Red Chrysanthemum;
3;A;4760;1020;3;1;;Red Chrysanthemum;
4;A;10000;2400;DMX;;;Explo X2 Wave Flamer 1:PRG31;
5;A;11000;2400;DMX;;;Explo X2 Wave Flamer 7:PRG31;
6;A;12000;2400;DMX;;;Explo X2 Wave Flamer 13:PRG31;

The ignition data fields are described in Table 3:

 

Table 2 – Special characteristics

Special characteristicsDescription
Sort order of rowsRows sorted ascending by event time.
What rows representEach row represents a unique firing event, for pyro a module/pin/event-time combination, and for DMX a device name / preset identifier combination. For example, a pyro chain of five shells will be one row, not five. A pair of shells shot together from the same position will be one row, not two, even if the shells are different effects. A flight of shells shot together from multiple positions with the same module-pin using scab wire is still one row. DMX examples are given below.
Sequences (Tracks)The user can divide a script into separately triggered sequences by tagging the script rows with <Sequence Group>.<Sequence Number> pairs in the Track field in Finale 3D, beginning with “1.1”. Pyrotronix supports up to four sequence groups, with thirty-two sequence triggers (buttons) per group. Each sequence can have up to twenty ignitions.
Time resolutionThe Pyrotronix system supports 1/100th second resolution.
DMX supportThe Pyrotronix system supports DMX fixtures by triggering pre-programmed or user-created presets on the controller. The PTX2 script exported from Finale 3D contains triggers based on the Device Type and Preset Identifiers of the effects in Finale 3D (from the Category and Custom Part Field fields), which must match the presets defined on the controller exactly. The triggers do not contain any parameters for the presets, so it is not possible to script parameterized effects like effects that depend on the angle or duration that the user can adjust in the Finale 3D user interface.

The DMX instructions for scripting in Finale 3D, ( DMX basic instructions ) do apply, except you need to create your own effect libraries in Finale 3D to match your presets (except for the Explo X2 Wave Flamer, for which Finale 3D‘s effect library matches the pre-defined presets in the Pyrotronix PTX C4 controller), and you need to configure the fixture positions in Finale 3D to “<Any fixture type>” from the DMX Fixture Type selector in the “Configure position as DMX fixture” context menu from right clicking the positions (except for the Explo X2 Wave Flamer, which you should select instead if desired).

Bandwidth limitationsFinale 3D provides options for automatically guaranteeing a minimum delay between firing events to accommodate communication bandwidth limitations on the controller. The two options are 60ms (“Cable + Radio”) and 30ms (“Cable”) minimum delays. The module type selector in the addressing dialog provides these options. The minimum delays are the only differences between the “Cable + Radio” and “Cable” options.
Electrical limitationsFinale 3D also provides options to limit the number of simultaneously firing channels to 20, to accommodate electrical limitations on some Pyrotronix controllers. The options are available from the module type selector in the addressing dialog.
Support for CSV script format for older controllersFinale 3D also supports exporting the CSV file format script for older Pyrotronix controllers. In the addressing dialog in Finale 3D, select the PTX module type options for the old CSV script file formats, or the new PTX2 module type options for the new script formats for the C4 controller. Only the PTX2 options have DMX capabilities.
DMX safety channel requirement warning disabledFinale 3D ‘s warning for missing safety channels for DMX effects is disabled for Pyrotronix exports based on the assumption that Pyrotronix users will handle safety channels manually on the controller, not within the script exported from Finale 3D.

When you export a firing script for Pyrotronix, Finale 3D presents an “Export Options” dialog with the choices shown in Table 3.

 

Table 3 – Export options

Option nameDescription
VersionChoose the PTX2 version or the old-style CSV version.
Separation TimeChoose the minimum separation time between shots — 30ms for wire connected modules and 60ms for radio connected modules.
LimitChoose the limit of maximum simultaneous firing channels. Some versions of PTX hardware have a limit of 20; others have no limit.

 

 

Each ignition row in the ignition rows section of the script contains a number of fields separated by the semicolon character. The names of the fields and their descriptions are in following table.

 

Table 4 – Specifications of ignition row fields

Field nameDescription
CueThe cue number beginning with 1 and incrementing at each new event time
Ignition typeThe letter “A” for a non-sequence event, or “S” for an event that is part of a sequence.
Event timeThe ignition time in milliseconds
DurationThe duration in milliseconds
Module numberThe module number, 1-99.
Pin numberThe pin number, 1-16.
Hazard classA hazard classification for purpose of disabling part of the show during a performance, a number 1-24 or blank.
DescriptionFor pyro, this field contains the name of the effect; for DMX, this field contains the <Device Name>:PRG<Preset Number>, where Preset Number is a two digit number corresponding to a pre-programmed or user-defined preset on the Pyrotronix controller. The Device Name is constructed from the Device Type in the effects’ Category field and the DMX Channel Base from the position, as described above in the Structure of PTX2 script file section. The Preset Number comes from the Custom Part Field field of the effect. Finale 3D automatically adds the PRG before the Preset Number in the script. The PRG letters thus should not be in the effects’ Custom Part Field. All pre-programmed and user-defined Preset Identifiers of presets on the Pyrotronix controller must be of the form PRGXX, where XX is a two digit number.

The Explo X2 Wave Flamer effects in the Generic Effects collection in Finale 3D already contain the numbers that correspond to built in presets on the Pyrotronix PTX C4 controller in the Custom Part Field; and also contain the Device Type in the Category field. For other fixtures and effects you will need to create your own DMX effect libraries for Pyrotronix, as described below.

SequenceThe sequence is either blank, or X.Y where X is the sequence group number 1-4 and Y is the sequence button number 1-32. Either all script events must contain sequence numbers, or none of them. Use the Track field in Finale 3D to specify the sequences (right click on the events in the script window and do “Set track…”).

The example script shown in Figure 2 is also available for download in Table 5.

[Project]
version=1.0
type=IN
[DMX devices]
Explo X2 Wave Flamer 1=Explo X2 Wave Flamer@1
Explo X2 Wave Flamer 7=Explo X2 Wave Flamer@7
Explo X2 Wave Flamer 13=Explo X2 Wave Flamer@13
[Ignition data]
1;A;2760;1020;1;1;;Red Chrysanthemum;
2;A;3760;1020;2;1;;Red Chrysanthemum;
3;A;4760;1020;3;1;;Red Chrysanthemum;
4;A;10000;2400;DMX;;;Explo X2 Wave Flamer 1:PRG31;
5;A;11000;2400;DMX;;;Explo X2 Wave Flamer 7:PRG31;
6;A;12000;2400;DMX;;;Explo X2 Wave Flamer 13:PRG31;

Figure 2 – Example Pyrotronix script for pyro and DMX

 

Creating DMX effect libraries to match presets on your Pyrotronix controller

Since Pyrotronix scripts control DMX fixtures by triggering pre-programmed or user-defined presets on the controller, the script exported from Finale 3D will contain only the triggers and not the actual DMX channel data. The DMX Patch field of the effects in Finale 3D is thus unused, as its purpose is to translate the effect definition into the DMX channel data that implement it. In its place, the Category field and Custom Part Field field of the effects in Finale 3D hold the Pyrotronix Device Type and Preset Number that together identify the preset to be triggered.

The Category field must contain the Device Type of the pre-programmed or user-defined preset on the controller exactly, except for optional capitalization. The Custom Part Field contains an integer identifying a preset for that Device Type. The number in the Custom Part Field is just an integer. Finale 3D automatically formats the integer as two digits with a leading zero if necessary and prepends the letters “PRG” to the front, such as for example PRG01, PRG02, and PRG03 for the first three presets. The preset identifiers on the Pyrotronix controller must match these presets — including the PRG — exactly.

Since the Device Type of the preset is specified in the effects, the Fixture Type field of the positions in Finale 3D is not required for Pyrotronix script exports. You can thus set the Fixture Type to “<Any DMX Fixture>” or set it to any of the predefined fixtures in Finale 3D, your choice. The advantage to setting it to a pre-defined fixture in Finale 3D is that Finale 3D‘s channel allocation functions will be able to allocate channel ranges back-to-back for your fixtures if the you choose pre-defined fixtures. If you use “<Any DMX Fixture>” then you will need to set the DMX Channel Base of the fixture positions manually in the positions window or by right clicking the positions and editing the position properties.

Since the DMX presets on Pyrotronix and their triggers do not have any parameters, it is not possible for the presets to depend on user-adjustable parameters in the Finale 3D user interface like the angle or duration of an effect. If you want to shoot a moving head wave flamer effect in a particular direction, you need to define a preset for that specific direction on your Pyrotronix controller and create a corresponding effect in Finale 3D with the matching Device Type and Preset Identifier.

 

Example files

Example files for a mixed pyro and DMX show are available for download in Table 5. The example show contains three DMX fixture positions and three pyro positions. The DMX fixture positions each contain a single shot of the Explo X2 Wave Flamer fixture, firing macro #31. They do not contain safety channel events; and the safety channel requirement warning is disabled for Pyrotronix script exports. The three pyro positions each contain one shell. The timeline for the example show is shown in Figure 3.

 

Figure 3 – Timeline for example mixed pyro and DMX show — 3 pyro shots, 3 DMX shots.

 

 

Table 6 – Downloads

Download linkExplanation
test-pyrotronix-dmx.finExample show file
test-pyrotronix-dmx.ptx2Example exported file (PTX2)