Replication and Deployment (RAD) Utility

Overview

Imaging is an effective tool for managing the software deployments of real-time (RT) targets. However, building a robust application to automate application deployment and management of real-time targets with imaging APIs is not a trivial undertaking. The Replication and Deployment (RAD) reference utility provides a turn-key solution for automated RT image deployment, replication, and management. It is built using functionality provided by the System Configuration VIs.

The RAD installer includes the LabVIEW Run-Time Engine 2016 and the NI System Configuration 16.0.1 Run-Time Engine. To install the reference application, unzip the installer ZIP file to an empty working directory and run the installer (setup.exe). The installer will place a compiled executable of the utility in <National Instruments>\RAD. The installer does not include the NI-RIO driver. To enable the RAD utility’s full feature set, the NI RIO driver should also be installed. The NI RIO driver is required to deploy bitiles to FPGA flash. If this driver is not installed, an image containing a bitfile for flash deployment cannot be deployed. If this feature is not being used, then the NI-RIO driver does not need to be installed.

The Source Code ZIP file contains only the source code with no installer. This code can be unzipped into any folder on your system. There are no additional libraries required.

*Depending on the installed version of RIO, some RIO-specific resource files may need to be copied from the RAD source\objmgr directory into the LabVIEW resource\objmgr directory.

The above referenced Code is provided As Is. It has not been tested or validated as a product, for use in a deployed application or system, or for use in hazardous environments. You assume all risks for use of the Code and use of the Code is subject to the Sample Code License Terms which can be found at: http://ni.com/samplecodelicense

1. User Guide

Being able to replicate the image of a real-time target makes deploying targets and systems easier and more efficient. Whether the user is making periodic backups of a system, deploying from a developed system to many new ones, updating an image on a target, or giving someone else the tools to duplicate a working system, replicating an image makes all of these applications possible. The Replication and Deployment utility makes the system replication simple and intuitive.

When replicating applications from one target to another, the application image is retrieved from one RT target and copied to another. An application image is comprised of the contents (all of the files and directories) of the hard drive of an RT target which define the behavior of the RT target, as well as any bitfiles set to deploy to FPGA flash memory. Application image versions can be managed (organized by both creation date and version number) and compared with RAD, allowing the user to leverage the benefits of source code control for configuration management. The utility only supports transferring images between identical controllers and backplanes. If you receive an image from a specific controller, you can only deploy that image to controllers with the same model number.

The Replication and Deployment utility shows these two entities, Deployment Targets and Application Images, in two tables on the main UI of the utility.

The Deployment Targets table shows all of the real-time targets available on the local subnet or, alternatively, only those network targets manually added to the list (configurable in Deployment Target Settings). These targets can be used for both image retrieval and image deployment. The Application Images table shows all of the available images which are currently stored on the local hard drive and can be deployed to a target system. Deployment of an application image to an RT target overwrites its current state, and it is good practice to back up a target images prior to a new deployment if it may be needed later.

Retrieving Application Images

The first step in replicating a real-time system is retrieving the application image. The Deployment Targets table of the RAD utility contains a list of the RT target systems on the network. Using the Settings button above the table you select the types of RT targets that will be shown in the table. The options for real-time targets include CompactRIO, FieldPoint, PXI, or all other systems. You can also choose whether or not you would like to see all targets on the local subnet, or just those targets added to the utility manually. The dialog box for selecting these options is shown below.

Figure 2: RT Target Configuration Dialog

After the target type selection is made in the configuration dialog and the Refresh button is clicked (above the Deployment Targets table) all of the available targets of the types specified will be listed in the table.

The user can view basic information about each target in the table. Additional information about each target system is available by right-clicking on a target in the table and selecting View Target Info.

Figure 3: RT Target Information Dialog

To add a target to the list that is not on the local subnet, click on the Add Target button to view a dialog similar to the one shown below.

Figure 4: Add Target Dialog

Next, enter in the IP address of the target that you would like to add to your user list and click Get Info. If the information displayed in the table looks accurate, click the Add button to add this target to the window. The target will remain added to this window even after closing and reopening the application. To permanently remove the item from the window, simply right-click the target that you would like to remove and select Delete Target.

The RAD utility also provides the functionality to change some of the network settings for targets that are on the network. In order to change the network configuration settings of a target, the user can select the target and click the Configure button to bring up a dialog box similar to the following.

Figure 5: RT Target Network Configuration

To copy the application image from a RT target to the local hard drive, select the appropriate target in the table and click the Retrieve button in the center of the UI.

If this is the first time an image will be created for this application, select New Application Image. If images have already been created for this application, consider inheriting the properties of an older image file either on the selected controller or on your local hard drive.

Figure 6: Select Image Properties Inheritance Source

After making this selection, the user will be presented with the following dialog box where they can specify the local file for the application image and specify some additional information which will be stored with the application image. If this is not a new image, properties from the old version of the image will automatically be populated.

Figure 7: Configure Application Image Properties

The version field can be used to keep track of different versions of the same application image. If this is not a new image, the old image version number will be displayed. This version number will be automatically incremented in the New Version field, but can be changed to any version number as long as the New Version is greater than the Old Version number.

In addition to specifying a Name, Version, and Description, the RAD also allows users to configure file and directory blacklists as well as select bitfiles for FPGA flash deployment. A user will see the following dialog after selecting Configure Retrieval and Deployment Blacklists. Click Add to designate additional files to blacklist.

Figure 8: Configure Retrieve and Deploy Blacklists

The retrieve blacklist is used to prevent specific files or directories from being gathered as part of an image. The deploy blacklist is used to protect specific files on the target when deploying an image. This feature is particularly useful for protecting data or configuration files during an upgrade. This is an advanced feature and additional help is provided in the utility via the Explain This button.

Figure 9: Retrieve and Deploy Blacklist Help

In addition to retrieving and deploying an image of the RT hard drive, the utility can also deploy bitfiles to FPGA flash memory. Saving a bitfile in flash memory has some advantages to deploying the bitfile from the RT EXE. For more information regarding the pros and cons of FPGA deployment options, see Managing FPGA Deployments.

If your application does require that one or more bitfiles get deployed to FPGA flash, bitfiles can be saved with an image during retrieval and then later deployed to flash when the image is deployed. Click Configure Bitfile(s) for FPGA Flash Deployment to edit your FPGA flash deployment settings for this particular image and the following dialog will appear.

Figure 10: FPGA Flash Deployment Settings Dialog

A user can then add one or more specific bitfiles located on the local hard drive to be saved with the retrieved image. Note that this bitfile must be found on the local hard drive because it cannot be retrieved from the FPGA flash directly. Also note that a user will receive a warning if the selected bitfile was not compiled to run when loaded, as this is the most typical use case for a FPGA flash deployment. Make sure that the RIO Resource name matches the name of the FPGA resource for your image. Once the proper settings have been specified click Done.

Figure 11: Choose Image Save Location

After all of the settings and descriptions are entered into the Application Image Properties dialog, click the OK button. At this point, a dialog will appear asking for the image save location. A default path will be provided. Next click the Retrieve image from controller button to copy the application image from the selected target. Note that retrieving an image from a controller will reboot it. Do not retrieve an image from a controller unless it is in a safe state to reboot.

During the retrieval process, the following dialog will be shown. This dialog will report accurate status and progress information.

Figure 12: Retrieve Application Image Progress Dialog

A few additional files will be transferred to the controller during the retrieval process. These files contain information about the properties of the created image. This makes these image properties available for future retrievals. If there are any errors during the retrieval process they will be shown in an error dialog afterwards.

Once the image is retrieved, it will be listed in the Application Images list. A user can then view the properties of an image by right-clicking an image and selecting View App Image Info. At that point, the following dialog will be displayed.

Figure 13: View App Image Info Dialog

A user can also see the software stack that was installed on the target when the image was created by clicking View Installed Software. This feature allows a user to better manage their library of images.

Figure 14: View Installed Software Dialog

Deploying Application Images

To deploy an application image to an RT target on the network, the image must be stored in a folder accessible to the computer running the RAD utility. This folder can be located on a shared network server. The Application Images table in the utility shows all of the available application images in a specified folder. In order to change the folder used to locate images, click the Settings button above the table to bring up a dialog similar to the following.

Figure 15: Application Images Settings Dialog

All of the application images in this folder (*.lvappimg) will be shown in the table unless they were created using an older version of the utility. In order to view or update the additional information of an application image in the table, you can select the image and click on the Configure button below the table. Using this dialog you can update the name, version, descriptions, blacklists, and FPGA deployment settings stored in the application image.

Figure 16: Application Image Configuration Dialog

To deploy an application image to one or more targets, select the image in the right hand table and select the desired RT targets in the left hand table. You can select multiple RT targets using a Ctrl-click or Shift-click or by clicking the Select All button. After completing your selection click on Deploy at the center of the UI. The following dialog will be shown to confirm your RT target selection and allow for additional target configuration options.

Figure 17: Application Image Deployment Dialog

If multiple targets were selected in the Deployment Targets table, then each selected controller appears in the above dialog.

The Replication And Deployment utility allows you to apply a specific network configuration to all RT targets during the deployment process. This configuration is mandatory if the current network settings for the target are unconfigured. By clicking on the Target Deployment Settings button you get the following dialog which allows you to configure the controllers’ network configuration settings as well as the deployment batch size.

Figure 18: Target Deployment Configuration Dialog

The RAD utility allows multiple targets to be deployed to simultaneously. The Deployment Batch Size is used to specify the maximum number of controllers that can be deployed to at the same time. For example, if four controllers are selected, and the Deployment Batch Size is 3, the first three controllers in the list will update simultaneously, and the fourth update will start once the first three finish.

The RAD utility supports multiple options for how IP settings are applied to targets during a deployment. The default option is to simply leave the controllers’ existing network settings alone. However, settings can also be copied from the image or set to a user-specified configuration. If user-specified, there is an option for each target to keep its existing name during the deployment, or for the same name to be applied to all targets. In addition, there is an option to assign each controller the same IP settings or to increment the static IP address applied to each target. Consider setting a particular configuration as the default if it is frequently used.

After verifying the selected targets and setting any desired network configuration options for your RT targets, click on Deploy Application Image to Listed Targets to begin the deployment process. Accurate status information will then be provided for each target. This process will take several minutes per batch. Stop After Current Batch can be used to halt the operation after the current batch completes, but there is no way to cancel a batch that is in progress.

Figure 19: Application Image Deployment Progress

After the deployment is completed, the deployment window is updated with the results of the deployment process. Any errors from the deployment will be shown in the table.

You can store the information and result from the deployment process in a text file using the Log Results button. This tab separated value (TSV) file can be loaded in Excel or imported into a variety of databases.

Comparing Application Images

In addition to retrieving and deploying application images, the utility provides tools for image management. The biggest such tool is the utility’s image comparison feature. The comparison tool first provides a preview of high level differences between the two images. It can also compare each file in two images to notify the user if any files have been modified, added, or removed.

There are two ways to perform a comparison. An Application Image saved to the local disk can be compared to either the files on a specific controller or to another image saved on disk. To view the comparison options for a specific image on disk, right-click that image and select Compare AppImage. If the user then selects Compare Local Image With Controller, the dialog will appear as shown below.

The Ignore Automatically Updated Files checkbox is used to determine whether or not the tool will ignore temporary files as well as files that are written to each time the target reboots. This allows the user to choose between a complete comparison of every file in both images, and a comparison that will filter out files that are expected to have differences.

The comparison tool can also be run using the Compare button in the middle of the main application window. If this button is clicked, the comparison of the selected controller and application image will begin automatically, populating the initial Comparison Results table. The Ignore Automatically Updated Files option will be checked.

Clicking the Compare Files button will complete the comparison process, comparing each file on both images for changes. Files that are found in one image and not the other are also identified. This process may take several minutes to complete and a progress dialog will be displayed until completion. If the tool completes with no differences found, the following dialog will appear.

Figure 24: Identical Images Notification

However, if any differences are identified, they will be listed in the following table. If desired, the results can then be logged to a TSV file similar in format to Figure 16.

Note: The option to "Compare Files" is not available for NI Linux Real-Time Controllers.

NI-Auth Interaction

The RAD will automatically detect if a target is protected by NI-Auth or a simple FTP password and will prompt for a password before allowing a user to interact with that target. If a target is found to be protected, the following dialog will be displayed to the user.

Figure 26: NI-Auth Login

If an invalid password is entered, the dialog will reappear until the password is valid or the user selects Cancel. If the password is valid, it will be saved with that controller’s IP address so that it won’t need to be entered again. In addition, the RAD will automatically attempt to use that password on any additional locked targets. This means that if every target on the network uses the same password, that password will only need to be entered once. Any saved passwords are automatically cleared when the RAD utility is closed. As a result, they will need to be reentered each RAD session.

Updating RTAD 2.x and RAD 3.x Images for Compatibility with the RAD Utility

The RAD utility uses a different image format than what was used for RTAD 2.x images. An image conversion utility is provided with the RAD to update these older images. If an older image is found in the selected repository, the following dialog will appear.

Figure 27: Older/Newer Images Found

To update these images, navigate to Convert Images from the Images menu in the RAD Toolbar. The following dialog will then be displayed.

Figure 28: Image Conversion Utility

This utility will first make a backup directory of all of the older images before updating them and saving the new copies in the selected directory.

Quick Steps for Retrieving an Application Image

The following is a quick list of steps for retrieving an application image from a RT target:

Click the Settings button above the Deployment Targets table to show the type of target to get the image from.

Select the RT target that contains the desired application image.

Verify that the retrieval target is in a state were it is safe for it to reboot.

Click the Retrieve button in the center of the user interface.

Determine whether or not this is a brand new image or a new version of an existing image.

Enter the appropriate properties for the application image.

Click the Retrieve application image button.

Quick Steps for Deploying an Application Image

The following a quick list of steps for deploying an application image to a RT target:

Click the Settings button above the Application Images table to select the folder where application images are stored.

Select the application image in the table to be deployed.

Select the target(s) to which to deploy the application image.

Verify that the deployment target(s) are in a state where it is safe for a reboot.

Click the Deploy button in the center of the user interface.

Configure any desired network configuration settings for each target using the Target Configuration Option button.

Improved the error handling for when a target is directly connected, but has an IP address on a remote subnet

SSE2 optimization is no longer automatically enabled because it causes failures on some older machines

RAD Version 5.5.2 (12/9/2013)

When deploying an image, RAD tries to force the target into safe mode (to prevent an FPGA watchdog from causing a failure to occur)

Fixed a bug related to batch deployment

RAD Version 5.5.1 (11/14/2013)

When retrieving an image, RAD first verifies that the app image directory is valid.

Retrieving an image from a target without NI System Configuration 5.5 succeeds

RAD Version 5.5.0 (11/11/2013)

NI Linux Real-Time controller support

Removal of AMC dependency

Improved image and driver version management

Uses Create System Image.vi (from the NI System Configuration API) to ensure that metadata is stored on both the target and in the image metadata

Target network setting for TCP/IP address request mode now work with all supported modes (including Link-Local Only and DHCP Only)

Application image file (.lvappimg) layout now contains image contents directly, as opposed to being nested inside a .sysimg archive, allowing it to be reused with Set System Image.vi (NI System Configuration API)

When an image is deployed with NI-Auth settings, the settings are now written to the target (previous NI-Auth settings are overwritten)

Accessing of targets with an FTP “Lock” and/or NI-Auth settings is improved.

Image Comparison now initially displays only a summary dialog (image metadata and installed software), which is much quicker

RAD now checks for NI System Configuration (nisyscfg) version 5.5.1 or higher and presents the user with a warning if an older version is installed

The RAD executable is now installed in the National Instruments\RAD directory (not under LabVIEW projects)

4. Feedback

You can provide us feedback and suggestions for improvements to the reference application by posting questions and comments through the LabVIEW Real-Time Application Deployment discussion forum. If you would like to provide any updates or improvement to this utility or engage in a related discussion with the LabVIEW developer community, please go to the RAD document in the NI Community.

Everything seems fine but I found that at least two critical VIs are broken. So code not works with LV2013. Requirements say LV2012 development envirroment is needed but I am using LV2013. If code modified recently why LV2013 compatibility is not checked?
FOLDER
...\subVIs\App Images\Deploy App Images\RIOSystemReplication
VIs
Set RIO Device Settings 2010.vi
Download Bitfile.vi
Because these two VIs are password protected (why?) I coudn't fix errors. Please remove password protection or at least fix these two VIs as soon as possible.

-2147220369
- Apr 10, 2014

what can I do after getting this error code? I have set all realtime-systems with an admin-password and this shell remain.

works great except for some drivers
- Jan 7, 2014

By Joe Guo, SignalX Tech.

I used it to create an image of a PXI-8115
that has two 4472, one 4462, one pxi CAN, the
drivers for the 4472 and 4462 were installed
properly, but the CAN card didn't show up in
MAX until I manually reinstalled all the
components through MAX.

Urgent
- Nov 20, 2013

Is it possible to make crio real-time
application .exe to installer, since every time
when am connecting the crio to new PC I
need to install the labview packages. If there
is an installer for my crio application, I can
install it on a new PC and run the same.

Only works without PW on the RT-Target
- Nov 29, 2012

By Laurent Pollara, Helbling Technik.

Hi,
The application is working perfectly expect
for an minor and a major bug.
Minor Bug: Cancel a non-critical operation
like creating an Image should be given to the
user.
Major Bug: Retrieving and Deploying an Image
provides an error message when the cRIO is
password-protected. (Error -2147220621 at
nisyscfg.lvlib and error-2147220361 too)
I debugged the program and found the origin
of the problem:
Initialize Session.vi and Get installed SW.vi
provide some errors, not handled in any case
structure (-2147220621, -2147220361).
As the nisysconfig VIs are password
protected, I could only workaround the pb in
2 steps.
Step 1. In every Case structure from NI-Auth,
I added from the case "-2147220611" the 2
other errors.
Step 2. In rad_OpenSystem Config Session.vi,
I added "get installed SW.vi" between
"Initialize Session.vi" and the case structure.
These 2 steps prevent until today from any
error message with this tool :-)
Don't hesitate to contact me for more
information.

Project needs missing VI's
- Sep 8, 2011

Top level VI is broken. I downloaded the AMC
library as well but it seems to want
\user.lib\SystemReplication\_subVIs.llb\ProgressUpdate.vi
It might make sense to package the VI's with
all required dependencies already included in
the project. It wastes a lot of time
clicking through links trying to figure out
which version on which webpage is required.
Also, the installer will not let you install
the libraries to more than one LV version. I
have 3 versions on my PC.

- Dec 9, 2010

Does the RT impage deployment also
include the FPGA bitfile? Does it deploy
the bitfile to FPGA automatically?