Command Syntax
The iW+ script language supports many commands (e.g. Beep, Alert, Print), each of which are followed by zero or more parameters. Parameters are separated by spaces (" ") or commas (", "). For example, commandName param1 param2 and commandName param1, param2 are identical. Commands typically reside on one row within a script and; unless a parameter is in quotes, capitalization is ignored (e.g. prInt and PRiNT are the same). One parameter cannot contain a space (" ") character; otherwise the script interpreter would think you have two parameters. To indicate a space, underscore characters "_" are sometimes substituted (e.g. print Test ch1_vin+! prints channel Ch1 Vin+'s value to the Test page). If you want spaces or you want to retain capitalization, the entire parameter must be enclosed in quotes "..." (e.g. Print "Hello ! ?").
Commands, Functions, Operators, and Keywords
The iW + script language provides Commands, Functions, Operators, and Keywords; all of which are similar. Commands and Functions both include an instruction name, followed by a list of parameters. The difference is that Functions return a value and the arguments are surrounded by parenthesis (e.g. y! = abs(x!) calculates the absolute value of variable x!) and Commands do not return a value and do not use parenthesis (e.g. alert "hello" shows an alert). Another difference is that Commands are given their own line within a script (i.e. one row); and Functions are often embedded in a mathematical expression, which may be passed as an argument to a Command. For example, a line of code such as Print (abs(x!)) involves one command (Print), one math expression ((abs(x!))), and one Function within that math expression (abs()).
A Keyword is similar to a Function, yet it has no arguments. For example, keyword cMonth returns the current month number. For example, executing Print (cMonth) in April would print 4. For a list of keywords, click here.
Lastly, an Operator (e.g. +, -, *, /, <, >, ...) mathematically combines two parameters, and returns one value. For example Operator "+" is used in mathematical expression (3 + 2) to return 5. For a list of operators, click here.
Script Engine Objects
iW+ contains an internal database of variables!, strings$, and defines#. String names must be suffixed with the "$" character, variables names with the "!" character, and define names with the "#" character. These objects are global -- any script can set, or read, any object. They are non-volatile in that they remain alive even when a script stops executing (so that another script can use them). Script code Delete Variables and the Reset All Scripts command in the Script menu deletes all objects in the database. Script code Clear Variables sets all variables! to 0.0, and all strings$/defines# to no-text (""). Script objects are described in more detail below:
Variables! are stored internally as 8 byte floating point numbers (15 digit mantissa, ±307 exponent). Variable names are suffixed with a "!" character (e.g. "var!", "x!"), and are often defined with an equals ("=") sign (e.g. var! = 3.2) . Variables can be passed as parameters to functions (e.g. Loop ctr!) and many commands support variables as destination or source arguments (e.g. print (abs(a! + b!))).
Strings$ contain a string of text, of any size, memory permitting. String names are suffixed with the "$" character (e.g. "str$", "name$"), and are often defined with an equals ("=") sign (e.g. str$ = "initialText") . Strings can be passed as parameters to functions (e.g. v! = sin(str$ + 2)) and many commands support strings as destination or source text (e.g. copy x$ y$ copies the text in string x$ to string y$). If you want to load a string$ with a number, place brackets "( )" around the source expression, to tell the Script interpreter to calculate a numerical value. For example, str$ = (abs(-1.5)) loads str$ with 1.5, not text "abs..".
Defines# are like strings, yet can only be set once and their names end in a "#" character. For example, Define MyChannels# "1/1/1/1, 1/1/1/4, Ch7_Vin+" allows one to use the name MyChannels# later in the code to refer to the list of channels. An equals ("=") character within a define declaration is optional (e.g. Define a# "abs" is the same as Define a# = "abs").
Referencing Segments within a String$ or Define#
Brackets following a string or define name identify a segment. For example, if str$ = "abcde", then print str$[1, 3] will print "bcd". The brackets contain two parameters separated by a comma "," where the first parameter refers to the base 0 index of the segment's first character; and the second parameter refers to the base 0 index of the segment's last character. Base 0 means the first character in a string is referred to as index #0. For example, with "abcde"; "a" is at index 0, "b" at index 1, "d" at index 3, etc.
"Text"
Quotes are used to encapsulate text that retains spaces & capitalizations. For example, Alert "Is anyone there?" displays the quoted text exactly as shown. If text is not in quotes, space characters indicate a new parameter and capital letters are converted to lower case by the script interpreter. Subsequently, non-quoted code is not sensitive to lower-case/upper-case discrepancies (e.g. Alert "hi" and AlErt "hi" are the same).
Comments
Comments are preceded by ";" or "//" characters. A row of text can begin with a comment, or one can place a comment after
a command and its parameters. For example, alert "hi" ; this is an alert
will show an alert that says "hi" and ignore the text after the ";" character.
Referencing User Defined Popupâs, Edit Fields, and Dynamic Text
Each user defined Popup menu,
Edit Field, and
Dynamic Text field has a name by which they can be referenced within script code. For example, if an Edit or Dynamic text field was named "Field1", then Field1$ = "abc" within a script would cause that field to display text "abc". From a script's point of view, Dynamic Text and Edit Fields are like string variables that can be read from, or written to, via their field name suffixed with a "$" character, and with space characters converted to underscore characters (e.g. field name "temp 1" is referenced as "temp_1$"). Popups are similar, except one prefixes a "!" character to their field name and their value is interpreted as an integer number beginning with 1 that relates to the current choice within the popup menu, where #1 is the upper-most choice. For example; if a popup has 3 choices "red", "green" and "blue"; and the user selects "green"; and one reads the popup value within a script; it would be read as 2. One can also reference Edit Fields and Dynamic text with a "!" suffix (instead of $) to interpret them as a number. For example, if text field f1 contains text "-1.2 abc", script code print Test (abs(f1!)) would print "1.2" to the Test page; and script code f1! = 3.1 + 1 would load field f1 with "4.1".
Referencing Hardware Channels In Script Code
For details on referencing hardware channels in script code, click here.
Math Expressions
A powerful feature within the iW+ script language is the ability to evaluate mathematical expressions. Parameters passed to functions with enclosing parenthesis are first evaluated mathematically. For example Print (2 * 3) prints the number "6". One can nest several parentheses within one expression. For example, var! = ((2 + 3) * (3 + 4)) correctly evaluates to 35. Objects within parenthesis are evaluated numerically. This means that one can place variables!, strings$, and defines# within a mathematical expression. For example, if v! = 2, s$ = "3", and def# = "4"; then ((v! * s$) + def#) evaluates to 10. Many common mathematical functions are supported, as noted here.
Numerical Constants
One can enter constants as integers (e.g. 3, -3), floating point numbers (e.g. 3.14, 2.73), scientific notation values (e.g. 1.34e-112), hexadecimal numbers with a "0x" prefix (e.g. 0xAC01), and binary numbers with a "0b" prefix (e.g. 0b01010). In some countries a comma "," is treated like a decimal "."; yet since commas are used to separate script parameters, iW+ requires that one refrain from this practice (e.g. script max(1, 2.2) returns the maximum of 1 and 2.2; whereas max(1, 2,2) would return an error). Constants can appear in any of the following formats.
Format
Notation
Example
Integer
±xxxxxx
-3, 312312
Floating Point
±xxx.yyy
3.1, -1221.1213
Scientific Notation
±xx.yyyezz
-1.123e-10
Hexadecimal
0xHHHHHH
0x12A, 0xacf0c2
Binary
0bxxxxxxxx
0b01, 0b1101011
Bit Values (i.e. 0 and 1)
In the world of digital, the value of a bit is either a 0 or a 1. Since scripts work with floating point numbers, bits are often read as 0.0 or 1.0. When a bit is set with a floating point value (e.g. 0.1, -3e10), it is set to 0 if the value is between -0.5 and +0.5; and set to 1 otherwise. This means that you need to set bit channels with a value that is close to 0, not simply less than 0. For example, in script code Dio3_Bit! = (0 < squarewave(1, 1)) we compare the +1 and -1 values from the squarewave() function with 0 instead of driving channel Dio3 Bit directly with those +1 and -1 values, since both -1 and +1 are interpreted as logic 1.
Several keywords represent Boolean values. low, off, zero, and false evaluate to 0; and hi, on, one and true evaluate to 1. For example, print (true + on + false) prints the value 2. In Summary, value 0 = logic 0 = low = off = zero = false = analog value > -.5 and < +.5; and value 1 = logic 1 = high = on = one = true = analog value > +.5 or < -.5. For an example use of false, click here.
Bit Operations
To operate on bits within 32bit integer values, one can use bitwise bOr (|), bAnd (&), bEor (^), 1's complement (comp()), left-shift (<<), and right-shift (>>) operators. Logically, "false" is represented as 0, and "true" as non-zero (e.g. 1). Bitwise bAnd, bOr and bEor are summarized below. For details on bit operators click here; and for details on working with Digital I/O Bits, click here.
Comparisons
Logical operators "And" and "Or" facilitate the comparison of two Boolean values. These are summarized
below, where T represents true and F represents false. Conditionally, the script language supports less
than (<), greater than (>), less than or equal to (<=), greater than or equal to (>=), equal to (==) and not
equal to (!=). For details on comparison operators click here.
Logical And: T and T = T, T and F = F, F and F = F
Logical. Or: T or T = T, T or F = T, F or F = F
Logical Not: not(T) = F, not(F) = T
Keywords that Return a Value
The math evaluator supports many keywords. For example "SecsSinceReset" returns the value of the instruNet hardware clock (62bit, 4MHz clock) in units of seconds , "MouseB" returns 1 if the mouse button is down, and 0 otherwise. "MouseX" returns the mouse horizontal pixel position. "MouseY" returns the mouse vertical pixel position, "true" returns 1, and "false" returns 0. One sometimes needs to enclose keywords with parenthesis to tell the script interpreter to return a number (e.g. print SecsSinceReset prints "SecsSinceResset" whereas print (SecsSinceReset) prints the number of seconds since reset). For a list of all keywords, click here.
\r and \t
Backslash characters followed by an "r" or "t" (i.e. "\r" & "\t") are used within quotes to indicate carriage-return and tab characters. For example Print "A = 1\rB = 2\rC = 3\r" prints three rows of text.
Working with Files and Text Editor Text
One can store text in either a Text Editor Page (e.g. Test, user defined page) or file on disk. The advantage of a disk file is it supports sizes up to 2GBytes (2e9 bytes); whereas a page supports a maximum of 32K characters. One programmatically writes to text pages and files using the Print, Copy, and Append commands. One can also clear, load from disk, save to disk and print Text Editor text via the File New, File Open, File Save As, and File Print menu commands. In order to write to a file, one must first Create a new file or Open an existing file, perform the write, and then Close the file. For details on all file commands, click here. For an easy-to-use example that logs to disk while digitizing, where the log rate is slower than the sample rate (e.g. log to disk one set of values every 10secs while digitizing and plotting data 100samples/sec/channel), click here; for an example that loads and saves static text to and from pages, click here; for an example that digitizes directly into a text file via the Record Setup dialog Digitize Into field, click here; and for an example that spools do disk via the Digitize or Table commands, click here.
Files that contain Script Code
Scripts are saved within the instrument setup .prf file. Subsequently, one can save all resident scripts by pressing the Network page Save button, and then restore them by pressing the Network page Open button (or Open/Save commands in the Setup menu). If one wants to save or load individual scripts to/from a text file (typically with an ".iBs" suffix), they can select the script in the Script page upper popup menus, and then Save/Load via the Script page Save/Open buttons.
Script, Variable, Hardware, Channel Settings & Diagnostic Reports
To view the values of all variables (i.e. str$, var!, def#) and see a printout of all scripts, select "Script Report"
in the Script menu. To see a list of installed hardware, select "Installed Hardware Report" under Hardware. To see
a combination of these two, along with the channel settings, select "Setup Report" in the Setup menu. To see this,
along with internal diagnostics information that is potentially helpful in debugging an internal iW+ software bug
(i.e. a report that can be emailed to your instruNet supplier), select "Internal Diagnostic Report" in the Help menu.
This Internal Diagnostic Report can also be generated by pressing the "SAVE DEBUG REPORT TO DISK" button within
an error alert.
Scripts That Run Other Scripts
One script can execute another script via either the Press command,
which executes a script associated with a button; or the Execute) command,
which executes a script in an open file or a string.
Example Scripts (.ibs) and Instruments (.prf)
Version 1.5 or later of the instruNet software contains examples in the Windows "... \ program files \ instruNet \ instruNet World+ \ ..." directory. For a list of several examples,
click here, and for more details,
click here.
Automatically Load Instrument file (.prf) at iW+ Application Launch
If one places a .prf instrument setup file (e.g. created by selecting Save Setup in the Setup menu) with the file name "iNet32_EndUserSetup.prf" in the "MyDocuments \ instruNet \ End User \ " directory or the directory of the instruNet World.exe file; that file will automatically load when one first opens the instruNet World window (e.g. when one launches the instruNet World application program), provided one is working with ≥ v3.4 of the instruNet software. This enables one to build a custom application that does not look like iW. When programming instruNet from another language (e.g. C, VB, Labview, DasyLab), this file is loaded when that program first tells instruNet to open one of its windows (e.g. the Record page). This is feature is supported even if the advanced iW+ (PLUS) software is not installed on the computer.
Automatically Execute Script file (.ibs) at iW+ Application Launch
If one places an .iBs script file (e.g. created by pressing Script page Save button) with the file name "Startup.iBs" in the "program files \ instruNet \ End User \" directory or the directory of the instruNet World.exe file, that script will automatically execute when one first opens the instruNet World window (e.g. when one launches the instruNet World application program). This enables one to build a custom application that does not look like iW+. To create this startup file, develop your script in the Script page, and then save it (e.g. via the Script page Save button) with the name "Startup.iBs" to one of the previously mentioned directories. Then exit instruNet World, run it again, and watch your startup script execute.
Automatically execute Script file (.ibs) after loading instruNet Driver
If one wants a script to execute after loading the instruNet driver (e.g. when DasyLab or Visual BASIC first accesses instruNet) and after each iW+ Reset (e.g. select Reset in Hardware menu), then use filename "iNetLoad.iBs" instead of "Startup.iBs", described above. This is helpful when controlling instruNet from another program (e.g. C, VB, Labview, and DASYLab) where the instruNet World window is not necessarily opened.
Scripting Tutorial
Below is a simple tutorial that helps one learn the iW+ script language. This tutorial assumes iW+ has been installed on your computer. If interested, please proceed with the following steps:
Simple Example
Launch iW+, press the Script tab at the base of the window to select the Script page, and then select After Test Script in the upper popup menus.
The Script page is used to create, edit, view, execute, and test instruNet Scripts.
Please type the following into the window:
Delete Buttons
NewButton Script "Print 3x"
For c! = 1 to 3
Print (Ch1_Vin+!)
Next
EndButton
End
Press the Execute button to execute this code which creates a button in the Script page. Subsequently, a button will appear at the top of the window entitled, "Print 3x".
Press the Print 3x button, and notice how the value of channel Ch1_Vin+ (i.e. Channel #1, from Network #1, Device #1 and Module #1) is printed three times (we are assuming you have at least one device attached to your computer).
Press the Save button to save your code to disk in a text file.
The first line of this program, "Delete Buttons", causes all previously created user defined buttons (not the standard buttons) to be deleted (so they do not accumulate each time you run this program). The NewButton command creates a new button in the Script page with the name "Print 3x". The code between NewButton and EndButton executes when "Print 3x" is pressed. This button causes a loop to execute 3 times, via the "For" statement. The body of the For loop is a simple print statement that prints the value of channel Ch1_Vin+ and a carriage return character.
Congratulations! You have now completed your first script program.
DVM Example
Press the Open button, navigate to file "...\ program files \ instruNet \ instruNet World+ \ Example Scripts (.iBs) \ Display Digital Voltmeter.iBs", and load the file into the instruNet Script editor.
Press the Execute button to run this program, and press the Stop button when done monitoring its activity.
This script reads several channels and prints them to one line in the text editor, once each second,
simulating a digital voltmeter.
Math Example
Press the Open button, navigate to file "...\ program files \ instruNet \ instruNet World+ \ Example Scripts (.iBs) \
Demonstrate Math Functions.iBs", and load the file into the instruNet Script text editor.
Press the Execute button to run this program.
Scroll up and down to review the various math-oriented features.
This script demonstrates many mathematical functions, bitwise operators, logical expressions,
string functions, and time related features.
Print Example
Press the Open button, navigate to file "...\ program files \ instruNet \ instruNet World+ \ Example Scripts (.iBs) \ Demonstrate Printing Functions.iBs", and load the file into the instruNet Script editor.
Press the Execute button to run this program.
Scroll up and down to review the various print and string related features.
Data Acquisition Example
Press the Open button, navigate to file "...\ program files \ instruNet \ instruNet World+ \ Example Scripts (.iBs) \ Set up channels - digitize - spool to disk.iBs", and load the file into the instruNet Script editor.
Press the Execute button to run this powerful program.
This code creates a new page called "Data", creates several buttons for this new page, and selects the new page.
Press the Script tab at the base of the window to return to the original code; peruse through it to read several of the comments; and then press the Data tab to return to the new data acquisition page.
Press the Setup button to set up several channels, per the Setup button script code.
Now press the Record button to digitize data into the Data page. Hold the mouse down to stop the data acquisition after several lines have been printed.
This program shows how scripts can set up channels, record into a text page, and
spool a large (e.g. 2Gbyte) file to disk (via the Spool button).
Overview
iW+ supports a powerful script language that is similar to the BASIC programming language, with added support for data-acquisition oriented tasks. Scripts are precompiled into an intermediate language that is interpreted at run time; and are therefore very fast. The iW+ script environment does not involve one long program that does all the work. Instead, the program is broken up into little segments, each of which is called a "Script". Scripts contain text that is executed in response to specific events. For example, a script might execute when a button is pressed, when a page is selected, when the instrument file is first loaded, every x seconds while digitizing, every y seconds at all times, when a digitization ends/begins, or when a scan begins/ends.
In a more specific example, one might have a button called "Turn on Pump" that when pressed, sets several output bits via several script commands. Additionally, another script might execute every 0.1secs to read several inputs and set several outputs based on those inputs (i.e. control). Scripts can also print notes and data to text pages and files; or, with several lines of code, spool digitized data to disk into one large text file, filling a 2 GByte file at rates of approximately 5000 points/second. For a list of the different types of scripts, click here.
Script Engine Objects
The iW+ Script Execution Engine manages the execution of all scripts and all script objects. Objects include variables!, strings$, open files, and defines #âs. All objects are Global, which means they can be read from, or written to, by all scripts. Scripts tend to be short pieces of code that execute for a short time, and then give back control to the mouse/menu bar. Only one Script executes at a time and the keyboard/mouse activity is disabled during their execution.
Script Engine States
The Script Execution Engine starts off in a reset state with no objects (e.g. variables) and no precompiled scripts. When a script is first executed, all scripts are precompiled and the Script Engine moves from its reset state to an operational state. Objects are created and modified as scripts are executed, and will stay resident in memory until they are deleted, or until a Script Engine reset is done.
The Script Engine reset occurs when one of the scripts is edited (i.e. in a Control Calculate field, a Panel Meter Calculate field, or the Script page editor), when one loads a .prf instrument file (e.g. "Open Setup" command in Setup menu, "Restore From System" command in Setup menu), when one clears the instrument (e.g. Network page Clear or Reset buttons) or when one selects "Reset All Scripts" in the Script menu.
Typing one character into a script (i.e. editing it) causes all objects (e.g. variables) to be deleted, and is therefore a significant event. This is done since the Script engine cannot execute scripts that are in the process of changing. In other words, one must not program scripts while operating an instrument. To view all scripts, select "Script Report" in the script menu; and to delete all scripts, one would select "Delete All Scripts" in the Script menu.
Stopping Scripts
To stop the currently executing script, click the Script page Stop button, or press keys CONTROL 'S' (one might need to hold these keys down for a moment). This is not the same as resetting the entire Script Engine (i.e. "Reset All Scripts" in Script menu), which causes objects to be deleted. To stop digitizing, click the Record page Stop button or press keys CONTROL 'S'.
If the periodic User Script is causing problems (e.g. showing error alerts), select the Script page (periodic scripts do not run when the script page is selected), select the User Event (in the upper popup menus) and type "end" at the top of the script to disable it. One can disable the Control Event script in a similar manner.
Script Error Reporting
If one line of script code produces an error (e.g. a function name is not spelled correctly), an alert will appear (describing the error), the script editor will open showing the script and the problematic line will possibly be highlighted. At this point, one can ignore the error or edit the line of code and fix it. If an edit occurs, the script engine will reset (all objects will be deleted), and one can try running again. If one ignores the error and the script runs again, it will probably show the error alert again unless it is a periodic script (i.e. panel meter calculate field, control calculate field, Control Script, User Script), in which case, it will be disabled until the next Script Engine Reset (i.e. which occurs when one edits a script, or selects "Reset All Scripts" in the Script menu). This disabling occurs with periodic scripts to alleviate the operator from being harassed with error alerts at the periodic execution rate (e.g. once a second).
Debugging your Scripts
Below are several techniques that aid the debugging process.
Respond to Error Alerts
One can easily respond to Alert messages that appear when a line of script code produces an error, as noted here.
Print Debug Text to Test Page Each Time A Line Of Script Code Executes
Debug Reporting causes information to be printed to the Test page each time a line of script code is executed. To turn it
on, set the Script Options Debug field (select Script Options in Script menu) to ON; or execute
a debug on line of script code (one can also turn it off with
script debug off).
Print Debug Text As Needed
One can add print statements to a script to indicate progress as it executes. For example, if variable v! is set to 3, then Print Test "v1! = " v! "\r" will print "v1! = 3" to the Test page. The "\r" inserts a carriage return to initiate a new line.
Stop Scripts with CONTROL 'S'
If you think your script is stuck in an infinite loop, you can stop it manually, as noted here.
Send Internal Diagnostic Report to instruNet Supplier
When an alert appears that potentially involves a bug in the iW+ software, a "Save Debug Report To Disk"
button appears at the bottom of the alert box (same as "Internal Diagnostic Report" in Help menu). When this button
is pressed, a diagnostic report is saved to disk, and if one adds a list of steps to reproduce the problem at the
bottom of this text file with WordPad or Notepad, and emails it to their instruNet supplier, then their supplier may
be able to provide additional feedback.
View Variable Values & Scripts
For details on how to view scripts and variable values, click here.
Working with instruNet Hardware
Maximum Sample Rate, User Rate and Control Rate
In summary, when outputting waveforms (and possibly digitizing as well) or doing auto-calibration while digitizing, the maximum digitize rate is approximately 100s/sec/ch, and the maximum output rate is approximately 10s/sec/ch. Yet when Only inputting (with "auto-calibration while digitize" off), the maximum sample rate is approximately 166,666 s/sec total aggregate (e.g. 1ch at 166K, 2ch at 83K each, 4ch at 41K each) when not integrating (i.e. no signal averaging);
and the inverse of the sum of the integration times when integrating.
Please see Sample Rate Vs. Integration Time Vs. Noise for
details on this inverse sum of integration thing. For more details on the maximum sample rate provided by the
instruNet hardware, please see i240 and i4xx Maximum Sample Rates. To determine the actual maximum sample rate for a specific setup, set the sample rate to a high number such as 1e9 (select Record Options in in Record menu), digitize (press Record page Start button), stop digitizing (press Record page Stop button), and then open the Record Options dialog to see the resulting sample period (it will have reverted to the maximum possible).
The maxium Control and User Rates are determined primarily by the speed of the computer. For example, a Pentium IV 1.5GHz computer running Windows XP supports a maximum control rate of 20 events/second without missing events. This limitation is not affected by running Microsoft Word and Microsoft Outlook in the background. If one does not mind missing one out of every several events, they can run faster. The maximum user rate is similar to the maximum control rate. Typically, one runs the User rate at 1 to 5 events/second; and runs the Control rate at <= 10 events/second. For an example that displays the number of missed control events since the start of digitization, in real-time while digitizing, click here. One technique for determining the actual maximum Control rate is to try different control rates (e.g. select Script Options in Script menu) and watch the NumControlEventsMissed state variable (as shown in the referenced example) -- if this field goes above 1.0 while digitizing, you missed a control event.
Referencing Channels in your Script code
Channels can be referenced in script code with a 4 number channel address, or with their user name suffixed
with a "!" character and with spaces converted to underscore characters. For example, Ch1 Vin+'s value is referenced
as "ch1_vin+!" in script code. Script names, variable names, string names, define names, and channel names are
non-case sensitive (e.g. "VIN!" is the same as "vin!" within a script). Channel user names can contain
numbers (0 · · · 9); alphanumeric characters (A · · · Z, a · · · z);
and characters "*", "/", "+", "-", "_", and "." (yet not symbols like "&", ">", "<", etc). To view/adjust a channel
user name, select the channel in the Channel Options submenu within the Hardware menu, and select General in the Settings
submenu within the Channel Options dialog.
When one suffixes a channel user name with the "!" character, it is interpreted as a numerical value (similar to an 8byte floating point variable). Alternatively, one can suffix a "$" character to interpret the channel's value as a string. For example, append s$ Ch1_Vin+$ appends the value of channel Ch1 Vin+, in string form, to string s$.
To reference a channel by its channel address, one separates the address's numbers with "/" characters in netNum / deviceNum / moduleNum / chanNum order. For example, "1/2/3/4" refers to netNum#1, deviceNum#2, moduleNum#3, and chanNum#4. For an example, click here.
Channel Lists
To specify a list of channels, enclose the entire list of channel addresses and/or channel user names (without the !/$ suffix) in quotes "...", and separate each address with a space character " ", comma "," or tab "\t". For example, "1/1/1/1, 1/1/1/4, Ch7_Vin+" refers to Channels #1, #4, #7 in the first hardware module. Channel Addresses are passed to the following commands: Table, Digitize, SetField, SetChannel, SetChannelBit, and Calibrate. Channel lists attached to a Define# can be placed on multiple rows of text (i.e. it is ok to place a carriage return between two channel addresses). For an example, click here, here, or here.
Reading Analog, Digital and Counter Input (not Output) Channels
The following procedure is often used when working with input channels.
Set up channel in the Network page per Setting Up Sensors (e.g. specify thermocouple sensor type, specify bidirectional i/o bit as input, etc).
View channel in the Network page to make sure it is set up properly.
Save instrument setup in .prf file (i.e. select Save Setup As in Setup menu).
Program the reading of the channel (e.g. write script code, create panel meters, etc).
Save the .prf instrument setup again.
Input channels can be read via any one of the following techniques.
Select a Voltage Input channel in the Network page for digitizing, select the Record page, Start digitizing, view the plot, and optionally save to disk; as done here.
View the channel in the Network page, which updates approximately twice a second.
Create a panel meter that shows the channel's value numerically in any page; as done here.
Create a dynamic text field that periodically updates text that represents the channel's state via one line of script code. Here, plotting can be either on or off (i.e. Display View field set to "Show" or "Hide") and Digitizing can be on or off (i.e. 4th column in Network page red or not). For an example click here.
Read the channel via its user name within a script expression, as noted here. For example, Print (Ch1_Vin+! * 10) prints the value of Ch1 Vin+ times 10. For an example click here.
Print multiple input channels to a text page or text file via the Table command, as shown here; or the Digitize command, as shown here.
When does the Actual Input Occur?
When not digitizing, the input occurs typically within 10 to 200 us of the code being executed. When digitizing and reading a voltage input channel that is enabled for digitizing (i.e. its digitize enable field in the Network page shows a red rectangle), then the script code simply takes the last digitized point without actually doing another measurement. When digitizing and reading an input channel other than a voltage input channel enabled for digitizing, then the script engine must interrupt the i2x0/i60x controller's processor from digitizing to do its input measurement. If digitizing at a fast rate (e.g. > 1K s/sec/ch), then the i2x0/i60x processor might be too busy to support the operation, and will produce an error alert. If this occurs, one should consider reducing the digitize sample rate, or enabling that channel for digitizing in the Network page (i.e. click to enable red rectangle).
If you want to digitize a channel yet not plot it, select Channel Options under Hardware,
select Display Settings, and then set the View field to Hide. The amount of free processor time is the sample period minus the sum of the integration times. For example, if you digitize 4 channels at a 100s/sec/ch rate (10ms sample period), and they each are integrated for 1ms each, then you will have 6ms (6ms = 10ms - (4 * 1ms)) each data point of free controller time. For details on this, please see Sample Rate Vs. Integration Time Vs. Noise.
Writing to instruNet Analog, Digital, and Clock Output (not Input) Channels
The following procedure is often used when working with output channels.
Set up channel in the Network page per Setting Up Sensors (e.g. specify clock output, specify bidirectional i/o bit as output, etc).
View channel in the Network page to make sure it is set up properly.
Save instrument setup in .prf file (i.e. select Save Setup As in Setup menu).
Optionally program the setting of the channel (i.e. if it requires further updates).
Save the .prf instrument setup file again.
Output channels can be set via any one of the following techniques.
Click on an output channel in the Network page to open its Channel Options dialog (or select Channel Options under Hardware), and then set the output state manually, per Working with Voltage Output Channels.
Update the channel with a Control Script, User Script, or Control calculate field, as described here. This is sometimes referred to as "control", "waveform generation", or "feedback loop". For an example, click here, here or here.
Update several channels with one line of script code via the SetChannel
or SetChannelBit commands. The later works with digital I/O bit channels
(e.g. Dio1 Bit).
When does the Actual Output Occur?
When not digitizing, the output occurs typically within 10 to 200 us of the code being executed.
When digitizing at a fast rate (e.g. > 1K s/sec/ch), the i2x0/i60x controller processor might be
too busy to support the operation, and will produce an error alert.
If this occurs, one should consider reducing the digitize sample rate or
see Sample Rate Vs. Integration Time Vs. Noise.
If the controller does have time to do the operation, it occurs the next time it is available,
which is typically within 10ms. The script engine does not wait for this to occur, and instead
places the output request into a queue that is executed at the next available moment.
The queue is processed in a first-in-first-out order. For example, if you write to Ch3
and then write to Ch6, Ch3 will be set before Ch6. If you update a channel with a new
value before it has a chance to output the previous value, then the oldest queue request is
updated with the latest value, and a new entry is not pushed into the queue. For example,
if our script code sets Ch3 to 1V, sets Ch6 to 2V, and then sets Ch3 to 3V, all very quickly
before the actual updates take place, then the output queue will contain Ch3 = 3V as its next
to process element, followed by Ch6 = 2V.
Digitizing and Plotting Different Kinds of Channels
There are several channel types, each of which are summarized below.
Channel Type
Channel Name
How to Enable for Digitizing or Waveform Outputting
How long does a line of Script code take to Execute?
Typically, a simple line of script code such as x! = y! * z! requires several microseconds to execute on a processor such as a 2GHz Pentium IV. For details, please see file "Benchmark Body of Loop.iBs" which shows how to measure script code execution times.
Working with Digital I/O Bits
Many hardware units contain bidirectional bit channels (e.g. Ch25 Uio1 on i430, Ch25 Dio1 on i100). When used as an input, approximately 2V to 12V applied to the signal is measured as logic 1, and approximately 0V to 0.8V is measured as logic 0. When used as an output, logic 0 pulls the signal low to approximately 0.8V, and logic 1 lets the signal terminal float to 5V via an internal ohm pull-up resistor (e.g. 3KΩ).
Each digital i/o bit is set up as either an input or output, and to view/adjust this setting, 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 set the Direction field to Input or Output.
To read a digital i/o bits value, one can suffix its user name with "!", convert spaces to underscores, and reference it like a variable in the script code (e.g. Print (Dio1_Bit! * 10) will print 10 or 0, depending on Dio1 Bits 1 or 0 value). To write to a bit, one can either place an equation in its Control Calculate field, or assign it a value with a line of script code in any script (e.g. Dio1_Bit! = 1). For an example of this, click here.
One can also access all bits at one time using a group channel (e.g. Ch29 Uio25_28 in i420), described in detail in Working With Digital I/O Channels. Here, one reads or writes a integer (e.g. 0 to 15 value when working with 4bits). For example, Print (GetBit(Ch25_Dio_Group!, 3)) will print a 0 or 1 with the i100 device depending on the status of Dio4 Bit. Notice that i100 bit 3, base 0, refers to screw terminal Dio4, which is base 1. Functions SetBit, ClrBit, and GetBit help one mathematically isolate individual bits within an 8 or 16bit value. The SetChannelBit command can also set and clear bits.
Doing Math with Digital I/O Bits
For details on working with Boolean 0 and 1 values, click here.
Reading back Output Channels (e.g. reading D/A output signal with A/D)
In some cases, one might want to read back an output channel. For example, one might want to set the 8bit i100 voltage output channel to 1.00000 volts, and then read back the actual voltage at the screw terminal using the i100 14bit a/d converter, for testing purposes, and to also to get an accurate reading of the actual output voltage. For example, one could set the output with a Ch3_Vout! = 1 line of code, and then read back the commanded value (i.e. 1.00000) by reading Ch3_Vout! (e.g. print (Ch3_Vout!)), yet this would read back the commanded value, not the actual voltage. To read back the actual voltage with the A/D, one would need to use the ChReadBack() function. For example, print (ChReadback(Ch3_Vout!)) would print a number like 1.00331 Volts, as read by the A/D. In the case of an output channel's Panel Meter, if the panel meter calculate field is empty or contains the "value" keyword, a read back is done with the A/D converter; otherwise, if the Panel Meter calculate field contains an equation that includes the "value" keyword, then "value" is interpreted as the last command output value.
Control and Waveform Generation
Control and waveform generation is implemented with Script code that periodically (e.g. 10 times/second) calculates and updates an instruNet analog or digital output channel as a function of input channels and/or mathematical functions. These scripts reside in the Control Calculate field, the Control Script, or the User Script. For an example waveform generation instrument, click here; and for an example feedback/control instrument, click here. For details on the maximum I/O rates, click here.
Feedback and Waveform Generation Math
Control and waveform generation scripts are typically created using standard math functions (e.g. +, -, *, sin, cos, abs); the current values of input and output analog and digital channels (in engineering units); and mathematical functions (e.g. Alarm, OnOff, Limit, PID, SineWave, SquareWave, TriangleWave, and Gen). For details on general math, click here.
Below are several examples of feedback/control math:
Below are several examples of waveform generation math:
DoutBit3! = (0 < squarewave(1, 1))
Slippage between Computer time and instruNet Controller time
The SineWave, SquareWave, TriangleWave, and Gen waveform generation functions keep track of time using the computer's crystal oscillator; whereas the instruNet controller keeps track of time using its own crystal oscillator. All crystals are accurate to approximately 0.01%, which is approximately 1 second every 10,000 seconds. This means that if you are digitizing for a long time, and you are also outputting a waveform via one of these functions, you might see a ± 0.01% time variation. For example, if the squarewave function outputs a continuous 10 second squarewave, and one digitizes this square wave for 10001 seconds with an instruNet input channel, the instruNet World plot display will show its 1000th 10sec cycle ending at between 9999 and 10001 seconds (not exactly at 10000.0) after digitization and squarewave generation start. If you want your script code to synchronize off of the controller's crystal, please refer to the DigitizeSecs keyword.
Hidden
Hidden
Hidden
Hidden