Reference Design for Plugin and Image Deployment to a CompactRIO using a Memory Device

[cpeacock]

Overview

After a LabVIEW Real-Time application has been deployed to a CompactRIO (CompactRIO) controller, it may become necessary to update the application code on the controller while the CompactRIO system is embedded in an application or device. This tutorial and reference design example illustrate one option of using a memory device to easily and quickly deploy a new application without the need to connect a laptop or other computer to the embedded CompactRIO hardware. This tutorial provides a step-by-step description and example of developing a LabVIEW Real-Time application, for deployment to a CompactRIO controller, which can be updated from a memory device after initial deployment.

Description

CompactRIOdeployment.zip, attached below, contains the reference design and example described in this tutorial. Unzip the file in an empty folder on your computer and open the LabVIEW project.

Hardware and Software Requirements

Software

Application Software: LabVIEW Full Development System 2012

Driver: NI-RIO 5.0

Toolkits and Add-Ons: LabVIEW Real-Time Module 2012

Language(s): LabVIEW

Hardware

Hardware Group: CompactRIO

Steps to Implement or Execute Code

Theory of Operation

The process of updating or deploying a new application image from a memory device to a CompactRIO controller is based on a simple file copy operation which replaces the files on the hard drive of the CompactRIO controller with files stored on a memory device. This file copy operation is added as a VI to the main LabVIEW Real-Time application deployed to the controller.  When the controller powers up the Real-Time application launches this VI which performs the copy operation after it determines whether a memory device containing updated files is present.

A LabVIEW Real-Time application and Real-Time OS once loaded and running on the controller is stored completely in the active memory (RAM) of the controller. This allows an application to delete and replace any files stored on the controller hard drive while the application is running in memory. The new application becomes active by performing a reboot operation on the controller and loading the new application during the boot process.

Note that a Real-Time system running Pharlap is not completely loaded into memory which limits write-access to the hard drive.  This limits the deployment of full images to VxWorks targets.  The deployment of a plug-in can still be performed on any target as long as the destination folder is not write-protected.

Process

Below are the main steps to generating an application and supporting the deployment from a memory device:

Initial Application Deployment

1. Using the code provided, open the Main Application and alter the hard coded default launch path to reflect the name and location of the VI that launches the plug-in application.
2. Build the Main Application into a Real-Time Application and deploy it to the CompactRIO over an Ethernet connection.
3. Develop the initial application that can be called dynamically as a plug-in.
4. Build the plug-in application and deploy it over an Ethernet connection to the directory that matches the launch path hard coded into the Main Application.

Developing and Deploying an Updated Application Plug-In

1. Develop the updated application that can be called dynamically as a plug-in.
2. Build the plug-in application and place it in a folder containing no other files.
3. Open and run the Copy Utility that is included in the provided code.
4. When prompted, navigate to the root directory of the memory device used for deployment.
5. Select the option to create a plug-in then navigate to the folder containing the plug-in application.
6. Specify the controller directory to which the plug-in application will be copied.
7. Enter the desired Version Number, Key, Deployment Blacklist, and Launch Path.
8. Deploy the updated application to an embedded CompactRIO controller using the updated memory device.

Developing and Deploying an Updated Controller Image and Application

1. Develop and build the updated plug-in application
2. Update the Main Application to reflect any changes in launch path then build the Real-Time Application.
3. Deploy the plug-in application, Real-Time Application, and any other system updates to a networked CompactRIO of same model as the deployment CompactRIO.
4. Open the Replication and Deployment utility and create an image of the networked CompactRIO.
5. Open and run the Copy Utility that is included in the provided code.
6. When prompted, navigate to the root directory of the memory device used for deployment.
7. Select the option to create an image then navigate to the image file.
8. Enter the desired Version Number, Key, Deployment Blacklist, and Launch Path.
9. Deploy the updated application to an embedded CompactRIO controller by inserting the memory device and restarting the controller.

Requirements and Restrictions

The  CompactRIO controllers in the 901X and 902X line contain a USB port that can be used to deploy an update using a USB memory device.  All CompactRIO controllers can use the NI-9802 C-Series module to deploy an update using a SD memory device.

The update process requires the main application to run properly in order to recognize the memory device and copy files from the device to the controller hard drive. Therefore, if the main application is not running successfully, such as may be the case if the hard drive of the controller has been corrupted, then this method of deploying a new application will not work. For this reason this method cannot be used to re-image, recover, or repair a corrupted controller hard drive. 

Initial Application Deployment

This section focuses on the steps required to setup a CompactRIO for updates via a memory device. The startup application that accommodates deployment via memory devices must be initially deployed using an Ethernet connection.  Deployment of the plug-in application need not accompany the initial deployment of the startup application, though it is convenient to do so during initial deployment if desired.

Once the code provided in this tutorial has been downloaded launch the .lvproj file and open the Main Application highlighted in Figure 1. Two Main Applications are provided in this code depending on the type of memory device that will be used. This tutorial uses the USB deployment example but an example demonstrating the use of an SD card is also provided.

Figure 1: LabVIEW Real-Time Application

1. Once the USB Main application has been launched, open and examine the block diagram.  The Deploy Image.vi has inputs that enable or disable Image Retrieval and Reboot on Update.  By default, Image Retrieval is disabled and Reboot on Update is enabled.  Within the case structure is the code used to launch the plug-in application. There is a hard coded path and a path loaded from an lvappimage.info file. Notice that the hard coded path is only used if the LaunchPath token is not found in the .info file.  Modify this hard coded path to reflect the expected name and location of the VI that will launch the plug-in application.

   Figure 2: USB Main Application block diagram

2. Build the Main Application into a Real-Time Application by using either the build specification included in the project or creating a new one and adding the Main Application as the top level VI.  Once the application has been built, the CompactRIO must be accessible via Ethernet before the application can be deployed. The easiest way to access the CompactRIO is to right click the controller in the project, select properties, and enter the IP address of the controller.  Once connected, right click the Real-Time Application build specification and select “Run as startup” which will deploy the application, set it as startup, and reboot the controller.

   Figure 3: USB Main Application build specification

3. Develop the initial application that can be called dynamically as a plug-in. For this tutorial we will use a very simple LabVIEW Real-Time application to illustrate and test the use of a plug-in application with the deployment code. The plug-in application that will be called dynamically will toggle (blink) the user LED on the CompactRIO controller.  The block diagram seen in Figure 4 belongs to the Application_Plugin.vi included in the provided code.

   Figure 4: LabVIEW Real-Time Plug-in Application

4. Build the plug-in application and deploy it over an Ethernet connection to the directory that matches the launch path hard coded into the Main Application.  The plug-in application must be built into either a source distribution or a packed library.  The packed library in the provided build specifications has been configured to deploy to the Application.lvlib to the /c/app/ directory which corresponds to the default hard coded path in the deployed startup application.  Once the packed library has been built it can be deployed from the project explorer since the CompactRIO is still connected via an Ethernet connection.  The Main Application should load the plug-in application which will blink the User LED next time the CompactRIO is restarted.

   Figure 5: LabVIEW Real-Time Plug-in Application Build Specification

The deployed application and executable together with all of the other files on the CompactRIO controller hard drive becomes the application image. If the initial application image needs to be deployed to multiple embedded controllers you can use the Replication and Deployment (RAD) utility.  It is good practice to keep an image of a controller even if it is not being replicated on other controllers to assist the creation of a blacklist for future updates.  In the next two sections we will discuss how to deploy an updated plug-in application and an updated controller image respectively.

Developing and Deploying an Updated Application Plug-In

After developing and deploying the initial application, we are now at the point where we want to develop an updated application and deploy it from a memory device to a CompactRIO system that is running the initial application. 

1. Develop the updated application that can be called dynamically as a plug-in. Deployment of an updated application can be simulated by manually editing the wait time to increase the blink rate of the Application_Plugin.vi that was previously deployed.

   Figure 6: Updated LabVIEW Real-Time Application

2. Build the plug-in application and place it in a folder containing no other files. Viewing the properties of the packed library build specifications included in the project will show that it has been configured to place builds in the C:\Builds\Packed_Library directory. Rebuilding the Packed_Library_Plugin will automatically place an updated packed library in the builds directory.

   Figure 7: Packed Library Build Specification Properties

3. Open and run the Copy Utility that is included in the provided code.

   Figure 8: Copy Utility

4. When prompted, navigate to the root directory of the memory device used for deployment. If there is already a folder named “appimg” on the root directory of the device, a message asking if you want to delete the appimg folder will pop-up.

   Figure 9: Memory Device Select Dialog

5. Select the option to create a plug-in then navigate to the folder containing the plug-in application.  If the plug-in application is contained within a single file as may be the case for an LLB then select that file and click Open.  Otherwise, navigate to the folder containing the plug-in application files and click Current Folder as seen in Figure 10 for the packed library and its supporting dll.

   Figure 10: Plug-in Application Select Dialog

6. Specify the controller directory to which the plug-in application will be copied. Modifying the default value is only necessary if the plug-in application is being deployed to a directory that is not located on the root directory of the controller.  Since placing the plug-in on the root directory of the controller greatly simplifies deployment, it is recommended that the Path Control be left unmodified before clicking OK.

   Figure 11: Plug-in Application Controller Directory

7. Enter the desired Version Number, Key, Deployment Blacklist, and Launch Path. The default values will work with the provided plug-in selected in step 5.

   Figure 12: Plug-in Application lvappimage.info File Configuration

8. Deploy the updated application to an embedded CompactRIO controller using the updated memory device. To update the image on an embedded controller place the memory device in the controller and reboot the controller.

During the application startup process the Deploy Image VI will detect the memory device, compare the key and version number between the lvappimage.info files on the controller and memory device, and if necessary will copy the application from the memory device to the controller. It will copy the application if the .info files contain a different key or version number or if there is no info file located on the controller. After placing the new application on the controller it will archive the controller’s old info file and copy over the info file that was on the memory device. If specified in the original application, the Deploy Image VI will reboot the controller after updating the application image to load the updated application. Depending on the size of the application image and the type and speed of memory used, this process can take several minutes to complete.

Developing and Deploying an Updated Controller Image and Application

It may be necessary to update several drivers or upgrade the version of LabVIEW Real-Time on a deployed CompactRIO to accommodate an updated version of an application. This is accomplished by imaging a CompactRIO of the same model with the desired updates and upgrades installed. The image is placed on a memory device and used to replace the existing image on the deployed CompactRIO. Deployment of a full image is considered riskier than deployment of a plug-in application since an error in the copy process may exclude necessary components of the OS or the startup application which would require an Ethernet connection to remedy.

1. Develop and build the updated plug-in application. As was discussed in the Initial Application Deployment section, the plug-in application must be built into a packed library or source distribution.
2. Update the Main Application to reflect any changes in launch path then build the Real-Time Application.
3. Deploy the plug-in application, Real-Time Application, and any other system updates to a networked CompactRIO of same model as the deployment CompactRIO.
4. Open the Replication and Deployment utility and create an image of the updated CompactRIO. The linked developer zone article provides step by step instructions on how to create an image of a networked RT target with the Replication and Deployment utility. The utility should create a file with the extension .lvappimg in the C:\AppImages folder.

   Figure 13: Replication and Deployment Utility

5. Open and run the Copy Utility that is included in the provided code.

   Figure 14: Copy Utility

6. When prompted, navigate to the root directory of the memory device used for deployment.

   Figure 15: Memory Device Select Dialog

7. Select the option to create an image then navigate to the image file. Select an image file created by the RAD utility and click OK. If the selected file does not have the extension .lvappimg then a pop-up will ask you if you are sure you want to proceed with the selected file. Depending on the size of the image, it may take a few minutes to transfer onto the memory device.

   Figure 16: CompactRIO Image Select Dialog

8. Enter the desired Version Number, Key, Deployment Blacklist, and Launch Path. Note that the displayed values reflect the current values in the lvappimage.info file that was generated with the image.  Click modify to save any changes to the .info file or click Don’t Modify to discard any changes and continue.

   Figure 17: Image lvappimage.info file configuration

9. Deploy the updated application to an embedded CompactRIO controller by inserting the memory device and restarting the controller.

SD Main Application Example

The provided code included examples of a Main Application that can be built into a startup application for either USB or an SD memory device.  Though the steps to deploy a plug-in application or image update are the same regardless of memory device, the steps for the initial configuration will be slightly different. The initial setup steps will require that an FPGA VI has been compiled that includes information on which slot the 9802 is in. In the example provided a 9802 has been added to the chassis in slot 1.  If desired, a 9802 could be added to every slot of the chassis and then compiled to accommodate the ability to deploy from any slot in the chassis. This would require modification of Main_Application_SD.vi since it checks a single slot before continuing to the Deploy Image.vi. 

Once it has been decided which slot the 9802 will be compiled in, the FPGA VI must be recompiled for the specific target that application will be deployed to. Changing the slot the the 9802 will be deployed to will require a recompile of the VI. Note that the included FPGA VI contains code that blinks the FPGA LED on the CompactRIO while it is running.

Figure 18: VI Compiled for FPGA Target

Once the FPGA vi has been compiled the NI 9802 RT Access (Host).vi which resides within the Main_Application_SD.vi must be pointed towards the compiled VI or the bitfile associated with the VI. The code seen in Figure 18 first loads this bitfile, then once it has been loaded it mounts the 9802 and passes the enumerated drive letter into the Deploy Image.vi which then executes the same code that it would use if a USB memory device were present.  The only difference between a startup application that detects a USB memory device and a SD memory device is the code in the NI 9802 RT Access (Host).vi loads the bitfile and mounts the drive before it calls the Deploy Image.vi.

Figure 19: Main_Application_SD.vi and NI 9802 RT Access (Host).vi Block Diagram

 

 

Implementation

This section will describe the code implemented within the Deploy Image.vi that is responsible for detecting a memory device, determining if there is an image present, and performing the copy operation. This VI is organized as a simple state machine in a sequence of steps managed in a Case structure. The steps are:

1. Check for USB memory
2. Compare Keys
3. Retrieve Image
4. Calculate List
5. Copy Files
6. Delete
7. Reboot Controller
8. Exit

The names of the different folders and files used by the VI are specified by constants on the diagram. These may be changed for your specific application, but you must make sure that they match to the folder and file names used in the Deploy Image VI.

During the copy process the VI maintains a log file on the USB device to store the progress of the operation and record any errors. 

Check for USB memory

In this first step the VI checks for the presence of a USB memory device. If the device is present and detected by LabVIEW it will appear as a hard drive with the letter U: designation (the RT OS will always enumerate the first external volume detected with the letter U). Using the Get Volume Info function the VI checks for the presence of a drive at U:.

In this step the replicationlog.txt file is created or opened and an initial entry is made on both the controller and memory device.

If a memory device is not detected the VI proceeds to Exit.  Otherwise, it proceeds on to Compare Keys.

 Compare Keys

The case checks to see if there are lvappimage.info files on the controller or the memory device. It then checks for the Version and Key tokens and compares the values between the two files. The result of transition code then depends on whether the Disable Image Retrieval has been left by default to true (true meaning that image retrieval is disabled) or if has been changed to false via the input terminal or a different default value.

If image retrieval remains disabled, then the VI proceeds to the Calculate List case if the memory has a .info and the controller does not have an .info file or if the keys in both .info files do not match.  Otherwise the VI proceeds to the Exit case.

If image retrieval is enabled, then the VI will proceed to Retrieve Image only if there is an .info file on the controller and there is not an .info file on the memory device.  Otherwise it uses the same logic as image retrieval disabled to determine whether to move into Calculate List or Exit.

Retrieve Image

If image retrieval is enabled and a .info file was detected on the controller but not the memory device then the Retrieve Image case will execute. This case contains the Retrieve Image.vi which copies all files and folders from the controller onto the memory device.  The files and folders are copied into the an appimage folder on the root directory of the memory device. Once copying has completed the memory device can be used to image other controllers running the requisite startup application.

The VI proceeds to Exit once Retrieve Image.vi has completed.

Calculate List

The case retrieves the blacklist from the lvappimage.info file on the memory device to determine which files and folders will not be overwritten or deleted during the copy process.

The copy list is generated by comparing a list of files on the memory device against the black list.  If a file is not on the black list or within a sub directory of a folder on the black list but is within the appimage folder on the memory device, it will be placed in the copy list.

The delete list is generated by comparing a list of files on the controller to the copy list and the black list.  If a file is not on the black list or within a sub directory of a folder on the black list or on the copy list but it is on the controller, it will be placed in the delete list.

Note that replicationlog.txt files, lvappiamge.info files, and c:\image_history on the memory device and controller are hard coded into the black list.  These will never be deleted or copied unless the code is manually modified to remove these from the blacklist. It should also be noted the lvappimage.info files are manually inserted at the end of the copy list to ensure that they are the last files copied over.

Once the lists have been calculated the VI proceeds to Copy Files.

Copy Files

This step copies all of the files and folders on the copy list from the appimage folder on the memory device over to its respective directory on the CompactRIO controller.

The last files to be copied will be the lvappimge.info files. Before the .info file from the memory device overwrites the controllers .info file, the old controller .info file will be copied into the c:\image_history directory.

If there is an error detected at any point during the copy process, copying halts, the error is logged, and the VI proceeds to Reboot Controller. Since the lvappiamge.info file is the last file copied over the controller should be able to begin the copying process again when restarted assuming the files being copied were part of a plug-in application and not the RT OS.

Once copying has completed the VI proceeds to Delete.

Delete

The step deletes all files and folders on the delete list off of the controller.

Reboot Controller

This step reboots the controller unless the Reboot on Update input has been changed to false.

Exit

The last step places a final comment in the log file and closes it.

Additional Information or References

Limitations and Customization

This example and tutorial present a basic implementation for deploying a plug-in application or a full image from a memory device to a CompactRIO controller. It may not satisfy all of the requirements or needs of a particular application. For example, in some instance it may be necessary to accommodate an update from either a USB or SD device.  Without any changes to the provided Main Applications there would not be a way to accommodate both options from a single cRIO.  Modifications would need to be made that would first check to see if one was present then check to see if the other is present and continue on with the deployment code if either turns up with a device present. Customization would also be required to accommodate SD deployment from any slot in a cRIO.  The current invocation requires a bitfile that has been compiled with the 9802 in a predefined slot.  A system could be configured that used a bitfile that was precompiled with a 9802 in every slot so that the startup application could check every slot for a memory device.  Another possible custom feature would be the examination of multiple memory devices rather than the first device detected. The current startup application checks only the first enumerated drive (which will always be a /U/ drive) and does not continue on to look for additional memory devices.

In the example the Deploy Image VI is run during the application startup process before the plug-in application VI is started. To update the application image on the controller the memory device is plugged into the controller and the controller is reset. During the following startup sequence the memory device will be detected and the new application image copied to the controller, followed by another software-initiated reboot operation which will load and run the new application. In some cases it may not be desirable to reset the controller to copy a new application image. In this case the Deploy Image VI can be integrated differently into an application so that it can run at any point in time and detect a memory device inserted into the controller. This could be done in a parallel loop running periodically (e.g. every 5 seconds) to check for the presence of a new application image. After the application image is updated the VI can send a message to the rest of the application to stop any ongoing process gracefully before resetting the controller to load and run the new application image.

As was mentioned earlier, the basic requirement for this deployment process to work is that the Deploy Image VI must run on the controller in order to detect the memory device and copy the new application to the controller hard drive. If for any reason the controller is in a state where this VI cannot run or if it is missing from the current application on the controller then this method will not work.  If the controller's hard drive is corrupted or if the deployed application will not run then the controller needs to be recovered or updated using an Ethernet connection from a system containing the Measurement & Automation Explorer (MAX) and the LabVIEW development environment.

This reference design was created by the NI Systems Engineering group. 

Please post your questions and comments for this reference design in the USB Deployment Discussion Forum.