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 for the NI-XNET logfile specification:
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.
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.
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.
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.
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.
| 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):
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 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. |
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. |
The NI-XNET Logfile specifications are also installed with NI-XNET (usually at C:\Program Files\National Instruments\NI-XNET\Documentation)