NI VeriStand Add-Ons Documents

cancel
Showing results for 
Search instead for 
Did you mean: 

NI VeriStand ActionVIs

NI VeriStand ActionVIs

Overview

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. 

Available ActionVIs

The nine implemented ActionVIs are:

  • ActionVIOnLoad
  • ActionVIOnDelete
  • ActionVIOnDeleteRequest
  • ActionVIOnSystemShutdown
  • ActionVIOnSave
  • ActionVIOnDownload
  • ActionVIOnPaste
  • ActionVIOnTargetTypeChange
  • ActionVIOnCompile

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

newfromtemplate.JPG

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.

OnLoadIcon.JPG

  ActionVIOnLoad

Occurs when a page is loaded into memory by NI VeriStand.

Block Diagram:

Onloadblock.png

Possible Use Cases:

  • Start a daemon: Daemons can be useful for running processes and gathering data in the background. If your custom device needs access to a large amount of data, rather than having each page parse through a file or request that data from an external source, your Daemon would simply get all this data on load (or get it in the background) then give it to the pages when requested. You would use named queues or functional globals to communicate between the Daemon and your pages.


  • Mutation of older versions: ActionVIOnLoad is commonly used to handle revisions in custom devices. This allows you  to mutate an older custom device (contained in a System Definition) with a newer version that you've downloaded to disk. This eliminates the need to remove and re-add the custom device to your System Definition to see the effects of the modified custom device.

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.


OnLoadExample.png

OnDeleteRequest.JPG

  ActionVIOnDeleteRequest

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:

deleterequestblock.png

Possible Use Cases:

  • Warn user: You can warn the user that they are about to delete the channel and what implications that will have. So you could pull any channel mappings that use that channel and advise the user that these mappings will be broken. You could also then give the user the option to delete these mappings if desired.


  • Confirm or Cancel: Allow the user, or your program to stop the deletion of a page. VeriStand automatically gives the user the chance to stop a deletion, so this is mostly useful for programmatically stopping certain pages form being deleted. So, if you have sections or pages that are crucial for your device to operate, you can stop these from being deleted.

The code snippet below demonstrates the use of this ActionVI to allow the user to confirm the deletion of a page:


deleterequestexample.png


OnDeleteRequest.JPG

  ActionVIOnDelete

Occurs when a page is deleted from the System Definition.

Block Diagram:

ondeleteblock.png

Possible Use Cases:

  • Channel Mappings: Alert the user which channel mapping are now broken from deleting that channel


  • Reconfigure hardware: If the page that was deleted specified custom configuration of your hardware, you may want to change back to a default configuration.

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:


ondeleteexample.png


sysshutdownicon.JPG

  ActionVIOnSystemShutdown

Occurs when the System Explorer is closed.

Block Diagram:

onsysshutblock.png

Possible Use Cases:

  • Close hardware connections: If you've opened any connections to hardware to configure it based on page values, then this is a good time to close those connections.


  • Close Daemons: If you launched a Daemon from ActionVIOnLoad, this is a good to send it a command to shutdown.

onsaveicon.JPG

  ActionVIOnSave

Occurs anytime the user saves the System Definition.

Block Diagram:

onsaveblock.png

Possible Use Cases:

  • Set properties: When a user saves, this is a good time to “save” any settings they currently have configured into properties for the custom device itself.


  • Save Configuration Data: If you wanted to know what was changed from one System Definition to another, you could implement a save log (similar to source control for your System Defintion file).

The code snippet below comes from the Engine Simulation Add-On where OnSave they set the properties for the custom device:

onsaveexample.png


ondwnldicon.JPG

  ActionVIOnDownload

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:

ondownloadblock.png

Possible Use Cases:

  • Configure a target: Downloading to the target means that you've deployed and any settings from the System Definition file are final. This is a good time to finalize any target configuration.

  • Deploy files to a target: Your custom device may need additional files, DLLs, dependencies, etc in order to operate properly. For example, a custom device that reads and writes to shared variables (Data Dashboard VeriStand Add-On) would want to deploy those shared variables at this time.

The code snippet below is from the Scan Engine / EtherCAT custom device. It is used to configure the target (scan rate, etc):

ondownloadexample.png


onpasteicon.JPG

  ActionVIOnPaste

Occurs when a user pastes a page into the configuration tree.

Block Diagram:

onpasteblock.png

Possible Use Cases:

  • Check channel properties: If you're pasting a page or item that handles the configuration of a target, you'd want to ensure that the new copied page doesn't try to configure the same piece of hardware. So, check for conflicts.


  • Prompt user for definition: If the pasted page will conflict with existing pages then you’d want to prompt the user for new values to use. This would be similar to the paste functionality already implemented within VeriStand (I.E. if you copy and paste a User Channel), but could be modified for a specific application.

ActionVIOnTargetTypeChange

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:

  • Check configuration settings: When changing targets, it's likely that many settings within your System Definition will become invalid. For example, if you're changing from PharLap to Windows, you may not have the same DAQ, FPGA, and other hardware resources available. If you're planning to change between these targets often, you could use this ActionVI to automatically disable the resources that will become invalid while also enabling resources you only want to use with the new target.


oncompileicon.JPG

  ActionVIOnCompile

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:

oncompileblock.png

Possible Use Cases:

  • Final Hardware Configuration – If your system definition file is compiling, it’s because the user is deploying the system. So, any final configuration of the hardware should be done at this time.


  • Gather host side settings – Often times, in your RT Engine VI, you’ll need to use settings and properties set in the System Definition. While these values could be read from the Real-Time side, it’s much faster to read all of the values on the host side, and compound them into a single cluster, convert that cluster to a variant, and write the variant as an Item Property.

The code snippet below demonstrates an ActionVIOnCompile which takes all of the custom device settings and writes them to a single property:

oncompileexample.png

Implementing an ActionVI

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:

actionvixmlexample.JPG

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/

4 Easy Steps to a New ActionVI

  1. Create a new ActionVI from its template. When you create a new custom device, using the Custom Device Template Tool found in vi.lib, the Project that is created for you will contain the Custom Device API.lvlib. If you expand this library, you see a templates folder. Expand the Templates folder and you see several other folders, one of which is labeled ActionVIs. If you expand this folder, you’re now looking at the templates for 8 of the ActionVIs. Remember, the template for ActionVIOnTargetTypeChange is currently missing. To create a new ActionVI, first locate the template for the ActionVI you wish to create, then right click on the template in the project and select “New from Template”. This will create a new VI from the ActionVI template which you can then save and begin to add your custom code.
  2. Implement Custom Code. Use the pre-defined inputs and outputs of the template to produce the functionality you desire. For simple testing and demonstration purposes, I recommend using a one button dialog function.
  3. Modify the Custom Device XML. Now that we’ve created our custom ActionVI, we need to declare it in the custom device’s XML so that when the action is triggered for this specific page, it will call this VI. The declaration of the ActionVI consists of two main parts: your identification of the type of ActionVI you’re registering, as well as the path to your ActionVI code on disk.Refer to the previous section for an example declaration. When specifying the path for your ActionVI and choosing where to place it within your Build Specification, remember that since ActionVIs execute on the host it is proper practice to include them in the Configuration LLB.
  4. Modify the Build Specification for the Configuration LLB. Now that we’ve created a new ActionVI, we need to include it in the Configuration LLB and re-build the LLB. Rebuilding the LLB will also include our modified XML file. To modify the build specification complete the following:

    1. Open the Configuration LLB build specification and go to Source Files
    2. Expand your Custom Device.lvlib
    3. Select your new ActionVI VI and move it over to always included
    4. Go to the Source File Settings category
    5. Expand your Custom Device.lvlib and select your new ActionVI VI
    6. Set it’s Destination to be the Configuration LLB
    7. Select OK to save these new settings to the Build Specification
    8. Right-Click the Build Specification and select Build

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.

ActionVIs within Current VeriStand Add-Ons

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:

  • ActionVIOnDelete
    • Scan Engine EtherCAT Add-On


  • ActionVIOnDownload
    • Scan Engine EtherCAT Add-On
    • J1939 Add-On
    • Data Dashboard Add-On


  • ActionVIOnLoad (Not All Listed)
    • Scan Engine EtherCAT Add-On
    • Engine Simulation Add-On
    • Sensor Simulation Add-On
    • Resistive Simulation Add-On
    • J1939 Add-On
    • Embedded Data Logger


  • ActionVIOnCompile
    • Resistive Simulation Add-On


  • ActionVIOnSave
    • Sensor Simulation Add-On
    • Engine Simulation Add-On


Simple ActionVI Example

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:

  • VeriStand 2012
  • LabVIEW 2012 (To open the source project and VIs)

Support and Contact

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/).

Comments
Active Participant Craig_
Active Participant

How can I implement an action which fires every time the system definition is run on the target?

Craig H. | CLA CTA CLED | Applications Engineer | National Instruments
Active Participant Ryan_S
Active Participant

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

snip.JPG

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.

Member NFT
Member

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.

Active Participant Ryan_S
Active Participant

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.

Member NFT
Member

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.

Active Participant Dagaror
Active Participant

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

Active Participant Ryan_S
Active Participant

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

Active Participant Dagaror
Active Participant

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

Contributors