The NI-XNET series of CAN, LIN, and FlexRay interfaces is a combination of accelerated CAN, LIN, and FlexRay interfaces and NI-XNET driver software. NI-XNET interfaces offer many performance, ease-of-use, and long-term support benefits over legacy NI-CAN products such as Series 2 PCI/PXI/PCMCIA interfaces.
To deliver next-generation performance and ease of use in NI-XNET CAN, LIN, and FlexRay interfaces, NI engineered a new API for NI-XNET products. NI recognizes the large install base of applications written in the older NI-CAN API and the need to maintain those applications over a long term.
To facilitate the transition of applications written for NI-CAN to NI-XNET and to help you benefit from the new features of NI-XNET interfaces, the NI-XNET driver includes an NI-CAN compatibility layer that emulates NI-CAN function calls at the driver level. Because this functionality is installed at the driver level, most applications written with NI-CAN require some minimal changes to work out of the box with NI-XNET. There are some notable differences between the two drivers that you should be aware of when you begin to work with NI-XNET interfaces.
This article explains how to use the NI-CAN compatibility library to implement NI-CAN applications with new NI-XNET hardware. It also examines potential compatibility issues and how to transition familiar NI-CAN concepts to the NI-XNET API.
To learn more about the basics of NI-CAN Channel APIs, read The NI-CAN Channel API.
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.
|NI-CAN Term||NI-XNET Term||Comment|
|CANdb File||Database||NI-XNET supports more database file formats than the NI-CAN Channel API, FIBEX, .DBC, and .NCD.|
|Message||Frame||"Frame" is the industry term for the bits that transfer on the bus. This term is used in standards such as CAN and FlexRay.|
|Channel||Signal||"Signal" is the industry term used in standards such as FIBEX.|
|Channel API Task||Session (Signal I/O)||Unlike NI-CAN, NI-XNET supports simultaneous use of channel (signal) I/O and frame I/O.|
|Frame API CAN|
|Session (Frame I/O Single-Point)||The NI-CAN CAN Object provided both input (read) and output (write) in one object. For better control, NI-XNET offers a different object for each direction. If the NI-CAN queue length for a direction is zero, that is analogous to NI-XNET Frame I/O Single-Point.|
|Frame API CAN|
|Session (Frame I/O Queued)||If the NI-CAN queue length for a direction is nonzero, that is analogous to NI-XNET Frame I/O Queued.|
|Session (Frame I/O Stream)||The NI-CAN Network Interface Object provided both input (read) and output (write) in one object. For better control, NI-XNET provides a different object for each direction.|
|Interface*||Interface||NI-CAN started interface names at CAN0, but NI-XNET starts at CAN1 (or FlexRay1).|
|Periodic||Cyclic||NI-CAN uses the term "periodic," but the NI-XNET Database Editor and NI-XNET property nodes use the term "cyclic."|
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.
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.
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.
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.
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.
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.
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.
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.
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 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.
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.
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.
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).
Many of the NI-CAN Frame API examples have similar NI-XNET examples.
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).
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.
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.
|NI-CAN SampleRate||NI-XNET Mode||Notes|
|Input||0||Signal Input, Single Point||N/A (no additional properties)|
|Input||>0||Signal Input, Waveform||Use NI-CAN SampleRate to set Session > Resample Rate property.|
|Output||0||Signal Output, XY||For each frame, use NI-XNET Database API to set CAN > Timing Type to Event Data and CAN > Transmit Time to zero (no debounce).|
|Output||>0||Signal Output, Waveform||For each frame, use NI-XNET Database API to set CAN > Timing Type to Cyclic Data, and set CAN > Transmit Time to the NI-CAN 1/SampleRate|
|Output/Recent||>0||Signal Output, Single Point||For each frame, use NI-XNET Database API to set CAN > Timing Type to Cyclic Data, and set CAN > Transmit Time to the NI-CAN 1/Sample Rate.|
|Timestampedinput||N/A||Signal Input, XY||N/A (no additional properties)|
Table 2. This table shows the fundamental differences between NI-CAN and NI-XNET sample rates for CAN communication.
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.