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.
The NI-CAN Logfile Specification was designed to meet the following characteristics:
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.
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
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
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:
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