This section contains additional information about the design and implementation of the RT Application Deployment (RTAD) utility to facilitate customizing this reference application for your application specific requirements. The source code of the utility is provided in the \examples\RTADU folder in LabVIEW and includes a project with an application executable and an installer build specification.
An Application Image is the contents of the hard drive on a RT target which defines the behavior and operations of the RT system. In order to create a RT application image you normally develop the application in the LabVIEW environment and initially deploy it to the RT target from the LabVIEW project. Typically this means building a RT executable, setting it to run on startup and deploying it to the RT target. Before using the RT Application Deployment utility you should have gone through this process and thoroughly tested your application on the standalone RT target.
There are some other uses of the RT Application Deployment utility which do not involve building a RT executable or even running an application on your RT target. For example you can use this utility to create and quickly deploy clean images of a RT target back or switch between different versions of LabVIEW Real-Time installed on a RT target.
The basic application image is created and deployed by the RT System Replication VIs used in the RTAD utility. These VIs store the files of the application image in a ZIP archive file. The RTAD utility uses *.lvappimg as the default extension for the application image files. You can use a different extension if desired or change the default used by the application.
Once created, both an application image properties file and any selected FPGA bitfiles are then added to the *.lvappimg file and the imaged controller.
Application Image Properties
In order to store additional information as part of the application image, the RTAD utility creates an additional INI configuration file (rtad_Create AppImage Info File.vi) during the retrieval process and adds it to the application image file created by the RT System Replication VIs. The file name for this file is lvappimage.info. It contains the following additional parameters:
- RTAD Version
- Application Image Name
- Application Image Version
- Application Image Description
- Application Image Identifier
- Date and Time of the Application Image
- Number of FPGA Flash Bitfiles
- Resource Name and Path for Each Bitfile
The utility reads information from this file (rtad_Read AppImage Properties.vi) when refreshing the application images table and allows you to update this information for existing application images.
The Application Image Identifier is a globally unique identifier (GUID). It is added to the lvappimage.info so that different versions of the same image can easily be tracked and identified, despite any changes to the image properties. However, no code has been created to expose this functionality. Instead the GUID is a feature that has been added simply to enable future enhancements to the tool.
You can add to or edit the information stored in this file in the source code.
The RT System Replication VIs also create an INI configuration file (RTImageInfo.ini) as part of creating the application image. You should not modify the contents of this file.
Code Design Overview
The RT Application Deployment utility uses the Queued Message Handler (QMH) design pattern as the basis of the main VI and several subVIs. This design pattern and the Asynchronous Message Communication (AMC) library used in the QMH are described in detail in the AMC and QMH documentation.
The QMH uses a basic event structure to receive user input from the front panel and creates messages in the queue to be processed by the VI. The message processor contains a case structure with a case for each of the operations of the VI. Some of the main operations of the RTAD utility handled are Refresh AppImages, Refresh Targets, Retrieve AppImage, and Deploy AppImage. Some user interaction may cause multiple operations to be performed by the message processor or some operations will always cause another operation to be performed. For example when the Retrieve AppImage operation is performed, it calls Refresh AppImages in order to update the table of application images on the main UI.
In addition when the utility is started some initial messages are placed on the queue in order to initialize the application.
The message processor contains an application state cluster in a shift register. This cluster contains basic information about the application including:
- Current Targets Setting
- List of Targets
- Application Images Settings
- List of Application Images
- Configuration File Path
Information from this cluster is used and updated by many operations in the utility.
In addition to this, the RTAD runs a resize engine in parallel with the rest of the application used to handle any application resize events. The resize engine was designed to equally grow and shrink the RT Targets and Application Images listboxes as the application is resized. All buttons are also shifted as necessary to properly align with the listboxes that have been resized. Finally, the columns of the multicolumn listboxes are auto-adjusted based on the resizing performed. This was achieved using splitter bars and VI Server properties.
The RTAD utility initialization process consists of these operations.
Init - Default: Initialization some front panel objects and values in the state cluster, such as the name for the application configuration file and default location of the application images folder.
Init - Load Config: Read the application configuration file and store the data in the state cluster.
Init - Configure Settings: Based on the data from the configuration file, initialize some other settings in the utility.
Refresh Targets - Update the list of RT targets in the state cluster. This operation also calls Update UI which refreshes the UI.
Refresh AppImages - Update the list of application images in the state cluster. This operation also calls Update UI which refreshes the UI.
RTAD Utility Configuration
The RTAD utility uses a configuration INI file (rtad_config.ini) which is stored in the same folder as the top level VI or executable. This information in this file is loaded during initialization of the utility and the file is updated during shutdown of the utility. It contains the following information about the utility.
Application Images Path
Folder where the application images are stored
RT Targets Settings
Setting which filters the RT targets that are displayed in the Real-Time Target table
User Added Targets Information
Information regarding the number of targets that have been manually added to the RT Targets listbox and their associated IP Addresses. This information is saved so that targets added to the list will remain in the list between application restarts until they are explicitly removed.
This entry is used to further customize the UI and/or operation of the RTAD utility. This setting is currently set to 'Manager'. If this setting is missing the Retrieve Application Images and Configure Application Image buttons are removed from the UI to prevent changes to the stored application images. You could define additional user profiles and configure the operation of the utility during the initialization process based on this setting. In a more complete implementation you would add complete user management and verification into this process.
This operation is performed using the RT Get Target Information VI from the RT utilities and returns a list of all RT targets on the local subnet as well as any targets manually entered into the utility.
During the Refresh Targets operation, as well as during several other longer operations in the utility, a Progress dialog is shown. This VI is a dynamic VI which is started using Util_Progress Show Progress Popup.vi. The progress bar is only intended to show activity by the utility and does not indicate the actual progress of the operation. The progress dialog is closed using Util_Progress Close Progress Popup.vi after the operation is completed.
Refresh Application Images
In order to update the list of application images available to the user, the utility retrieves a list of all files in the application images folder matching the default extension (*.lvappimg). For each of these files it extracts the default (RTImageInfo.ini) and custom configuration (lvappimage.info) files from the ZIP archive and reads the pertinent information. This list of application images is stored as a cluster array in the state cluster of the utility.
Retrieving Application Images
The retrieval of application images follows a specific sequence of steps implemented in rtad_Retrieve Application Image From Target.vi.
- First prompt the user to choose whether this is a new application, or if the application properties can be inherited from an older version on the controller or saved to disk.
- Prompt the user to select a file name for the application image and enter or edit the basic information about the image such as a name, version and description. The user can select an existing application image file as the destination in which case the file will be overwritten with the new application image.
- Edit FPGA Flash deployment settings to be saved with the image upon retrieval if required.
- Once all of the settings have been properly specified, retrieve the application image from the target and store the files in the specified file.
- If this is a new image, create a new GUID to associate with it.
- Create a custom application image information file (lvappimage.info).
- Remove the old lvappimage.info file as well as any flash bitfiles from the retrieved image if they exist, and then add the updated version of these files back to the zip directory.
- Also delete these image information files from the target if necessary and then FTP the updated versions to the controller. This ensures that the files on the controller exactly match the image files saved to disk.
- Clean up any files saved in the temporary folder.
The utility uses the LabVIEW RT Utilities API to retrieve an image from a target, and the FTP API installed with LabVIEW Real-Time to handle all other FTP functions. Wrapper VIs were created around all deployment and FTP functions so that a different deployment or file transfer technology could easily be used in the utility. To use a different deployment or file transfer API, simply replace the code in the existing wrapper functions with the desired code and convert any inputs or outputs as necessary.
Any files transferred to the controller are saved in the controllers C: directory. The application assumes that all controllers are using the standard username and password for their FTP server. If your controller’s FTP server is password protected, the utility will have to be modified to accommodate this. The proper credentials could be read from file, hard-coded into the FTP Wrapper functions, or entered at run-time by the user. Alternatively, the code that performs the FTP after retrieval could simply be removed.
The created lvappimage.info file gets transferred to the controller after the image retrieval so that the controller image is identical to the locally saved version and so that if a new image is created from the controller, the old image properties can be made available.
The FPGA bitfiles are saved with the image so that the user does not have to keep track of the local version of the bitfile on disk. Once the image has been created, the FPGA bitfile used to create the image can be modified or deleted, but the behavior of the image will remain unchanged if redeployed. The only downside to this approach is that the bitfiles can occasionally get very large, and will use limited disk space on the controller. If this is a concern, the utility can be modified to always search for the bitfile on local disk instead of within retrieved or deployed images.
Deploying Application Images and Custom RT Target Network Settings
Deploying an application image to one or more targets is a more intricate process as it must first check for image compatibility, deploy the application image files, deploy any selected bitfiles to FPGA flash, and finally apply any custom network settings to the selected RT targets.
The image compatibility simply checks to see if the hardware of the original controller matches the destination controller. By default, only the controller type is compared. However, an additional comparison of the controller backplane can be enabled to ensure that the image’s bitfiles can properly be deployed to flash. The CRI is used to retrieve backplane information from a cRIO controller during retrieval and deployment. If the backplanes don’t match, then the user will be notified that the image is incompatible. There are currently some limitations to this approach. The CRI can only retrieve information from a controller if RIO has been installed. As a result, a backplane compatibility check cannot be performed on a unconfigured target. Also, the CRI currently only works for cRIO backplanes, although it can be modified to support PXI FPGA targets. It is because of these limitations that this feature is disabled by default.
If desired, the FPGA portion of the compatibility check can be enabled by changing the CRI_INSTALLED conditional disable symbol in the project to True. When enabled, this check is only performed if the image contains a bitfile for FPGA flash. Therefore, there is no safeguard against a RT application that attempts to deploy its FPGA bitfile to an incompatible backplane at runtime.
If the target compatibility check returns no errors, the deployment process then begins. The following flowchart describes the process. This process, along with the target compatibility check, occurs sequentially for each selected deployment target in a loop.
Figure 21: Deployment Process Flowchart
The deployment process also includes the option to configure and then apply custom network settings to the RT targets during the deployment process. This option is of interest where you may have a large number of RT targets configured for DHCP during the deployment process in order to automatically assign them different IP addresses, but you want them all to have the same static IP address after deployment when each controller is built into its own system.
The option to apply custom network settings is handled in two steps. The first is the configuration of these settings which is handled by rtad_Target Configuration Options Dialog.vi. The information from this step is stored in a cluster and passed to the second step. The second step is the application of these custom settings to each RT target before the application image has been applied to a specific target. The application of custom network settings is handled by rtad_Configure Target.vi. In order to further customize or enhance this process you would normally update both of these VIs according to your needs and modify the cluster in order to pass the configuration information.
The deployment of the application image to each RT target is implemented in rtad_Deploy Image State Machine.vi. This sequential process does require several minutes for each RT target, depending on the size and number of files in the application image. The current RT System Replication VIs do not support simultaneous deployment of application images to multiple targets.
The FPGA flash deployment requires a version of NI-RIO to be installed. This feature is enabled by default. To disable this feature and run the utility on a machine without NI-RIO, the source code must be modified so that the RIO_INSTALLED conditional disable symbol in the project is set to False.
If the image contains an FPGA bitfile for flash deployment, then the ni-rt.ini file on the target is modified so that the start-up exe does not run on a reboot. The target is then rebooted and the FPGA bitfiles are deployed. The ni-rt.ini token is reset to its original state, and the target is rebooted for the last time. The deployment process will not wait for the reboot to complete during the last reboot. This may prevent the deployed target from appearing in the Target List after a deployment. Hitting refresh after a few moments should show the target in the list once again.
Deployment Results and Log
During the deployment process the result of the deployment for each RT target is stored in a String Array Shift Register in the For loop, and the table of selected targets on the dialog UI is updated. This string array and additional information about each target can be logged after the deployment process is completed. The RTAD utility stores this data in a Tab Separated Value (TSV) file, which can be opened in a text editor or Microsoft Excel, or can be imported into a database. This file contains the following information about each target in the deployment process:
- RT Target Model
- RT Target Model Code
- RT Target Serial Number
- MAC Address
- IP Address
- Host Name
- Application Image Name
- Application Image Version
- Date and Time of Deployment
- Result of the Deployment Process
The VI (rtad_Write Deployment Results to File.vi) which stored this data to file can of course be updated to directly store the data in a database.
Comparing Application Images
The comparison tool works by creating a checksum of every file in the two images and then compares these checksums one by one. The file names of any files that are different or that appear in one image and not the other are then saved. The comparison is performed by the rtad_RT Image Compare Dialog.vi which can run as a dialog or in the background. This VI was designed so that it can also run as a standalone tool or as a component of a different application.
The comparison process is fairly straightforward. First two images are gathered. If the tool is comparing two images saved locally, then no work is required to gather the images. However, a comparison of a local image to the image of a network controller requires that the network controller image is first retrieved.
Once the images are gathered, checksums are calculated for each file in both images and an array of file path/checksum pairs for both images are then compared. Any files with differing checksums as well as any files contained in one list and not the other are then noted.
The tool includes the option to ignore files that are commonly modified automatically by the controller. These files include anything in the controller’s temp directory as well as certain system files that may be modified at startup. This file list was found empirically and may not be exhaustive. Additional files can be added to the ignore list by adding them to the array constant in rtad_Calculate Checksum.vi.
The comparison results are then displayed in a table. This table contains a list of modified files, files found only in the first image, and files found only in the second image. Finally, the user has the option to log these results to file.