NI-XNET记录文件规范

概述

NI-XNET记录文件规范定义了用于存储嵌入式网络数据(CAN、FlexRay和LIN)的简单、开放的二进制文件格式。记录文件主要用于NI-XNET、NI-CAN和CompactRIO范例中记录、重放和显示嵌入式网络数据。NI-XNET日志文件也用于NI-XNET总线监视器等NI工具中。

内容

注意

虽然为了兼容,支持NCL记录文件格式,但建议新应用程序使用TDMS记录文件格式。详细信息见TDMS嵌入式网络数据。

目标

NI-XNET记录文件规范的目标:

  • 简单:记录文件中每个事件(帧)的格式类似于NI-XNET、NI-CAN和用于CAN的LabVIEW FPGA I/O接口(CompactRIO CAN模块)使用的帧格式。这使得应用程序开发更简单、更高效。
  • 打开:本文档中完整定义了NI-XNET记录文件的编码,并在范例中提供了源代码。可将范例代码原封不动地加入应用程序,以确保应用程序在NI工具中正常运行。或者,可增强范例代码以创建自己的记录文件格式(使用自己的文件扩展名)。
  • 二进制:为了支持高效记录全部总线负载,格式为二进制,而不是用户可读的文本。该二进制格式与NI-XNET的原始帧格式非常相似。该文件格式与NI-XNET原始格式的唯一区别在于,在文件中,多字节元素使用特定的字节顺序,而NI-XNET始终使用原生字节顺序。
  • 扩展:每个NI-XNET日志文件以包含版本信息的头信息开头。该规范的后续版本将生成具有更新版本的文件。虽然应用程序可以专注于支持单个版本,但未来的NI工具将解释所有版本。
  • 帧(非波形):所有NI嵌入式网络软件都以帧的形式提供数据的读取和写入。帧数据表示通过线缆传输的原始位。由于帧数据是高效的,且其定时与网络定时相对应,因此这是NI-XNET日志文件中使用的格式。NI-XNET还支持从特定网络帧获取的每个信号的波形。虽然将嵌入式网络数据存储为波形效率较低,但为此目的可使用二进制格式,如NI TDM流格式(.tdms)(更多信息见LabVIEW或DIAdem帮助)。

注:

根据NI-XNET记录文件规范创建的记录文件不能用于为NI-CAN记录文件规范设计的应用程序。

NI-CAN日志文件可用于符合NI-XNET日志文件规范的应用程序。

文件扩展名

NI-XNET记录文件使用的文件扩展名为:

.ncl

所有NI嵌入式网络产品均假定具有该扩展名的文件完全符合此规范。

NI提供访问NI-XNET日志文件的源代码。如未作任何改动将源代码合并至应用程序,可对该应用程序使用的文件继续使用.ncl扩展名。

如果改变NI-XNET记录文件的编码,即使采用看似兼容的方式,也必须将文件扩展名从.ncl改为其他扩展名。新的文件扩展名将文件标识为违反您自己的规范,因此可确保该文件不会被用于嵌入式网络的NI软件产品错误解析。

行文规范

规范中的每个元素使用下列类型:

U8位8位无符号整数

U16 16位无符号整数,对齐文件中的16位偏移量

U32 32位无符号整数,按文件中的32位偏移量对齐

U64 64位无符号整数,对齐文件中的64位偏移量

在header中,U16、U32或U64类型的元素使用大端字节顺序(最高有效字节在先)。在每个事件(帧)中,多字节元素使用头信息的EventIsLittleEndian元素指定的字节顺序。

在下文中,术语API指用于访问嵌入式网络硬件的NI软件。这是NI-XNET、NI-CAN或LabVIEW FPGA CAN节点。

在NI-XNET原始帧格式中,U16、U32或U64的元素始终使用原生字节顺序。由于该原生字节顺序可能与日志文件中的EventIsLittleEndian元素不同,这是NI-XNET格式与日志文件格式的唯一区别。

表头

头是记录文件的第一个元素序列。每个日志文件只有一个头信息。

元素类型说明
签名U16所有NI-XNET记录文件的固定值,用于验证文件的二进制编码符合该规范。值为十六进制4E49(ASCII中的“NI”)
页眉大小U16头的大小,以U32的倍数(4字节递增)为单位,包括签名和头大小。
Header主版本U8头信息的主要版本(即1.5中的1)。这表明改动破坏了与前期版本的兼容性。
头文件升级版本U8头信息的升级版本(5 in 1.5)。这表明改动保留了与升级版本0的兼容性。
事件主版本U8文件中所有事件的主版本。  这表明改动破坏了与前期版本的兼容性。
事件升级版本U8文件中所有事件的升级版本。  这表明改动保留了与升级版本0的兼容性。
小端事件U8

如该元素为0,事件中的所有多字节元素(类型U16、U32或U64)将使用big-endian字节顺序(最高有效字节在先)。如该元素为1,事件中的所有多字节元素均使用little-endian字节顺序(最低有效字节优先)。

为获得最佳性能,建议使用计算平台特有的字节顺序。通常对于Windows和PXI LabVIEW Real-Time是little-endian,对于CompactRIO是big-endian。

为了将日志文件从一个计算平台移植到另一个计算平台,建议使用big-endian字节顺序。

在范例代码中,打开日志文件函数使用输入参数指定所需的字节顺序:原生或big-endian。打开函数后,将自动处理所有字节交换。应用程序可使用API读取/写入帧,并与读取/写入日志文件函数交换帧,而无需在帧之间交换特殊的字节交换代码。

(预留)3 U8所有三个字节必须为零。这些字节填充头信息,使其大小为4字节的倍数。

 

对于该规范,头信息必须始终包含以下十六进制的字节序列:

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

XX是EventIsLittleEndian,即0(big-endian)或1(little-endian)。

头信息从1.0升级到1.1是因为增加了EventIsLittleEndian元素。如果NI-XNET范例代码读取header 1.0(HeaderSize 2),它将假定事件的big-endian。

将事件从1.0升级到2.0是因为增加了FlexRay的事件类型。与之前的CAN帧不同,FlexRay帧的大小可以不同。升级还反映了little-endian元素的可能性(1.0总是big-endian)。如果NI-XNET范例代码读取事件1.0,则假定所有事件都是24字节CAN帧,所有元素都是big-endian。

事件

头信息之后,NI-XNET记录文件将包含零个或多个事件。每个事件通常表示一个帧,但它也可以编码其他信息,如错误或触发。

日志文件中的每个事件以下列24字节基本单位开始。基本单位后跟零个或多个8字节载荷单位。FlexRay帧需要额外的载荷单元,最多可包含254个总载荷字节。

5.1.基本单位

元素类型说明
时间标识U64

64位时间标识,以100纳秒递增。时间标识格式可以是绝对(日期/时间)或相对(从零开始)。

对于NI-XNET,时间标识的格式总是绝对的。对于LabVIEW开发,NI-XNET帧中的时间标识为LabVIEW时间标识类型,范例代码将其转换为U64,作为文件I/O的一部分。对于C/C++开发,NI-XNET帧内的时间标识为U64(与该元素相同)。

对于NI-CAN,默认的时间标识格式为绝对,但可根据需要配置相对时间。在LabVIEW中开发时,NI-CAN帧中的时间标识为浮点(DBL)秒,范例代码将其转换为U64,作为文件I/O的一部分。在C/C++中开发NI-CAN时,NI-CAN帧内的时间标识为little-endian顺序的两个U32元素。

对于LabVIEW FPGA开发,时间标识的格式总是相对的。时间标识是小端顺序的两个U32元素。

标识符U32

帧的标识符。

当类型指定CAN帧时,位29(十六进制20000)表示CAN标识符的格式:设置为扩展,清除为标准。如位29清零,低位11位(0-10)包含CAN帧标识符。如设置位29,低位29位(0-28)包含CAN帧标识符。

类型指定FlexRay帧时,较低的16位包含插槽编号。

所有未使用的位均为0。

类型U8

事件类型(帧)。

该元素指定帧的基本类型。对于每种类型,标识符、标志和信息元素的解释各不相同。

对于NI-XNET开发而言,这对应于CAN和FlexRay帧中的Type元素。

对于在LabVIEW中开发的NI-CAN,这对应于CAN和LIN帧中的IsRemote元素。

对于使用C/C++(或其他语言)的NI-CAN开发,对应于CAN和LIN帧中的FrameType元素。

对于LabVIEW FPGA开发而言,这对应于CAN帧中的类型元素。

该元素的高位4位指定协议(十六进制):

  • 0 CAN
  • 1 LIN
  • 2 FlexRay
  • 三维预留(未使用)
  • E 无(与协议无关)
  • F 自定义(仅限于日志文件中的客户特定类型)

该元素的低位4位为指定类型。

最常见的十六进制类型为00(CAN数据帧)、01(CAN远程帧)、12(LIN全帧)、20(FlexRay数据帧)和21(FlexRay null帧)。关于其他类型,见API文档。

自定义类别(高4位的F)专门用于记录文件。除了在嵌入式网络帧上使用该记录文件格式之外,您可能需要编码其他数据,例如模拟或数字测量,或按下前面板按钮的时间。创建此类自定义事件时,需了解后续版本的API不会从读取函数返回该类型。此外,可能需要API写入函数忽略这些自定义事件。从00到EF十六进制的所有类型都预留给NI产品使用,但F0到FF类型可作为自定义类型使用。使用这些自定义类型之一时,NI产品将忽略该事件。标识符、标志、信息和有效载荷的定义由您决定。如需与其他公司交换日志文件,建议使用与.ncl不同的文件扩展名(或不同的签名),以避免自定义类型的不同定义之间的冲突。

除自定义帧类型和信息元素的前2位外,必须假定事件的所有其他位都已被NI产品预留。对于当前未使用的位(即标识符的位30和31),API读取函数将始终返回0,且对于传递至API写入的帧必须始终使用0。

标志U8

符合帧类型的8个布尔标志。

NI-XNET中存在该元素。它用于CAN和FlexRay(详细信息见NI-XNET文档)。

NI-CAN帧中不存在该元素。

LabVIEW FPGA CAN帧(InfoA)中已存在该元素,但目前未使用(保留用于以后)。

信息U8

限定帧类型的信息。

NI-XNET中存在该元素。不用于CAN。对于FlexRay帧,它提供帧的周期计数(0至63)。

NI-CAN帧中不存在该元素。

LabVIEW FPGA CAN帧(InfoB)中已存在该元素,但目前未使用(保留用于以后)。

该元素的高2位专用于自定义,与类型元素的自定义范围非常相似。这2个自定义位允许用户添加信息至CAN、LIN和FlexRay帧(NI范围内的类型)。API读取将始终将2个自定义位返回为0,但您可以在写入日志文件之前使用自己的位或。如需从记录文件中读取帧并将其传递至API写入函数,API将忽略这2个自定义位中的任何值。

有效载荷长度U8

载荷长度表示载荷中有效数据字节的数量。

对于所有CAN和LIN帧,有效载荷长度不能超过8。由于该基本单元始终包含8字节的有效载荷数据,因此整个CAN/LIN帧包含在基本单元中,不存在额外的有效载荷单元。

对于FlexRay帧,有效载荷长度的范围是0至254字节。如载荷长度为0至8,仅存在基本单位。如有效载荷长度为9或更大,一个或多个有效载荷单位跟随基本单位。额外载荷单位以8字节递增,以优化DMA传输的效率。例如,如载荷长度为9,字节0-7在基本单位载荷中,字节8在下一个载荷单位的第一个字节中,下一个载荷单位的最后7个字节将被忽略。

换言之,原始数据中的每个帧的长度可以不同。可使用伪码计算每帧的大小(字节):

U16帧大小;// 最大FlexRay帧最大值272
  FrameSize = 24; // 24字节基本单位
  如(有效载荷长度>8)
    帧大小 = 帧大小 +
      (U16)(载荷长度 - 1) AND 0xFFF8;

伪码中的最后一行减1,然后截断为8的最近倍数(使用按位与)。这将为额外的载荷单元添加字节。例如,载荷长度为9至16时,需要额外的8字节载荷单元。

范例代码代表用户处理可变长度帧编码的详细信息。

有效载荷8 U8该元素在记录文件中始终使用8个字节,但有效字节数由有效载荷长度决定。

 

5.2.有效单位

附加载荷单元的数量(0至31)由基本单元的载荷长度元素决定。

元素类型说明
有效载荷8 U8该元素在记录文件中始终使用8个字节,但有效字节数由有效载荷长度决定。

 

更多信息 

NI-XNET日志文件规范也随NI-XNET一起安装(通常位于C:\Program Files\National Instruments\NI-XNET\Documentation)

Was this information helpful?

Yes

No