Archive of Reference Design for Deploying CompactRIO Application Updates using a USB Memory Device

This page houses archive version of the Reference Design used to deploy to a CompactRIO using a memory device. The Reference Design has been updated and published on a separate page. The download links and documentation for old Reference Design can be found below. If starting a new deployment management effort, please use the current version of the Reference Design, which can be found at: Reference Design for Plugin and Image Deployment to a CompactRIO using a Memory Device

usb_deployment_103.zip 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.

usb_deployment_103_install.zip contains a Windows installer that will automatically install the reference example into your LabVIEW examples directory. Unzip the file into an empty folder and run setup.exe.

The reference example contained in these two zip files is identical.

Feedback and Questions

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.

Theory of Operation

The process of updating or deploying a new application image from a USB 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 the USB memory device. This file copy operation is added as a VI to the main LabVIEW Real-Time application deployed to the controller. 

A LabVIEW Real-Time application once loaded and running on the controller is stored completely in the active memory (RAM) of the controller. This allows us to delete and replace the application 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.

Process

Below are the main steps to generating an application and supporting the deployment from USB memory option:

Initial Application Deployment

1. Develop the initial application.
2. Add the code provided in this tutorial to the application to support updating the deployed application from a USB memory device in the future.
3. Build the application into an executable and deploy it to all of the embedded controllers over an Ethernet connection using the normal LabVIEW deployment options (LabVIEW project, RT System Replication tool).

Developing and Deploying an Update to the Application

1. Develop the updated application.
2. Add the code provided in this tutorial to the updated application to support updating the deployed application from a USB memory device in the future.
3. Build the application into an executable and deploy it to a CompactRIO target using an Ethernet connection to create the new master image.
4. Retrieve the new controller image from the master target using the VI provided in this tutorial.
5. Place the new controller image on a USB memory device.
6. Deploy the updated application to embedded CompactRIO controllers using the USB memory device.

Requirements and Restrictions

The following CompactRIO controllers support this example for updating the deployed application from USB:

• cRIO-9012
• cRIO-9014

Current versions of other CompactRIO controllers do not include a USB port.

The update process requires the main application to run properly in order to recognize the USB 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 can not be used to re-image, recover, or repair a corrupted controller hard drive. 

Initial Application Deployment

The first time an application executable is deployed to the CompactRIO controller it must be deployed using a direct Ethernet connection. It can be deployed using the LabVIEW Project Explorer or using an FTP client to copy files directly to the hard drive on the controller. This initial deployed application must contain the code to detect a USB memory device and copy files for an updated application from the USB memory to the controller.

One option for deploying this initial application to the controller is the RT System Replication tools. Using these tools you can build a turn-key application to deploy a new controller image to a CompactRIO system.

For this tutorial we will use a very simple LabVIEW Real-Time application to illustrate and test the use of the USB deployment code. The main RT application will toggle (blink) the user LED on the CompactRIO controller. Different versions of this main application will blink the LED at different rates. The first version will toggle the LED at 1 second intervals.

Figure 1: LabVIEW Real-Time application - version 1

In order to update the deployed code from the USB memory device in the future, we must add code to the main application that will handle the deployment process. The VI that handles the update process (Deploy Image.vi) is described in detail below.

Figure 2: Complete application code to be deployed including the USB Deploy Image VI

Once this code has been added, the main application can be built into an executable and deployed to a CompactRIO controller. The controller is configured to load and run the application when the system is started (Right click on the individual build specification » Set as startup). The build process and deployment is handled through the Build Specification in the LabVIEW Project Explorer.

Figure 3: LabVIEW Project Explorer including the build specification for two versions of the main application

The deployed application executable together with all of the other files on the CompactRIO controller hard drive becomes the application image. In the next section we will retrieve the application image from one CompactRIO controller so that we can deploy it to other controllers. If the initial application image needs to be deployed to multiple embedded controllers you can use the standard LabVIEW Real-Time application deployment options. 

Using an FTP client you can retrieve the application image from the master CompactRIO controller and store it on the hard drive of a computer. You can then copy this application image to other CompactRIO controllers over an Ethernet connection using the FTP client. The RT System Replication tools allow you to automate this process in a LabVIEW VI.

Developing and Deploying an Updated Application

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 USB memory device to a CompactRIO system that is running the initial application.

The first step is to develop the updated application and then add the VI to support future deployment from USB memory. For our example the updated application (Application 2) will toggle the user LED on the CompactRIO controller at 0.1 second interval. The final code of the updated application is almost identical to the first version.

Figure 4: Complete updated application code to be deployed including the USB Deploy Image VI

The next step is to build the application into an executable and deploy it to a CompactRIO controller to create the controller image which will then be deployed to other embedded CompactRIO controllers. This is done using the LabVIEW project build specification as was done for the original application. 

After the executable is deployed to a CompactRIO controller and set to Autostart (Set as startup) we retrieve the application image from the controller hard drive. This can be done using a FTP client by copying all of the files and folders from the CompactRIO controller to an empty folder on a development computer. The collection of files and folder copied from the controller is the image which will be deployed to other embedded controllers. This image must be copied to a USB memory device for deployment.

[+] Enlarge Image

Figure 5: FTP client view of a CompactRIO system with a deployed startup application

For deployment from the USB memory device the Deploy Image VI will look for the image in a specific folder on the USB memory device. In the example provided with the tutorial this folder is called \appimage, so the image should be copied to this folder on the USB memory.

Another option to retrieve the application image from the master CompactRIO controller is to use Retrieve Image.vi provided with the examples. This VI is intended to run directly on the CompactRIO controller containing the master application image and will copy the image to a USB memory device connected to the master CompactRIO controller. IT will copy the contents of the controller hard drive to the \appimage folder on the USB memory device

Figure 6: Example using the Retrieve Image VI to copy an application image from the CompactRIO master

After placing the application image on the USB memory device in the appropriate folder you can deploy it to embedded controllers that contain the original application. 

To update the image on an embedded controller place the USB memory device in the USB slot on the controller and reboot the controller. During the application startup process the Deploy Image VI will detect the USB memory device, will compare the image on the USB device to the image on the controller, and if necessary will copy the application image from the USB memory device to the controller. It will copy the image if an INI file containing a unique ID (GUID) does not match between the USB device and the controller. After placing the new image on the controller it will update the GUID INI file on the controller. 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 USB memory used, this process can take several minutes to complete.

Implementation

This section will describe in more detail the operation of the Retrieve Image and Deploy Image VIs.

Retrieve Image VI

The Retrieve Image VI is used to copy the contents of a CompactRIO controller hard drive ("application image") to a USB memory device connected to the controller. 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. Delete previous image
3. Copy files
4. Remove GUID
5. 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 the 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. Using the Get Volume Info function the VI checks for the presence of a drive at U:.

In this step the log file is created or opened and an initial entry is made.

Delete previous image

If specified by the calling VI, any current application image contained on the USB memory device is deleted in the second step.

Copy files

This step copies all of the files and folders from the CompactRIO controller to the specified folder (\appimage) on the USB memory device. The Recursive File List VI is used to retrieve a list of files on the hard drive which are copied inside of the For loop to the USB memory. During the copy process the user LED on the controller blinks continuously.

If a previous image stored on the USB drive was not deleted, then the new image will be copied on top of the existing image. Any files with the same name will be copied over the existing file.

Remove GUID

After the copy process is completed, any INI GUID files are deleted on the USB memory device. These files are used during the deployment process to synchronize the version of the image on the USB memory device and target controller. This file must be deleted when a new application image is created so that the new image will be copied over any previous application image. The INI file will be created with a new GUID on the USB memory device after the first deployment process.

Exit

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

The Retrieval Status indicator returns the result of the retrieval process.

Deploy Image VI

The Deploy Image VI performs the opposite operation to the Retrieve Image VI, copying the contents of the application image from the USB memory device to a CompactRIO controller. It is organized in a very similar fashion as a simple state machine in a Case structure. The VI performs the following steps:

1. Check for USB memory
2. Compare GUIDs
3. Copy files
4. Update GUIDs
5. Reboot Controller
6. 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 Retrieve 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 the 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. Using the Get Volume Info function the VI checks for the presence of a drive at U:.

In this step the log file is created or opened and an initial entry is made.

Compare GUIDs

The second step reads the INI file containing the unique ID (GUID) on the controller and on the USB memory device. If the two GUIDs are identical then the current image on the USB memory has already been placed on the controller and does not need to be copied again. If the GUIDs are different or if the file is missing on either the controller or USB memory device, then the new image will be copied to the controller.

The default name for the INI GUID file is replicationguid.txt. These files should normally not be edited manually or deleted from the controller or USB memory device. Deleting this file will force the deployment process to occur on the next attempt.

Copy files

This step copies all of the files and folders from the application image on the USB memory device to the CompactRIO controller. The Recursive File List VI is used to retrieve a list of files on the hard drive which are copied inside of the For loop to the controller hard drive. During the copy process the user LED on the controller blinks continuously.

Update GUIDs

After the application image has been copied to the CompactRIO controller the INI GUID files need to be synchronized. If the USB memory does not contain the file, a new file with a new GUID will be created and also copied to the controller. If the USB memory already contains this file, it will be copied to the controller. This process associates one GUID with the application image stored on the USB memory device and the same GUID will be copied to every controller with the same application image.

Reboot Controller

After the image has been updated and the GUID files synchronized, the controller is normally rebooted to load and run the new application on the controller. This step also places a final comment in the log file and closes it before rebooting.

When the controller is rebooted the Deploy Image VI will run again and repeat the process. At this point the two GUID files should be identical in which case the application image will not be copied and the VI will jump to the Exit step.

Exit

This step is only called if the application image was not copied to the controller or if the controller was not rebooted after the copy process. It places a final comment in the log file and closes it.

The Retrieval Status indicator returns the result of the deployment process.

Customizing the Deployment Process

This example and tutorial present a basic implementation for deploying a static application image from a USB 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 customize or edit individual files of the application image during the deployment process. This could be the IP address of the CompactRIO controller which needs to be copied from the current NI-RT.INI file to the same file in the new application image. Without any changes this example will copy all of the files from the application image on the USB memory device straight to the controller hard drive replacing any existing files with the same name. 

If the configuration for different embedded controllers which will be updated with an application image are not identical, it will be necessary to make some modifications to the deployed files. In the case of the IP address stored in the NI-RT.INI file, you may want to read these values before the deployment process and store them in a temporary location/file. After the deployment of the static image is complete, you can retrieve the stored values and update the new image files with the previous values. These changes would be implemented in additional steps in the Deploy Image VI.

Another customization of the example could add data and/or version information to the INI file currently used to store the GUID. With the current implementation we can detect differences between the application image on the USB memory and the controller, but we can not identify which of these is the newer version and which is older. We assume we always want to copy the image from the USB device to the controller if the two are not identical. By adding date or version information to the INI file we could add additional algorithms that would only allow a newer application to be copied over and older image. This change would be added to the Compare GUIDs step in the Deploy Image VI. It would also require the INI file to be created and filled with the correct information when the application image is created. Currently the INI file is created during the first deployment process. 

Limitations

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 USB memory device and copy the new application image to the controller hard drive. If for any reason the controller is in a state where this VI can not 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.

In the example the Deploy Image VI is run during the application startup process before the main application VI is started. To update the application image on the controller the USB device is plugged into the controller and the controller is reset using the manual reset button. During the following startup sequence the USB 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 USB 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.

Requirements

Filename: usb_deployment_103_install.zip

Software Requirements

Application Software: LabVIEW Full Development System 8.5.1
Toolkits and Add-Ons: LabVIEW Real-Time Module 8.5.1
Language(s): LabVIEW

Hardware Requirements

Hardware Group: CompactRIO
Hardware Model: cRIO-9012, cRIO-9014
Driver: NI-RIO 2.4

Filename: usb_deployment_103.zip

Software Requirements

Application Software: LabVIEW Full Development System 8.5.1
Toolkits and Add-Ons: LabVIEW Real-Time Module 8.5.1
Language(s): LabVIEW

Hardware Requirements

Hardware Group: CompactRIO
Hardware Model: cRIO-9012, cRIO-9014
Driver: NI-RIO 2.4

Reader Comments | Submit a comment »