NI-XNET Logfile Specification

Aperçu

This NI-XNET logfile specification defines a simple, open, binary file format for storage of embedded network data (CAN, FlexRay, and LIN). The primary purpose of the logfile is usage within NI-XNET, NI-CAN and CompactRIO examples for logging, replay, and display of embedded network data. The NI-XNET logfile is also used within National Instruments tools, such as the NI-XNET 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.

Goals

Goals for the NI-XNET logfile specification:

  • Simple: The format of each event (frame) in the logfile is analogous to the frame format used by NI-XNET, NI-CAN, and 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-XNET 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. This binary format is very similar to the raw frame format of NI-XNET. The only difference between this file format and the NI-XNET raw format is that within the file, multi-byte elements use a specific byte order, whereas NI-XNET always uses native byte order.
  • Extensible: Each NI-XNET 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 tools will interpret all versions.
  • Frames (not waveforms): All NI embedded network software provides read and write of data as frames. The frame data represents the raw bits that transfer over the cable. Since the frame data is efficient, and its timing corresponds to the network timing, this is the format used within the NI-XNET logfile. NI-XNET also supports waveforms with each signal obtained from a specific network frame. Although storage of embedded network data as waveforms is less efficient, you can use binary formats such as the NI TDM Streaming format (.tdms) for this purpose (refer to LabVIEW or DIAdem help for more information).

NOTE!

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

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

File Extension

The file extension used by NI-XNET logfiles is:

       .ncl

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

NI provides source code for access to NI-XNET 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 encoding of NI-XNET 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 embedded networks.

Conventions

The specification uses the following types for each element:

        U8            8 bit unsigned integer

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

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

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

Within the Header, elements of type U16, U32, or U64 use big endian byte order (most significant byte first). Within each Event (frame), multi-byte elements use the byte order specified by the EventIsLittleEndian element of the header.

In the following text, the term API refers to the National Instruments software that you use to access embedded networks hardware. This is NI-XNET, NI-CAN, or LabVIEW FPGA CAN nodes.

Within the NI-XNET raw frame format, elements of U16, U32, or U64 always use native byte order. Since that native byte order might differ from the EventIsLittleEndian element in a logfile, this is the only difference between the NI-XNET format and the logfile format.

Header

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

Element Type Description
Signature U16 A fixed value for all NI-XNET 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.
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.
EventIsLittleEndian U8

If this element is 0, all multi-byte elements (type U16, U32, or U64) in the Event use big-endian byte order (most significant byte first). If this element is 1, all multi-byte elements in the Event use little-endian byte order (least significant byte first).

For optimal performance, it is recommended to use the byte order that is native to your computing platform. This is typically little-endian for Windows and PXI LabVIEW Real-Time, and big-endian for CompactRIO.

For best portability of logfiles from one computing platform to another, it is recommended to use big-endian byte order.

In the example code, the Open Logfile function takes an input parameter that you use to specify the desired byte order: native or big-endian. After that Open function, all byte swapping is handled for you automatically. Your application can read/write frames using the API, and exchange those with the Read/Write Logfile functions, without special byte swapping code in-between.

(reserved) 3 U8 All three bytes must be zero. These bytes pad the header such that it remains a multiple of 4 bytes in size.

 

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

     4E   49   00   03   01   01   02   00   XX   00   00   00

XX is EventIsLittleEndian, which is either 0 (big-endian) or 1 (little-endian).

The upgrade of the header from 1.0 to 1.1 was due to the addition of the EventIsLittleEndian element. If NI-XNET example code reads header 1.0 (HeaderSize 2), it assumes big-endian for the event.

The upgrade of the event from 1.0 to 2.0, was due to the addition of event types for FlexRay. Unlike previous CAN frames, FlexRay frames can vary in size. The upgrade also reflects the possibility of little-endian elements (1.0 was always big-endian). If NI-XNET example code reads event 1.0, it assumes that all events are 24-byte CAN frames, with all elements big-endian.

Event

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

Every event in the logfile begins with the following 24-byte base unit. The base unit is followed by zero or more 8-byte payload units. The additional payload units are required for FlexRay frames, which can contain up to 254 total payload bytes.

5.1. Base Unit

Element 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-XNET, the timestamp format is always absolute. For development in LabVIEW, the timestamp within NI-XNET frames is the LabVIEW timestamp type, which the example code converts to U64 as part of the file I/O. For development in C/C++, the timestamp within NI-XNET frames is U64 (same as this element).

For NI-CAN, the default timestamp format is absolute, but you can configure relative time if desired. For development in LabVIEW, the timestamp within NI-CAN frames is floating-point (DBL) seconds, which the example code converts to U64 as part of the file I/O. For NI-CAN development in C/C++, the timestamp within NI-CAN frames is two U32 elements in little-endian order.

For LabVIEW FPGA development, the timestamp format is always relative. The timestamp is two U32 elements in little-endian order.

Identifier U32

Identifier of the frame.

When Type specifies a CAN frame, bit 29 (hex 20000000) indicates the format of the CAN identifier: set for extended, clear for standard. If bit 29 is clear, the lower 11 bits (0-10) contain the CAN frame identifier. If bit 29 is set, the lower 29 bits (0-28) contain the CAN frame identifier.

When Type specifies a FlexRay frame, the lower 16 bits contain the slot number.

All unused bits are zero.

Type U8

Type of event (frame).

This element specifies the fundamental type of the frame. Interpretation of the Identifier, Flags, and Info elements are different for each type.

For NI-XNET development, this corresponds to the Type element in the CAN and FlexRay frames.

For NI-CAN development in LabVIEW, this corresponds to the IsRemote element in the CAN and LIN frames.

For NI-CAN development in C/C++ (or other languages), this corresponds to the FrameType element in the CAN and LIN frames.

For LabVIEW FPGA development, this corresponds to the Type element in the CAN frame.

The upper 4 bits of this element specify the protocol (hexadecimal):

  • 0   CAN
  • 1   LIN
  • 2   FlexRay
  • 3-D   Reserved (unused)
  • E   None (unrelated to protocol)
  • F   Custom (customer-specific types in logfile only)

The lower 4 bits of this element are the specific type.

The most common types in hexadecimal are 00 (CAN data frame), 01 (CAN remote frame), 12 (LIN full frame), 20 (FlexRay data frame), and 21 (FlexRay null frame). Refer to your API documentation for other types.

The Custom category (F in upper 4 bits) is specifically designed for use in logfiles. In addition to using this logfile format for embedded network frames, you may need to encode other data, such as analog or digital measurements, or the time that a front-panel button is pressed. When you create such custom events, you need to know that future versions of the API will not return that type from the Read function. In addition, you may want the API Write function to ignore these custom events. Although all types from 00 to EF hex are reserved for use by NI products, types F0 to FF are available to you as custom types. When you use one of these custom types, NI products ignore the event. The definition of the Identifier, Flags, Info, and Payload is up to you. If you intend to exchange logfiles with other companies, we recommend using a different file extension than .ncl (or a different Signature), to avoid conflicts between different definitions of custom types.

Other than the custom frame Type, and the upper 2 bits of the Info element, you must assume that all other bits of the event are reserved for future use by NI products. For bits that are currently unused (i.e. bit 30 and 31 of Identifier), the API Read function will always return 0, and you must always use 0 for frames passed to the API Write.

Flags U8

Eight boolean flags that qualify the frame’s Type.

This element exists in NI-XNET. It is used for CAN and FlexRay (refer to NI-XNET documentation for details).

This element does not exist in NI-CAN frames.

This element exists in LabVIEW FPGA CAN frames (InfoA), but currently it is not used (reserved for future).

Info U8

Information that qualifies the frame’s Type.

This element exists in NI-XNET. It is not used for CAN. For FlexRay frames, it provides the cycle count for the frame (0 to 63).

This element does not exist in NI-CAN frames.

This element exists in LabVIEW FPGA CAN frames (InfoB), but currently it is not used (reserved for future).

The upper 2 bits of this element are dedicated to custom use, much like the Custom range for the Type element. These 2 custom bits enable you to add information to CAN, LIN, and FlexRay frames (Types in the NI range). The API Read will always return the 2 custom bits as 0, but you can OR in your own bits prior to writing to the logfile. If you want to read frames from a logfile and pass them to the API Write function, the API will ignore any value in these 2 custom bits.

PayloadLength U8

The PayloadLength indicates the number of valid data bytes in Payload.

For all CAN and LIN frames, PayloadLength cannot exceed 8. Since this base unit always includes 8 bytes of payload data, the entire CAN/LIN frame is contained in the base unit, and no additional payload units exist.

For FlexRay frames, PayloadLength ranges from 0 to 254 bytes. If PayloadLength is 0 to 8, only the base unit exists. If PayloadLength is 9 or greater, one or more payload units follow the base unit. Additional payload units are provided in increments of 8 bytes, to optimize efficiency for DMA transfers. For example, if PayloadLength is 9, bytes 0-7 are in the base unit’s Payload, byte 8 is in the first byte of the next payload unit, and the last seven bytes of the next payload unit are ignored.

In other words, each frame in the raw data can vary in length. The size (in bytes) of each frame can be calculated using the pseudocode:

  U16 FrameSize; // maximum 272 for largest FlexRay frame
  FrameSize = 24; // 24 byte base unit
  if (PayloadLength > 8)
    FrameSize = FrameSize +
      (U16)(PayloadLength - 1) AND 0xFFF8;

The last line in the pseudocode subtracts one, and truncates to the nearest multiple of 8 (using bitwise AND). This adds bytes for additional payload units. For example, PayloadLength of 9 through 16 requires one additional payload unit of 8 bytes.

The example code handles the details of this variable-length frame encoding on your behalf.

Payload 8 U8 This element always uses 8 bytes in the logfile, but the number of valid bytes is determined by PayloadLength.

 

5.2. Payload Unit(s)

The number of additional payload units (0 to 31) is determined by the PayloadLength element of the base unit.

Element Type Description
Payload 8 U8 This element always uses 8 bytes in the logfile, but the number of valid bytes is determined by PayloadLength.

 

More information 

The NI-XNET Logfile specifications are also installed with NI-XNET (usually at C:\Program Files\National Instruments\NI-XNET\Documentation)