Migrating NI-CAN Applications to NI-XNET

If you are starting to write a new application using NI-XNET, you do not need the compatibility layer. You need it only if you want to use existing NI-CAN applications with NI-XNET devices.

The compatibility library supports CAN and LIN interface devices and modules. It does not support vehicle multiprotocol interface devices and modules, such as the PCIe-8510, PXIe-8510, and NI 9860, which require a transceiver cable. Nor does it support C-Series LIN modules since there is no NI-CAN based equivalent.

For existing applications to work, both NI-XNET and NI-CAN drivers must be installed. The NI-XNET installation package contains all of the necessary components for the compatibility library to function. Refer to Installing the NI-XNET Compatibility Library for NI-CAN for detailed instructions.

Generally speaking, the NI-CAN API is associated with legacy CAN hardware including Series 2 CAN interfaces. NI-XNET is the primary driver for the next-generation NI-XNET CAN, LIN, and FlexRay interfaces. New applications for NI-XNET interfaces use the NI-XNET driver and API. 

If you have an existing application that uses NI-CAN, NI provides a compatibility library to help you reuse that code with newer NI-XNET CAN C Series, PCI, and PXI interfaces. Features of the compatibility library apply to the NI-CAN API, not to NI-XNET. Refer to the NI-CAN Hardware and Software Manual for more information about compatibility library features.

If your existing application uses NI-CAN and you intend to use only NI-XNET CAN C Series, PCI, and PXI hardware from now on, you may want to transition your code to NI-XNET. NI-XNET unifies many concepts of the earlier NI-CAN API, but the key features are similar. The following table cross references NI-CAN terms and analogous NI-XNET terms.

Note: See Migration Options for USB-8472/73/76 CAN Interface for more information.

Table 1. NI-CAN Terms and Analogous NI-XNET Terms

The following figure highlights the numbering difference between NI-XNET and NI-CAN. The top "CAN0" corresponds to the NI-CAN port name to use the first port of the PCI-8513 board. You can use this same port with the NI-XNET API using CAN1. You can rename the NI-CAN ports to be the same as the NI-XNET ports – this does not cause any problems.

Figure 1. Numbering Difference Between NI-XNET and NI-CAN

Note: If the NI-CAN compatibility layer is installed, an NI-XNET interface shows up twice in NI Measurement & Automation Explorer (MAX). This is normal because both drivers report the presence of the board to MAX – one entry is for the NI-CAN drive, and the other for NI-XNET.

The following figure shows a similar situation, except it uses a real-time (RT) target. NI-XNET devices are displayed under the RT target in MAX, but the NI-XNET devices that NI-CAN uses through the compatibility layer show up only under the NI-CAN RT Hardware Configuration tool. You can see that CAN1 in NI-XNET is the same port as CAN0 under NI-CAN.

Figure 2.  Viewing CAN interfaces for use with NI-XNET and the Compatibility Layer has a different view.

To open the NI-CAN RT Hardware Configuration window, launch MAX and select Tools » NI-CAN » RT Hardware Configuration, and then provide the IP address for the RT target.

While the NI-XNET compatibility library for NI-CAN strives to ensure basic functionality, you cannot always completely map the library from NI-CAN to NI-XNET due to hardware-specific features or core differences in the NI-XNET platform.

Below are some of the main incompatible functions along with workarounds. For a more complete list, see the NI-CAN Hardware and Software Manual for Version 2.7 or later. 

1.  Automatic Response to Remote Frames

This feature is available on NI-XNET hardware; however, the new architecture does not provide a way to maintain compatibility. If your application requires this feature, you need to upgrade your code to use the NI-XNET API. For more information on how to handle remote frames with the NI-XNET API, see the NI-XNET Hardware and Software Manual. 

2.  External Transceivers

This feature is available on some of our NI-XNET hardware. The PCI-8513 and PXI-8513 models are examples of XNET hardware that can optionally use external transceivers.

3. Master Timebase Rate

NI-XNET interfaces automatically detect clock input frequency and synchronize without any parameters from the user. Because this process is automatic, you no longer have the option to change the master timebase rate. NI-XNET interfaces support different clock rates for synchronization (1 MHz, 10 MHz, and 20 MHz) without explicitly changing the master timebase. The 1 MHz and 10 MHz rates are also available for export.  

 4.  Logging Communication Errors and Warnings

NI-XNET offers a new way to log bus errors. Instead of logging CAN frames with the bus state encode, you can now simply read the bus state:

Figure 3.  Bus errors can now be viewed by observing the bus state.

This feature is native to the NI-XNET API; compatibility with NI-CAN is not possible.

5.  Timestamp Format

NI-XNET now uses only the absolute timestamp format. However, functions are available to obtain a timestamp of specific events. With these timestamps, you can calculate "relative" time from different references without having to recapture data in another format.

Figure 4.  NI-XNET uses the absolute timestamps, but there are still ways to get relative timestamps.

If you require this feature, you need to change your code to use the NI-XNET API.

6.  Timestamp Transmit and Timeline Recovery

This feature was not available in NI-XNET 1.0 but was introduced in NI-XNET 1.1. The feature is now called "CAN Replay."

Figure 5.  Configuring a CAN Replay can be done with a frame output stream.

7.  RTSI Events

NI-XNET has RTSI features for synchronizing a timebase and a start trigger. However, it is not possible to configure events (in other words, transmit a CAN frame) on a RTSI pulse. It is also not possible to configure RTSI events based on CAN events.

You may need to modify your application to use the NI-XNET API for a variety of reasons. The next section describes how to change your NI-CAN code to use the NI-XNET API.

The following information is intended to help you translate familiar concepts from NI-CAN to NI-XNET to assist in code transition. It does not cover every possible application. If you need help converting any part of your code, contact NI.

Frame API

Opening the Interface

NI-CAN interfaces require configuration before you can open them. In NI-XNET, you first create a session on the interface and then you can use property nodes to change any properties of the session. This is the same model used by many other NI APIs, including NI-DAQmx. 

Figure 6.  Configuring bus properties is done differently in NI-XNET than in NI-CAN.

Reading Frames

Reading frames is similar in NI-CAN and NI-XNET:

Figure 7.  The code needed to read frames in both APIs is very similar.

With the increase in performance and the new NI device-driven DMA engine architecture, you do not need to query the NI-XNET device to see how many frames are available. This was required in NI-CAN for performance reasons. The functionality is still available in NI-XNET but is no longer required for reading all available frames. (-1 input in the nxRead function returns all available frames.)

Figure 8.  Querying to see how many frames are available is easier with NI-XNET.

The frame format features similar information in NI-CAN and NI-XNET but is presented in a slightly different way:

Figure 9.  Similar frame data is contained in each cluster for NI-CAN and NI-XNET.

Writing a Single Frame

The nxWrite (Frame CAN).vi in NI-XNET uses an array of frames as input. Therefore, if you want to send a single frame, you must create an array of one frame.

Figure 10.  Sending frame data in NI-XNET requires an array of data to be an input.

Writing Multiple Frames

NI-XNET uses the array length to know how many frames to write.

Figure 11.  Similar function calls are available in NI-CAN and NI-XNET for sending frames.

Writing Periodic Frames

In NI-CAN, writing periodic frames with the Frame API requires configuring an object for each frame to send or receive. NI Series 2 CAN interfaces have a 49-object limit. 

Figure 12.  Sending a period frame in NI-CAN requires configuring objects with separate function calls.

Configuring individual periodic frames in NI-XNET is slightly different. With tight NI-XNET integration with signal and frame databases, the easiest way to take advantage of periodic frames in NI-XNET is to use a FIBEX database file to describe the frames the network uses. When you use the FIBEX database, the NI-XNET driver automatically configures and handles the periodic frames with no extra interaction from the application. 

For example, consider configuring a periodic (known as "cyclic" in NI-XNET) frame in the database with the arbitration ID, payload length, and period. Once configured and saved, the application can use a single point session to transmit or receive this frame. The I/O control dynamically loads all frames from a database, which makes it easy to select the frames in the application. You must configure an alias telling NI-XNET which database to use for this functionality to work, which is discussed in the next section. 

Figure 13.  Sending periodic frames in NI-XNET can be significantly simplified.

When opening a session, the NI-XNET driver reads all of the settings from the database. It then configures a cyclic transmission and/or reception in the driver and NI-XNET firmware. From the application, you simply update the value, and NI-XNET automatically transmits the newest value during the next cycle. NI-XNET also features Queued sessions, which you can use to queue up many values.

The key advantage of using signal databases is code maintainability. Updating the database automatically updates the code, requiring no code changes to track changes in the arbitration ID, transmission rates, bit definitions, and so on. If you want to change a parameter, you can just change the database file. No changes are needed in the code.

NI-XNET provides functions to change the values loaded from the database file programmatically. This does not change the actual values written in your database file – only the values loaded by the NI-XNET driver at run time.

Figure 14.  Low-level functions can be used to configure the sending of periodic frames in NI-XNET.

If you do not want to have a database file and you want to set everything at run time, you can also create an "in memory" database. This way, you can develop an entire network configuration programmatically and use it in your application. You can look at the CAN Dynamic Database Creation.vi example located at Help»Find Examples under Hardware Input and Output»CAN»NI-XNET»Databases (Editing and Managing).

Other Frame API Functions

Many of the NI-CAN Frame API examples have similar NI-XNET examples.  

Channel API 

Editing a Database File

You can choose from two primary techniques to edit a database file: before or during run time. To edit a database file before execution in NI-CAN, the database editor in MAX is required. NI-XNET moves all database editing in a stand-alone database editor. You can launch the database editor from Start»All Programs»National Instruments»NI-XNET Database Editor.

Figure 15.  The NI-XNET Database Editor is a stand-alone tool for editing CAN databases.

Read more about the NI-XNET Database Editor in the Introduction to FIBEX and the NI-XNET Database Editor white paper. 

NI-XNET features functions to edit a FIBEX database file programmatically. You can use these functions to build custom database manipulation tools into your application. View the NI LabVIEW software shipping examples by going to Help»Find Examples and browsing to Hardware Input and Output»CAN»NI-XNET»Databases (Editing and Managing). 

Single Point Input and Output

In NI-CAN, you must point your application to the .DBC or .NCL file on your hard drive. In NI-XNET, you must first add an alias to the database file (.DBC, .NCL, or FIBEX .xml) before running the application. You can achieve this in several different ways. You can open the example named CAN Signal Input Single Point.vi located at Hardware Input and Output»CAN»NI-XNET»Intro to Sessions»Signal Sessions. Right-click on the signal list and go to Browse for Database File to select your database file on the disk. The NI-XNET driver automatically creates an alias for this database so you can easily select it again.

Figure 16.  Selecting a database in NI-XNET allows for referencing it in an application.

The NI-XNET I/O Control then automatically reads your database file and populates all the signal names. This makes it very easy to choose which signal to use in your application.

Figure 17.  The control automatically updates with available signals in the database.

The following image compares the block diagrams for NI-CAN and NI-XNET single point channel/signal write. The read is similar and both drivers' feature examples. 

Figure 18.  Sending single point data is similar in NI-CAN and NI-XNET.

Waveform Input and Output

Reading and writing waveform data is also similar in NI-CAN and NI-XNET, and each driver features examples for comparison.

Figure 19.  Waveform reading and writing is similar in both APIs.

One difference is that NI-XNET uses a default sample rate of 1000. You can easily change the sample rate using a property node.

Figure 20.  The resample rate of a waveform can be configured with a property.

Summary

Table 2.  This table shows the fundamental differences between NI-CAN and NI-XNET sample rates for CAN communication.

Reading the Database Off the Disk

In NI-CAN, you can use a database directly on the disk. In NI-XNET, you usually manually create an alias to that file so you can use the NI-XNET I/O Control in your application. However, if you are distributing your application or you want to emulate NI-CAN behavior, you can programmatically create a database alias for a file on the disk. To do so, view the Managing Local Databases.vi example located at Hardware Input and Output»CAN»NI-XNET»Databases (Editing and Managing).

The NI-XNET compatibility layer for NI-CAN greatly simplifies the transition of NI-CAN code to take advantage of next-generation NI-XNET CAN and FlexRay interfaces. Despite minor differences, most NI-CAN applications function with little to no modification on NI-XNET hardware when used with the compatibility layer. 

• Migration Options for USB-8472/73/76 CAN Interface
• NI-XNET CAN, LIN, and FlexRay Platform Overview
• NI-CAN Hardware and Software Manual
• Explore replacement options for NI-CAN supported hardware from NI