To deliver next-generation performance and ease of use in NI-XNET CAN, LIN, and FlexRay interfaces, National Instruments 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 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. However, 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 about which NI-CAN APIs work with which NI CAN interfaces, read the NI Embedded Networks Products Overview.
1. Installing Support for the Compatibility Library
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 851x CAN devices. Follow this decision matrix to make sure you are installing the proper software for your application.
Figure 1. Understanding when to use NI-XNET and the Compatibility Layer can help with future applications.
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. During installation, you are presented with an option to install the NI-CAN compatibility layer, which installs the latest version of NI-CAN and the library functions. Note that this option is not enabled by default.
Figure 2. You must manually select the NI-XNET Compatibility Layer to be installed.
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, National Instruments provides a compatibility library to help you reuse that code with new C Series, PCI, and PXI NI-XNET CAN products. Because the features of the compatibility library apply to the NI-CAN API and not NI-XNET, these features are described in NI-CAN documentation. For more information, refer to the NI-CAN Hardware and Software Manual.
If your existing application uses NI-CAN and you intend to use only new PCI and PXI NI-XNET 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. Table 1 lists NI-CAN terms and analogous NI-XNET terms.
|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 Figure 1 screenshot shows 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 NI 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 3. Numbering Difference Between NI-XNET and NI-CAN
Note that for an NI-XNET interface that has the NI-CAN compatibility layer installed, the board 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 image below shows a similar situation except it uses a real-time (RT) target. The NI-XNET devices show up under the RT target in MAX, but the NI-XNET devices used by NI-CAN 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 4. Viewing CAN interfaces for use with NI-XNET and the Compatibility Layer has a different view.
To get to the screen in this picture, go in MAX to Tools » NI-CAN » RT Hardware Configuration. Then type in the IP address for the RT target.
5. Incompatible Code
While the NI-XNET compatibility library for NI-CAN (NI-XCL) strives to ensure basic functionality, you cannot always completely map the library from NI-CAN to NI-XNET because of either hardware-specific features or core differences in the NI-XNET platform.
Here are some of the main incompatible functions along with workarounds. For a complete table, see the NI-CAN Hardware and Software Manual for Version 2.7 or later.
1. Hardware Filters
Transceiver filters were traditionally indicated for applications where only a few CAN IDs were being considered on a high bus load. In some cases, NI-CAN devices sustain full bus bandwidth, which leads to buffer overflows. The NI-XNET hardware architecture uses the NI-XNET device-driven DMA engine to eliminate the occurrence of buffer overflows. NI-XNET CAN interfaces are able to process high bus loads and transmit at maximum rates without overrunning buffers. If your applications extensively use hardware filters, NI recommends setting up CAN Objects, or reading the entire bus using the Network Interface Objects. The best option for these applications is to modify your code to use the native NI-XNET API.
2. 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.
3. External Transceivers
This feature is available on some of our NI-XNET hardware. The PCI-8513 and the PXI-8513 are examples of hardware that can optionally use external transceivers.
4. 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, 10, and 20 MHz) without explicitly changing the master timebase. The 1 and 10 MHz rates are also available for export.
5. 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 5. Bus errors can now be viewed by observing the bus state.
However, because this uses the native XNET API, compatibility with NI-CAN is not possible.
6. 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 6. 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.
7. 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 7. Configuring a CAN Replay can be done with a frame output stream.
8. 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.
6. Changing NI-CAN to NI-XNET
You may need to modify your application to use the NI-XNET API for a variety of reasons. The next section explains how to change your NI-CAN code to use the NI-XNET API.
This paper is meant 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 National Instruments.
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 8. Configuring bus properties is done differently in NI-XNET than in NI-CAN.
Reading frames is similar in NI-CAN and NI-XNET:
Figure 9. 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 10. 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 10. 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 11. 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 12. 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 13. 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 14. 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 15. 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»Example Finder in Hardware Input and Output»CAN»NI-XNET Advanced.
Other Frame API Functions
Many of the NI-CAN Frame API examples have similar NI-XNET examples.
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 16. The NI-XNET Database Editor is a stand-alone, intuitive 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»Advanced.
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 Single Point Input.vi located at Hardware Input and Output»CAN»NI-XNET»Basic. Right-click on the signal list and go to Browse for Database File and 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 17. 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 18. The control automatically updates with available signals in the database.
The below 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 19. 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 20. 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 21. The resample rate of a waveform can be configured with a property.
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»Advanced.
7. NI-XNET Compatibility Layer Simplifies the Transition
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.