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:

1. Start with a new instrument by selecting New Setup in the Setup menu.
2. Select Network page by clicking Network tab at bottom of window.
3. Select any number of channels for digitizing. This may be done by clicking on the rectangle in the 4th column which will turn red.
4. Select Record page by clicking on the Record tab.
5. Open the Record Setup dialog by clicking Setup button.
6. Set the sample rate field in units of samples-digitized-per-second-per-channel.
7. Set the number of Scans field to 1 (i.e. load one RAM buffer of data and then stop digitizing).
8. Set the Scan Mode field to Strip Chart.
9. Set the # of points field as desired (total acquisition time in seconds = SampleRate * NumberOfPoints.
10. Click OK and then Save the new instrument file (select Save Setup As in Setup menu).

• Sample Rate Vs. Integration Time Vs. Noise
• Digitze to RAM or File?

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.

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.

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.

Related Topics: Control and Waveform Generation, Feedback and Waveform Generation Math, Maximum I/O rates, Control Script, Control Calculate field, Working with instruNet Hardware Channels, Working with Digital I/O Bits, SineWave() function, and Gen() function.

Feedback / Control Loop Example

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.

Related Topics: Panel Meters, Dynamic Text, User Script.

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.

define destinationChannels# = "
1/1/1/4, 1/1/1/7, 1/1/1/10,
1/1/1/13, 1/1/1/16, 1/1/1/19, 1/1/1/22
"

; 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 PageName ButtonName 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.

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.

Related Topics: Show/Hide Page, Show/Hide Button, Show/Hide Menubar and Select commands.

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.

Related Topics: Working with Files.

Print Digitized Channels Example

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.

The code that produces this table, in real-time, is shown below:

; 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"

; 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.

Related Topics: Working with instruNet Hardware.

Feedback Control and Print Example

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.

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".

print "\rCh1 Vin = " (Ch1_Vin+!)
print "\rCh3 Vout = " (Ch3_Vout!)
print "\rCh25 Dig In = " (Ch25_Dio_Group!) "\r"
print "\rCycle Chan#1\r"
cycle! = 0

; print formatted Ch1 Vin channel
print %5d:cycle! " " %+2.3f:ch1Value!

endwhile
end

Related Topics: Control and Waveform Generation, Feedback and Waveform Generation Math, Maximum I/O Rates, Working with instruNet Hardware.

Channel Setup and Calibration Example

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".

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:

SetField chList, settingsGroup, fieldName, newFieldValue

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.

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.

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".

Related Topics: Working with Files, FileOk file error variable.

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.

for f! = 1 to 3

; ==================================
; If...Elseif...Elseif...Else

print "\r"

if (f! == 1)
    print "f! = 1"
elseif (f! == 2)
    print "f! = 2"
else
    print "f! > 2"

; ==================================
; one line If...Then...

if (f! == 2) then print ", inside-if"

; ==================================
; While ()... Endwhile

w! = 0
while (w! < 2)

w! = w! + 1
print ", w! = "w!

endwhile

; ==================================
; Loop

i! = 0
loop 2

  print ", i! = " i!

endLoop

; ==================================
; Goto...Label

goto LabelOne

LabelTwo:

    Next
    End

LabelOne:
    print ", inside goto."
    Goto LabelTwo

When this code is executed, the following text is printed:

f! = 1, w! = 1, w! = 2, i! = 0, i! = 0, inside goto.
f! = 2, inside-if, w! = 1, w! = 2, i! = 0, i! = 0, inside goto.
f! > 2, w! = 1, w! = 2, i! = 0, i! = 0, inside goto.

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".

Tutorial Examples

Click here for the Scripting Tutorial examples.