NI VeriStand ActionVIs
ActionVIs are an advanced feature that can be implemented within any VeriStand custom device to allow the custom device to react to nine common actions a user may take. They are called from an Action Engine framework within the VeriStand application which reacts to these pre-defined events and calls the appropriate ActionVI. ActionVIs can also be thought of as statically defined Callbacks within the VeriStand application. It's key to note that because these ActionVIs, or Callbacks, are within the compiled VeriStand application, the user cannot add additional items to be monitored. It's also important to note that all ActionVIs execute on the host.
Consider the scenario: You're creating a custom device for VeriStand and need to make sure that if the user loads a System Definition file with an older version of the custom device, that it automatically mutates it's channels, settings, etc to the newer version. You can't perform this check in the Initialization phase of the custom device because its already been added to the System Definition. So, how do we react to the custom device being loaded? The answer is ActionVIs, and in this particular scenario the ActionVIOnLoad which will run when the custom device is first loaded into memory. We would implement this ActionVI by placing XML tags within the custom device's XML under the page tags for the custom device's main page. By using this ActionVI, you allow the custom device to mutate itself automatically when the user opens the System Definition. This is one of nine ActionVIs that are implemented as of NI VeriStand 2012.
The nine implemented ActionVIs are:
Since ActionVIs are called dynamically, they must adhere to a template with a pre-defined connector pane. When in your custom device Project, created using the Custom Device Template Tool found at <LabVIEW>\vi.lib\NI VeriStand\Custom Device Tools\Custom Device Template Tool, the templates can be found in the Custom Device API.lvlib >> Templates >> ActionVI folder. To create a new ActionVI, right click on the desired template and select "New from Template".
You can now go to the block diagram and implement your desired functionality. However, DO NOT modify the connector pane. This can cause the ActionVIs to be called incorrectly and the errors aren't always very descriptive. Each ActionVI, its inputs, and common use cases are described below.
Occurs when a page is loaded into memory by NI VeriStand.
Block Diagram:
Possible Use Cases:
The code snippet below is taken from the Scan Engine / EtherCAT Add-On and demonstrates the use of this ActionVI to mutate the device in the System Definition for newer versions.
Occurs when a user tries to delete an item. This ActionVI can be used to deny the delete request. If a delete request is denied, the item will not be deleted and ActionVIOnDelete will not be thrown.
Block Diagram:
Possible Use Cases:
The code snippet below demonstrates the use of this ActionVI to allow the user to confirm the deletion of a page:
Occurs when a page is deleted from the System Definition.
Block Diagram:
Possible Use Cases:
The code snippet below is from the Scan Engine / EtherCAT custom device when you delete the local chassis. This ActionVI is being used to reconfigure the hardware after you delete a page that was being used for custom configuration:
Occurs when the System Explorer is closed.
Block Diagram:
Possible Use Cases:
Occurs anytime the user saves the System Definition.
Block Diagram:
Possible Use Cases:
The code snippet below comes from the Engine Simulation Add-On where OnSave they set the properties for the custom device:
Occurs when the custom device is downloaded to the target. This event will throw every time the System Definition is deployed to a Real-Time System. This event does not throw if the target is Windows.
Block Diagram:
Possible Use Cases:
The code snippet below is from the Scan Engine / EtherCAT custom device. It is used to configure the target (scan rate, etc):
Occurs when a user pastes a page into the configuration tree.
Block Diagram:
Possible Use Cases:
Occurs when the user changes the target specified in the System Definition.
Block Diagram:
Unfortunately, while this ActionVI is implemented within the VeriStand Action Engine, its template is missing from the Custom Device API library. This is documented in CAR# 413698.
Possible Use Cases:
Occurs when the system definition file is compiled. Note that if a system is deployed, un-deployed, then deployed without any changes, this ActionVI will only throw on the first deployment because the NI VeriStand system definition won’t recompile.
Block Diagram:
Possible Use Cases:
The code snippet below demonstrates an ActionVIOnCompile which takes all of the custom device settings and writes them to a single property:
Now that we know what ActionVIs are and what we can do with them, how do we implement them? ActionVIs are called from the XML of a page and ActionVIs can be created for any page; this means the main page of the custom device, or any child pages you choose to create. There aren't any limits on the number of ActionVIs you implement for any given page, with the exception that a page can't have two of the same ActionVI. I.E. The main page of my custom device can't have two ActionVIOnDownloads but it could have one of each ActionVI and all of my pages could have a different implementation of ActionVIOnDownload. In the event that multiple ActionVIs are called, they are executed based on their placement in the custom device XML, from top to bottom. The most important part of implementing an ActionVI is properly declaring it within your custom device XML. An example of the XML needed to implement the ActionVIOnDownload is below:
Further information about properly formatting your XML can be found here:
Custom Device XML Tags
http://zone.ni.com/reference/en-XX/help/372846F-01/veristandmerge/cd_xml_tags/
NI VeriStand Directories and Aliases
http://zone.ni.com/reference/en-XX/help/372846F-01/veristand/vs_dir_aliases/
You’ve now added your ActionVI to your custom device and the new Configuration LLB and new XML are now in the custom devices folder that VeriStand uses for your System Explorer. However, you’re ActionVI isn’t ready to be called yet. VeriStand, by design, parses the XML files of all custom devices when it loads. So, since you’ve modified the XML of the custom device, you’ll need to restart VeriStand in order for the new XML to be loaded and used. However, if you ever make changes to an ActionVI (or custom device for that matter) and haven’t modified the XML then you can simply rebuild the Configuration LLB and see the changes.
When writing code, it can be extremely helpful to see examples of how code has been implemented by other developers. Below is a list of the VeriStand Add-Ons that currently use ActionVIs:
After reading this documentation, are you still unsure about what ActionVIs are and when they occur? Would you like to be able to see them occur? Well then you're in luck! I've created a simple ActionVI Example custom device which implements eight of the nine ActionVIs. Remember, we can't implement ActionVIOnTargetTypeChange since it doesn't have a template. The example custom device is attached to this document, both as source and as a compiled custom device. Simply move the folder called "ActionVIs Example Built" to your custom devices folder at <Public Documents>\National Instruments\NI VeriStand 2012\Custom Devices. Then, restart NI VeriStand and add the "ActionVIs Example" custom device to your System Definition file. There are directions on the main page of the custom device on how to cause each ActionVI to occur. The source code for the custom device is also provided within the "ActionVIs Example Source" folder. Use of the custom device and/or modifying the source will require the following software:
This add-on is provided as open-source software. If it does not meet your exact specification, you are encouraged to modify the source code to meet your needs. It is not officially supported by National Instruments.
National Instruments does not support this code or guarantee its quality in any way. THIS EXAMPLE PROGRAM IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND AND SUBJECT TO CERTAIN RESTRICTIONS AS MORE SPECIFICALLY SET FORTH IN NI.COM'S TERMS OF USE (http://ni.com/legal/termsofuse/unitedstates/us/).
How can I implement an action which fires every time the system definition is run on the target?
Unfortunately, there isn't a direct ActionVI to handle when the System Definition is deployed, but there is a product suggestion for an ActionVIOnDeploy. However, we can work around this by using ActionVIOnDownload. How we implement the functionality depends on if your Controller is set as a Real-Time target or as Windows. If you're deploying to a Real-Time target, ActionVIOnDownload will throw everytime you deploy your System Definition File (so basically a ActionVIOnDeploy) and I take advantage of this functionality in the NI VeriStand Add-On: Data Dashboard to deploy the shared variable library every time the user deploys the System Definition File. However, if you're deploying to your Windows system, ActionVIOnDownload doesn't get called at all because the custom device isn't being downloaded. However, we can mimic the execution timing of the ActionVIOnDownload by placing it in the initialization portion of your RT Engine VI and because your target is Windows, this code will execute on the host just as the ActionVI would. In that case, I recommend adding something similar to the image below to the initialization section of your RT Engine VI that checks the OS you're running on and, if it's Windows, runs the same code you would have in your ActionVIOnDownload (in this case, deploy a SV Library).
This will then allow you to switch your controller between Windows and RT Targets and have the functionality of an ActionVIOnDeploy. One final note: Remember that if the code we wanted to execute "on deploy" could be run on the RT target, then this could be implemented completely in the initialization phase of the RT Driver VI of your Custom Device and wouldn't require an ActionVI. However, in the case of deploying a shared variable library (above) this code must be executed on the host, which is why we would implement the functionality through ActionVIOnDownload.
It's mentioned several times in this document that the template is missing for the ActionVIOnTargetTypeChange, but is there a way we can construct a VI the old fashioned way that matches the correct connector pane layout? Apparently this VI has been missing since at least 2013 and still hasn't been added in VeriStand 2015! This functionality would be very useful for me in a project I'm working on.
Hey NFT,
I'll check on that to see where we stand with the CAR. Can I ask what functionality you're looking to implement?
It's likely one of the other ActionVIs would work as well (usually OnCompile is the catch-all) or if you're trying to change displays or something then reading some properties within your page might be an option.
The custom device I'm working on only supports Windows, so I want to warn the user when they switch operating systems on the controller. I'd hate to wait until they save or compile the system definition because it's possible they may have done a lot of other configuration work to the system definition after switching target types, and they'd have to go back and undo all of it.
Hi all,
I implemented an ActionVIOnSave. This ActionVIOnSave modifies the system explorer tree when the user presses the save button. The funtionality is:
- Once the save button is pressed, the ActionVIOnSave reads the Aliases from the System Explorer and creates a channel under the Custom Device for every Alias.
This implementation does not allow to save properly the system definition file. The Asterisk symbol remains on the System Explorer (Look at the screenshot below)
Is this an expected behaviour?
Thank you very much
Hey Dagaror,
I've never tested it but my understanding is that the system tree is already saved by the time ActionVIOnSave is triggered, and the code in the ActionVI is meant to set properties and other configuration items, not create new system nodes. At least that's how OnCompile acts, and I would assume similar behavior with OnSave. However, you could programmatically call save from within the ActionVI (it won't cause another callback, so no worries there) and that might get rid of the unsave asterisk. Maybe...
Should that not work, I'd recommend posting your question in the VeriStand forum here, since this thread isn't actively monitored.
Hope that helps! --Ryan_S
Hi Ryan,
thank you for your reply.
I tried to implement the save action inside of the ActionVI but it did not work. The asterisk remains. I will post in the VeriStand forum.
Thank you again