NI-CAN Logfile Specification

Overview

This NI-CAN logfile specification defines a simple, open, binary file format for storage of CAN data. The primary purpose of the logfile is usage within NI-CAN and CompactRIO examples for logging, replay, and display of CAN data. The NI-CAN logfile is also used within National Instruments CAN tools, such as the Bus Monitor.

Contents

NOTE!

Although the NCL logfile format is supported for compatibility, the TDMS logfile format is recommended for new applications. For more information, refer to Embedded Network Data in TDMS.

Logfile created with the NI-XNET Logfile Specification cannot be used with application designed for the NI-CAN Logfile Specification.

NI-CAN Logfiles can be used with applications designed for with the NI-XNET logfile specification.

NI-CAN Logfile Characteristics

The NI-CAN Logfile Specification was designed to meet the following characteristics:

  • Simple: The format of each event (frame) in the logfile is analogous to the frame format used by NI-CAN, and also the LabVIEW FPGA I/O interface for CAN (CompactRIO CAN module). This makes application development easier and more efficient.
  • Open: The encoding of the NI-CAN logfile is fully specified in this document, and source code is provided in examples. You can incorporate the example code into your application unchanged, which will ensure that your application operates properly with NI tools. Alternately, you can enhance the example code to create your own logfile format (with your own file extension).
  •   Binary: In order to support efficient logging of full bus loads, the format is binary rather than human-readable text.
  • Extensible: Each NI-CAN logfile begins with a header that includes version information. Subsequent versions of this specification will result in files with updated versions. Although your applications can focus on support of a single version, future NI-CAN tools will interpret all versions.
  • Frames (not waveforms): Since CAN frames occur on the network in an event-driven manner (not cyclically scheduled), CAN frames provide the most efficient means of file storage. NI-CAN also supports CAN waveforms with each channel (signal) obtained from a specific CAN message identifier. Although storage of CAN data as waveforms is less efficient, you can use binary formats such as the NI Test Data Exchange format (.tdm) for this purpose (refer to LabVIEW or DIAdem help for more information). Alternately, you can use the NI-CAN logfile for CAN data, then use NI-CAN’s frame-to-channel conversion feature to convert the CAN frames into waveforms for display.
  • Big-endian: The ordering for multi-byte integers is big-endian (most-significant byte first).

File Extension

The   file extension used by all NI-CAN logfiles is:

    .ncl

All NI-CAN products assume that any file with this extension is fully complaint to this specification.

NI provides source code for access to NI-CAN logfiles. If you incorporate the source code into your application without change, you can continue to use the .ncl extension for files used by that application.

If you change the code for NI-CAN logfiles, even in a seemingly compatible way, you must change the file extension from .ncl to some other extension. This new file extension identifies your files as complaint to your own specification, and therefore ensures that the file will not be misinterpreted by NI software products for CAN.

Conventions

The specification uses the following types for each field:

            U8                   8 bit unsigned integer

            U16                 16 bit unsigned integer, big-endian, aligned at 16-bit offset in file

            U32                 32 bit unsigned integer, big-endian, aligned at 32-bit offset in file

            U64                 64 bit unsigned integer, big-endian, aligned at 64-bit offset in file

Header Information

The header is the first sequence of fields in the logfile. Only one header exists per logfile.

 

 Field

Type 

 Description

 Signature

 U16

A fixed value for all NI-CAN logfiles, used to validate that the file’s binary encoding complies with this specification. The value is hexadecimal 4E49 (“NI” in ASCII).

 HeaderSize

 U16

Size of the header in multiples of u32 (4 byte increments), including the Signature and HeaderSize. The NI-CAN logfile is designed to support parsing with arrays of u32.

 HeaderMajorVersion

 U8

Major version for the header (i.e. 1 in 1.5). This indicates a change that breaks compatibility with the previous version.

HeaderUpgradeVersion 

 U8

Upgrade version for the header (i.e. 5 in 1.5). This indicates a change that retains compatibility with upgrade version 0.

 EventMajorVersion

 U8

Major version for all events in the file.  This indicates a change that breaks compatibility with the previous version.

 EventUpgradeVersion

 U8

Upgrade version for all events in the file.  This indicates a change that retains compatibility with upgrade version 0.

Table 1:  NI-CAN Logfile Header Information

For this specification, the header must always consist of the following byte sequence in hexadecimal:

     4E   49   00   02   01   00   01   00

Event Information

After the header, the NI-CAN logfile will contain zero or more events. Each event typically represents a single CAN frame, but it can also encode other information such as errors or triggers.

For this version of the specification, the size of each event in the logfile is the same. This fixed size is 24 bytes (as shown in the subsequent table). Given that the size of the header and the size of each event are fixed, you can often determine the number of events from the file’s size.

In the subsequent text, the phrase Net Interface Read function refers to the reference for the NI-CAN Frame API Read function for the Network Interface. Depending on which application development environment you use, this can be found in the NI-CAN Hardware and Software Manual in either:

  • Chapter 10, Frame API for LabVIEW, ncReadNetMult.vi
  • Chapter 11, Frame API for C, ncRead, CAN Network Interface Object

It is highly recommended that the first frame in the logfile consist of an NI-CAN start trigger frame (type 4). The start trigger contains an absolute timestamp (date/time) for the start of the CAN measurement, as well as an indication of the timestamp format for subsequent CAN frames (absolute or relative). If the start trigger is missing from a logfile, the start of the CAN measurement is assumed to be the same as the timestamp of the first CAN frame. For more information on the start trigger frame, refer to the Net Interface Read function.

 

 Field

 Type

 Description

 Timestamp

 U64

64-bit timestamp in 100 nanosecond increments. The timestamp format can be absolute (date/time) or relative (zero-based).

For NI-CAN development in LabVIEW, the timestamp within NI-CAN frames is floating-point (DBL) seconds. For logfile access, you must convert this floating timestamp to/from two U32 fields (see examples). LabVIEW’s binary file I/O functions use big-endian, so you can simply access the most-significant U32 followed by the least significant U32.

For NI-CAN development in C/C++ (or other languages), the timestamp within NI-CAN frames is two U32 fields. Since each U32 in NI-CAN is stored as little-endian (least-significant byte first), you must swap the byte order prior to accessing the logfile.

For LabVIEW FPGA development, the timestamp is two U32 fields. LabVIEW’s binary file I/O functions use big-endian, so you can simply access the most-significant U32 followed by the least significant U32.

Identifier

U32

Identifier of the CAN frame.

Bit 29 (hex 0x20000000 ) indicates the format of the CAN identifier: set for extended, clear for standard.

The conventions for byte swapping match the technique described for each U32 portion of the Timestamp.

Type

U8

Type of event (frame).

This field is 0 to indicate a CAN data frame, and 1 to indicate a CAN remote frame. NI-CAN supports additional values.

For NI-CAN development in LabVIEW, this corresponds to the IsRemote field in the CAN frame. For information on types other than CAN frames, refer to the Net Interface Read function.

For NI-CAN development in C/C++ (or other languages), this corresponds to the FrameType field in the CAN frame. For information on types other than CAN frames, refer to the Net Interface Read function.

For LabVIEW FPGA development, this corresponds to the Type field in the CAN frame. LabVIEW FPGA supports only CAN data frames and CAN remote frames.

InfoA

U8

Information that qualifies the Type.

This information does not exist for NI-CAN.

This information exists for LabVIEW FPGA, but currently it is not used (reserved for future).

When reading the logfile you should ignore this field. When writing the logfile you must set this field to zero.

InfoB

U8

Information that qualifies the Type.

You should interpret this field the same as InfoA (ignore).

DataLength

U8

For CAN data frames, the DataLength indicates the number of valid bytes in Data. For CAN remote frames, the DataLength indicates the bytes requested, not the number of valid bytes in Data. For all other frame Type values, the DataLength indicates the number of valid bytes in Data.

Data

U8

This field always contains 8 bytes in the logfile, but the number of valid bytes is often determined by DataLength.

Table 2:  NI-CAN Logfile Event information