Software Documentation

Exporting a firing system scriptDocumentation

IntegrationIntermediate Last updated: July 24, 2019

3 Cobra

To create and export a script for the Cobra firing system, please follow these three steps:

  1. Address the show (“Addressing > Address show”).
  2. Export the script to a USB thumb drive (“File > Export > Export firing scripts“).
  3. Insert the USB thumb drive into the 18R2 (To start your show, press cue #1 on channel 00!).

Step 2 creates the script file, which is a standard format CSV file with a “CSV” extension.  The file format details are described below in this section.

 

Figure 1 – Cobra firing system

 

Cobra modules have 6, 18, 36, or 72 pins (cues), but as far as addresses are concerned the modules with more than 18 pins are just two or four 18-pin modules combined, with each of the 18-pin modules having a separately assignable module number (channel number).  If you use 36 or 72 pin modules, simply treat them as multiple 18-pin modules stuck together, and assign their separate module numbers to whatever is needed at their physical locations.  If you use 6-pin modules, take care to avoid assigning pins above 6 or create a custom module with a 6-pin limit.

 

Table 1 – File format and encoding

File format Extension Text encoding Field delimiter End-of-line
Text .csv ASCII Comma CRLF

The script contains rows for the firing events, i.e., unique combinations of module, pin, and ignition-time. Multiple effects can be combined on a single cue. The special characteristics of the script are shown in the following table:

 

Table 2 – Special characteristics

Special characteristics Description
Script formats for different Cobra firmware versions Finale 3D can export COBRA v3.0, COBRA v4.0, COBRA v5.0, and COBRA v6.0 format scripts.  COBRA v3.0 and v4.0 scripts have 10th second resolution; later versions have 100ths second resolution.  Beginning with COBRA v6.0, the script supports launch position coordinates, hazard class, definable pulse time,  and embedded part numbers.
Sort order of rows Event rows in each section of the script are sorted ascending first by Event Time.
What rows represent Rows represent firing events, i.e., unique module-pin-ignition-time events. If multiple effects are triggered on the same cue, the effects are combined in name field, but the row is still just one row.
Structure of script file The script file begins with a header with position coordinates, followed by one or more sections (one for non-semi-automatic) of event rows, each section with its own two-row header, followed by “end” as a row by itself.
Header with position coordinates Beginning with COBRA v6.0, the script includes a header with the version number and position coordinates. The rows indicate the coordinates of the positions and the list of modules at each position, in a simple syntax illustrated by this example:

@version 6
@beginPositions
@Pos-01,-50.0,0.0,-8.0,3.0,1
@Pos-02,-37.5,0.0,-8.0,3.0,2,5,6,7,8
@endPositions

The three coordinates following the position name are in meters: right (East), out toward viewer (South), and up toward the sky. The fourth field is the diameter of the position in meters. The remaining fields are the module channel numbers at that position.

Semi-automatic firing Cobra firing systems support three types of semi-automatic and step firing methods: 1) “Separate Scripts By Tracks”, 2) “Step Script By Tracks”, and 3) “Step Script By Events”.  In Finale 3D, you can select any of these semi-automatic methods from the addressing menu, or select “Standard Script” for the fully-automatic method used for pyromusicals.  The Separate Scripts By Tracks method splits the script into multiple scripts that are triggered on demand by pressing the corresponding cue button on the Cobra controller.  The Step Script By Tracks method is similar, but advances through the tracks of the show sequentially with the step button on the controller, instead of by random access.  The Step Script By Events method advances one event at a time sequentially with the step button.  Examples of all four script formats are provided in Table 4.

For both the Separate Scripts By Tracks method and the Step Script By Tracks method, in Finale 3D the Track property in script rows indicates the section of the show to which the row belongs. For Separate Scripts By Tracks the Track also indicates the button on the Cobra controller that triggers the section, which is the Track value itself, a number 1-18 (please unhide the Track property in the script to use this feature). In Finale 3D, the Track field in the script table is hidden by default; unhide it from the blue gear menu. In the Cobra script file, sections are listed sequentially with a comment row and header row above the event rows, e.g.,

#Track 1
0,1,,0,audiobox

The Track value in the 3D script is the number in the #Track comment row, and also in the following header row after the word “cue”.  The rows in each section of a semi-automatic script have time values relative to the first event in the section, which is always time zero. In the Finale 3D script, the sections can be in any order and can even have interwoven events, but generally people place the sections one after another in the Finale 3D script, with some space in between to tell the apart.

See semi-automatic-firing for further instructions.

Special characters To avoid the need for an escaping convention, Finale 3D filters out comma, semicolon, double-quote, backslash, and all control characters from the exported script. The Cobra controller implements the Excel escaping convention, but Finale 3D filters the characters anyway to avoid types of errors that are common when users import and export from Excel and text editors.
Minimum separation between cues None
Hazard class COBRA v6.0 and later firmware recognizes the “Hazard” field of Finale 3D, which is exported as a text field identifying a class of events that can be disabled on the fly based on conditions during the show.
Pulse Time COBRA v6.0 and later firmware supports a user-defined pulse duration for which cue is to be energized.
Multi-hit pins Supported in the script format and with manual addressing in Finale 3D, for non-pyro effects like flames and relays that can be triggered multiple times. Finale 3D handles multi-hit pins in the Cobra exporter the same as it handles single-hit pins — whatever pin address is in the script row in Finale 3D will be copied to the exported script row for Cobra, whether or not the pin address is unique. The standard pyro addressing functions in Finale 3D assign pins sequentially, so it may be easiest to address multi-hit pins in Finale 3D by editing the script table by hand and then locking the edited rows so the show can be re-addressed for pyro without affecting them.

After the header, each row in the script has a number of fields separated by the vertical bar character. The names of these fields and their descriptions are the following:

 

Table 3 – Specifications of script fields

Field name Description
Event Time Ignition time of the event, in the format: 00:00:01.00s
Channel Channel number (same as the Module Number and Rail Address), in the format: channel 10
Cue Cue number (same as the Pin Address), in the format: cue 1
Name Effect name, a text string, at most 80 characters long; (COBRA v6.0 and later: field includes the part number in curly braces immediately following the description, e.g., “Description {Part Number}”
Hazard (COBRA v6.0 and later) Text string identifying a class of events that can be disabled on the fly based on conditions during the show
Pulse Time (COBRA v6.0 and later) Duration for which cue is to be energized, in floating point format (0.01 second resolution); or blank for the default duration. Finale 3D writes the empty string value, unless the cue contains an event of type flame, other_effect, or not_an_effect, in which case Finale 3D writes the duration of the event as shown in the script row. See #type.

An example semi-automatic script with two sections is shown below. The first track section contains two events with hazard classes (wind, rain), and a third event with an explicit pulse duration.

@version 6
@beginPositions
@Pos-01,-50.0,0.0,-8.0,3.0,1
@Pos-02,-37.5,0.0,-8.0,3.0,2,5,6,7,8
@endPositions
#Track 1
0,1,,0,audiobox
00:00:00.00s,channel 1,cue 1,White Chrysanthemum {G2SH1000},wind,
00:00:02.90s,channel 2,cue 1,White Chrysanthemum {G2SH1000},rain,
00:00:05.40s,channel 2,cue 4,Long Flame Projector Shot {GXX1101},,0.41
#Track 2
0,2,,0,audiobox
00:00:00.00s,channel 5,cue 1,Green Chrysanthemum {G2SH1001},,
00:00:01.00s,channel 6,cue 1,Green Chrysanthemum {G2SH1001},,
00:00:02.00s,channel 7,cue 1,Green Chrysanthemum {G2SH1001},,
00:00:03.00s,channel 8,cue 1,Green Chrysanthemum {G2SH1001},,
end

Figure 2 – Example Cobra script

 

Table 4 – Example files

Download link Explanation
test_cobra.fin Example show
test_cobra_standard_script.csv Example exported standard script (fully-automatic)
test_cobra_separate_scripts_by_tracks.csv Example exported semi-automatic script (separate scripts by tracks)
test_cobra_step_script_by_tracks.csv Example exported step script by tracks
test_cobra_step_script_by_events.csv Example exported step script by events