Embedded Network Data in TDMS

Overview

This article describes how embedded networks data is stored within National Instruments Technical Data Management Streaming (.TDMS) files. The National Instruments TDMS file format provides efficient and flexible storage on NI platforms. The TDMS file format enables storage of a wide variety of measurement types in a single binary file, including CAN, FlexRay, LIN, and so on.

Embedded Networks Logfile

This section specifies the method used to store raw frame data within TDMS. Although you also can store signal waveforms within TDMS, raw frame data is the most efficient and complete way to store embedded networks data. Raw frame data can be easily converted to protocol-specific frames or signal waveforms for display and analysis.

TDMS is recommended for new applications that access embedded networks data within files. For examples that demonstrate use of TDMS with NI-XNET, refer to the NI-XNET Logging and Replay category in the NI Example Finder (for example, Hardware Input and Output : CAN : NI-XNET : Logging and Replay).

Previous versions of NI-XNET and NI-CAN used a file format called NCL to store raw frame data. If you have an existing application that uses NCL, you can continue to use that file format. If you need to store multiple sources of data in a single file (for example, multiple CAN interfaces, or CAN with analog input), you should consider transitioning your application from NCL to TDMS. Since both file formats use the same raw frame data, the changes required for this transition are relatively small.

Within the TDMS file, a sequence of raw frames is stored in a distinct TDMS channel for each embedded networks interface (for example, each CAN port). From the TDMS perspective, the frame data is an array of U8 values. The U8 array represents one or more raw frames.

The version of TDMS used with this specification must be 2.0 or higher. For more information on TDMS, please see the article TDMS File Format Internal Structure.

Channel Name and Group Name

The name of the TDMS channel can use any conventions that you desire, but it should be sufficient to identify the network that is stored. For example, if you log data from two CAN interfaces, you might name the first TDMS channel "Powertrain network" and the second TDMS channel "Body network." If you have a database that contains distinct clusters for each network, the Name (Short) property often provides a useful description of the network, and can be used directly as the TDMS channel name.

The name of the TDMS group can also use any conventions you desire. The group name is required for NI-XNET frame data, but if you do not use multiple groups in the TDMS file you can select a simple group name (for example, "My Group").

Channel Data

The data you read and write to the TDMS channel must be an array of U8 values. No other TDMS data types are supported.

The channel data contains one or more frames encoded using the Raw Frame Format. The raw frame format encodes all information received on the network, along with precise timestamps. For more information on the raw frame format refer to the NI-XNET Hardware and Software Manual. The protocols supported include CAN, FlexRay, and LIN.

The TDMS Channel Properties specify additional requirements for encoding of the raw frame data.

Channel Properties

Special properties are used on each TDMS channel to distinguish the data from a plain array of U8 samples. Properties are also provided to assist in interpreting the data, such as conversion to signals (which have physical units).

All properties for NI-XNET frame data use the prefix NI_network_. This prefix ensures that the properties do not conflict with names used by your application. The table below lists the channel properties.

Name Type Permissions Description
NI_network_protocol I32 Required

Specifies the network protocol used for all frames in this channel.

The property value is an enumeration:

  • 0 - CAN
  • 1 - FlexRay
  • 2 - LIN
NI_network_frame_version I32 Required

Specifies the raw frame encoding version. The encoding of this number is specific to each protocol listed in NI_network_protocol.

For CAN, FlexRay, and LIN, the version encoding is the Upgrade Version in lowest order byte, and Major Version in next order byte. The two upper order bytes are 0.

The Major Version indicates a change that breaks compatibility with the previous version.

The Upgrade Version indicates a change that retains compatibility with Upgrade Version 0.

NI_network_frame_byte_order I32 Required

Specifies the byte order for multibyte elements within each frame’s data. For example, the frame’s Identifier is a 32-bit value, and Timestamp is a 64-bit value. Refer to Raw Frame Format for details.

This property does not specify byte order for TDMS properties or other TDMS channels. This property does not specify byte order for signals within the frame’s Payload (that is, covered by specifications like CANdb, LDF, and FIBEX).

The property value is an enumeration:

  • 0 - Little-endian (that is, least significant byte in lowest offset, Intel byte order)
  • 1 - Big-endian (that is, most significant byte in lowest offset, Motorola byte order)
NI_network_content string Optional

Provides information that describes the content of the payload of frames on this network. This typically is information to map and scale physical-unit values from each frame's payload. The encoding of this string is specific to each protocol listed in NI_network_protocol.

For CAN, FlexRay, and LIN, the string encoding is:

<alias>.<cluster>

The <alias> specifies an alias to a network database file. This alias provides a short name, used to refer to a database file across multiple systems.

The <cluster> refers to a specific cluster (network) within the database. A database file can specify multiple networks within a vehicle. This portion of the string is optional (you can use <alias> without “.” or <cluster>). If the cluster does not exist, it is assumed that only one network is specified within the database.

This property is optional. For applications that read the logfile, if this property does not exist, the effect will depend on the goal:

  • Display of frame values: no effect—the network content is not needed.
  • Display of signal values: application opens a dialog to ask the customer to browse to the database file.

If any of the required properties are not present, the data in the TDMS file will be interpreted as plain U8 samples rather than raw frames.