Obwohl das NCL-Protokolldateiformat aus Kompatibilitätsgründen unterstützt wird, wird das TDMS-Protokolldateiformat für neue Anwendungen empfohlen. Weitere Informationen finden Sie unter Embedded Network Data in TDMS.
Ziele für die NI-XNET Protokolldateispezifikationen:
Eine mit der NI-XNET-Protokolldateispezifikation erstellte Protokolldatei kann nicht mit einer für die NI-CAN-Protokolldateispezifikationen entwickelten Anwendung verwendet werden.
NI-CAN Protokolldateien können mit Anwendungen verwendet werden, die mit der NI-XNET Protokolldateispezifikation entwickelt wurden.
Die von NI-XNET-Protokolldateien verwendete Dateierweiterung lautet:
.ncl*.ncl
Alle Embedded-Netzwerkprodukte von NI gehen davon aus, dass jede Datei mit dieser Erweiterung dieser Spezifikation entspricht.
NI bietet Quellcode für den Zugriff auf NI-XNET Protokolldateien. Wenn Sie den Quellcode unverändert in Ihre Anwendung integrieren, können Sie weiterhin die Erweiterung .ncl für Dateien verwenden, die von dieser Anwendung verwendet werden.
Wenn Sie die Kodierung von NI-XNET Protokolldateien ändern, auch wenn dies scheinbar kompatibel ist, müssen Sie die Dateierweiterung von .ncl in eine andere ändern. Diese neue Dateierweiterung kennzeichnet Ihre Dateien als Beschwerde gegen Ihre eigenen Spezifikationen und stellt somit sicher, dass die Datei nicht von Softwareprodukten von NI für Embedded-Netzwerke falsch interpretiert wird.
Die Spezifikation verwendet für jedes Element die folgenden Typen:
U8 8-Bit-Integer ohne Vorzeichen
U16 16 Bit vorzeichenloser Integer, ausgerichtet am 16 Bit Offset in Datei
U32 32-Bit-Integer ohne Vorzeichen, ausgerichtet am 32-Bit-Offset in der Datei
U64 64-Bit-Integer ohne Vorzeichen, ausgerichtet am 64-Bit-Offset in der Datei
Elemente des Typs U16, U32 oder U64 verwenden innerhalb des Headers die Big-Endian-Byte-Reihenfolge (höchstwertiges Byte zuerst). Multibyte-Elemente verwenden in jedem Ereignis (Frame) die Byte-Reihenfolge, die durch das EreignisistLittleEndian-Element des Headers festgelegt ist.
Im Folgenden bezeichnet der Begriff API die Software von National Instruments, mit der Sie auf Embedded-Netzwerkhardware zugreifen. Hierbei handelt es sich um NI-XNET, NI-CAN oder LabVIEW FPGA CAN Knoten.
Im Roh-Frame-Format von NI-XNET verwenden Elemente von U16, U32 oder U64 immer native Byte-Reihenfolge. Da diese native Byte-Reihenfolge vom Ereignis-IstLittleEndian-Element in einer Protokolldatei abweichen kann, ist dies der einzige Unterschied zwischen dem NI-XNET-Format und dem Protokolldateiformat.
Der Header ist die erste Folge von Elementen in der Protokolldatei. Pro Protokolldatei existiert nur ein Header.
| Elemente | Typ | Beschreibung |
| Signatur | U16 | Fester Wert für alle NI-XNET Protokolldateien, mit dessen Hilfe überprüft wird, ob die Binärkodierung der Datei dieser Spezifikation entspricht. Der Wert lautet hexadezimal 4E49 („NI“ in ASCII). |
| HeaderGröße | U16 | Größe des Headers in Vielfachen von U32 (4 Byte-Schritte), einschließlich Signatur und HeaderGröße. |
| HeaderHauptversion | U8 | Hauptversion für den Header (d. h. 1 zu 1,5). Dies deutet auf eine Änderung hin, die die Kompatibilität mit der vorherigen Version beeinträchtigt. |
| HeaderUpgradeVersion | U8 | Version des Headers aktualisieren (d. h. 5 in 1,5). Dies deutet auf eine Änderung hin, die die Kompatibilität mit der Upgrade-Version 0 beibehält. |
| EreignisHauptversion | U8 | Hauptversion für alle Ereignisse in der Datei. Dies deutet auf eine Änderung hin, die die Kompatibilität mit der vorherigen Version beeinträchtigt. |
| EventUpgradeVersion | U8 | Version aktualisieren für alle Ereignisse in der Datei. Dies deutet auf eine Änderung hin, die die Kompatibilität mit der Upgrade-Version 0 beibehält. |
| EreignisIstLittleEndian | U8 | Wenn dieses Element 0 ist, verwenden alle Multibyte-Elemente (Typ U16, U32 oder U64) im Ereignis die Big-Endian-Byte-Reihenfolge (höchstwertiges Byte zuerst). Wenn dieses Element 1 ist, verwenden alle Multibyte-Elemente im Ereignis die Little-Endian-Byte-Reihenfolge (niedrigstwertiges Byte zuerst). Für eine optimale Leistung wird empfohlen, die Byte-Reihenfolge zu verwenden, die Ihrer Computerplattform eigen ist. Dies ist in der Regel bei Windows und PXI LabVIEW Real-Time Little-Endian und bei CompactRIO Big-Endian. Für eine optimale Übertragbarkeit von Protokolldateien von einer Computerplattform auf eine andere wird die Verwendung der Big-Endian-Byte-Reihenfolge empfohlen. Im Beispielcode verwendet die Funktion "Protokolldatei öffnen" einen Eingangsparameter, mit dem die gewünschte Byte-Reihenfolge festgelegt wird: native oder big-endian. Nach der Funktion "Öffnen" werden alle Bytes automatisch ausgetauscht. Ihre Anwendung kann mit Hilfe der API Frames lesen/schreiben und diese mit den Funktionen "Protokolldatei lesen/schreiben" austauschen, ohne dass zwischendurch Code durch spezielle Bytes ausgetauscht wird. |
| (reserviert) | 3 U8 | Alle drei Bytes müssen 0 sein. Diese Bytes füllen den Header so auf, dass er ein Vielfaches von 4 Bytes bleibt. |
Für diese Spezifikation muss der Header immer aus der folgenden Byte-Folge im Hexadezimalformat bestehen:
4E 49 00 03 01 02 00 XX 00 00 00
XX ist EventIsLittleEndian, also entweder 0 (Big-Endian) oder 1 (Little-Endian).
Das Upgrade des Headers von 1.0 auf 1.1 ist auf das Hinzufügen des Elements EventIsLittleEndian zurückzuführen. Wenn NI-XNET Beispielcode Header 1.0 (HeaderGröße 2) liest, wird von Big-Endian für das Ereignis ausgegangen.
Das Upgrade des Ereignisses von 1.0 auf 2.0 ist auf das Hinzufügen von Ereignistypen für FlexRay zurückzuführen. Im Gegensatz zu vorherigen CAN-Frames können FlexRay-Frames unterschiedlich groß sein. Das Upgrade spiegelt auch die Möglichkeit von Little-Endian-Elementen wider (1.0 war immer Big-Endian). Wenn NI-XNET Beispielcode das Ereignis 1.0 liest, wird davon ausgegangen, dass alle Ereignisse 24-Byte-CAN-Frames mit allen Elementen Big-Endian sind.
Nach dem Header enthält die NI-XNET Protokolldatei null oder mehr Ereignisse. Jedes Ereignis stellt in der Regel einen Rahmen dar, kann aber auch andere Informationen wie Fehler oder Trigger enthalten.
Jedes Ereignis in der Protokolldatei beginnt mit der folgenden 24-Byte-Basiseinheit. Der Basiseinheit folgen null oder mehr 8-Byte-Nutzdateneinheiten. Die zusätzlichen Nutzdateneinheiten werden für FlexRay-Frames benötigt, die insgesamt bis zu 254 Nutzdatenbytes enthalten können.
| Elemente | Typ | Beschreibung |
| Zeitstempel | U64 | 64-Bit-Zeitstempel in Schritten von 100 Nanosekunden. Das Zeitstempelformat kann absolut (Datum/Zeit) oder relativ (nullbasiert) sein. Bei NI-XNET ist das Zeitstempelformat immer absolut. Bei der Entwicklung in LabVIEW ist der Zeitstempel in NI-XNET Frames der LabVIEW Zeitstempeltyp, den der Beispielcode als Teil der Datei-I/O in U64 umwandelt. Für die Entwicklung in C/C++ lautet der Zeitstempel in NI-XNET-Frames U64 (wie dieses Element). Bei NI-CAN ist das Standard-Zeitstempelformat absolut, aber Sie können die relative Zeit auf Wunsch konfigurieren. Bei der Entwicklung in LabVIEW ist der Zeitstempel in NI-CAN Frames Fließkomma (DBL) Sekunden, die der Beispielcode als Teil der Datei-I/O in U64 umwandelt. Bei der Entwicklung von NI-CAN in C/C++ beträgt der Zeitstempel innerhalb von NI-CAN-Frames zwei U32-Elemente in Little-Endian-Reihenfolge. Bei der Entwicklung von LabVIEW FPGA ist das Zeitstempelformat immer relativ. Der Zeitstempel besteht aus zwei U32-Elementen in Little-Endian-Reihenfolge. |
| Bezeichner | U32 | Kennung des Rahmens. Wenn Typ einen CAN-Frame angibt, zeigt Bit 29 (Hex 20000000) das Format der CAN-Kennung an: Erweitert, Standard löschen. Wenn Bit 29 leer ist, enthalten die unteren 11 Bit (0-10) die CAN-Frame-Kennung. Wenn Bit 29 gesetzt ist, enthalten die unteren 29 Bit (0-28) die CAN-Frame-Kennung. Wenn Typ einen FlexRay-Frame angibt, enthalten die unteren 16 Bit die Slot-Nummer. Alle ungenutzten Bits sind Null. |
| Typ | U8 | Art des Ereignisses (Frame). Dieses Element gibt den Grundtyp des Rahmens an. Die Interpretation der Elemente Bezeichner, Flags und Info ist für jeden Typ unterschiedlich. Für die Entwicklung von NI-XNET entspricht dies dem Typelement im CAN- und FlexRay-Frame. Für die Entwicklung von NI-CAN in LabVIEW entspricht dies dem IsRemote-Element im CAN- und LIN-Frame. Für die Entwicklung von NI-CAN in C/C++ (oder anderen Sprachen) entspricht dies dem FrameType-Element im CAN- und LIN-Frame. Für die Entwicklung von LabVIEW FPGA entspricht dies dem Typelement im CAN-Frame. Die oberen 4 Bit dieses Elements geben das Protokoll (hexadezimal) an:
Die unteren 4 Bits dieses Elements entsprechen dem spezifischen Typ. Die gängigsten Hexadezimaltypen sind 00 (CAN-Daten-Frame), 01 (CAN-Netzwerk-Frame), 12 (LIN-Voll-Frame), 20 (FlexRay-Daten-Frame) und 21 (FlexRay-Nullabgleich). Weitere Typen finden Sie in der API-Dokumentation. Die Kategorie Benutzerdefiniert (F in den oberen 4 Bit) wurde speziell für die Verwendung in Protokolldateien entwickelt. Zusätzlich zu diesem Protokolldateiformat für eingebettete Netzwerk-Frames müssen Sie möglicherweise andere Daten kodieren, z. B. analoge oder digitale Messungen oder den Zeitpunkt, zu dem eine Schaltfläche auf dem Panel gedrückt wird. Wenn Sie solche benutzerdefinierten Ereignisse erstellen, müssen Sie wissen, dass zukünftige Versionen der API diesen Typ nicht von der Funktion "Lesen" ausgeben. Darüber hinaus möchten Sie möglicherweise, dass die Funktion API: Schreiben diese benutzerdefinierten Ereignisse ignoriert. Obwohl alle Typen von 00 bis EF Hexadezimal für die Verwendung durch NI-Produkte reserviert sind, stehen Ihnen die Typen F0 bis FF als benutzerdefinierte Typen zur Verfügung. Bei Verwendung eines dieser benutzerdefinierten Typen wird das Ereignis ignoriert. Die Definition von Kennung, Flags, Info und Nutzdaten liegt bei Ihnen. Wenn Sie beabsichtigen, Protokolldateien mit anderen Unternehmen auszutauschen, empfehlen wir die Verwendung einer anderen Dateierweiterung als .ncl (oder einer anderen Signatur), um Konflikte zwischen verschiedenen Definitionen benutzerdefinierter Typen zu vermeiden. Außer dem benutzerdefinierten Frame-Typ und den oberen 2 Bit des Info-Elements müssen Sie davon ausgehen, dass alle anderen Bits des Ereignisses für die zukünftige Verwendung durch NI-Produkte reserviert sind. Für Bits, die derzeit nicht verwendet werden (z. B. Bit 30 und 31 von Identifier), gibt die Funktion "API: Lesen" immer 0 aus. Für Frames, die an "API: Schreiben" übergeben werden, muss immer 0 verwendet werden. |
| Flags | U8 | Acht boolesche Flags, die den Frame-Typ qualifizieren. Dieses Element ist in NI-XNET vorhanden. Es wird für CAN und FlexRay verwendet (siehe Dokumentation zu NI-XNET). Dieses Element ist in NI-CAN Frames nicht vorhanden. Dieses Element ist in LabVIEW FPGA CAN Frames (InfoA) vorhanden, wird aber derzeit nicht verwendet (für zukünftige Zwecke reserviert). |
| Info | U8 | Angaben zum Typ des Frames. Dieses Element ist in NI-XNET vorhanden. Es wird nicht für CAN verwendet. Bei FlexRay-Frames wird die Periodenanzahl für den Frame angegeben (0 bis 63). Dieses Element ist in NI-CAN Frames nicht vorhanden. Dieses Element ist in LabVIEW FPGA CAN Frames (InfoB) vorhanden, wird aber derzeit nicht verwendet (für zukünftige Zwecke reserviert). Die oberen 2 Bits dieses Elements sind für die benutzerdefinierte Verwendung vorgesehen, ähnlich wie der benutzerdefinierte Bereich für das Element "Typ". Diese 2 benutzerdefinierten Bits ermöglichen das Hinzufügen von Informationen zu CAN-, LIN- und FlexRay-Frames (Typen im NI-Bereich). Die API "Lesen" gibt die 2 benutzerdefinierten Bits immer als 0 aus, aber Sie können ODER in Ihren eigenen Bits vor dem Schreiben in die Protokolldatei. Wenn Sie Frames aus einer Protokolldatei lesen und an die Funktion API: Schreiben übergeben möchten, ignoriert die API jeden Wert in diesen 2 benutzerdefinierten Bits. |
| Nutzdatenlänge | U8 | Die Nutzdatenlänge gibt die Anzahl gültiger Datenbytes in Nutzdaten an. Bei allen CAN- und LIN-Frames darf die Nutzdatenlänge 8 nicht überschreiten. Da diese Basiseinheit immer 8 Byte Nutzdaten enthält, ist der gesamte CAN/LIN-Frame in der Basiseinheit enthalten und es gibt keine zusätzlichen Nutzdateneinheiten. Für FlexRay-Frames reicht die Nutzdatenlänge von 0 bis 254 Byte. Wenn PayloadLength 0 bis 8 ist, existiert nur die Basiseinheit. Wenn Nutzdatenlänge 9 oder größer ist, folgen mindestens eine Nutzdateneinheit auf die Basiseinheit. Zusätzliche Nutzdateneinheiten werden in Schritten von 8 Byte bereitgestellt, um die Effizienz für DMA-Übertragungen zu optimieren. Wenn z. B. Nutzdatenlänge 9 ist, befinden sich die Bytes 0 bis 7 in der Nutzdateneinheit der Basiseinheit, Byte 8 im ersten Byte der nächsten Nutzdateneinheit und die letzten sieben Bytes der nächsten Nutzdateneinheit werden ignoriert. Das heißt, jeder Rahmen in den Rohdaten kann unterschiedlich lang sein. Die Größe (in Byte) jedes Rahmens kann mit Hilfe des Pseudocodes berechnet werden: U16 FrameSize; // Maximum 272 für größten FlexRay-Frame Die letzte Zeile im Pseudocode subtrahiert 1 und kürzt auf das nächste Vielfache von 8 (mit bitweise UND). Dadurch werden Bytes für zusätzliche Nutzdateneinheiten hinzugefügt. So erfordert beispielsweise die Nutzdatenlänge von 9 bis 16 eine zusätzliche Nutzdateneinheit von 8 Byte. Der Beispielcode verarbeitet die Details dieser längenvariablen Rahmenkodierung in Ihrem Namen. |
| Nutzlast | 8 U8 | Dieses Element verwendet immer 8 Bytes in der Protokolldatei, aber die Anzahl gültiger Bytes richtet sich nach PayloadLength. |
Die Anzahl der zusätzlichen Nutzdateneinheiten (0 bis 31) wird durch das Element Nutzdatenlänge der Basiseinheit festgelegt.
| Elemente | Typ | Beschreibung |
| Nutzlast | 8 U8 | Dieses Element verwendet immer 8 Bytes in der Protokolldatei, aber die Anzahl gültiger Bytes richtet sich nach PayloadLength. |
Die NI-XNET Protokolldatei-Spezifikationen werden auch mit NI-XNET installiert (in der Regel unter C:\Programme\National Instruments\NI-XNET\Dokumentation)