EXAMPLES SOFTWARE > INSTRUNET WORLD PLUS SOFTWARE (iW+) >
For a tutorial on scripting, click here. For a list of several example iW+ instruments, click here; and for details on these examples, keep reading.
How to View and Run an Example Script File
To view an example script file included with iW+: select the Script Page (i.e. press the Script tab),
select "After Test Script" in the upper popup menus, click the Open button, select an example script
file in the "..program files \ instruNet \ instruNet World+ \ Example Scripts (.iBs) \ · " directory.
If you want to execute this script, press the Script page Execute button.
Digitize multiple channels into RAM memory and save to disk post acquisition, possibly to Microsoft-Excel
Instrument "Record 2Ch to RAM.prf" illustrates a simple case where one presses the Start button to begin recording any number of channels at a user defined rate and duration, and presses the Stop button to stop recording. One would then press the Save As button to save the waveforms to disk post-acquisition (in fast, compact, binary format), and/or select the Save Waveforms to Excel menu command (only available on iW+) to save the waveforms to disk in one large text file named "Excel Waveform Data.txt". These waveform files may later be opened by Microsoft Excel (each wave is given its own column) post acquisition.
To view the data at a later date with instruNet world, one would select Open Waveforms in the Record menu and then select the previously saved binary file. To view the data with Excel, one would run Excel, and then open the previously saved "Excel Waveform Data.txt" text file by selecting Open in the File menu within Excel, pathing to where the file was saved too and selecting it. In this file, columns are separated by tabs, and rows are separated by carriage returns. For details on the maximum I/O rates, click here.
To open this instrument: Press the Open button in the Network page, and then select file "..program files \ instruNet \ instruNet World+ \ Example Instruments (.prf) \ Record 2Ch to RAM.prf".
To create this instrument from scratch:
Start with a new instrument by selecting New Setup in the Setup menu.
Select Network page by clicking Network tab at bottom of window.
Select any number of channels for digitizing. This may be done by clicking on the rectangle in the 4th column which will turn red.
Select Record page by clicking on the Record tab.
Open the Record Setup dialog by clicking Setup button.
Set the sample rate field in units of samples-digitized-per-second-per-channel.
Set the number of Scans field to 1 (i.e. load one RAM buffer of data and then stop digitizing).
Set the Scan Mode field to Strip Chart.
Set the # of points field as desired (total acquisition time in seconds = SampleRate * NumberOfPoints.
Click OK and then Save the new instrument file (select Save Setup As in Setup menu).
Digitize Waveforms directly to Disk (for cases where RAM is not large enough)
This is similar to the steps outlined in instrument "Record 2Ch to RAM.prf" described above,
however the Record Setup dialog's (click Setup button in Record page) Digitize Into field is set to "To File", the File Type
field is set to "Binary Merge", and the # of Scans field is larger than 1. For details on this, please
see Sample Rate Vs. Integration Time Vs. Noise
and Digitze to RAM or File?. Note: Waveforms larger than RAM memory are more
difficult to handle (e.g. you cannot load them into Excel); therefore, one should only use this real-time spooling to
disk technique if direct to RAM recording (as described in the previous example) is not feasible
(e.g. due to RAM memory not being large enough to hold all data).
Output Waveforms that are defined with Mathematical Equations
Example instrument "Waveform Generation Example.prf" outputs a sine wave from Vout3, a square plus sine wave from Vout6, a repeating pulse train from Vout9, a single pulse from Dout1, and a square wave from Dout3. Additionally this instrument digitizes the waves applied to Vin1, Vin4, and Vin7. If one attaches these inputs with a wire to the outputs being driven by iW+, then one can read back, view, and test the output waveforms.
In this example, we digitize at 10 samples/second/channel (Sample Rate in Record Setup dialog set to 10) and
we output at a rate of 10 samples/sec/ch (Control Rate field in Script Options dialog
set to 10). Vout3 outputs a 4V amplitude 0.5Hz sine wave (Control calculate field
set to sinewave(4, 0.5)). Vout6 outputs a 2V amplitude 0.1Hz square wave plus 1V amplitude
3Hz sinewave minus 3 (Control calculate field set
to (squarewave(2, 0.1) + sinewave(1, 3)) - 3); Vout9 repeatedly outputs a
pulse train that is 0V for 1sec, then ramps to 4V in 2sec, followed by two pulses of duration 2sec (3V) and 1sec (0.5V)
(Control calculate field set to gen(flat, 0, 1, ramp, 4, 2, flat 3, 2, flat 1, .5, recycle, 1));
Dout1 outputs a 2sec On 3sec Off one time pulse (Control calculate field set to
gen(flat, 1, 2, flat, 0, 3 ));
and Dout3 outputs a 1Hz square wave (Control Script
contains Dio3_Bit! = (0 < squarewave(1, 1))<).
Notice that Dout3 is defined in the Control Script; whereas the other outputs are defined in Control Calculate fields.
Channel Names
In this example, the User Names for each channel were changed from their defaults to easier to read names (e.g. "Ch1Vin+" was changed to "Vin1", "Ch3 Vout" was changed to "Vout3", "Dio1 Bit" was changed to "Dout1", "Dio2 Bit" was changed to "Din3", etc). For details on referencing channel names in script code, click here.
Setting Digital I/O Bits to be an Input or Output
In this example we use the i100 bi-directional Dio1 Bit through Dio4 Bit channels to output and input digital bits. Since these are bidirectional, we specified their directions in the Bit Options area of the Channel Options dialog. To view and/or adjust a direction, select a Dio Bit channel in the Channel Options submenu within the Hardware menu, select Bit Options in the Settings submenu within the Channel Options dialog, and then adjust the Direction field to either Input (i.e. read bit into computer) or Output (i.e. output 0 or 1 from computer).
To Run this Instrument: Press the Open button in the Network page, select file "...\ program files \ instruNet \ instruNet World+ \ Example Instruments (.prf) \ Waveform Generation Example.prf", select the Record page (press Record tab), press the Start button to begin I/O operation, and press the Stop button to stop.
Example instrument "Control Example.prf" is similar to the previous example of "Waveform Generation Example.prf". The difference is that we added 2 output channels that are a function of inputs. Dout5 is high (1) if Vout3 (our sine wave) plus Vin1 is > 2V (Dout5 Control Calculate field set to ((Vout3! + Vin1!) > 2)); and Vout12 is defined in a PID feedback loop (Control Calculate field set to Limit(Vin7!, 1, 2)).
To Run this Instrument: Press the Open button in the Network page, select file "...\ program files \ instruNet \ instruNet World+ \ Example Instruments (.prf) \ Control Example.prf", select the Record page (press Record tab), press the Start button to begin I/O operation, and press the Stop button to stop.
Display Numerical values While Digitizing
Example instrument "Control Example + Panel Meters.prf" is similar to "Control Example.prf", described above, yet it also displays numerical values in real-time. Several numerics are Panel Meters, which are real-time numeric displays that correspond to specific analog or digital input or output channels; and some are Dynamic Text fields, which are updated in the script language with a "FieldName$ = ..." line of code. For example, if a text field was named "Field1", then Field1$ = "abc" in a script would cause the field to display "abc", until its next update.
In this example instrument, text field "Pump1" is defined as Vin1 multiplied by Vin4 and is updated 2 times each second. This is implemented with a Pump1$ = (Vin1! * Vin4!) line of code in the User Script (click Script tab, and then select After User Event in upper popup menus) and with the User Rate field in the Script Options dialog set to 2 updates-per-second. The Pump1 field was created by selecting Create Panel Item > Text Field in the Setup menu.
This example instrument also displays digitize state variables in the upper-left corner while digitizing. For example, the "# Missed C Evts" field shows the # of missed control events since beginning the digitization. These upper-left corner text fields are updated with assignment equations in the After User Event script. For example numMissed_cEvts! = NumControlEventsMissed copies the NumControlEventsMissed digitize state variable into a Record page field named "numMissed_cEvts". For details on all real-time digitize state variables, click here. For details on maximum I/O rates, click here.
To Run this Instrument: Press the Open button in the Network page, select file "...\ program files \ instruNet \ instruNet World+ \ Example Instruments (.prf) \ Control Example + Panel Meters.prf", select the Record page (press Record tab), press the Start button to begin I/O operation, and press the Stop button to stop.
Copy Channel Settings from one Channel to Multiple other Channels
Setting up many channels (e.g. >16) manually in the instruNet World Network page can be laborious. As an alternative, one can setup one channel manually (e.g. for strain gage, thermocouple, etc); and then copy that setup to many other channels in one button press. This is done with the iW+ CopySettings command. To see this in action, setup Ch1 Vin+ as a Thermocouple (Select Ch1 Vin+ in the Channel Options submenu within the Hardware menu, select Thermocouple in the Sensor field, press OK to accept the recommendations, and then exit the Channel Options dialog). The next step would be to select the Script page (i.e. press the Script tab), select After Test Script in the upper popup menus, click the Open button, select file "...\ program files \ instruNet \ instruNet World+ \ Example Scripts (.iBs) \ Copy Channel Settings.iBs" to load this script (shown below), and then press the Execute button to run the script and copy Ch1's settings to several other channels. To view your work, select the Network page (press Network tab), and notice how 8 channels are setup for Thermocouple.
; Copy the settings from one channel to each of the
; destination channels.
CopySettings ch1_vin+, destinationChannels#
Create Custom Instrument With Limited Capabilities
In some cases, it is helpful to create an instrument with limited functionality (i.e. fewer buttons and fewer menu commands), to the degree that the end user may only do what is intended by the person who creates the instrument. This is done by hiding the menubar (i.e. set Menubar field to Hide after selecting Window Options in Setup menu), hiding pages (via Hide PageName script code), hiding buttons as desired (via Hide PageNameButtonName script code), and selecting a page (e.g. Record) in which to begin (via Select PageNamecode). To show the menubar and pages (i.e. tabs at bottom of window) after they are hidden, one can press keys CONTROL SHIFT 'M'.
For example, please load file "...\ program files \ instruNet \ instruNet World+ \ Example Instruments (.prf) \ Record 2Ch to RAM, Limited Buttons.prf" (i.e. Select Open in Setup menu). Notice that only the Record Start and Stop buttons are present. Here, the operator can Record waveforms and view them, yet is disallowed from changing the channel settings. To see how we did this, press CONTROL SHIFT 'M', select the Script page (press Script tab), and select After Load Settings in the upper popup menus. This script, shown below, is executed after loading the instrument (i.e. .prf file), and is used to hide buttons, tabs, and the menubar.
Hide Menubar
; hide entire menubar
Hide Network
; hide several tabs
Hide Test
Hide Script
Hide Record Open
; hide several buttons
Hide Record Save
Hide Record Setup
Hide Record Print
Select Record
; select Record page
To do this to one of your own instruments: Set up your channels as desired, paste the above text into the After Load Settings script, edit this script as desired, and then save your new instrument (select Save As in Setup menu). Try loading it back in (select Open in Setup menu), and notice how many of controls are hidden. To see them, press CONTROL SHIFT 'M'.
To automatically load this .prf instrument file when one launches the iW+ application program, click here.
Log to Disk or Text Editor while Digitizing Example
This example instrument digitizes multiple channels at the rate set in the Record Setup Sample Rate field, and plots them in the Record page; yet also, simultaneously, at a slower rate, writes a row of channel values to a file on disk or to the Data Page (click Data at bottom of screen), while digitizing. Each channel is given its own column, and each row shows the values of these channels at one place in time. The resulting data is easily loaded into a spreadsheet program such as Excel. Two panel meters are also shown in the Record page.
To see this in action, load file "...\ program files \ instruNet \ instruNet World+ \ Example Instruments (.prf) \ Log To Disk While Digitizing.prf" (i.e. Select Open in Setup menu), press the HELP tab at the bottom of the window, read to learn how this works, press the Record page Start button, wait 3 seconds, press Stop, and then press the Data tab to see the log result.
The following code creates a button called "Record", that when pressed, digitizes 3 points from several channels and prints the results to the instruNet World Test page, in a table-like format. As shown below, each channel has its own column and each dataset its own row.
Ch1 Vin+
Ch4 Vin+
Volts
Volts
1.231531e-2
3.976332e0
1.899534e-2
2.453343e0
The code that produces this table, in real-time, is shown below:
NewButton Test "Record"
; create a new button in the Test Page
; tell user what we are going to do Alert "We are now going to record. Press Mouse to Stop."
; print the following to the Test page:
; XYZ Data: date=xx/yy/xz, time=pp:dd:qq Print Test "\rXYZ Data: date=" date ", time=" time "\r\r"
Calibrate Hardware
; calibrate all instruNet hardware
; define a list of channels Define MYCHAN# "1/1/1/1, 1/1/1/4"
; print header to the Test page Table MYCHAN# general user_name Test "\t" "\r" 16
Table MYCHAN# general units_label Test "\t" "\r" 16
; print the value of each channel in the list one row at a time,
; one row per second, 3 rows (3 secs), mouse down to stop Loop 3 1 mouseStop
Table MYCHAN# general value_input Test "\t" "\r" 16
Endloop
EndButton
The NewButton Test "Record" command defines a new button.
The two parameters after NewButton are the instruNet
World page name (e.g. Test, Script, new-user-page1, etc) and the new button name. When this button is
pressed, the code between the NewButton command and EndButton
command (i.e. the "body") is executed. This button causes about 10 lines of code to be executed.
The ";" and "//" characters indicate that a comment follows, and is ignored by the interpreter. The
first command is an Alert that displays the text in quotes in
an alert box. Alerts are helpful at guiding the user during an experiment. The above
Print command prints several lines of text to the Test page. The first
Print parameter refers to a page followed by quoted text which is printed as is. Keywords like 'time' and 'date' are
substituted with the current time or date. The "\r" and "\t" within the quoted text are replaced with a carriage
return and tab, respectively.
The Calibrate Hardware command tells instruNet to calibrate
all hardware and to correct for any minute temperature related drifts in the measurement circuitry, which is a
nice thing to do before acquiring data.
The Define statement specifies a list of channels and assigns the
name MYCHAN# to that list. Each channel is referred to by
its network#/ device#/ module#/ channel# address. For example, 1/1/1/4 refers to Ch4 in Module #1, of Device #1,
attached to Network #1. The list of channels can be quite long, and are referred to with a Define name, which is a
unique word that ends in a "#" character. The Define statement can be used to consolidate a long string into one word,
and when that word later appears in the code, the interpreter substitutes the Define text for that word.
The Table command line prints a field's value for a list of channels. The
first Table command in the above example prints the channel name field. The second Table command prints the units-label
field, while the third Table command prints the value of each channel three times (due to the
Loop 3 1 mouseStop). The "\t" "\r" 16
in the Table commands tells the interpreter to place a tab between each column, a carriage return at the end of the row,
and pad each point with spaces so that each point consumes exactly 16 characters.
The Loop command tells the interpreter to execute the body of the loop 3 times,
at a rate of once through the loop every 1 second, and a mouse down will cause the interpreter to fall out of the loop
(to allow the user to stop early).
Another way to stop execution is to press the Stop button in the Script page, or press keys CONTROL 'S'.
Another way to digitize, is to use the Digitize command, which
consolidates the loop and table commands into 1 line of code, and is capable of moving data faster, as noted
here.
The code below prints the value of several channels and then enters a feedback loop. The loop runs until the mouse is pressed. An example of printed output text is shown below. The value of channel Ch1 Vin is printed once a second on the last line of the printout.
Ch1 Vin
= -1.9359991
Ch3 Vout
= 0.5221114754677
Ch25 Dig In
= 231
Cycle
Chan#1
4
-0.256
The ch1Value! = Ch1_Vin+! line reads the value of channel Ch1 Vin into variable ch1Value!. The following print command prints the loop number in 5 integer digits, and then prints Ch1 in floating point format with 3 digits to the right of the decimal. The Synchronize 1 command causes the loop to execute once each second. The following code sets outputs depending on the state of channel Ch1 Vin.
For the source code to this example, please View and/or Run file "...\ program files \ instruNet \ instruNet World+ \ Example Scripts (.iBs) \ Read and write to channels.iBs".
The code below sets up a batch of strain gages and a batch of thermocouples. For source code similar to this example, please View and/or Run file "...\ program files \ instruNet \ instruNet World+ \ Example Scripts (.iBs) \ Set up channels - digitize - spool to disk.iBs".
Define GAGES# "1/1/1/1, 1/1/1/4"
; strain gages channels
Define TCs# "1/1/1/7, 1/1/1/10"
; thermocouples channels
Define THs# "1/1/1/13, 1/1/1/16"
; thermistor channels
Define VRs# "1/1/1/19, 1/1/1/22"
; voltage ratio potentiometers
NewButton Data "Setup"
; ==== SETUP STRAIN GAGES ====
SetF GAGES# Hardware Sensor Strain_Gage
; sensor type
SetF GAGES# Hardware Wiring Q_Bridge
; wiring type
SetF GAGES# General Units_Label "µStrain"
; vertical units label
SetF GAGES# Mapping Scale 1.0e6
; Internal to External EU mapping
SetF GAGES# Hardware Integrate 0.016
; integration each channel for 16ms
SetF GAGES# Constants Ro 350
; bridge resistance, in ohms
SetF GAGES# Constants GF 2.155
; strain gage factor
SetF GAGES# Constants "delta,_Rlead" 3.8
; bridge lead resistance
SetF GAGES# Constants Vout 4.5
; excitation output voltage
SetF GAGES# Hardware Range "+- 10mV"
; Voltage input range, in Volts
SetF GAGES# Display Display_Max +4000
; Display Top, in Eng. Units
SetF GAGES# Display Display_Min -4000
; Display Bottom, in Eng. Units
; ==== SETUP THERMOCOUPLES ====
SetF TCs# Hardware Sensor T_Thermocpl
; sensor type
SetF TCs# Hardware Wiring "Vin+ - Vin-"
; wiring type
SetF TCs# General Units_Label "C"
; vertical units label
SetF TCs# Hardware Integrate 0.016
; integrate each channel for 16ms
SetF TCs# Hardware Range "+- 10mV"
; Voltage input range, in Volts
SetF TCs# Display Display_Max +100
; Display Top, in Eng. Units
SetF TCs# Display Display_Mi 0.0
; Display Bottom, in Eng. Units
; ==== SETUP THERMISTORS ====
SetF THs# Hardware Sensor Thermistor
; sensor type
SetF THs# Hardware Wiring "Voltage Divider"
; wiring type
SetF THs# General Units_Label "C"
; vertical units label
SetF THs# Hardware Integrate 0.001
; integrate each channel for 16ms
SetF THs# Constants Ro 2252
; thermistor 25C resistance, in ohms
SetF THs# Constants Rshunt 4700
; shunt resistor, in ohms
SetF THs# Constants Vinit 0.0
; min temp C (this affects Vrange)
SetF THs# Constants V_Poisson 70
; max temp C (this affects Vrange)
SetF THs# Constants alpha 0.00147253
; steinhart A
SetF THs# Constants "delta, Rlead" .000237371
; steinhart B
SetF THs# Constants GF 1.06442e-007
; steinhart C
SetF THs# Constants Vout 0.55
; excitation output voltage
SetF THs# Hardware Range "+- .6V"
; Voltage input range, in Volts
SetF THs# Display Display_Max +70
; Display Top, in Eng. Units
SetF THs# Display Display_Min 0.0
; Display Bottom, in Eng. Units
; -- SETUP VOLTAGE RATIO POT-
SetF VRs# Hardware Sensor Voltage
; sensor type
SetF VRs# Hardware Wiring Bridge
; wiring type
SetF VRs# General Units_Label "V/V"
; vertical units label
SetF VRs# Hardware Integrate 0.001
; integrate each channel for 1ms
SetF VRs# Constants Vinit 0.0
; Calibation voltage
SetF VRs# Constants Ro 5000
; vout's load, in ohms
SetF VRs# Constants Vout 5
; excitation output voltage
SetF VRs# Hardware Range "±5V"
; Voltage input range, in Volts
Alert "Thank you. All channels are now set up. Press the Network tab to view the settings."
EndButton
This example makes extensive use of the SetField command (abbreviated "SetF"). The syntax for the SetField command is:
The first parameter of the SetField command refers to a list of channels. This could be one channel (e.g. 1/1/1/4, Ch1_Vin+), a list of channels (e.g. "1/1/1/1, 1/1/1/4, Ch7_Vin+"), or a define name# that was previously set to either of these. The above example uses two channel lists, one for strain gages, and one for thermocouples. The second SetField parameter is the Setting name (e.g. General, Constants, Hardware), which corresponds to the Settings popup choices inside the Network page Channel Setup Dialog. The third parameter is the field name, which corresponds to the names of the fields in the Channel Setup Dialog. The forth parameter is the new value for the field, which is set for all channels in the specified list.
The following example creates a button that balances the strain gage channels when pressed. Balancing involves measuring the voltage across the bridge when the gage is unstrained (i.e. 0 µStrain) and then loading this value into the Vinit field within the Constants setting group.
NewButton Test "Balance"
; create new button in Test page
Alert "Please apply 0 strain and then press OK."
Calibrate GAGES# Vinit
; balance all strain gages
Alert "Thank you. That was good."
EndButton
The "Calibrate chList Vinit" command loads the Vinit field with the voltage at the channel screw terminals, for every channel in the chList, and subsequently balances the bridges with one line of code. If one did "Calibrate chList Int1", then the value of each channel would be loaded into the Mapping Internal1 (or Internal2 if Int2 was specified) field, to facilitate a two point calibration.
File I/O Example
The code below creates a button called "Save As" that saves the contents of the Test page to disk in a text file.
NewButton Test "Save As"
; create new button in Test page
Create "MyNewFile" showDialog
if (FileOk == false) then end
; create a new file via Save dialog
; if user pressed CANCEL, stop the script
Copy Test MyNewFile
; copy contents of 'Test' page into the file
Close MyNewFile
; close the file
EndButton
The Create command creates a new file on disk. The first parameter is the file's name, and subsequent code must reference this file by this internal filename. The second parameter is a keyword that specifies the directory in which the file is saved. Keyword 'showDialog' instructs the interpreter to show the File Save dialog, and let the user decide where to place the file. Other directory keywords are 'appDir', which refers the same directory as the application file; 'osDir', which refers to the Operating System directory where the instruNet driver is kept; and 'masterDir', which is a global pathname that can be moved to any folder via the SetMasterDir command. The Copy command is capable of copying text from a page, file, variable!, string$, define#, numerical constant, or text in quotes; into a page, open file, or string$. In the this example, the Copy command copies the contents of the Test page into a new, open, file; and the Close command closes this open file when finished.
In general, files must first be established with the Create or Open command. Create creates a new file, whereas Open opens an existing file. Once a file is open, it is read to or written from via the Print, Table, Digitize, Clear, Copy and Append commands. Then, when finished, it must be closed with the Close command. To close all open instruNet files, use Close All. In general, one can write data either to an instruNet text window, or to an open file. The text windows provide visual feedback, whereas direct to text file is faster and disk based files can be up to 2GBytes in length. For an example of file I/O, please View and/or Run file "...\ program files \ instruNet \ instruNet World+ \ Example Scripts (.iBs) \ Read and write Files.iBs".
Spool to disk via Digitize & Table script commands
Both the Table and Digitize commands can send a data to the instruNet World text editor, or a file on disk of up to 2GBytes in size. For an example of the these commands, please see Tutorial Data Acquisition Example.
Programming Example
The code below shows an example of the For, Loop, While, Goto/Label, If/Then, and If/Elseif/Else/Endif commands.
The For command facilitates a loop with a loop variable. The If / [elseif] / [else] / endif commands allow one to make decisions. While continues to loop while the test case is true; while, Loop loops a fixed number of times. Goto jumps to a Label, and labels are simply a unique word, suffixed with a ":" character. For an example use of these commands, please View and/or Run file "...\ program files \ instruNet \ instruNet World+ \ Example Scripts (.iBs) \ Demonstrate Programming Functions.iBs".