Archived: LabVIEW Communications 2.0 to 2.1 and 3.0 Migration Guide

LabVIEW Communications 2.1 and 3.0 automatically convert your LabVIEW Communications 2.0 projects to equivalent versions in LabVIEW Communications 2.1 and 3.0. Due to inherent differences between LabVIEW Communications 2.0 and LabVIEW Communications 2.1, however, the organization and structure of your projects will be different following the conversion process. Additionally, some manual reconfiguration might be required depending on the application. The purpose of this guide is to highlight the major differences in project structure and organization after the conversion process.

It is not possible to open projects created with LabVIEW Communications 1.0 or 1.1 in LabVIEW Communications 2.1 (or later). Older projects should first be migrated to LabVIEW Communications 2.0 using the LabVIEW Communications 1.1 to 2.0 Migration Guide or rewritten entirely in LabVIEW Communications 2.1 (or later). 

1. To start the conversion process, open a LabVIEW Communications 2.0 project in LabVIEW Communications 2.1 or 3.0.

 When opening a LabVIEW Communications 2.0 project in LabVIEW Communications 2.1 or 3.0 the following dialog box will display:

2. Select Convert and Load to proceed.

 A progress dialog box displays the current state of the conversion process:

3. When the conversion completes, review the report and then select Close on the dialog box. The following table lists common errors that can occur during conversion:
   

Use the following conversion behavior explanations to better understand the new format of your host applications and libraries in LabVIEW Communications 2.1 and 3.0 and make any necessary changes to your converted projects to restore their original functionality.

• The conversion process moves top-level VIs, type definitions (now G Types), and subVIs into Library documents.
  
  1. The names of the libraries are Library.gcomp or Library_X.gcomp where X is a unique number identifying the library.
  2. The conversion process creates namespaces in these libraries that correspond to the original on-disk folders containing the various project documents.
• FPGA Host Interface nodes have broken references after conversion. To resolve the issue, update each affected FPGA Host Interface node to point to the correct resource in the existing bitfile. For example, to update the Read DMA FIFO node, select the node on the diagram, select the Item tab, and in the General section select the FIFO drop-down to select the correct FIFO name:

• The MathScript Node is not supported in LabVIEW Communications 2.1 (or later). Use an Interface for MATLAB® to call MATLAB functions or scripts. Refer to the Migrating from MathScript Node to Interface for MATLAB®  help topic for more information.
  
  Note: There is a known issue tracked by Bug ID 707042 that any project containing a MathScript Node that had the Show Label checkbox selected will fail to migrate properly. The failure will occur even if the Show Label checkbox was later deselected. The Conversion dialog may report Converting source files to components failed with unknown error and when you attempt to open the VI that contained the MathScript Node an error is thrown stating that The source file format is invalid. The issue is captured on the LabVIEW Communications System Design Suite 2.1 Known Issues List and the issue is fixed in LabVIEW Communications 3.0. To workaround the issue in LabVIEW Communications 2.1:
  
  
  1. Open a backup copy of the project in LabVIEW Communications 2.0.
  2. Open the VI containing the MathScript Node.
  3. Drop a new MathScript Node onto the diagram.
  4. Copy the text from the old node into the new node.
  5. Delete the old node from the diagram.
  6. Rewire as necessary.
  7. Save the VI and attempt the conversion process again.
     
• Shared Library Interface documents that use Type Definitions as the Type for function parameters will be broken following conversion. This is a known issue tracked by Bug ID 706310 and is captured on the LabVIEW Communications System Design Suite 2.1 Known Issues List and LabVIEW Communications System Design Suite 3.0 Known Issues List. To resolve the issue:
  
  1. Open each affected SLI document

  2. Review the Errors and Warnings tab for the SLI document and note the missing GType names:
     
     

     

     
     

  3. Locate the function parameter(s) associated with each affected GType:
     
     

     

     
     

  4. Click on each affected function parameter and on the Item tab click the GType dropdown and select the correctGType from the list:
     
     

     

     
     
  5. Repeat the process until there are no more errors on the Errors and Warnings tab of the SLI document

Use the following conversion behavior explanations to better understand the new format of your FPGA applications and libraries in LabVIEW Communications 2.1 and 3.0 and make any necessary changes to your converted projects to restore their original functionality.

• The conversion process places any FPGA VI with a Build Output set to Bitfile in its own Application document, inheriting the Build Name from the original VI’s Build Options. The root namespace in the Application document is also the Build Name.
  
• If a single VI was targeted to multiple FPGA targets (and each had the Build Output set to Bitfile), the conversion process creates a single Application document, but you can select from multiple FPGA targets when viewing the Application document contents.

• The conversion process moves any FPGA VI with a Build Output set to None into a Library document. To compile a top-level FPGA VI after conversion you must move it into an Application document.
  
• The conversion process generally groups other documents (.gcdl, .gmrd, .gvi, .eip, etc.) used in a single Bitfile Application into a single Library document.
  • The names of the libraries are Library.gcomp or Library_X.gcomp where is X is a unique number identifying the library. The root namespace will match the library document name.
  • The conversion process creates namespaces in these libraries that correspond to the original on-disk folders containing the various project documents.
• The conversion process moves FPGA VIs with a Build Output Setting of Optimized FPGA VI into Library documents, but note that the Optimized FPGA Library checkbox is not selected. Manually select this checkbox from the Item tab of the SystemDesigner view of the Library to treat those VIs as Optimized FPGA VIs after the conversion process. In some cases an Optimized FPGA VI can be moved into a Library containing other document types during conversion. In order to treat it as an Optimized FPGA VI, you must move it into a library separate from the other document types.

• 
  
  

  • If an Optimized FPGA VI is not part of a Bitfile Application, the conversion process moves it into its own Library document. If the same Bitfile Application uses multiple Optimized FPGA VIs, the conversion process moves the Optimized FPGA VIs into the same Library document. If multiple Bitfile Applications use an Optimized FPGA VI, the conversion process moves the Optimized FPGA VI into its own Library document. You must replace call sites of the Optimized FPGA VIs within other documents by navigating to each Optimized FPGA VI from the Project Items palette category and adding them to the diagram.
    

  
  

  • The conversion process moves Resource Collections into Library documents, and the names of the resources contained in the .grsc documents change to include the namespace in the library.  As a result, the names of the resources in the project are different from the names of the resources in bitfiles compiled before the conversion.
    
  • Xilinx CORE Generator IP Nodes are broken after conversion.
    

  

  To resolve the issue:

  1. Select the Xilinx IP Node and click Configure Xilinx IP to open a dialog that automatically upgrades the IP.
     
     

     

     
     
     

     

     
     
  2. Confirm the correct configuration options in the Re-customize IP dialog and click OK. The Errors and Warnings pane displays an error message in the VI that contains the Xilinx COREGEN IP Node while the Xilinx tool processes the changes:

  
  

  • External IP (EIP) Documents and External IP Nodes are broken following conversion. The reason for this is that the conversion process moves EIP Documents into components, but it does not move the VHD source files they reference. Therefore, the VHD source files are in a different location than the EIP Document expects.

  Example error message in a VI containing an EIP Node:
  
  

  

  Example error message in an EIP Document:
  
  
  

  To resolve the issue point the EIP Document to the VHD source at the correct location and click Parse and Verify. Note that all Signal Configuration, Generic, and Clock settings in the EIP Document will revert to default values. If you were using non-default values, then you must manually set those values.

   

Use the following conversion behavior explanations to better understand the new format of your RT applications and libraries in LabVIEW Communications 2.1 and 3.0 and make any necessary changes to your converted projects to restore their original functionality.

• Generally, the same rules apply to RT target conversion as Host conversion.
• A real-time controller with the LabVIEW Communications 2.0 image is not compatible with LabVIEW Communications 2.1 or 3.0.
• Installing LabVIEW Communications 2.1 (or later) on a machine with an existing installation of LabVIEW Communications 2.0 prevents the older version of the software from communicating with real-time targets. This is a result of LabVIEW Communications 2.1 (and later) upgrading software components used for system discovery and communication, rendering these components incompatible with LabVIEW Communications 2.0.  This a known issue tracked by Bug ID  688821 and is captured on the LabVIEW Communications System Design Suite 2.1 Known Issues List.
• The vesion of the real-time image applied on the RT Controller must match the version of LabVIEW Communications used on the Windows Host PC. Therefore, the LabVIEW Communications 2.1 (or 3.0) real-time image must be applied to any RT controller being used with LabVIEW Communications 2.1 and 3.0. Refer to the Provisioning a Real-time Controller for LabVIEW Communications System Design Suite tutorial for instructions on applying the correct LabVIEW Communications Real-time image.

Use the following conversion behavior explanations to better understand the new format of your USRP streaming applications and libraries in LabVIEW Communications 2.1 and 3.0 and make any necessary changes to your converted projects to restore their original functionality.

Host

• The conversion process groups the top-level host VIs into a single Library document:

• When opened, the top-level Host VIs list errors in dependencies that are related to a mismatch between the resource names in the project and those configured on FPGA Host Interface Nodes:

• Due to the fact that the USRP Resources.grsc Resource Collection is now located in a Library document (see FPGA section below), the resource names in the project no longer match those compiled into the bitfile. To resolve the issue, update each affected FPGA Host Interface node to point to the correct resource name in the existing bitfile. For example, to update the Read DMA FIFO node, select the node on the diagram, select the Item tab, and in the General section, select the FIFO drop-down to select the correct FIFO name:

• Within the library that also contains the top-level Host VIs, the conversion process creates a namespace for the Host SubVIs folder that contains all .gvi documents.

• The conversion process moves existing type definitions from the Host SubVIs folder to a separate library that has a Host SubVIs namespace:

Note: Type definitions are referred to as G Types in LabVIEW Communications 2.1

FPGA

• If the build output of the top-level FPGA VI was set to None prior to conversion, the conversion process moves it into a Library document:

Note: In order to compile a bitfile using this top-level VI, you must move it into an Application document. This can be accomplished by dragging and dropping the top-level VI from the Library document into an Application document (see help) targeted to the USRP.

• If the build output of the top-level FPGA VI was set to Bitfile prior to conversion, the conversion process moves it into an Application document named Bitfile.gcomp.

Note: The Application documents inherit the Build Names that were set in the VI’s Build Options.

• The conversion process moves the USRP Resources.grsc Resource Collection into a Library document. Due to this change, when recompiling the bitfile, you need to update host-side VIs that reference the resources in this Resource Collection.
• The conversion process moves all documents from the FPGA SubVIs folder into FPGA SubVIs namespaces in Library documents.
• Any compiled bitfiles stored in the Builds folder still exist at the same location.
  
  

Special Considerations for the USRP-2974 Streaming Project

• The NI-USRP 18.3 driver is required to use the USRP-2974 in LabVIEW Communications 2.1. The driver can be updated using NI Package Manager. LabVIEW Communications 3.0 will automatically install a version of the USRP driver that supports the USRP-2974.
• The behavior described in the Host section above will apply to the VIs on the Real-time Controller. Additionally, it is necessary to provision the USRP-2974 with the correct LabVIEW Communications 2.1 (or later) image linked to from the Provisioning a Real-time Controller for LabVIEW Communications System Design Suite tutorial. The version of the image applied to the controller should match the version used on the Host PC.
• Due to a known issue the top-level FPGA VI will be broken with missing dependency errors following conversion:
  
  
  As a workaround it is recommended that a new USRP-2974 Streaming Project be opened  in LabVIEW Communications 2.1 or 3.0 and the changes to the FPGA VIs manually integrated into the new project. Alternatively, if the FPGA VI does not need to be recompiled in the new version then the migrated host VIs can be used with a bitfile compiled in LabVIEW Communications 2.0.

Use the following conversion behavior explanations to better understand the new format of your FlexRIO streaming applications and libraries in LabVIEW Communications 2.1 and 3.0 and make any necessary changes to your converted projects to restore their original functionality.

Host

• The conversion process moves all top-level host VIs into a single Library document:

• Due to a change in the data types used in the 579x API, you must modify the Register Bus terminal and Register Bus (out) terminals to match the new data types. Alternatively, replace the affected subVIs using the VIs attached to the this page. In order to manually make the changes:
  
  1. From the top-level VI open each broken subVI.
  2. Right-click the terminals that the broken wires are connected to and select Create control or Create indicator, as necessary.
  3. Connect the new terminals to the appropriate subVI terminals.
  4. Edit the subVI icon to include the new terminals.
  5. Delete Register Bus wires in the top-level VI and rewire as necessary.
     
• The top-level host VIs reveal errors in dependencies that are related to a mismatch between the resource names in the project and those configured on FPGA Host Interface Nodes:

Note: Due to the fact that the conversion process moved the 579x Resources.grsc Resource Collections into a Library document (see FPGA section below), the resource names in the project no longer match those compiled into the bitfile. To resolve the issue, update each affected Host Interface node to point to the correct resource name in the existing bitfile.

• The conversion process moves all subVIs into a Host SubVIs namespace in the same Library document as the top-level host VIs:

FPGA

• The conversion process moves the top-level FPGA VI for each PXIe-7975R target into a BitfileX.gcomp Application document, where X is a unique number identifying the build name from the original project.
• To recompile any of the bitfiles, click on the appropriate Application document and click the Build button.

Note: After pressing the build button, an error dialog may appear regarding a bitfile name conflict. To resolve this issue, open the affected Application document and select the Include target name or Include automatic numbering checkboxes.

• The conversion process moves all Resource Collections into a single Library document that is reused by each target:

• The conversion process moves all External IP and Clock-Driven Logic documents into a single Library document within an FPGA SubVIs namespace:

The recommended migration path for LabVIEW Communications Application Frameworks projects is to integrate custom IP into a new version of the relevant Application Framework in LabVIEW Communications 2.1.

An alternative migration path is to use the conversion utility to open an existing LabVIEW Communications 2.0 project in LabVIEW Communications 2.1 and then make the changes outlined below. After migrating an existing Application Framework project you will not be able to run the project in LabVIEW Communications 2.1 because it will be unlicensed. For more information on this limitation contact support at ni.com/support.

All Application Frameworks

• After conversion there will be errors in the top-level FPGA VI as well as the USRP Stream RX.gcdl and USRP Stream TX.gcdl documents. The Error message states:
  
  This control is bound to a property that does not accept a data item with this unbuffered type.
  
  To fix this issue select the indicator highlighted in the error message and replace it with Library_2:USRP RIO:FPGA SubVIs:Stream Control State.gtype
• After migrating an existing Application Framework project you will not be able to run the project in LabVIEW Communications 2.1 because it will be unlicensed. For more information on this limitation contact support at ni.com/support.

802.11 Application Framework

• There will be several error messages in VIs indicating that …not accessible because it belongs to another library and is not exported. To fix the issue open Library_3.gcomp:Common:Host and exclude everything in the LabVIEW namespace.
• When the above change is made there will be an error regarding a missing dependency for Common:Host:LabVIEW:Read Description NonRecursive.gvi. To fix the issue open Library_3.gcomp:802_11 v2_2:Host:MAC High Abstraction: 802.11 Clear and Log MAC Middle SAP errors.gvi, select Read Description NonRecursive.gvi and replace it with Data Types:Errors:Read Description from the palette.
• There will be several error messages that FIFOs are not found throughout the project. To resolve the issue open 802.11 FPGA Reference.gtype, click configure and either point to the bitfile recompiled (after conversion) in LabVIEW Communications 2.1 or point to the bitfile application in the project.

LTE Application Framework

• The LTE Application Framework v2.2 did not use typedefs for the FPGA reference and although the DMA FIFO calls are migrated correctly, the FPGA reference type cast needs to be updated in all VIs using DMA FIFO calls. The references can be updated by applying the following rules:
  • For DL related FIFOs use the DL FPGA bitfile
  • For UL RX related FIFOs use the eNodeB FPGA bitfile
  • For UL TX related FIFOs use the UE FPGA bitfile
• The enum in the LTE Read Constellation Data.gvi must be updated because the Constellation Select enum does not match the expected FPGA implementation. To fix the issue:

  1. Update the FPGA reference for the type cast from the DL FPGA bitfile:

     

  2. Select the enum constant PDSCH Dec Input and delete UL EQ Output and PUSCH Dec input items.

     
     
     

  3. Repeat step B in case 1 of the case structure and confirm the wire is no longer broken:
     

     

The LabVIEW Communications product documentation provides detailed information in addition to the tasks discussed in this guide. Hardware manuals also contain valuable information about the features and performance characteristics of NI RIO devices.

The main NI support page, ni.com/support, provides quick access to manuals, KnowledgeBase documents, tutorials, example code, community forums, technical support, and customer service.

• What Is the LabVIEW Communications System Design Suite?
• LabVIEW Communications System Design Suite 2.1 Manual
• LabVIEW Communications System Design Suite 3.0 Manual