Software Documentation

Exporting a firing system scriptDocumentation

IntegrationIntermediate Last updated: September 30, 2019

10 FireOne

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

  1. Design the show. If you are creating a semi-automatic show (SEM file), then select the ranges of the effects on the timeline corresponding to triggered sequences and assign them a track number by right clicking on the selected group and doing “Edit properties…” from the context menu.
  2. Address the show (“Addressing > Address show”).
  3. Export the script (“File > Export > Export firing scripts“).

Step 2 creates the script file, which is a FIR file or SEM file depending on your choices in the dialog.  The file format details are described in this section.

 

Figure 1 – Fireone control panel

 

FireOne has two firing system script formats, FIR and SEM, for standard start-to-end shows and for manually triggered “semi-automatic” shows, respectively.  The script files are mostly the same, except for the difference in file extension and a few fields, which are specified in the tables below.

 

Table 1 – File format and encoding

File format Extension Text encoding Field delimiter End-of-line
MDB .FIR or .SEM UTF-16 Not applicable Not applicable

FIR and SEM files are actually MDB files with the extension renamed.  MDB is the 32-bit format for Microsoft Access database applications.  It used to be that Microsoft Access and Excel could open MDB files directly, making it easy to view the data in FireOne script files, but after the transition to 64-bit systems Microsoft no longer supports reading or writing MDB files from its applications.  For your convenience, Finale 3D has a function, “File > Tools > Open firing system script as generic table” which opens a FIR or SEM file as a generic table for you to view or copy/paste into Excel or other applications, if you have need.

 

Table 2 – Special characteristics

Special characteristics Description
Time representation All times are represented in decimal fractions of a second, either as a string in a time format “00:00:00.00” or as an integer milliseconds.  In spite of the fact that the integer fields are in milliseconds and that FireOne hardware ostensibly supports millisecond resolution (as does Finale 3D), the FIR and SEM files are only capable of representing hundredth of a second resolution.
Sort order of rows In FIR files, rows are sorted ascending by event time.  In SEM files, rows are sorted first by event number (corresponding to the Track number in the Finale 3D script), then ascending by event time.  Thus in the SEM files each sequence of rows with the same event number is a contiguous sequence, beginning with the first row having a delay time of 0.
What rows represent Each row represents a unique module-pin-eventTime combination, and contains all the information in the script file that is associated with that module-pin-eventTime combination.  For example, a 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.  However, two flame projector shots at different times, triggered by the same module-pin, will be two rows because they are at different times.
Chains counting as one unit Some display companies follow the convention that one chain is one unit for stock keeping records; others follow the convention that a chain of five shells is five units.  The FireOne FIR and SEM files have a Qty field that represents the number of units.  The meaning of this field for chains — whether it is the number of shells in the chain or just one per chain — cannot be determined from the file intrinsically, so when you import a FireOne FIR file into Finale 3D, you are given the option to choose whether chain quantities indicate the number of chains or devices.  When you export a FIR or SEM file from Finale 3D, the quantity is always counting individual devices (not full chains).
Time base Finale 3D only supports the hundredths-of-a-second time base HH:MM:SS.XX for FireOneFIR and SEM script files, both for importing and exporting.  Please make sure your firing system is configured for the hundredths-of-a-second time base, as opposed to a frames time base.
Tables in the FIR and SEM file FireOne FIR and SEM files exported from Finale 3D will contain two tables, SMPTE and FireData.  The SMPTE table will contain a single row with four fields: TimeBase, ShowName, CuesPerSlat, ReportTimeBase; the fields having values HH:MM:SS.XX, the name of the show, 32, and hh:mm:ss.x.  The FireData table will contain the fields defined in the table below.
Special characters FIR and SEM file data may include all Unicode characters (represented in UTF-16 in the MDB file).
Semi-automatic firing In Finale 3D, the Track property in script rows indicates the sequence identifier for semi-autonomous firing mode (please unhide the Track property in the script to use this feature). The rows in each sequence of a SEM file 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.

To create an SEM file instead of a FIR file, please choose the module type “FireOne Module For Semi-Auto (SEM)” in the addressing dialog or position properties dialog before addressing the show. See Semi-automatic firing for instructions.

Using only 30 pins In the addressing dialog and the position properties dialog, you can choose the “FireOne Module, 30 Pins” instead of the standard “FireOne Module” if you want to leave the last two pins unused. You can also create a custom module in the “Addressing > Addressing settings” menu with an arbitrary maximum number of used pins.
Multi-hit pins Non-pyro effects like flames and relays can be triggered multiple times on the same module-pin. 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.
Slats While FireOne modules all have 32 pins, you may have hardware to divide the pins up into slats, such as four slats of 8 pins each, for the purpose of igniting effects at multiple launch positions without all the ematches extending all the way to the module.  When using slats it is essential that the pin numbers used for effects at a position correspond only to the slats at that position.

Finale 3D’s addressing functions support addressing constraints based on slats to allow slats from the same module to be located at different positions. Although FireOne module/pin addresses don’t provide any indication of slats (each module’s pins are 1-32 no matter how you might partition them into slats), you can configure the modules in Finale 3D as having “virtual slats” in order to make use of the slat-based addressing constraints.

Virtual slats allow you to partition the channels of a module into separate slats for which you can assign addressing constraints to guarantee good pin assignments for your physical layout. For example, suppose you have one module with 32 pins that are distributed out to four launch positions on four physical “slats” or “rails” with 8 pins each. It would be important to have the addressing constraint that each slat is restricted to a single launch position, for otherwise you might have wires running from position to position. To partition the pins into virtual slats, create a custom FireOne module with a rail address template like #99-D-#8 to split the 32 pin modules into four 8-pin slats, A, B, C, D. Because these are virtual slats, even though their addresses appear like “2-B” and “3” for module 2, slat B, pin 3 (of slat B), the addresses are converted automatically in the exported FIR or SEM script the contiguous 32-pin range of the module. The virtual slat address “2-B” and “3” convert to module 2, pin 11 (pins 1-8 correspond to slat A, so the third pin in slat B is pin 11).

Ignored fields in FIR and SEM files The FIR and SEM file format includes the following fields that are ignored by Finale 3D for importing and exporting: ID, ScriptTime, BreakTime, Type, Length, SayWhen, SayWhenText, SayWhat, Conflict, PyroSlat, PyroCue.  The ScriptTime and BreakTime fields are obsolete fields in the file format.  The Type field is ignored when importing into Finale 3D because it is a free form text field that may not match the specific type values permitted in Finale 3D’s Type field; and ignored when exporting to avoid confusion about that.

The script data rows in the FIR and SEM files contain the following fields, in addition to the ignored fields mentioned above.  Except where noted, Finale 3D both imports and exports these fields, allowing you to import existing shows previously scripted in other software and saved as FIR files, or to re-import shows previously exported from Finale 3D.  Obviously, since FIR files do not contain all the information in a Finale 3D show file, such as the coordinates of the positions, some information is lost if you export a FIR file and then re-import it.  But in all cases, when you import FIR files Finale 3D will create simulations from the descriptions automatically and layout the positions in a reasonable default arrangement, so importing FIR files usually produces a usable result for making a render or editing the script.

 

Table 3 – Specifications of script fields

Field name Description
LaunchTimeMS (Integer) Event time in milliseconds, rounded to nearest hundredth of a second
LaunchTimeText (String) Event time in the format 00:00:00.00
ScriptTimeMS (Integer) Effect time in milliseconds, rounded to nearest hundredth of a second
ScriptTimeText (String) Effect time in the format 00:00:00.00
DelayTimeMS (Integer) The value 0 (different for SEM files; see below)
DelayTimeText (String) The value “00:00:00.00” (different for SEM files; see below)
Slat (Integer from 1 to 99) Module address number
Cue (Integer from 1 to 32) Pin address number
Position (String, up to 10 UTF-16 code units) Launch position names, separated by spaces; but truncated to 10 characters in accordance with the file format restrictions
Qty (Integer) Number of devices
Priority (Integer from 1 to 16) Safety/hazard group number from the “Lockout” column, 1 by default
Description (String, up to 60 UTF-16 code units) The first effect names, preceded by a count in parentheses of the number of devices combined on this row if more than one
Comment (String, up to 60 UTF-16 code units) Combined notes from all rows in the Finale 3D script associated with this module-pin combination, with redundant notes eliminated, separated by spaces
ProductNumber (String, up to 16 UTF-16 code units) The part number of the effect, or the first effect if there are more than one; the first effect being arbitrarily chosen if there are multiple effects at the same time for this module-pin combination
Size (String, up to 8 UTF-16 code units) The caliber with or without units, e.g., 3 or 3″ or 75mm (least caliber if multiple effects)
Event (Integer) The value 0 (different for SEM files; see below).  Ignored when importing FIR files.
Effects (String, up to 16 UTF-16 code units) The angle of the first shot, printed as signed integer.  Angles exported from Finale 3D follow the convention that 0 is up and negative numbers are to the left.  Angles imported into Finale 3D follow that convention by default, but the user has the option of selecting a different angle convention at time of import.
Duration (String, unknown length limit) This field is not exported by Finale 3D, but it is imported.  When imported, it is interpreted as the duration of the effect, if the field is not empty.  The units (milliseconds, seconds, etc.) can be specified by the user at the time of importing. If the field is empty, Finale 3D will generate a default duration based on the effect type and size.
Location (String, unknown length limit) This field is not exported by Finale 3D, but it is imported as the “Storage Location” field.
Cost (String, unknown length limit) This field is not exported by Finale 3D, but it is imported as the “Cost” field.

The firing rows in an SEM file are the same except for these changes:

 

Table 4 – SEM file differences

Field name Description
Field name Description
DelayTimeMS (Integer) Event time delta from the first firing row in the triggered sequence, in milliseconds rounded to nearest hundredth of a second
DelayTimeText (String) Event time delta in the format 00:00:00.00
Event (Integer from 1 to 999) Track number, or 1 if no track number

An example SEM script file is shown below, with the vertical bar (|) separating fields.  This example consists of two tracks, each with nine consecutive shots separated by 0.1 seconds.  Scrolling to the right, you can see the last numerical field in each row, which is the Event field, representing the track, is “1” for the first nine rows and “2” for the second nine rows.  You can also see, in approximately the middle of the rows, that the DelayTimeMs fields of the rows are 0, 100, 200, … 800, 0, 100, 200, … 800, reflecting the fact that the first event in each track has a delay time of zero, and the subsequent rows in the track have delays that increase by 100ms.

ID|ScriptTime|Position|Qty|BreakTime|Duration|Priority|Cost|Location|Comment|LaunchTime|Description|ProductNumber|Size|Color|VendorNumber|Type|ScriptTimeMS|LaunchTimeMS|DelayTimeMS|ScriptTimeText|LaunchTimeText|DelayTimeText|Effects|Event|Slat|Cue|Length|SayWhen|SayWhenText|SayWhat|Conflict|PyroSlat|PyroCue
2||Pos-01|1|||1||| |0.0|extérieur vert centre bleu|P1249|3.94||||5000|1720|0|00:00:05.00   |00:00:01.72   |00:00:00.00   |-45   |1|1|1|||||||
3||Pos-02|1|||1||| |0.0|extérieur vert centre bleu|P1249|3.94||||5100|1820|100|00:00:05.10   |00:00:01.82   |00:00:00.10   |-34   |1|2|1|||||||
4||Pos-03|1|||1||| |0.0|extérieur vert centre bleu|P1249|3.94||||5200|1920|200|00:00:05.20   |00:00:01.92   |00:00:00.20   |-22   |1|3|1|||||||
5||Pos-04|1|||1||| |0.0|extérieur vert centre bleu|P1249|3.94||||5300|2020|300|00:00:05.30   |00:00:02.02   |00:00:00.30   |-11   |1|4|1|||||||
6||Pos-05|1|||1||| |0.0|extérieur vert centre bleu|P1249|3.94||||5400|2120|400|00:00:05.40   |00:00:02.12   |00:00:00.40   |      |1|5|1|||||||
7||Pos-06|1|||1|||note1|0.0|extérieur vert centre bleu|P1249|3.94||||5500|2220|500|00:00:05.50   |00:00:02.22   |00:00:00.50   |11    |1|6|1|||||||
8||Pos-07|1|||1|||note2|0.0|extérieur vert centre bleu|P1249|3.94||||5600|2320|600|00:00:05.60   |00:00:02.32   |00:00:00.60   |23    |1|7|1|||||||
9||Pos-08|1|||1|||note3|0.0|extérieur vert centre bleu|P1249|3.94||||5700|2420|700|00:00:05.70   |00:00:02.42   |00:00:00.70   |34    |1|8|1|||||||
10||Pos-09|1|||1||| |0.0|extérieur vert centre bleu|P1249|3.94||||5800|2520|800|00:00:05.80   |00:00:02.52   |00:00:00.80   |45    |1|9|1|||||||
11||Pos-01|1|||1||| |0.0|extérieur vert centre bleu|P1249|3.94||||10000|6720|0|00:00:10.00   |00:00:06.72   |00:00:00.00   |-45   |2|1|2|||||||
12||Pos-02|1|||1||| |0.0|extérieur vert centre bleu|P1249|3.94||||10100|6820|100|00:00:10.10   |00:00:06.82   |00:00:00.10   |-34   |2|2|2|||||||
13||Pos-03|1|||1||| |0.0|extérieur vert centre bleu|P1249|3.94||||10200|6920|200|00:00:10.20   |00:00:06.92   |00:00:00.20   |-22   |2|3|2|||||||
14||Pos-04|1|||1||| |0.0|extérieur vert centre bleu|P1249|3.94||||10300|7020|300|00:00:10.30   |00:00:07.02   |00:00:00.30   |-11   |2|4|2|||||||
15||Pos-05|1|||1||| |0.0|extérieur vert centre bleu|P1249|3.94||||10400|7120|400|00:00:10.40   |00:00:07.12   |00:00:00.40   |      |2|5|2|||||||
16||Pos-06|1|||1||| |0.0|extérieur vert centre bleu|P1249|3.94||||10500|7220|500|00:00:10.50   |00:00:07.22   |00:00:00.50   |11    |2|6|2|||||||
17||Pos-07|1|||1||| |0.0|extérieur vert centre bleu|P1249|3.94||||10600|7320|600|00:00:10.60   |00:00:07.32   |00:00:00.60   |23    |2|7|2|||||||
18||Pos-08|1|||1||| |0.0|extérieur vert centre bleu|P1249|3.94||||10700|7420|700|00:00:10.70   |00:00:07.42   |00:00:00.70   |34    |2|8|2|||||||
19||Pos-09|1|||1||| |0.0|extérieur vert centre bleu|P1249|3.94||||10800|7520|800|00:00:10.80   |00:00:07.52   |00:00:00.80   |45    |2|9|2|||||||

Figure 1 – Example FireOne SEM script for semi-automatic firing

 

Table 5 – Example files

Download link Explanation
fireone_tiny_fir.fir Example exported FIR file
fireone_tiny_sem.sem Example exported SEM file
fireone_tiny_fir.fin Example show file addressed for start-to-end firing (FIR)
fireone_tiny_sem.fin Example show file addressed for semi-automatic firing (SEM)