VARS - ad3ller/oskar GitHub Wiki
Controlling hardware with sequencer.vi
The principle
The VARs system is used to control hardware with the sequencer. For every line of a sequence file, Sequencer.vi broadcasts the message:
I don't care who you are or how you do it but I need each VAR from this list set to these values. Please let me know when it's done!
More explicitly, for each line of a sequence there is a VAR Array
, e.g.
Name | Value |
---|---|
VAR1 | value1 |
VAR2 | value2 |
⁞ | ⁞ |
VARn | valuen |
This is read by Sequencer.vi and for each row two Boolean columns are added: Received and Set (both initially False), as well as the string Option (see below). This new array is passed to a global variable and can be viewed on the tab Vars
in sequencer.vi. For each row the sequencer waits for Received to become True, then proceeds to the next row. After all VARS have been received the sequencer waits for all Set values to be True (i.e., for every row of the array/ each requested VAR), before continuing to the acquisition stage.
Separate programs with control over the hardware corresponding to each VAR must be written that can "listen" for requests from the sequencer. The simple example of PAUSE.vi can be found in the VARS folder. This vi listens for a VAR called PAUSE. Upon receiving the VAR from the sequencer it sets Received to True, then feeds the VAR value into a wait function (in ms). After waiting for the requested amount of time it updates Set to True. In the real world, Set would be changed to True after, e.g., the voltage had been changed, or the laser adjusted, etc.
A similar example called HOLD.vi updates Set when the user presses the button on its front panel (the VARs value is irrelevant). This example can be used to record a measurement that requires manual input (e.g., movement of a manipulator) and the VAR value can be used as a note (e.g., of the position it should have been moved to).
Use these examples as a template for making new VAR controls, replacing the code in the centre section with a subVI that can take the VAR value as an input. Use an output of the hardware control subVI to ensure the sequencer does not proceed until the desired hardware change has been completed. Note: any VAR hardware control programs should be added to the oskar project in order to have access to the global variables.
To see the VARs system in action try and run /Examples/example_seqs.osq
with sequencer.vi - be sure to have the VAR control PAUSE running.
The reality
It's important to understand the technical details for how VARs are actually made in order to do something useful with them. Open the template `PAUSE' and navigate to the block diagram. There are 5 main sections to this code - namely:
- Create a notifier based on the name written in the control
Var
(in this case: Var = PAUSE). This must match the notifier created by the Sequencer, i.e., the VAR name written in the sequence file. - Wait for the notifier which, when received, will pass a value indicating the index of the matching VAR in the Global variable `VARS' (array of clusters).
- Acquire the semaphore `Global' to prevent any other VAR vi from writing to the global variables. Use the index obtained in the notifier to select the correct row from the VAR array. Read the value and write the Boolean Received to True. Release the semaphore.
- Do something with the VAR value. In this case, convert it to an I32 and feed this to the Wait function. Generically, this is where the vi must somehow interpret the VAR value (passed as a string) then act upon it, for instance, you may pass the value to a subVI that sets the wavelength of a dye laser. Or the delay of a channel in a TTL generator. Or the frequency of a waveform generator. Or the output of a high-voltage supply. Etc., etc., etc.
- Acquire the semaphore again. In the appropriate row of the global variable `VARS', write Set to True. Release the semaphore and then wait to receive another notifier.
You can make a copy of PAUSE to use as a template, change the value of VAR (i.e., the name used by the sequencer to communicate with the vi) and write into step 4 the code specific to your own needs. See CHANNEL for a more complicated example that uses options, and which records values set for each channel as a variant. In this way newly received values can be compared to the last value set for that channel to determine if anything needs to be changed.
Note, it is a good idea to write suitable limits for the values that can be passed to the hardware vi, just in case a bug causes a value meant for a wildly different piece of hardware to be passed, or if the sequence file was simply made with a silly value.
Options
Options add flexibility to VAR control and can be used (optionally) by appending the VAR name with a question mark, e.g., VAR?OPTION (for this reason, only use question marks in VAR names when specifying options). Sequencer.vi splits the name at the ? and transmits the name and option separately as individual strings. It's up to the VAR vi to act on the option as appropriate. For example, you could create a VAR control that can set the voltages on a channel of an AO device with VAR name `VOL'. The option string could be interpreted as which channel (A or B) to control. In this case the VAR array would be,
Name | Value |
---|---|
VOL?A | 5 |
VOL?B | 10 |
The vi would first set channel A to 5 V then channel B to 10 V.
This is generally better than having separate VAR vi's for each channel as it forces the order they are set and prevents interference from simultaneous attempts to communicate with one device. The options format can be used quite efficiently even with many channels, for example, VAR?1/2/3 could be used to build an array of AO voltages but only when a specific option is received (e.g., VAR?update) will the commands be sent to the hardware. The level of sophistication in interpreting the options depends entirely on the VAR vi, and not on the sequencer.
To see how options can be used with VARS try /Examples/example_chan.osq
with CHANNEL.vi.
When testing you may avoid saving data by disabling the Save option on the Sequencer.vi front panel.