-
Notifications
You must be signed in to change notification settings - Fork 51
NI XNET General Functions
- nxBlink
- nxClear
- nxConnectTerminals
- nxConvertByteArrayToFramesSinglePoint
- nxConvertFramesToByteArraySinglePoint
- nxConvertFramesToSignalsSinglePoint
- nxConvertSignalsToFramesSinglePoint
- nxConvertTimestamp100nsTo1ns
- nxConvertTimestamp1nsTo100ns
- nxCreateSession
- nxCreateSessionByRef
- nxdbAddAlias
- nxdbAddAlias64
- nxdbCloseDatabase
- nxdbCreateObject
- nxdbDeleteObject
- nxdbDeploy
- nxdbFindObject
- nxdbGetDatabaseList
- nxdbGetDatabaseListSizes
- nxdbGetDBCAttribute
- nxdbGetDBCAttributeSize
- nxdbGetProperty
- nxdbGetPropertySize
- nxdbMerge
- nxdbOpenDatabase
- nxdbRemoveAlias
- nxdbSaveDatabase
- nxdbSetProperty
- nxdbUndeploy
- nxDisconnectTerminals
- nxFlush
- nxFutureTimeTrigger
- nxGetProperty
- nxGetPropertySize
- nxGetSubProperty
- nxGetSubPropertySize
- nxReadFrame
- nxReadSignalSinglePoint
- nxReadSignalWaveform
- nxReadSignalXY
- nxReadState
- nxReadStateTimeTrigger
- nxSetProperty
- nxSetSubProperty
- nxStart
- nxStatusToString
- nxStop
- nxSystemClose
- nxSystemOpen
- nxWait
- nxWriteFrame
- nxWriteSignalSinglePoint
- nxWriteSignalWaveform
- nxWriteSignalXY
- nxWriteState
Blinks LEDs for the XNET interface to identify its physical port in the system.
nxStatus_t _NXFUNC nxBlink ( nxSessionRef_t InterfaceRef, u32 Modifier);
nxSessionRef_t InterfaceRef: The XNET Interface I/O name.
u32 Modifier: Controls LED blinking:
Disable (0): Disable blinking for identification. This option turns off both LEDs for the port.
Enable (1): Enable blinking for identification. Both LEDs of the interface's physical port turn on and off. The hardware blinks the LEDs automatically until you disable, so there is no need to call the nxBlink function repetitively.
Both LEDs blink green (not red). The blinking rate is approximately three times per second.
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
Each XNET device contains one or two physical ports. Each port is labeled on the hardware as Port 1 or Port 2. The XNET device also provides two LEDs per port. For a two-port board, LEDs 1 and 2 are assigned to Port 1, and LEDs 3 and 4 are assigned to physical Port 2.
When your application uses multiple XNET devices, this function helps to identify each interface to associate its software behavior to its hardware connection (port). Prior to running your XNET sessions, you can call this function to blink the interface LEDs.
For example, if you have a system with three PCI CAN cards, each with two ports, you can use this function to blink the LEDs for interface CAN4, to identify it among the six CAN ports.
The LEDs of each port support two states:
- Identification: Blink LEDs to identify the physical port assigned to the interface.
- In Use: LED behavior that XNET sessions control.
You can use the nxBlink function only in the Identification state. If you call this function while one or more XNET sessions for the interface are open (created), it returns an error, because the port's LEDs are in the In Use state.
When you create an XNET session for the interface, the LEDs for that physical port transition to the In Use state. If you called the nxBlink function previously to enable blinking for identification, that LED behavior no longer applies. The In Use LED state remains until all XNET sessions are cleared. This typically occurs when the application terminates. The patterns that appear on the LEDs while In Use are documented in LEDs.
Clears (closes) the XNET session.
nxStatus_t nxClear ( nxSessionRef_t SessionRef);
nxSessionRef_t SessionRef: The reference to the session to clear. This session reference is returned from nxCreateSession.
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
This function stops communication for the session and releases all resources the session uses. nxClear internally calls nxStop with normal scope, so if this is the last session using the interface, communication stops.
You typically use nxClear when you need to clear the existing session to create a new session that uses the same objects. For example, if you create a session for a frame named frameA using Frame Output Single-Point mode, then you create a second session for frameA using Frame Output Queued mode, the second call to nxCreateSession returns an error, because frameA can be accessed using only one output mode. If you call nxClear before the second nxCreateSession call, you can close the previous use of frameA to create the new session.
Connects terminals on the XNET interface.
nxStatus_t _NXFUNC nxConnectTerminals ( nxSessionRef_t SessionRef, const char * source, const char * destination);
nxSessionRef_t SessionRef: The reference to the session to use for the connection.
const char * source terminal: The connection source name.
const char * destination terminal: The connection destination name.
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
This function connects a source terminal to a destination terminal on the interface hardware. The XNET terminal represents an external or internal hardware connection point on a National Instruments XNET hardware product. External terminals include PXI Trigger lines for a PXI card, RTSI terminals for a PCI card, or the single external terminal for a C Series module. Internal terminals include timebases (clocks) and logical entities such as a start trigger.
The terminal inputs use the Terminal I/O names. Typically, one of the pair is an internal and the other an external.
The following table lists all valid combinations of source terminal and destination terminal.
| Source | Destination | ||||||
|---|---|---|---|---|---|---|---|
| PXI_Trigx | FrontPanel0 FrontPanel1 |
Start Trigger | MasterTimebase | Log Trigger | TimeTrigger3 | NetworkTimePPS3 | |
| PXI_Trigx | X | X | |||||
| FrontPanel0 FrontPanel1 |
X | X | X | X | |||
| PXI_Star1 | X | X | X | X | X | X | |
| PXI_Clk101 | X | X | X | X | X | ||
| StartTrigger | X | X | X | X | X | ||
| CommTrigger | X | X | X | X | X | ||
| FlexRayStartCycle2 | X | X | X | X | X | ||
| FlexRayMacrotick2 | X | X | X | ||||
| 1MHzTimebase | X | X | X | X | X | ||
| 10MHzTimebase | X | X | X | X | X | X | |
| TimeTrigger3 | X | X | X | X | X | X | |
| NetworkTimePPS3 | X | X | X | X | X | X | |
| NetworkTime1MHz3 | X | X | X | X | X | X |
1 Valid only on PXI hardware.
2 Valid only on FlexRay hardware.
3 Valid only on Ethernet hardware.
4 Not valid on Ethernet hardware.
The following table describes the valid source terminals.
| Source Terminal | Description |
|---|---|
| PXI_Trigx | Selects a general-purpose trigger line as the connection source (input), where x is a number from 0 to 7. For PCI cards, these are the RTSI lines. For PXI cards, these are the PXI Trigger lines. For C Series modules in a CompactDAQ chassis, all modules in the chassis automatically share a common timebase. For information about routing the StartTrigger for CompactDAQ, refer to the XNET Session Interface:Source Terminal:Start Trigger property. |
| FrontPanel0 FrontPanel1 |
Selects a general-purpose Front Panel Trigger line as the connection source (input). |
| PXI_Star |
Selects the PXI star trigger signal. Within a PXI chassis, some PXI products can source star trigger from Slot 2 to all higher-numbered slots. PXI_Star enables the PXI XNET hardware to receive the star trigger when it is in Slot 3 or higher. |
Note You cannot use this terminal with a PCI device.
| PXI_Clk10 |
Selects the PXI 10 MHz backplane clock. The only valid destination terminal for this source is MasterTimebase. This routes the 10 MHz PXI backplane clock for use as the XNET card timebase. When you use PXI_Clk10 as the XNET card timebase, you also must use PXI_Clk10 as the timebase for other PXI cards to perform synchronized input/output. |
Note You cannot use this terminal with a PCI device.
| StartTrigger |
Selects the start trigger, which is the event set when the when the Start Interface transition occurs. The start trigger is the same for all sessions using a given interface. You can route the start trigger of this XNET card to the start trigger of other XNET or DAQ cards to ensure that sampling begins at the same time on both cards. For example, you can synchronize two XNET cards by routing StartTrigger as the source terminal on one XNET card and then routing StartTrigger as the destination terminal on the other XNET card, with both cards using the same PXI Trigger line for the connections. |
| CommTrigger |
Selects the communicating trigger, which is the event set when the Comm State Communicating transition occurs. The communicating trigger is the same for all sessions using a given interface. You can route the communicating trigger of this XNET card to the start trigger of other XNET or DAQ cards to ensure that sampling begins at the same time on both cards. The communicating trigger is similar to a start trigger, but is used if your clock source is the FlexRayMacrotick, which is not available until the interface is properly integrated into the bus. Because you cannot generate a start trigger to another interface until the synchronization clock is also available, you can use this trigger to allow for the clock under this special circumstance. |
| FlexRayStartCycle |
Selects the FlexRay Start of Cycles as an advanced trigger source. This generates a repeating pulse that external hardware can use to synchronize a measurement or other action with each FlexRay cycle. |
Note You can use this terminal only with a FlexRay device.
| FlexRayMacrotick |
Selects the FlexRay Macrotick as a timing source. The FlexRay Macrotick is the basic unit of time in a FlexRay network. You can use this source terminal to synchronize other measurements to the actual time on the FlexRay bus. In this scenario, you would configure the FlexRayMacrotick as the source terminal and route it to a PXI Trigger or front panel terminal. After the interface is communicating to the FlexRay network, the Macrotick signal becomes available. You also can connect the FlexRayMacrotick to the MasterTimebase. This configures the counter that timestamps received frames to run synchronized to FlexRay time, and also allows you to read the FlexRay cycle macrotick to do additional synchronization with the FlexRay bus in your application. |
Note You can use this terminal only with a FlexRay device.
| 1MHzTimebase |
Selects the XNET card's local 1 MHz oscillator. The only valid destination terminals for this source are PXI_Trig0–PXI_Trig7. This source terminal routes the XNET card local 1 MHz clock so that other NI cards can use it as a timebase. For example, you can synchronize two XNET cards by connecting 1MHzTimebase to PXI_Trigx on one XNET card and then connecting PXI_Trigx to MasterTimebase on the other XNET card. |
| 10MHzTimebase | Selects the XNET card's local 10 MHz oscillator. This routes the XNET card local 10 MHz clock for use as a timebase by other NI cards. For example, you can synchronize two XNET cards by connecting 10MHzTimebase to PXI_Trigx on one XNET card and then connecting PXI_Trigx to MasterTimebase on the other XNET card. |
| TimeTrigger |
Selects the Time Trigger of the Ethernet interface as a source. You write an absolute timestamp for a future time to nxFutureTimeTrigger, and the connected destination terminal will pulse at that future time. The pulse rises then falls, and the rising edge occurs at the future time. |
| NetworkTimePPS |
For an Ethernet interface, selects network time (that is, time synchronization protocol such as IEEE Std 802.1AS) as a source. The connected destination terminal generates a pulse per second (PPS). The pulse rises and then falls, and the rising edge occurs in phase with midnight in International Atomic Time (TAI). This terminal pulses regardless of whether the time synchronization protocol is synced. |
| NetworkTime1MHz |
For an Ethernet interface, selects network time (that is, time synchronization protocol such as IEEE Std 802.1AS) as a source. The connected destination terminal pulses at a 1 MHz rate. The pulse rises and then falls, and the rising edge occurs in phase with midnight in TAI. This terminal pulses regardless of whether the time synchronization protocol is synced. |
Note If the signal from the external timebase becomes unstable or unusable, NI-XNET hardware reverts to the default timebase. Error code 0xBFF63078 is generated when this event occurs. Use nxReadState to detect the fault.
The following table describes the valid destination terminals.
| Destination Terminal | Description |
|---|---|
| PXI_Trigx | Selects a general-purpose trigger line as the connection destination (output), where x is a number from 0 to 7. For PCI cards, these are the RTSI lines. For PXI cards, these are the PXI Trigger lines. For C Series modules in a CompactDAQ chassis, all modules in the chassis automatically share a common timebase. For information about routing the StartTrigger for CompactDAQ, refer to the XNET Session Interface:Source Terminal:Start Trigger. |
Caution NI-XNET does not automatically reserve PXI trigger lines. Driving the same line from two devices may cause hardware damage. Before configuring a PXI trigger line as a destination terminal, reserve it through the PXI chassis properties in NI Measurement & Automation Explorer.
| FrontPanel0 FrontPanel1 |
Selects a general-purpose Front Panel Trigger line as the connection destination (output). |
| StartTrigger |
Selects the start trigger, which is the event that allows the interface to begin communication. The start trigger occurs on the first source terminal low-to-high transition. The start trigger is the same for all sessions using a given interface. This causes the Start Interface transition to occur. You can route the start trigger of another XNET or DAQ card to ensure that sampling begins at the same time on both cards. For example, you can synchronize with an M-Series DAQ MIO card by routing the AI start trigger of the MIO card to a RTSI line and then routing the same PXI Trigger line with StartTrigger as the destination terminal on the XNET card. The default (disconnected) state of this destination means the start trigger occurs when nxStart is invoked with the scope set to either Normal or Interface Only. Alternately, if Auto Start? is enabled, reading or writing to a session may start the interface. |
| MasterTimebase |
MasterTimebase instructs the XNET card to use the connection source terminal as the master timebase. The XNET card uses this master timebase for input sampling (including timestamps of received messages) as well as periodic output sampling. Your XNET hardware supports incoming frequencies of 1 MHz, 10 MHz, and 20 MHz, and automatically detects the frequency without any additional configuration. For example, you can synchronize a CAN and DAQ M Series MIO card by connecting the 10 MHz oscillator (board clock) of the DAQ card to a PXI_Trig line, and then connecting the same PXI_Trig line as the source terminal. For PXI and PXI Express form factor hardware, you also can use PXI_Clk10 as the source terminal. This receives the PXI 10 MHz backplane clock for use as the master timebase. MasterTimebase applies separately to each port of a multiport XNET card, meaning you could run each port off of a separate incoming (or onboard) timebase signal. If you are using a PCI board, the default connection to the MasterTimebase is the local oscillator. If you are using a PXI or PXI Express board, the default connection to the MasterTimebase is the PXI_Clk10 signal, if it is available. Some chassis allow PXI_Clk10 to be turned off. In this case, the hardware automatically uses the local oscillator as the default MasterTimebase. |
| Log Trigger | The Log Trigger terminal generates a frame when it detects a rising edge. When connected, this frame is transferred into the queue of the Frame Stream Input session if the session is started. For information about this frame, including the interpretation of the frame payload, refer to Special Frames. |
| TimeTrigger |
Selects the Time Trigger of the Ethernet interface as a destination. When a rising edge occurs on the source terminal, the Time Trigger captures an absolute timestamp, which you can read using nxReadStateTimeTrigger. |
| NetworkTimePPS |
For an Ethernet interface, selects a pulse per second (PPS) sourced from a trigger line (i.e., PXI_Trigx) as an alternate source of local time to steer network time. This allows sharing network time across Ethernet interfaces. When the interface acts as the source of time in the network or when ProtocolEnabled? is false, the interface will frequency- and phase-lock its network time to the PPS. If the interface is not the source of time in the network (i.e., ProtocolEnabled? is true and Port State is nxEnetTimePortState_Slave), PPS pulses have no effect and network time will be obtained from the grandmaster on the network as usual. To determine when the PPS is synchronized, use the Interface:Ethernet:Trigger PPS Synced? property on the interface that receives the PPS. After synchronization, you can correct for any whole-second offset between the interface that sources the PPS and any interface that receives it with these steps: 1. Use nxReadState with StateID of nxState_TimeCurrent to read the current network time on the sourcing interface, and then immediately read the current network time on the receiving interface. 2. Subtract the receiving port's network time from the sourcing port's network time, round to the nearest integer, and then multiply by 1E9. This is the whole-second offset in nanoseconds. 3. Write the resulting value to the Interface:Ethernet:Time Sync:Adjust Network Time property of the receiving port. |
Converts between an NI-XNET byte array signal and a frame using a session of Conversion Mode.
nxStatus_t nxConvertByteArrayToFramesSinglePoint ( nxSessionRef_t SessionRef, u8 * ValueBuffer, u32 SizeOfValueBuffer void * Buffer, u32 SizeOfBuffer, u32 * NumberOfBytesReturned);
nxSessionRef_t SessionRef: The session to convert. This session is returned from nxCreateSession. The session mode must be Conversion.
u8 * ValueBuffer: Provides a byte array representation of the signal value. The value is transferred 1:1 to the signal in the frame. If the session contains more than one signal, or the signal cannot be represented as a byte array, an error is returned.
u32 SizeOfValueBuffer: You should set this to the size (in bytes) of the array passed to ValueBuffer. If this is too small to fit one element for each signal in the session, an error is returned.
u32 SizeOfBuffer: You should set this to the size (in bytes) of the array passed to Buffer. This number does not represent the number of frames to convert. As encoded in raw data, each frame can vary in length. Therefore, the number represents the maximum raw bytes to be converted, not the number of frames. For each frame used in the session, you must provide buffer space in the array passed to Buffer. CAN and LIN frames are always 24 bytes in length. To convert a specific number of frames, multiply that number by 24. FlexRay frames vary in length. For example, if you pass SizeOfBuffer of 91, the buffer may return 80 bytes, within which the first 24 bytes encode the first frame, and the next 56 bytes encode the second frame. If SizeOfBuffer is positive, the data array size is no greater than this number. The minimum size for a single frame is 24 bytes, so you must use at least that number.
void * Buffer: Returns an array of bytes. The raw bytes encode one or more frames using the Raw Frame Format. This frame format is the same for read and write of raw data, and it is also used for log file examples. The data always returns complete frames. For each frame that appears in the session, exactly one frame is returned. If the buffer is not large enough to hold all the data, an error is returned.
u32 * NumberOfBytesReturned: Returns the number of valid bytes in the Buffer array.
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
The signal value written to the ValueBuffer array is written to a raw frame buffer array. For the frame included in the session, a frame is generated in the array that contains the signal value. Signals not present in the session are written as their respective default values; empty space in the frames that signals do not occupy is written with the frame's default payload.
The frame header values are filled with appropriate values so that this function's output can be directly written to a Frame Output session.
Converts between NI-XNET frames and a byte array signal using a session of Conversion Mode.
nxStatus_t nxConvertFramesToByteArraySinglePoint ( nxSessionRef_t SessionRef, void * FrameBuffer, u32 NumberOfBytesForFrames, u8 * ValueBuffer, u32 SizeOfValueBuffer);
nxSessionRef_t SessionRef: The session to convert. This session is returned from nxCreateSession. The session mode must be Conversion.
void * FrameBuffer: Provides the array of bytes, representing frames to convert. The raw bytes encode one or more frames using the Raw Frame Format. This frame format is the same for read and write of raw data and also is used for log file examples. For information about which elements of the raw frame are applicable, refer to Raw Frame Format. The data you write is queued for transmit on the network. Using the default queue configuration for this mode, you can safely write 1536 frames if you have a sufficiently long timeout. To write more data, refer to the XNET Session Number of Values Unused property to determine the actual amount of queue space available for writing.
u32 NumberOfBytesForFrames: The size (in bytes) of the buffer passed to FrameBuffer. This is used to calculate the number of frames to convert.
u32 SizeOfValueBuffer: You should set this to the size (in bytes) of the array passed to ValueBuffer. If this is too small to fit one element for each signal in the session, an error is returned.
u8* ValueBuffer: Returns a byte array representation of the signal value.
If the session contains more than one signal, or the signal cannot be represented as a byte array, an error is returned. The data returns the most recent value received for the signal. If multiple frames for the signal are received since the previous call to nxReadSignalSinglePoint (or session start), only signal data from the most recent frame is returned. If no frame is received for the corresponding signals since you started the session, the XNET Signal Default Value is returned.
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
The frames passed into the FrameBuffer array are read one by one, and the signal values found are written to internal buffers for each signal. Frames are identified by their identifier (FlexRay: slot/cycle count/chA/B) field. Frames unknown to the session are silently ignored. After all frames in the FrameBuffer array are processed, the internal signal buffers' status is returned in the ValueBuffer array. The signal internal buffers' status is being preserved over multiple calls to this function.
This way, for example, data returned from multiple calls of nxFrameRead for a Frame Input Stream Mode session (or any other Frame Input session) can be passed to this function directly.
Converts between NI-XNET frames and signals using a session of Conversion Mode.
nxStatus_t nxConvertFramesToSignalsSinglePoint ( nxSessionRef_t SessionRef, void * FrameBuffer, u32 NumberOfBytesForFrames, f64 * ValueBuffer, u32 SizeOfValueBuffer, nxTimestamp100ns_t * TimestampBuffer, u32 SizeOfTimestampBuffer);
nxSessionRef_t SessionRef: The session to convert. This session is returned from nxCreateSession. The session mode must be Conversion.
void * FrameBuffer: Provides the array of bytes, representing frames to convert. The raw bytes encode one or more frames using the Raw Frame Format. This frame format is the same for read and write of raw data and also is used for log file examples. For information about which elements of the raw frame are applicable, refer to Raw Frame Format. The data you write is queued for transmit on the network. Using the default queue configuration for this mode, you can safely write 1536 frames if you have a sufficiently long timeout. To write more data, refer to the XNET Session Number of Values Unused property to determine the actual amount of queue space available for writing.
u32 NumberOfBytesForFrames: The size (in bytes) of the buffer passed to FrameBuffer. This is used to calculate the number of frames to convert.
u32 SizeOfValueBuffer: You should set this to the size (in bytes) of the array passed to ValueBuffer. If this is too small to fit one element for each signal in the session, an error is returned.
u32 SizeOfTimestampBuffer: You should set this to the size (in bytes) of the array passed to TimestampBuffer. If TimestampBuffer is not NULL, and this is too small to fit one element for each signal in the session, an error is returned.
f64* ValueBuffer: Returns a one-dimensional array of signal values. Each signal value is scaled, 64-bit floating point.
Each array element corresponds to a signal configured for the session. The order of signals in the array corresponds to the order in the session list. The data returns the most recent value received for each signal. If multiple frames for a signal are received since the previous call to nxReadSignalSinglePoint (or session start), only signal data from the most recent frame is returned. If no frame is received for the corresponding signals since you started the session, the XNET Signal Default Value is returned.
nxTimestamp100ns_t* TimestampBuffer: Optionally returns a one-dimensional array of timestamp values of the times when the corresponding signal values arrived. nxTimestamp100ns_t is an absolute timestamp in 100 nanosecond increments. This 64-bit type contains the number of 100 ns intervals that have elapsed since 1 January 1601 00:00:00 Coordinated Universal Time (UTC). In previous releases, this timestamp was called nxTimestamp_t. You can pass TimestampBuffer as NULL; in this case, no timestamps are returned. You also should pass 0 to SizeOfTimeStampBuffer in this case.
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
The frames passed into the FrameBuffer array are read one by one, and the signal values found are written to internal buffers for each signal. Frames are identified by their identifier (FlexRay: slot/cycle count/chA/B) field. Frames unknown to the session are silently ignored. After all frames in the FrameBuffer array are processed, the internal signal buffers' status is returned in the ValueBuffer array, and optionally, the corresponding timestamps from the frames where a signal value was found are returned in the TimestampBuffer array. The signal internal buffers' status is being preserved over multiple calls to this function.
This way, for example, data returned from multiple calls of nxFrameRead for a Frame Input Stream Mode session (or any other Frame Input session) can be passed to this function directly.
Converts between NI-XNET signals and frames using a session of Conversion Mode.
nxStatus_t nxConvertSignalsToFramesSinglePoint ( nxSessionRef_t SessionRef, f64 * ValueBuffer, u32 SizeOfValueBuffer void * Buffer, u32 SizeOfBuffer, u32 * NumberOfBytesReturned);
nxSessionRef_t SessionRef: The session to convert. This session is returned from nxCreateSession. The session mode must be Conversion.
f64 * ValueBuffer: Provides a one-dimensional array of signal values. Each signal value is scaled, 64-bit floating point. Each array element corresponds to a signal configured for the session. The order of signals in the array corresponds to the order in the session list. The data provides the value for the conversion of each signal.
u32 SizeOfValueBuffer: You should set this to the size (in bytes) of the array passed to ValueBuffer. If this is too small to fit one element for each signal in the session, an error is returned.
u32 SizeOfBuffer: You should set this to the size (in bytes) of the array passed to Buffer.
This number does not represent the number of frames to convert. As encoded in raw data, each frame can vary in length. Therefore, the number represents the maximum raw bytes to be converted, not the number of frames. For each frame used in the session, you must provide buffer space in the array passed to Buffer. CAN and LIN frames are always 24 bytes in length. To convert a specific number of frames, multiply that number by 24. FlexRay frames vary in length. For example, if you pass SizeOfBuffer of 91, the buffer may return 80 bytes, within which the first 24 bytes encode the first frame, and the next 56 bytes encode the second frame. If SizeOfBuffer is positive, the data array size is no greater than this number. The minimum size for a single frame is 24 bytes, so you must use at least that number.
void * Buffer: Returns an array of bytes.
The raw bytes encode one or more frames using the Raw Frame Format. This frame format is the same for read and write of raw data, and it is also used for log file examples. The data always returns complete frames. For each frame that appears in the session, exactly one frame is returned. If the buffer is not large enough to hold all the data, an error is returned.
u32 * NumberOfBytesReturned: Returns the number of valid bytes in the Buffer array.
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
The signal values written to the ValueBuffer array are written to a raw frame buffer array. For each frame included in the session, one frame is generated in the array that contains the signal values. Signals not present in the session are written as their respective default values; empty space in the frames that signals do not occupy is written with the frame's default payload.
The frame header values are filled with appropriate values so that this function's output can be directly written to a Frame Output session.
This function converts an nxTimestamp100ns_t value to an nxTimestamp1ns_t value.
nxStatus_t _NXFUNC nxConvertTimestamp100nsTo1ns ( nxTimestamp100ns_t From, nxTimestamp1ns_t * To);
nxTimestamp100ns_t From:The nxTimestamp100ns_t value to convert from.
nxTimestamp1ns_t * To: Pointer to a buffer that returns the nxTimestamp1ns_t value that was converted from nxTimestamp100ns_t.
This function converts the value of an nxTimestamp100ns_t timestamp to a timestamp of type nxTimestamp100ns_t.
nxTimestamp100ns_t is an absolute timestamp in 100 nanosecond increments. This 64-bit type contains the number of 100 ns intervals that have elapsed since 1 January 1601 00:00:00 Coordinated Universal Time (UTC). In previous releases, this timestamp was called nxTimestamp_t.
nxTimestamp1ns_t is an absolute timestamp in 1 nanosecond increments. This 64-bit type contains the number of 1 ns intervals that have elapsed since 1 January 1970 00:00:00 International Atomic Time (TAI).
This function converts an nxTimestamp1ns_t value to an nxTimestamp100ns_t value.
nxStatus_t _NXFUNC nxConvertTimestamp1nsTo100ns ( nxTimestamp1ns_t From, nxTimestamp100ns_t * To);
nxTimestamp1ns_t From: The nxTimestamp1ns_t value to convert from.
nxTimestamp100ns_t * To: Pointer to a buffer that returns the nxTimestamp100ns_t value that was converted from nxTimestamp1ns_t.
This function converts the value of an nxTimestamp1ns_t timestamp to a timestamp of type nxTimestamp100ns_t.
nxTimestamp1ns_t is an absolute timestamp in 1 nanosecond increments. This 64-bit type contains the number of 1 ns intervals that have elapsed since 1 January 1970 00:00:00 International Atomic Time (TAI).
nxTimestamp100ns_t is an absolute timestamp in 100 nanosecond increments. This 64-bit type contains the number of 100 ns intervals that have elapsed since 1 January 1601 00:00:00 Coordinated Universal Time (UTC). In previous releases, this timestamp was called nxTimestamp_t.
Creates an XNET session at run time using strings.
nxStatus_t nxCreateSession ( const char * DatabaseName, const char * ClusterName, const char * List, const char * Interface, u32 Mode, nxSessionRef_t * SessionRef);
const char * DatabaseName: The XNET database to use for interface configuration. The database name must use the or syntax (refer to Databases).
Three special values for this parameter exist:
- :memory:—This is the default in-memory database. You can create and manipulate it using the nxdb... functions. As long as you do not save its content to a real database file using nxdbSaveDatabase, its content is available to nxCreateSession with this special parameter. After you create the session, you must set the XNET Session Interface:64bit Baud Rate property prior to starting the session.
- :can_fd: or :can_fd_brs:—These databases are similar to the default in-memory database, but configure the cluster in either CAN FD or CAN FD+BRS mode, respectively. After you create the session, you must set the XNET Session Interface:64bit Baud Rate and Interface:CAN:64bit FD Baud Rate properties prior to starting the session.
- :can_j1939:—This database is similar to the empty in-memory database (:memory:), but configures the cluster in CAN SAE J1939 application protocol mode. After you create the session, you must set the XNET Session Interface:64bit Baud Rate property using a Session node. You must set this baud rate prior to starting the session.
- :subordinate:—This "database" is available only for a mode of nxMode_FrameInStream. A subordinate session uses the cluster and interface configuration from other sessions. For example, you may have a test application with which the end user specifies the database file, cluster, and signals to read/write. You also have a second application with which you want to log all received frames (input stream), but that application does not specify a database. You run this second application using a subordinate session, meaning it does not configure or start the interface, but depends on the primary test application. For a subordinate session, start and stop of the interface (using the nxStart/nxStop functions) is ignored. The subordinate session reads frames only when another nonsubordinate session starts the interface.
const char * ClusterName: The XNET cluster to use for interface configuration. The name must specify a cluster from the database given in the DatabaseName parameter. If it is left blank, the cluster is extracted from the List parameter; this is not allowed for modes of nxMode_FrameInStream or nxMode_FrameOutStream.
const char * List: Provides the list of signals or frames for the session.
The List syntax depends on the mode:
| Mode | List Syntax |
|---|---|
| nxMode_SignalInSinglePoint, nxMode_SignalOutSinglePoint |
List contains one or more XNET Signal names. If more than one name is provided, a comma must separate each name. Each name must be one of the following options, whichever uniquely identifies a signal within the database given in the DatabaseName parameter: - <Signal> - <Frame>.<Signal> - <Cluster>.<Frame>.<Signal> - <PDU>.<Signal> - <Cluster>.<PDU>.<Signal> List may also contain one or more trigger signals. For information about trigger signals, refer to Signal Output Single-Point Mode or Signal Input Single-Point Mode. |
| nxMode_SignalInWaveform, nxMode_SignalOutWaveform |
List contains one or more XNET Signal names. If more than one name is provided, a comma must separate each name. Each name must be one of the following options, whichever uniquely identifies a signal within the database given in the DatabaseName parameter: - <Signal> - <Frame>.<Signal> - <Cluster>..<Signal> - <PDU>.<Signal> - <Cluster>.<PDU>.<Signal> |
| nxMode_SignalInXY, nxMode_SignalOutXY |
List contains one or more XNET Signal names. If more than one name is provided, a comma must separate each name. Each name must be one of the following options, whichever uniquely identifies a signal within the database given in the DatabaseName parameter: - <Signal> - <Frame>.<Signal> - <Cluster>.<Frame>.<Signal> - <PDU>.<Signal> - <Cluster>.<PDU>.<Signal> |
| nxMode_FrameInStream, nxMode_FrameOutStream | List is empty (" "). |
| nxMode_FrameInQueued, nxMode_FrameOutQueued |
List contains only one XNET Frame or PDU name. Only one name is supported. Each name must be one of the following options, whichever uniquely identifies a frame within the database given in the DatabaseName parameter: - <Frame> - <Cluster>.<Frame> - <PDU> - <Cluster>.<PDU> |
| nxMode_FrameInSinglePoint, nxMode_FrameOutSinglePoint |
List contains one or more XNET Frame or PDU names. If more than one name is provided, a comma must separate each name. Each name must be one of the following options, whichever uniquely identifies a frame within the database given in the DatabaseName parameter: - <Frame> - <Cluster>.<Frame> - <PDU> - <Cluster>.<PDU> |
| nxMode_SignalConversionSinglePoint |
List contains one or more XNET Signal names. If more than one name is provided, a comma must separate each name. Each name must be one of the following options, whichever uniquely identifies a signal within the database given in the DatabaseName parameter: - <Signal> - <Frame>.<Signal> - <Cluster>.<Frame>.<Signal> - <PDU>.<Signal> - <Cluster>.<PDU>.<Signal> |
const char * Interface: The XNET Interface to use for this session. If Mode is nxMode_SignalConversionSinglePoint, this input is ignored. You can set it to an empty string.
u32 Mode: The session mode. It can be one of the following constants defined in nixnet.h:
| nxMode_SignalInSinglePoint | 0 |
|---|---|
| nxMode_SignalInWaveform | 1 |
| nxMode_SignalInXY | 2 |
| nxMode_SignalOutSinglePoint | 3 |
| nxMode_SignalOutWaveform | 4 |
| nxMode_SignalOutXY | 5 |
| nxMode_FrameInStream | 6 |
| nxMode_FrameInQueued | 7 |
| nxMode_FrameInSinglePoint | 8 |
| nxMode_FrameOutStream | 9 |
| nxMode_FrameOutQueued | 10 |
| nxMode_FrameOutSinglePoint | 11 |
| nxMode_SignalConversionSinglePoint | 12 |
nxSessionRef_t* SessionRef: Returns the handle to the session created. Pass this value to any other NI-XNET API functions.
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
This function creates a session using the named database objects specified in List from the database named in DatabaseName.
Creates an XNET session at run time using database references.
nxStatus_t nxCreateSessionByRef ( u32 NumberOfDatabaseRef, nxDatabaseRef_t * ArrayOfDatabaseRef, const char * Interface, u32 Mode, nxSessionRef_t * SessionRef);
u32 NumberOfDatabaseRef: The number of references passed in ArrayOfDatabaseRef.
nxDatabaseRef_t *ArrayOfDatabaseRef: The array of database objects to be used in the session. This can be an array of signal references, an array of frame references, or a single cluster reference, depending on the mode:
| Mode | ArrayOfDatabaseRef Syntax |
|---|---|
| nxMode_SignalInSinglePoint, nxMode_SignalOutSinglePoint | ArrayOfDatabaseRef contains one or more XNET Signal refs. |
| nxMode_SignalInWaveform, nxMode_SignalOutWaveform | ArrayOfDatabaseRef contains one or more XNET Signal refs. |
| nxMode_SignalInXY, nxMode_SignalOutXY | ArrayOfDatabaseRef contains one or more XNET Signal refs. |
| nxMode_FrameInStream, nxMode_FrameOutStream | ArrayOfDatabaseRef contains only one XNET Cluster ref. |
| nxMode_FrameInQueued, nxMode_FrameOutQueued | ArrayOfDatabaseRef contains only one XNET Frame or PDU ref. |
| nxMode_FrameInSinglePoint, nxMode_FrameOutSinglePoint | ArrayOfDatabaseRef contains one or more XNET Frame or PDU refs. |
const char * Interface: The XNET Interface to use for this session.
u32 Mode: The session mode. It can be one of the following constants defined in nixnet.h:
| nxMode_SignalInSinglePoint | 0 |
|---|---|
| nxMode_SignalInWaveform | 1 |
| nxMode_SignalInXY | 2 |
| nxMode_SignalOutSinglePoint | 3 |
| nxMode_SignalOutWaveform | 4 |
| nxMode_SignalOutXY | 5 |
| nxMode_FrameInStream | 6 |
| nxMode_FrameInQueued | 7 |
| nxMode_FrameInSinglePoint | 8 |
| nxMode_FrameOutStream | 9 |
| nxMode_FrameOutQueued | 10 |
| nxMode_FrameOutSinglePoint | 11 |
Note You can use the nxMode_FrameInQueued, nxMode_FrameInSinglePoint, nxMode_FrameOutQueued, and nxMode_FrameOutSinglePoint modes for PDUs also.
nxSessionRef_t* SessionRef: Returns the handle to the session created. Pass this value to any other NI-XNET API functions.
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
This function creates a session using the referenced database objects from an open database specified in ArrayOfDatabaseRef.
Adds a new alias to a database file.
Note You no longer should use this function. nxdbAddAlias64 (which supports baud rate sizes up to 64 bits) has superseded it.
nxStatus_t _NXFUNC nxdbAddAlias ( const char * DatabaseAlias, const char * DatabaseFilepath, u32 DefaultBaudRate);
Refer to nxdbAddAlias64 for a description of this function.
Adds a new alias with baud rate size of up to 64 bits to a database file.
nxStatus_t _NXFUNC nxdbAddAlias64 ( const char * DatabaseAlias, const char * DatabaseFilepath, u64 DefaultBaudRate);
const char * DatabaseAlias: Provides the desired alias name. Alias names are more flexible than other XNET database objects. Alias names must match the following rules:
- Begin with a letter (a-z, A-Z), number (0-9), hyphen (-), or underscore (_).
- May contain spaces and the following symbols: ! # $ % & ' ( ) + - ; = ` { } ~
- Must not end with a space.
If the alias name already exists, this function changes the previous filepath to the specified filepath.
const char * DatabaseFilepath: Provides the path to the CANdb, FIBEX, AUTOSAR, or LDF file. Commas are not allowed in the alias name, because nxdbGetDatabaseList returns the alias list as a comma-separated list of strings.
u64 DefaultBaudRate: Provides the default baud rate, used when filepath refers to a CANdb database (.dbc) or an NI-CAN database (.ncd). These database formats are specific to CAN and do not specify a cluster baud rate. Use this default baud rate to specify a default CAN baud rate to use with this alias. If Filepath refers to a FIBEX database (.xml), AUTOSAR database (.arxml), or LIN LDF file, the DefaultBaudRate parameter is ignored. The FIBEX, AUTOSAR, and LDF database formats require a valid baud rate for every cluster, and NI-XNET uses that baud rate as the default.
If this call replaces an existing alias with the same name, the previous default baud rate will be retained if this value is set to zero (0).
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
NI-XNET uses alias names for database files. The alias names provide a shorter name for display, allow for changes to the file system without changing the application, and enable efficient deployment to LabVIEW Real-Time (RT) targets.
This function is supported on Windows only. For RT targets, you can pass the new alias to nxdbDeploy to transfer an optimized binary image of the database to the RT target. After deploying the database, you can use the alias name in any application for the Windows host and RT target.
When replacing an existing alias with the same name, special rules apply. The alias may have additional properties associated with it, which are added when the alias is created through the XNET Database Editor or the LabVIEW API. These properties are not configurable when adding an alias using this function. These include the CAN FD ISO Mode, default FD baud rate, and ignore application protocol properties. These properties will be retained from the existing alias, and will be used with the new alias if applicable.
If you wish to discard all properties from the previous alias, the alias should first be removed with a call to nxdbRemoveAlias.
Saving Database Files
On Linux, environment variable NIXNET_USE_SYSTEM_LOCALE determines whether NI-XNET saves database files using its default locale setting of en_US.cp1252 (0) or the current system locale (1).
Importing Database Files
To set the locale used for importing files, define a "locale" key in a Javascript Object Notation (JSON) file in the same path as the database. Note that a JSON file must be saved with UTF-8 encoding. For example, in a file .import.json that resides in the same file path as the database, you can define the following key to import database files using a locale of en_US.iso88591:
{ "locale": "en_US.iso88591" }
If no JSON configuration file is present during import, the NIXNET_USE_SYSTEM_LOCALE environment variable controls whether the file is imported using the default NI-XNET locale setting en_US.cp1252 (0) or the current system locale (1).
Closes the database.
nxStatus_t _NXFUNC nxdbCloseDatabase ( nxDatabaseRef_t DatabaseRef, u32 CloseAllRefs);
nxDatabaseRef_t DatabaseRef: The reference to the database to close.
u32 CloseAllRefs: Indicates that a database open multiple times (refer to nxdbOpenDatabase) should be closed completely (CloseAllRefs = 1), or just the reference counter should be decremented (CloseAllRefs = 0), and the database remains open. When the database is closed completely, all references to objects in this database become invalid.
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
This function closes a database. For the case that different threads of an application are using the same database, nxdbOpenDatabase and nxdbCloseDatabase maintain a reference counter indicating how many times the database is open. Every thread can open the database, work with it, and close the database independently using CloseAllRefs = 0. Only the last call to nxdbCloseDatabase actually closes access to the database.
Another option is that only one thread executes nxdbCloseDatabase once, using CloseAllRefs = 1, which closes access for all other threads. This may be convenient when, for example, the main program needs to stop all running threads and be sure the database is closed properly, even if some threads could not execute nxdbCloseDatabase.
Creates a new XNET cluster.
nxStatus_t _NXFUNC nxdbCreateObject ( nxDatabaseRef_t ParentObjectRef, u32 ObjectClass, const char * ObjectName, nxDatabaseRef_t * DbObjectRef);
nxDatabaseRef_t ParentObjectRef: The reference to the parent database object. You first must open a database file using nxdbOpenDatabase.
u32 ObjectClass: The class of object to be created.
const char * ObjectName: The name of the database object to create. The name must be unique for all database objects of the same class in a database. Lowercase letters (a–z), uppercase letters (A–Z), numbers, and the underscore (_) are valid characters for the name. The space ( ), period (.), and other special characters are not supported within the name. The name must begin with a letter (uppercase or lowercase) or underscore, and not a number. The name is limited to 128 characters.
nxDatabaseRef_t * DbObjectRef: The reference to the newly created database object.
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
This function creates an XNET database object. You can create the following objects using this function:
- nxClass_Cluster; parent is nxClass_Database object
- nxClass_Frame; parent is nxClass_Cluster object
- nxClass_PDU; parent is nxClass_Cluster
- nxClass_Subframe; parent is nxClass_PDU or nxClass_Frame1
- nxClass_Signal; parent is nxClass_PDU or nxClass_Frame1
- nxClass_ECU; parent is nxClass_Cluster
- nxClass_LINSched; parent is nxClass_Cluster
- nxClass_LINSchedEntry; parent is nxClass_LINSched
The ObjectName input becomes the nxProp..._Name property of the created object.
The database object is created and remains in memory until the database is closed. This function does not change the open database file on disk. To save the newly created object to the file, use nxdbSaveDatabase.
1You can create a subframe or signal on a frame object only if there is a one-to-one relationship between frames and PDUs, or PDUs are not used (for example, in DBC files).
Deletes an XNET database object and all its child objects.
nxStatus_t _NXFUNC nxdbDeleteObject ( nxDatabaseRef_t DbObjectRef);
nxDatabaseRef_t DbObjectRef: References the database object to delete.
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
This function deletes an XNET database object with all its child objects. When deleting a frame, it also deletes mapped PDUs (and signals and subframes contained in those PDUs) if they are no longer referenced by another frame in the database. To avoid deleting PDUs with a frame, unmap the PDUs by setting the XNET Frame PDU References property to an empty array before deleting the frame object.
Upon deletion, the references to all deleted objects are closed and no longer can be used.
The objects are deleted from a database in memory. The change is in force until the database is closed. This function does not change the open database file on disk. To save the changed database to the file, use nxdbSaveDatabase.
Deploys a database to a remote Real-Time (RT) target.
nxStatus_t _NXFUNC nxdbDeploy ( const char * IPAddress, const char * DatabaseAlias, u32 WaitForComplete, u32 * PercentComplete);
const char * IPAddress: The target IP address.
const char * DatabaseAlias: Provides the database alias name. To deploy a database text file, first add an alias using nxdbAddAlias64.
u32 WaitForComplete: Determines whether the function returns directly or waits until the entire transmission is completed.
u32 * PercentComplete: Indicates the deployment progress.
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
This function transfers an optimized binary image of the database to the RT target. After deploying the database, you can use the alias name in any application for the Windows host and the LabVIEW RT target.
This function is supported on Windows only. RT database deployments are managed remotely from Windows.
This function must access the remote RT target from Windows, so IPAddress must specify a valid IP address for the RT target. You can find this IP address using NI MAX.
If the RT target access is password protected, use the following syntax for the IP address: user:password@IPaddress.
Remote file transfer can take a few seconds, especially when the RT target is far away.
If WaitForComplete is true, this function waits for the entire transfer to complete, then returns. The return value reflects the deployment status, and PercentComplete is 100.
If WaitForComplete is false, this function transfers a portion of the database and returns before it is complete. For an incomplete transfer, the return value returns success, and PercentComplete is less than 100. You can use PercentComplete to display transfer progress on your front panel. You must call nxdbDeploy in a loop until PercentComplete is returned as 100, at which time the return value reflects the entire deployment status.
Finds an object in the database.
nxStatus_t _NXFUNC nxdbFindObject ( nxDatabaseRef_t ParentObjectRef, u32 ObjectClass, const char * ObjectName, nxDatabaseRef_t * DbObjectRef);
nxDatabaseRef_t ParentObjectRef: The reference to the parent object.
u32 ObjectClass: The class of the object to find.
const char * ObjectName: The name of the object to find.
nxDatabaseRef_t * DbObjectRef: A reference to the found object that you can use in subsequent function calls to reference the object.
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
This function finds an object relative to a parent object.
Unlike nxdbCreateObject, this function allows ParentObjectRef to be a grandparent or great-grandparent.
If ParentObjectRef is a direct parent (for example, frame for signal), the ObjectName to search for can be short, and the search proceeds quickly.
If ParentObjectRef is not a direct parent (for example, database for signal), the ObjectName to search for must be qualified such that it is unique within the scope of ParentObjectRef.
For example, if the class of ParentObjectRef is nxClass_Cluster, and ObjectClass is nxClass_Signal, you can specify ObjectName of mySignal, assuming that signal name is unique to the cluster. If not, you must include the frame name as a prefix, such as myFrameA.mySignal.
You must call this function to get a reference to a database object before you can access it.
NI-XNET supports the following database classes:
- nxClass_Cluster
- nxClass_Frame
- nxClass_PDU
- nxClass_Signal
- nxClass_Subframe
- nxClass_ECU
- nxClass_LINSched
- nxClass_LINSchedEntry
Gets the current list of databases on a system.
nxStatus_t _NXFUNC nxdbGetDatabaseList ( const char * IPAddress, u32 SizeofAliasBuffer, char * AliasBuffer, u32 SizeofFilepathBuffer, char * FilepathBuffer, u32 * NumberOfDatabases);
const char * IPAddress: The target IP address.
If IPAddress is an empty string, this function retrieves aliases and file paths for the local Windows system. If IPAddress is a valid IP address, this function retrieves aliases and file paths for the remote RT target. You can find this IP address using NI MAX.
u32 SizeofAliasBuffer: The size of the buffer provided to take the list of alias names.
u32 SizeofFilepathBuffer: The size of the buffer provided to take the list of filepaths of the database files.
char * AliasBuffer: Returns a comma-separated list of strings, one for every alias registered in the system. If no aliases are registered, the list is empty.
char * FilepathBuffer: Returns a comma-separated list of strings that contain the file paths and filenames of the databases assigned to the aliases, one for every alias registered in the system. If no aliases are registered, the list is empty. This parameter applies to Windows targets only; on RT targets, this list always is empty.
u32 * NumberOfDatabases: Returns the number of databases registered on the system.
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
For a local Windows call (IP address empty), FilepathBuffer returns a comma-separated list of file paths. The number of elements in this list is the same as in AliasBuffer. It provides the Windows file path for each corresponding alias.
For a remote call to RT, FilepathBuffer is empty. NI-XNET handles the file system on the RT target automatically, so that only the alias is needed.
If the LabVIEW RT target access is password protected, use the following syntax for the IP address: user:password@IPaddress.
This function is supported on Windows only. RT database deployments are managed remotely from Windows.
This call checks for the existence of the database file and removes any aliases that are no longer valid.
Gets the buffer sizes required to read the current list of databases on a system.
nxStatus_t _NXFUNC nxdbGetDatabaseListSizes ( const char * IPAddress, u32 * SizeofAliasBuffer, u32 * SizeofFilepathBuffer);
const char * IPAddress: The target IP address.
If IPAddress is an empty string, this function retrieves aliases and file paths for the local Windows system. If IPAddress is a valid IP address, this function retrieves aliases and file paths for the remote RT target. You can find this IP address using NI MAX.
u32 SizeofAliasBuffer: Size of the buffer provided to take the list of alias names.
u32 SizeofFilepathBuffer: Size of the buffer provided to take the list of file paths of the database files.
u32 SizeofAliasBuffer: Size of the buffer needed to take the list of alias names.
u32 SizeofFilepathBuffer: Size of the buffer needed to take the list of file paths of the database files.
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
For a local Windows call (IP address empty), SizeofFilepathBuffer returns the size of a buffer needed to query the list of file paths.
For a remote call to RT, SizeofFilepathBuffer is empty. NI-XNET handles the file system on the RT target automatically, so that only the alias is needed.
If the LabVIEW RT target access is password protected, use the following syntax for the IP address: user:password@IPaddress.
This function is supported on Windows only. RT database deployments are managed remotely from Windows.
Reads an attribute value, attribute enumeration, defined attributes, or signal value table from a DBC file.
nxStatus_t nxdbGetDBCAttribute ( nxDatabaseRef_t DbObjectRef, const u32 Mode, const char* AttributeName, const u32 AttributeTextSize, char* AttributeText, u32* IsDefault);
nxDatabaseRef_t DbObjectRef: The reference to the database object for which to get the attribute.
const u32 Mode: The mode specification of this function. Depending on this value, the function returns the following data:
- Mode 0: Get Attribute Value: For a given object (for example, a signal), the function returns the attribute value assigned to the object. The attribute values always are returned as text in AttributeText. The DBC specification also allows defining other data types, such as integer or float. If necessary, you can convert the value to a number by using, for example, the atoi() function. If the attribute is defined as an enumeration of text strings, the attribute value returned here is the index to the enumeration list, which you can retrieve using Mode 1 of this function.
- Mode 1: Get Enumeration: For a given attribute name, the function returns the enumeration text table as a comma-separated string in AttributeText. Because the enumeration for a given attribute name is the same for all objects of the same type, ObjectRef can point to any object with the given class (ObjectRef specifies the class). If no enumeration is defined for an attribute, the function returns an empty string.
- Mode 2: Get Attribute Name List: Returns all attribute names defined for the given object type as a comma-separated string. ObjectRef can point to any object in the database of the given class (ObjectRef specifies the object class). AttributeName is ignored (it should be set to empty string or NULL).
- Mode 3: Get Signal Value Table: This is valid only when ObjectRef points to a signal. AttributeName is ignored (it should be set to empty string or NULL). If the given signal contains a value table, the function returns a comma-separated list in the form {[value,string],,}. The list contains any number of corresponding value,string pairs. If no value table is defined for the signal, the result is an empty string.
const char* AttributeName: The attribute name as defined in the DBC file.
u32 AttributeTextSize: The size in bytes for the AttributeText buffer passed to this function, including \0 for the end of string mark.
char* AttributeText: The buffer in which the attribute value is returned. You can use the nxdbGetDBCAttributeSize function to determine the minimum buffer size for the given attribute.
u32* IsDefault: Indicates that a default value is used instead of a specific value for this object. DBC files define a default value for an attribute with the given name, and then specific values for particular objects. If the specific value for an object is not defined, the default value is returned. If the value returned in IsDefault is 0 (false), the attribute value is specific for this object; otherwise, it is a default. IsDefault has no meaning if the Mode parameter is not 0 (refer to the Mode description above).
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
Depending on the Mode parameter, this function reads an attribute value, attribute enumeration, list of existing attributes, or value table of a signal from a DBC file. Refer to the Mode parameter description above for details.
Attributes are supported for the following object types:
- Cluster (DBC file: Network attribute)
- Frame (DBC file: Message attribute)
- Signal (DBC file: Signal attribute)
- ECU (DBC file: Node attribute)
Databases other than DBC do not support attributes. Attributes are not saved to a FIBEX file when you open and save a DBC file.
Retrieves the minimum size of the buffer required by the nxdbGetDBCAttribute function.
nxStatus_t nxdbGetDBCAttributeSize ( nxDatabaseRef_t DbObjectRef, const int Mode, const char* AttributeName, u32* AttributeTextSize);
nxDatabaseRef_t DbObjectRef: The reference to the database object for which to get the attribute size.
const u32 Mode: The mode specification of this function. Refer to nxdbGetDBCAttribute for details.
const char* AttributeName: The attribute name as defined in the DBC file.
u32* AttributeTextSize: Returns the required buffer size in bytes for the attribute value, including \0 for the end of string mark.
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
You can use nxdbGetDBCAttributeSize prior to calling the nxdbGetDBCAttribute function to retrieve the required buffer size. Using this size, you can allocate memory for a buffer large enough to hold the attribute value.
Reads properties for an XNET Database object.
nxStatus_t _NXFUNC nxdbGetProperty ( nxDatabaseRef_t DbObjectRef, u32 PropertyID, u32 PropertySize, void * PropertyValue);
nxDatabaseRef_t DbObjectRef: The reference to the database object for which to get the property value.
u32 PropertyID: Specifies the ID of the property to get.
u32 PropertySize: The size of the property to get.
void * PropertyValue: A void pointer to a buffer that receives the property value.
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
This function is used to read properties for an XNET Database object.
Refer to the following topics for information about properties you can use with this function:
XNET Cluster Properties
XNET Database Properties
XNET ECU Properties
XNET Frame Properties
XNET Signal Properties
XNET Subframe Properties
Gets a property value size in bytes.
nxStatus_t _NXFUNC nxdbGetPropertySize ( nxDatabaseRef_t DbObjectRef, u32 PropertyID, u32 * PropertySize);
nxDatabaseRef_t DbObjectRef: The reference to the database object for which to get the property value size.
u32 PropertyID: Specifies the ID of the property for which to get the size.
u32 PropertySize: The size of the property to get.
u32 PropertySize: The size of the property value in bytes.
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
Use this function to get a property value size in bytes.
Refer to the following topics for information about properties you can use with this function:
XNET Cluster Properties
XNET Database Properties
XNET ECU Properties
XNET Frame Properties
XNET Signal Properties
XNET Subframe Properties
Merges database objects and related subobjects from the source to the destination cluster.
nxStatus_t _NXFUNC nxdbMerge ( nxDatabaseRef_t TargetClusterRef, nxDatabaseRef_t SourceObjRef, u32 CopyMode, const char * Prefix, u32 WaitForComplete, u32 *PercentComplete);
nxDatabaseRef_t TargetClusterRef: References the cluster object where the source object is merged.
nxDatabaseRef_t SourceObjRef: References the object to be merged into the target cluster.
u32 CopyMode: Defines the merging behavior if the target cluster already contains an object with the same name.
Const char * Prefix: The prefix to be added to the source object name if an abject with the same name and type exists in the target cluster.
U32 WaitForComplete: Determines whether the function returns directly or waits until the entire transmission is completed.
u32 * PercentComplete: Indicates the merging progress.
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
This function merges a database object with all dependent child objects into the target cluster. This function works with the following objects: Frame, PDU, ECU, LIN Schedule, or a cluster. All listed objects must have unique names in the cluster. They are referenced here as objects, as opposed to child objects (for example, a signal is a child of a frame).
If the source object name is not used in the target cluster, this function copies the source objects with the child objects to the target. If an object with the same name exists in the target cluster, you can avoid name collisions by specifying the prefix to be added to the name.
If an object with the same name exists in the target cluster, the merge behavior depends on the CopyMode input:
- nxdbMerge_CopyUseSource: The target object with all dependent child objects is removed from the target cluster and replaced by the source objects.
- nxdbMerge_CopyUseTarget: The source object is ignored (the target cluster object with child objects remains unchanged).
- nxdbMerge_MergeUseSource: This adds child objects from the source object to child objects from the destination object. If target object contains a child object with the same name, the child object from the source frame replaces it. The source object properties (for example, payload length of the frame) replace the target properties.
- nxdbMerge_MergeUseTarget: This adds child objects from the source object to child objects from the destination object. If the target object contains a child object with the same name, it remains unchanged. The target object properties remain unchanged (for example, payload length).
Target frame F1(v1) has signals S1 and S2(v1). Source frame F1(v2) has signals S2(v2) and S3.
(v1) and (v2) are two versions of one object with same name, but with different properties.
- Result of nxdbMerge_CopyUseSource: F1(v2), S2(v2), S3.
- Result of nxdbMerge_CopyUseTarget: F1(v1), S1, S2(v1).
- Result of nxdbMerge_MergeUseSource: F1(v2), S1, S2(v2), S3.
- Result of nxdbMerge_MergeUseTarget: F1(v1), S1, S2(v1), S3.
If the source object is a cluster, this function copies all contained PDUs, ECUs, and LIN schedules with their child objects to the destination cluster.
Depending on the number of contained objects in the source and destination clusters, the execution can take a longer time. If WaitForComplete is true, this function waits until the merging process gets completed. If the execution completes without errors, PercentComplete returns 100. If WaitForComplete is false, the function returns quickly, and PercentComplete returns values less than 100. You must call nxdbMerge repeatedly until PercentComplete returns 100. You can use the time between calls to update a progress bar.
Opens a database file.
nxStatus_t _NXFUNC nxdbOpenDatabase ( const char * DatabaseName, nxDatabaseRef_t * DatabaseRef);
const char * DatabaseName: The database alias or file pathname to open.
nxDatabaseRef_t * DatabaseRef: A reference to the database that you can use in subsequent function calls to reference the database.
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
This function opens a database. When an already open database is opened, this function grants access to the same database and increases an internal reference counter. A multiple referenced (open) database must be closed as many times as it has been opened. Until it is completely closed, the access to this database remains granted, and the database uses computer resources (memory and handles). For more information, refer to nxdbCloseDatabase.
Saving Database Files
On Linux, environment variable NIXNET_USE_SYSTEM_LOCALE determines whether NI-XNET saves database files using its default locale setting of en_US.cp1252 (0) or the current system locale (1).
Importing Database Files
To set the locale used for importing files, define a "locale" key in a Javascript Object Notation (JSON) file in the same path as the database. Note that a JSON file must be saved with UTF-8 encoding. For example, in a file .import.json that resides in the same file path as the database, you can define the following key to import database files using a locale of en_US.iso88591:
{ "locale": "en_US.iso88591" }
If no JSON configuration file is present during import, the NIXNET_USE_SYSTEM_LOCALE environment variable controls whether the file is imported using the default NI-XNET locale setting en_US.cp1252 (0) or the current system locale (1).
Removes a database alias from the system.
nxStatus_t _NXFUNC nxdbRemoveAlias ( const char * DatabaseAlias);
const char * DatabaseAlias: The name of the alias to delete.
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
This function removes the alias from NI-XNET, but does not affect the database text file. It just removes the alias association to the database file path.
This function is supported on Windows only, and the alias is removed from Windows only (not RT targets). Use nxdbUndeploy to remove an alias from a Real-Time (RT) target.
Saves the open database to a FIBEX 3.1.0 file file or exports a cluster from a database to a specific file format.
nxStatus_t _NXFUNC nxdbSaveDatabase ( nxDatabaseRef_t DatabaseRef, const char * DbFilepath);
nxDatabaseRef_t DatabaseRef: References the database to be saved or the database cluster to be exported.
const char * DbFilepath: Contains the pathname to the database file or is empty (saves to the original filepath).
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
If the DatabaseRef parameter is a database reference, this function saves the XNET database current state to a FIBEX 3.1.0 file. The file extension must be .xml. If the target file exists, it is overwritten.
If the DatabaseRef parameter is a cluster reference, this function exports the cluster in a specific file format. A CAN cluster is exported as a CANdb++ database file (.dbc). A LIN cluster is exported as a LIN database file (.ldf). A FlexRay cluster cannot be exported, and the function returns an appropriate error. If the target file exists, it is overwritten.
XNET saves to the FIBEX file only features that XNET sessions use to communicate on the network. If the original file was created using non-XNET software, the target file may be missing details from the original file. For example, NI-XNET supports only linear scaling. If the original FIBEX file used a rational equation that cannot be expressed as a linear scaling, XNET converts this to a linear scaling with factor 1.0 and offset 0.0.
If DbFilepath is empty, the file is saved to the same FIBEX file specified when opened. If opened as a file path, it uses that file path. If opened as an alias, it uses the file path registered for that alias. In the case of a cluster export, the filepath must not be empty.
Saving a database is not supported under Real-Time (RT), but you can deploy and use a database saved on Windows on a Real-Time (RT) target (refer to nxdbDeploy).
Saving Database Files
On Linux, environment variable NIXNET_USE_SYSTEM_LOCALE determines whether NI-XNET saves database files using its default locale setting of en_US.cp1252 (0) or the current system locale (1).
Importing Database Files
To set the locale used for importing files, define a "locale" key in a Javascript Object Notation (JSON) file in the same path as the database. Note that a JSON file must be saved with UTF-8 encoding. For example, in a file .import.json that resides in the same file path as the database, you can define the following key to import database files using a locale of en_US.iso88591:
{ "locale": "en_US.iso88591" }
If no JSON configuration file is present during import, the NIXNET_USE_SYSTEM_LOCALE environment variable controls whether the file is imported using the default NI-XNET locale setting en_US.cp1252 (0) or the current system locale (1).
Writes properties for an XNET Database object.
nxStatus_t _NXFUNC nxdbSetProperty ( nxDatabaseRef_t DbObjectRef, u32 PropertyID, u32 PropertySize, void * PropertyValue);
nxDatabaseRef_t DbObjectRef: The reference to the database object for which to get the property value.
u32 PropertyID: Specifies the ID of the property to set.
u32 PropertySize: The size of the property to set.
void * PropertyValue: A void pointer to a buffer that contains the property value to set.
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
Use this function to write properties for an XNET Database object.
Refer to the following topics for information about properties you can use with this function:
XNET Cluster Properties
XNET Database Properties
XNET ECU Properties
XNET Frame Properties
XNET Signal Properties
[XNET Subframe Properties
Undeploys a database from a remote LabVIEW Real-Time (RT) target.
nxStatus_t _NXFUNC nxdbUndeploy ( const char * IPAddress, const char * DatabaseAlias);
const char * IPAddress: The target IP address.
const char * DatabaseAlias: Provides the database alias name.
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
This function completely deletes the database file and its alias from the RT target.
This function is supported on Windows only. RT database deployments are managed remotely from Windows.
This function must access the remote RT target from Windows, so IPAddress must specify a valid IP address for the RT target. You can find this IP address using NI MAX.
If the RT target access is password protected, you can use the following syntax for the IP address: user:password@IPaddress.
Disconnects terminals on the XNET interface.
nxStatus_t _NXFUNC nxDisconnectTerminals ( nxSessionRef_t SessionRef, const char * source, const char * destination);
nxSessionRef_t SessionRef: The reference to the session to use for the connection.
const char * source terminal: The connection source name.
const char * destination terminal: The connection destination name.
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
This function disconnects a specific pair of source/destination terminals previously connected with nxConnectTerminals.
When the final session for a given interface is cleared, NI-XNET automatically disconnects all terminal connections for that interface. Therefore, nxDisconnectTerminals is not required for most applications.
This function typically is used to change terminal connections dynamically while an application is running. To disconnect a terminal, you first must stop the interface using nxStop with the Interface Only scope. Then you can call nxDisconnectTerminals and nxConnectTerminals to adjust terminal connections. Finally, you can call nxStart with the Interface Only scope to restart the interface.
You can disconnect only a terminal that has been previously connected. Attempting to disconnect a nonconnected terminal results in an error.
Flushes (empties) all XNET session queues.
nxStatus_t _NXFUNC nxFlush ( nxSessionRef_t SessionRef);
nxSessionRef_t SessionRef: The reference to the session to flush. This session is from nxCreateSession.
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
With the exception of single-point modes, all sessions use queues to store frames. For input modes, the queues store frame values (or corresponding signal values) that have been received, but not obtained by calling nxRead. For output sessions, the queues store frame values provided to nxWrite, but not transmitted successfully.
nxStart and nxStop have no effect on these queues. Use nxFlush to discard all frame queues for this session as well as any pending signal values, if applicable.
Note: Prior to NI-XNET 19.0, Signal Input Waveform sessions discarded only underlying frame queues and did not discard pending signal values. For example, if you call nxWrite to write three frames, then immediately call nxStop, then call nxStart a few seconds later, the three frames transmit. If you call nxFlush between nxStopand nxStart, no frames transmit.
As another example, if you receive three frames, then call nxStop, the three frames remains in the queue. If you call nxStart a few seconds later, then call nxRead, you obtain the three frames received earlier, potentially followed by other frames received after calling nxStart. If you call nxFlush between nxStop and nxStart, nxRead returns only frames received after the calling nxStart.
Note: If there are multiple input stream sessions open on the same interface when an overflow error occurs, all input stream sessions must be either stopped or flushed before new data can be received.
Provides the future timestamp for an exported Time Trigger.
nxStatus_t _NXFUNC nxFutureTimeTrigger ( nxSessionRef_t SessionRef, nxTimestamp1ns_t When, u32 Timescale);
nxSessionRef_t SessionRef: The session on which to generate the future time trigger. This session is returned from nxCreateSession.
nxTimestamp1ns_t When: Provides the future timestamp at which the exported Time Trigger terminal will transition from low to high. The Time Trigger generates a pulse (low to high followed by high to low). The timestamp is an nxTimestamp1ns_t absolute time, using the timescale specified in the Timescale input. If you set When to zero, the Time Trigger will pulse immediately.
u32 Timescale: Specifies the timescale that is used with the Time Trigger. Possible values are:
- nxTimescale_LocalTime: This is the local timescale of the XNET hardware (such as the PXI backplane clock).
- nxTimescale_NetworkTime: This is the network timescale (time sync protocol such as IEEE Std 802.1AS).
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
When you use nxConnectTerminals with source terminal of TimeTrigger (i.e., exported), the destination terminal is set low. nxFutureTimeTrigger provides a future timestamp for the exported Time Trigger to generate a pulse (low to high followed by high to low).
If you provide a when timestamp that cannot be generated (e.g., in the past, or too soon in the future for XNET to handle), this VI returns an error.
If you invoke nxFutureTimeTrigger while a previous invocation of nxFutureTimeTrigger is pending, an error is returned; future timestamps are not queued.
An invocation of nxFutureTimeTrigger is cancelled if you disconnect the exported Time Trigger (using the nxDisconnectTerminals, nxClear, or by stopping execution of your top-level VI).
Retrieves an XNET session property.
nxStatus_t nxGetProperty ( nxSessionRef_t SessionRef, u32 PropertyID, u32 PropertySize, void * PropertyValue);
nxSessionRef_t SessionRef: The session to get the property from. This session is returned from nxCreateSession.
u32 PropertyID: The ID of the property desired. The appropriate constants are listed in the Properties section and defined in nixnet.h.
u32 PropertySize: The number of bytes provided for the buffer passed to PropertyValue. This can be a fixed-size (for example, 4 bytes for a u32 property) or variable-sized buffer. If the property has variable size (for example, a string property whose size is determined at runtime), call nxGetPropertySize to retrieve the necessary size of the buffer beforehand.
void * PropertyValue: Returns the value of the desired property.
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
Refer to the following topics for information about properties you can use with this function:
XNET Device Properties
XNET Interface Properties
XNET Session Properties
XNET System Properties
Retrieves the data size of an XNET session property.
nxStatus_t nxGetPropertySize ( nxSessionRef_t SessionRef, u32 PropertyID, u32 * PropertySize);
nxSessionRef_t SessionRef: The session to get the property from. This session is returned from nxCreateSession.
u32 PropertyID: The ID of the property desired. The appropriate constants are listed in the Properties section and defined in nixnet.h.
u32 * PropertySize: Returns the number of bytes to be provided for the buffer to retrieve the property. Pass a buffer of that size to nxGetProperty.
Note For string properties, the property size returned includes the space for the terminating NULL byte.
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
Refer to the following topics for information about properties you can use with this function:
XNET Device Properties
XNET Interface Properties
XNET Session Properties
XNET System Properties
Retrieves a property of a frame or signal within an XNET session.
nxStatus_t nxGetSubProperty ( nxSessionRef_t SessionRef, u32 ActiveIndex, u32 PropertyID, u32 PropertySize, void * PropertyValue);
nxSessionRef_t SessionRef: The session to get the property from. This session is returned from nxCreateSession.
u32 ActiveIndex: Identifies the frame or signal within the session. It is the index to the list given in nxCreateSession.
u32 PropertyID: The ID of the property desired. The properties to use with this function are listed in the Frame Properties topic for the session. Within your code, applicable PropertyID values begin with the prefix nxProp_SessionSub.
u32 PropertySize: The number of bytes provided for the buffer passed to PropertyValue. This can be a fixed-size (for example, 4 bytes for a u32 property) or variable-sized buffer. If the property has variable size (for example, a string property whose size is determined at runtime), call nxGetSubPropertySize to retrieve the necessary size of the buffer beforehand.
void * PropertyValue: Returns the value of the desired property.
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
Retrieves the data size of a property of a frame or signal within an XNET session.
nxStatus_t nxGetSubPropertySize ( nxSessionRef_t SessionRef, u32 ActiveIndex, u32 PropertyID, u32 * PropertySize);
nxSessionRef_t SessionRef: The session to get the property from. This session is returned from nxCreateSession.
u32 ActiveIndex: Identifies the frame or signal within the session. It is the index to the list given in nxCreateSession.
u32 PropertyID: The ID of the property desired. The properties to use with this function are listed in the Frame Properties topic for the session. Within your code, applicable PropertyID values begin with the prefix nxProp_SessionSub.
u32 * PropertySize: Returns the number of bytes to be provided for the buffer to retrieve the property. Pass a buffer of that size to nxGetSubProperty. Note For string properties, the property size returned includes the space for the terminating NULL byte.
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
Reads data from a session as an array of raw bytes.
nxStatus_t nxReadFrame ( nxSessionRef_t SessionRef, void * Buffer, u32 SizeOfBuffer, f64 Timeout, u32 * NumberOfBytesReturned);
nxSessionRef_t SessionRef: The session to read. This session is returned from nxCreateSession. The session mode must be Frame Input Stream Mode, Frame Input Queued Mode, or Frame Input Single-Point Mode.
u32 SizeOfBuffer: SizeOfBuffer is the size of the provided memory buffer (passed by the Buffer argument). This is the limit of the number of bytes nxReadFrame delivers.
As encoded in raw data, each frame can vary in length. Therefore, the number represents the maximum raw bytes to read, not the number of frames. Standard CAN and LIN frames are always 24 bytes in length. To read a specific number of standard CAN and/or LIN frames, multiply that number by 24. CAN FD and FlexRay frames vary in length. For example, if you pass SizeOfBuffer of 91, the buffer might return 80 bytes, within which the first 24 bytes encode the first frame, and the next 56 bytes encode the second frame. The minimum useful size for a single frame is 24 bytes. You should allow at least that number of bytes.
f64 Timeout: The time to wait for number to read frame bytes to become available; the timeout is represented as 64-bit floating-point in units of seconds.
To avoid returning a partial frame, even when SizeOfBuffer bytes are available from the hardware, this read may return fewer bytes in Buffer. For example, assume you pass SizeOfBuffer of 70 bytes and Timeout of 10 seconds. During the read, two frames are received, the first 24 bytes in size, and the second 56 bytes in size, for a total of 80 bytes. The read returns after the two frames are received, but only the first frame is copied to data. If the read copied 46 bytes of the second frame (up to the limit of 70), that frame would be incomplete and therefore difficult to interpret. To avoid this problem, the read always returns complete frames in Buffer. If Timeout is positive, nxReadFrame waits for SizeOfBuffer frame bytes to be received, then returns complete frames up to that number. If the bytes do not arrive prior to the timeout, an error is returned.
If Timeout is negative, nxReadFrame waits indefinitely for SizeOfBuffer frame bytes. If Timeout is zero, nxReadFrame does not wait and immediately returns all available frame bytes up to the limit SizeOfBuffer specifies. If the session mode is Frame Input Single-Point, you must set Timeout to 0.0. Because this mode reads the most recent value of each frame, Timeout does not apply.
void * Buffer: Returns an array of bytes.
The raw bytes encode one or more frames using the Raw Frame Format. This frame format is the same for read and write of raw data, and it is also used for log file examples. The data always returns complete frames. Note For PDU sessions, only the payload for the specified PDU is returned in the array of bytes. For an example of how this data applies to network traffic, refer to Frame Input Stream Mode, Frame Input Queued Mode, or Frame Input Single-Point Mode.
u32 * NumberOfBytesReturned: Returns the number of valid bytes in the Buffer array.
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
The raw bytes encode one or more frames using the Raw Frame Format. The session must use Frame Input Stream Mode, Frame Input Queued Mode, or Frame Input Single-Point Mode. The raw frame format is protocol independent, so the session can use either a CAN, FlexRay, or LIN interface.
The raw frames are associated to the session's list of frames as follows:
- Frame Input Stream Mode: Array of all frame values received (list ignored).
- Frame Input Queued Mode: Array of frame values received for the single frame specified in the list.
- Frame Input Single-Point Mode: Array of single frame values, one for each frame specified in the list.
Note: If an overflow error occurs while multiple input stream sessions are open on the same interface, all input stream sessions must be either stopped or flushed before new data can be received. For more information, refer to nxFlush.
Reads data from a session of Signal Input Single-Point Mode.
nxStatus_t nxReadSignalSinglePoint ( nxSessionRef_t SessionRef, f64 * ValueBuffer, u32 SizeOfValueBuffer, nxTimestamp100ns_t * TimestampBuffer, u32 SizeOfTimestampBuffer);
nxSessionRef_t SessionRef: The session to read. This session is returned from nxCreateSession. The session mode must be a Signal Input Single-Point Mode.
u32 SizeOfValueBuffer: Should be set to the size (in bytes) of the array passed to ValueBuffer. If this is too small to fit one element for each signal in the session, an error is returned.
u32 SizeOfTimestampBuffer: Should be set to the size (in bytes) of the array passed to TimestampBuffer. If TimestampBuffer is not NULL and this is too small to fit one element for each signal in the session, an error is returned.
f64* ValueBuffer: Returns a one-dimensional array of signal values. Each signal value is scaled, 64-bit floating point.
Each array element corresponds to a signal configured for the session. The order of signals in the array corresponds to the order in the session list. The data returns the most recent value received for each signal. If multiple frames for a signal are received since the previous call to nxReadSignalSinglePoint (or session start), only signal data from the most recent frame is returned. If no frame is received for the corresponding signals since you started the session, the XNET Signal Default Value is returned. For an example of how this data applies to network traffic, refer to Signal Input Single-Point Mode. A trigger signal returns a value of 1.0 or 0.0, depending on whether its frame arrived since the last Read (or Start) or not. For more information about trigger signals, refer to Signal Input Single-Point Mode.
nxTimestamp100ns_t* TimestampBuffer: Optionally returns a one-dimensional array of timestamp values of the times when the corresponding signal values arrived. Each timestamp value is an absolute timestamp in 100 nanosecond increments. This 64-bit type contains the number of 100 ns intervals that have elapsed since 1 January 1601 00:00:00 Coordinated Universal Time (UTC). In previous releases, this timestamp was called nxTimestamp_t.
TimestampBuffer can be passed as NULL; then no timestamps are returned. SizeOfTimeStampBuffer also should be passed 0 in this case.
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
Reads data from a session of Signal Input Waveform Mode.
The data represents a waveform of resampled values for each signal in the session.
nxStatus_t nxReadSignalWaveform ( cnxSessionRef_t SessionRef, f64 Timeout, nxTimestamp100ns_t * StartTime, f64 * DeltaTime, f64 * ValueBuffer, u32 SizeOfValueBuffer, u32 * NumberOfValuesReturned);
Note In the following, N means the maximum number of samples to read. It is calculated from SizeOfValueBuffer. nxSessionRef_t SessionRef: The session to read. This session is returned from nxCreateSession. The session mode must be Signal Input Waveform.
f64 Timeout: The time to wait for N samples to become available.
The timeout is represented as 64-bit floating-point in units of seconds. If Timeout is positive, nxReadSignalWaveform waits for N samples, then returns that number. If the samples do not arrive prior to the timeout, an error is returned. If Timeout is negative, nxReadSignalWaveform waits indefinitely for N samples. If Timeout is zero, nxReadSignalWaveform does not wait and immediately returns all available samples up to the limit N specifies. Because time determines sample availability, typical values for this timeout are 0 (return available) or a large positive value such as 100.0 (wait for a specific N).
u32 SizeOfValueBuffer: The size (in bytes) of the array passed to ValueBuffer. It is used to calculate N = trunc (SizeOfValueBuffer / (sizeof (f64) * (number of signals in the session))). There always is a maximum of N samples per waveform returned, even if SizeOfValueBuffer is not a multiple of (sizeof (f64) * (number of signals in the session)).
nxTimestamp100ns_t* StartTime: Optionally returns the start time of the waveform returned in ValueBuffer. It is the absolute time of the first sample, given as the number of 100 ns intervals that have elapsed since 1 January 1601 00:00:00 Coordinated Universal Time (UTC). In previous releases, this timestamp was called nxTimestamp_t. StartTime can be passed as NULL; in this case, no value is returned.
f64* DeltaTime: Optionally returns the time increment between successive values of the waveform returned in ValueBuffer. The value returned is 1.0/Resample Rate. DeltaTime can be passed as NULL; in this case, no value is returned.
f64* ValueBuffer: Returns a two-dimensional array of f64 samples. First, N samples are reserved for the first signal in the session, then N samples for the second, and so on. N * (number of signals in the session) * sizeof (f64) should be passed in SizeOfValueBuffer to recalculate N.
For an example of how this data applies to network traffic, refer to Signal Input Waveform Mode.
u32* NumberOfValuesReturned: The number of waveform samples per signal that have been returned in ValueBuffer. This is always less than or equal to N. NumberOfValuesReturned can be passed as NULL; in this case, no value is returned.
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
The data represents a waveform for each signal in the session.
Reads data from a session of Signal Input XY Mode.
nxStatus_t nxReadSignalXY ( nxSessionRef_t SessionRef, nxTimestamp100ns_t * TimeLimit, f64 * ValueBuffer, u32 SizeOfValueBuffer, nxTimestamp100ns_t * TimestampBuffer, u32 SizeOfTimestampBuffer, u32 * NumPairsBuffer, u32 SizeOfNumPairsBuffer);
Note In the following, N means the maximum number of samples to read per signal. It is calculated from SizeOfValueBuffer and SizeOfTimestampBuffer.
nxSessionRef_t SessionRef: The session to read. This session is returned from nxCreateSession. The session mode must be Signal Input XY.
nxTimestamp100ns_t* TimeLimit: The timestamp to wait for before returning signal values. nxTimestamp100ns_t is an absolute timestamp in 100 nanosecond increments. This 64-bit type contains the number of 100 ns intervals that have elapsed since 1 January 1601 00:00:00 Coordinated Universal Time (UTC). In previous releases, this timestamp was called nxTimestamp_t.
If TimeLimit is valid, nxReadSignalXY waits for the timestamp to occur, then returns available values (up to number to read). If you increment TimeLimit by a fixed number of seconds for each call to nxReadSignalXY, you effectively obtain a moving window of signal values.
The Timeout of other nxRead functions specifies the maximum amount time to wait for a specific (number to read) values. The TimeLimit of nxReadSignalXY does not specify a worst-case timeout value, but rather a specific absolute timestamp to wait for.
u32 SizeOfValueBuffer: The size (in bytes) of the array passed to ValueBuffer. N is calculated from this as: N = trunc (SizeOfValueBuffer / (sizeof (f64) * (number of signals in the session))). If both SizeOfValueBuffer and SizeOfTimestampBuffer deliver a valid N value (N > 0), the smaller of the two values is used to avoid buffer overflows.
u32 SizeOfTimestampBuffer: The size (in bytes) of the array passed to TimestampBuffer. N is calculated from this as: N = trunc (SizeOfTimestampBuffer / (sizeof (f64) * (number of signals in the session))). If both SizeOfValueBuffer and SizeOfTimestampBuffer deliver a valid N value (N > 0), the smaller of the two values is used to avoid buffer overflows.
u32 SizeOfNumPairsBuffer: The size (in bytes) of the array passed to NumPairsBuffer. For each signal in the session, an array element should be provided. If the buffer is too small, an error is returned.
f64* ValueBuffer: Returns a two-dimensional array of f64 samples. First, N samples are reserved for the first signal in the session, then N samples for the second, and so on. N * (number of signals in the session) * sizeof (f64) should be passed in SizeOfValueBuffer to recalculate N.
For an example of how this data applies to network traffic, refer to Signal Input XY Mode.
nxTimestamp100ns_t* TimestampBuffer: Returns a two-dimensional array of timestamps. First, N timestamps are reserved for the first signal in the session, then N timestamps for the second, and so on. N * (number of signals in the session) * sizeof (f64) should be passed in SizeOfTimestampBuffer to recalculate N.
nxTimestamp100ns_t is an absolute timestamp in 100 nanosecond increments. This 64-bit type contains the number of 100 ns intervals that have elapsed since 1 January 1601 00:00:00 UTC.
u32* NumPairsBuffer: Returns a one-dimensional array of signal/timestamp pair counts, one for each signal in the session. Upon output, the samples and timestamps for signal #(i) in the preceding arrays are valid up to, but not including, index NumPairsBuffer[i] (zero based).
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
The data represents an XY plot of timestamp/value pairs for each signal in the session.
Reads communication states of an XNET session.
nxStatus_t nxReadState ( nxSessionRef_t SessionRef, u32 StateID, u32 StateSize, void * StateValue, nxStatus_t * Fault);
nxSessionRef_t SessionRef: The session to read. This session is returned from nxCreateSession.
u32 StateID Indicates the state to be read. Possible values are:
| nxState_TimeCurrent | Current interface time |
|---|---|
| nxState_TimeCommunicating | Time interface started communicating |
| nxState_TimeStart | Time interface was started |
| nxState_CANComm | CAN communication state |
| nxState_FlexRayComm | FlexRay communication state |
| nxState_FlexRayStats | FlexRay statistics |
| nxState_LINComm | LIN communication state |
| nxState_SessionInfo | Session running state |
| nxState_J1939Comm | J1939 communication state |
| The value determines the format output as StateValue. |
u32 StateSize: Indicates the size of the buffer provided for StateValue.
void * StateValue: Returns the trigger timestamp value. StateValue must point to a nxTimeLocalNetwork_t buffer. This struct contains both the local and network timestamps of the first rising edge of the imported Time Trigger since it was armed. The two timestamps are captured atomically.
StateID = nxState_TimeCommunicating:
StateValue must point to an nxTimestamp100ns_t buffer. It is filled with the time the interface started communicating in 100 ns increments since 1 Jan 1601 00:00:00 UTC. This time is usually later than the interface start time (StateID = nxState_TimeStart), because the interface must undergo a communication startup procedure.
If the interface is not communicating when this read is called, an invalid time is returned (0).
StateID = nxState_TimeStart:
StateValue must point to an nxTimestamp100ns_t buffer. It is filled with the time the interface was started in 100 ns increments since 1 Jan 1601 00:00:00 UTC.
If the interface is not started when this read is called, an invalid time is returned (0).
StateID = nxState_CANComm:
StateValue must point to a u32 buffer. It is filled with a communication state DWORD, which is comprised of several bit fields. You can use macros in nixnet.h to access these bit fields.
| Bit | Meaning |
|---|---|
| 0–3 | Communication State |
| Error Active (0) | This state reflects normal communication, with few errors detected. The CAN interface remains in this state as long as receive error counter and transmit error counter are both below 128. |
|---|---|
| Error Passive (1) |
If either the receive error counter or transmit error counter increment above 127, the CAN interface transitions into this state. Although communication proceeds, the CAN device generally is assumed to have problems with receiving frames. When a CAN interface is in error passive state, acknowledgement errors do not increment the transmit error counter. Therefore, if the CAN interface transmits a frame with no other device (ECU) connected, it eventually enters error passive state due to retransmissions, but does not enter bus off state. |
| Bus Off (2) |
If the transmit error counter increments above 255, the CAN interface transitions into this state. Communication immediately stops under the assumption that the CAN interface must be isolated from other devices. When a CAN interface transitions to the bus off state, communication stops for the interface. All NI-XNET sessions for the interface no longer receive or transmit frame values. To restart the CAN interface and all its sessions, call nxStart. |
| Init (3) |
This is the CAN interface initial state on power-up. The interface is essentially off, in that it is not attempting to communicate with other nodes (ECUs). When the start trigger occurs for the CAN interface, it transitions from the Init state to the Error Active state. When the interface stops due to a call to nxStop, the CAN interface transitions from either Error Active or Error Passive to the Init state. When the interface stops due to the Bus Off state, it remains in that state until you restart. |
| 4 |
Transceiver Error Transceiver error indicates whether an error condition exists on the physical transceiver. This is typically referred to as the transceiver chip NERR pin. False indicates normal operation (no error), and true indicates an error. |
| 5 |
Sleep Sleep indicates whether the transceiver and communication controller are in their sleep state. False indicates normal operation (awake), and true indicates sleep. |
| 8–11 |
Last Error Last error specifies the status of the last attempt to receive or transmit a frame (decimal value in parentheses): |
| None (0) | The last receive or transmit was successful. |
|---|---|
| Stuff (1) | More than 5 equal bits have occurred in sequence, which the CAN specification does not allow. |
| Form (2) | A fixed format part of the received frame used the wrong format. |
| Ack (3) |
Another node (ECU) did not acknowledge the frame transmit. If you call the appropriate nxWrite function and do not have a cable connected, or the cable is connected to a node that is not communicating, you see this error repeatedly. The CAN communication state eventually transitions to Error Passive, and the frame transmit retries indefinitely. |
| Bit 1 (4) | During a frame transmit (with the exception of the arbitration ID field), the interface wanted to send a recessive bit (logical 1), but the monitored bus value was dominant (logical 0). |
| Bit 0 (5) | During a frame transmit (with the exception of the arbitration ID field), the interface wanted to send a dominant bit (logical 0), but the monitored bus value was recessive (logical 1). |
| CRC (6) | The CRC contained within a received frame does not match the CRC calculated for the incoming bits. |
| 16–23 |
Transmit Error Counter The transmit error counter begins at 0 when communication starts on the CAN interface. The counter increments when an error is detected for a transmitted frame and decrements when a frame transmits successfully. The counter increases more for an error than it is decreased for success. This ensures that the counter generally increases when a certain ratio of frames (roughly 1/8) encounter errors. When communication state transitions to Bus Off, the transmit error counter no longer is valid. |
| 24–31 |
Receive Error Counter The receive error counter begins at 0 when communication starts on the CAN interface. The counter increments when an error is detected for a received frame and decrements when a frame is received successfully. The counter increases more for an error than it is decreased for success. This ensures that the counter generally increases when a certain ratio of frames (roughly 1/8) encounter errors. |
StateID = nxState_FlexRayComm:
StateValue must point to a u32 buffer. It is filled with a communication state DWORD, which is comprised of several bit fields. You can use macros in nixnet.h to access these bit fields.
| Bit | Meaning |
|---|---|
| 0–3 |
POC State POC state specifies the FlexRay interface state (decimal value in parentheses): |
| Default Config (0) | This is the FlexRay interface initial state on power-up. The interface is essentially off, in that it is not configured and is not attempting to communicate with other nodes (ECUs). |
|---|---|
| Ready (1) |
When the interface starts, it first enters Config state to validate the FlexRay cluster and interface properties. Assuming the properties are valid, the interface transitions to this Ready state. In the Ready state, the FlexRay interface attempts to integrate (synchronize) with other nodes in the network cluster. This integration process can take several FlexRay cycles, up to 200 ms. If the integration succeeds, the interface transitions to Normal Active. You can use nxReadState to read the time when the FlexRay interface entered Ready. If integration succeeds, you can use nxReadState to read the time when the FlexRay entered Normal Active. |
| Normal Active (2) | This is the normal operation state. The NI-XNET interface is adequately synchronized to the cluster to allow continued frame transmission without disrupting the transmissions of other nodes (ECUs). If synchronization problems occur, the interface can transition from this state to Normal Passive. |
| Normal Passive (3) | Frame reception is allowed, but frame transmission is disabled due to degraded synchronization with the cluster remainder. If synchronization improves, the interface can transition to Normal Active. If synchronization continues to degrade, the interface transitions to Halt. |
| Halt (4) |
Communication halted due to synchronization problems. When the FlexRay interface is in Halt state, all NI-XNET sessions for the interface stop, and no frame values are received or transmitted. To restart the FlexRay interface, you must restart the NI-XNET sessions. If you clear (close) all NI-XNET sessions for the interface, it transitions from Halt to Default Config state. |
| Config (15) |
This state is transitional when configuration is valid. If you detect this state after starting the interface, it typically indicates a problem with the configuration. Check the fault? output for a fault. If no fault is returned, check your FlexRay cluster and interface properties. You can check the validity of these properties using the NI-XNET Database Editor, which displays invalid configuration properties. In the FlexRay specification, this value is referred to as the Protocol Operation Control (POC) state. For more information about the FlexRay POC state, refer to Summary of the FlexRay Standard. |
| 4–7 |
Clock Correction Failed Clock correction failed returns the number of consecutive even/odd cycle pairs that have occurred without successful clock synchronization. If this count reaches the value in the XNET Cluster FlexRay:Max Without Clock Correction Passive property, the FlexRay interface POC state transitions from Normal Active to Normal Passive state. If this count reaches the value in the XNET Cluster FlexRay:Max Without Clock Correction Fatal property, the FlexRay interface POC state transitions from Normal Passive to Halt state. In the FlexRay specification, this value is referred to as vClockCorrectionFailed. |
| 8–12 |
Passive to Active Count Passive to active count returns the number of consecutive even/odd cycle pairs that have occurred with successful clock synchronization. This count increments while the FlexRay interface is in POC state Error Passive. If the count reaches the value in the XNET Session Interface:FlexRay:Allow Passive to Active property, the interface POC state transitions to Normal Active. In the FlexRay specification, this value is referred to as vAllowPassiveToActive. |
| 13 |
Channel A Sleep? Indicates whether channel A currently is asleep. |
| 14 |
Channel B Sleep? Indicates whether channel B currently is asleep. |
StateID = nxState_FlexRayStats:
StateValue must point to an nxFlexRayStats_t buffer (defined in nixnet.h). It is filled with communication statistics values. The values are:
u32 NumSyntaxErrorChA
The number of syntax errors that have occurred on channel A since communication started.
|
A syntax error occurs if: - A node starts transmitting while the channel is not in the idle state. - There is a decoding error. - A frame is decoded in the symbol window or in the network idle time. - A symbol is decoded in the static segment, dynamic segment, or network idle time. - A frame is received within the slot after reception of a semantically correct frame (two frames in one slot). - Two or more symbols are received within the symbol window. |
|---|
| u32 NumSyntaxErrorChB |
The number of syntax errors that have occurred on channel B since communication started.
u32 NumContentErrorChA
The number of content errors that have occurred on channel A since communication started.
|
A content error occurs if: - In a static segment, a frame payload length does not match the global cluster property. - In a static segment, the Startup indicator (bit) is 1 while the Sync indicator is 0. - The frame ID encoded in the frame header does not match the current slot. - The cycle count encoded in the frame header does not match the current cycle count. - In a dynamic segment, the Sync indicator is 1. - In a dynamic segment, the Startup indicator is 1. - In a dynamic segment, the Null indicator is 0. |
|---|
| u32 NumContentErrorChB |
The number of content errors that have occurred on channel B since communication started.
u32 NumSlotBoundaryViolationChA
The number of slot boundary violations that have occurred on channel A since communication started.
A slot boundary violation error occurs if the interface does not consider the channel to be idle at the boundary of a slot (either beginning or end).
u32 NumSlotBoundaryViolationChB
The number of slot boundary violations that have occurred on channel B since communication started.
For more information about these statistics, refer to Summary of the FlexRay Standard.
StateID = nxState_LINComm:
StateValue must point to a u32 array buffer. It is filled with a communication state DWORD, which is comprised of several bit fields, and a schedule DWORD, which is comprised of a single bit field. You can use macros in nixnet.h to access these bit fields.
Communication State DWORD
| Bit | Meaning |
|---|---|
| 0 | Reserved |
| 1 |
Sleep Indicates whether the transceiver and communication controller are in their sleep state. False (0) indicates normal operation (awake), and true (1) indicates sleep. This value changes from 0 to 1 only when you set the XNET Session Interface:LIN:Sleep property to nxLINSleep_RemoteSleep or nxLINSleep_LocalSleep. This value changes from 1 to 0 when one of the following occurs: - You set the XNET Session Interface:LIN:Sleep property to nxLINSleep_RemoteWake or nxLINSleep_LocalWake. - The interface receives a remote wakeup pattern (break). In addition to this nxReadState function, you can wait for a remote wakeup event using the nxWait function with the nxCondition_IntfCommunicating condition. |
| 2–3 | Communication State |
| Idle (0) |
This is the LIN interface initial state on power-up. The interface is essentially off, in that it is not attempting to communicate with other nodes (ECUs). When the start trigger occurs for the LIN interface, it transitions from the Idle state to the Active state. When the interface stops due to a call to XNET Stop, the LIN interface transitions from either Active or Inactive to the Idle state. |
|---|---|
| Active (1) | This state reflects normal communication. The LIN interface remains in this state as long as bus activity is detected (frame headers received or transmitted). |
| Inactive (2) |
This state indicates that no bus activity has been detected in the past four seconds. Regardless of whether the interface acts as a master or slave, it transitions to this state after four seconds of bus inactivity. As soon as bus activity is detected (break or frame header), the interface transitions to the Active state. The LIN interface does not go to sleep automatically when it transitions to Inactive. To place the interface into sleep mode, set the XNET Session Interface:LIN:Sleep property when you detect the Inactive state. |
| 4–7 |
Last Error Specifies the status of the last attempt to receive or transmit a frame. It is an enumeration. For a table of all values for last error, refer to the Last Error Table. |
| 8–15 |
Last Error Received Returns the value received from the network when last error occurred. For a table that describes how this field is populated based on the last error, refer to the Last Error Table. |
| 16–23 |
Last Error Expected Returns the value that the LIN interface expected to see (instead of last received). For a table that describes how this field is populated based on the last error, refer to the Last Error Table. |
| 24–29 |
Last Error ID Returns the frame identifier in which the last error occurred. For a table that describes how this field is populated based on the last error, refer to the Last Error Table. |
| 30 | Reserved |
| 31 |
Transceiver Ready Indicates whether the LIN transceiver is powered from the bus. True (1) indicates the bus power exists, so it is safe to start communication on the LIN interface. If this value is false (0), you cannot start communication successfully. Wire power to the LIN transceiver and run your application again. |
Schedule DWORD
| Bit | Meaning |
|---|---|
| 0–7 |
Schedule Index Indicates the LIN schedule that the interface currently is running. This index refers to a LIN schedule that you requested using the nxWriteState function. It indexes the array of schedules represented in the XNET Schedule Interface:LIN:Schedule Names property. This index applies only when the LIN interface is running as a master. If the LIN interface is running as a slave only, this element should be ignored. |
| 8–31 | Reserved |
| Last Error Table |
The following table lists each value for last error, along with a description, and applicable use of last received, last expected, and last identifier. In the last error column, the decimal value is shown in parentheses after the string name.
| Last Error | Description | Last Received | Last Expected | Last Identifier |
|---|---|---|---|---|
| None (0) | No bus error has occurred since the previous communication state read. | 0 (N/A) | 0 (N/A) | 0 (N/A) |
| Unknown ID (1) | Received a frame identifier that is not valid (0–63). | 0 (N/A) | 0 (N/A) | 0 (N/A) |
| Form (2) | The form of a received frame is incorrect. For example, the database specifies 8 bytes of payload, but you receive only 4 bytes. | 0 (N/A) | 0 (N/A) | Received frame ID |
| Framing (3) | The byte framing is incorrect (for example, a missing stop bit). | 0 (N/A) | 0 (N/A) | Received frame ID |
| Readback (4) | The interface transmitted a byte, but the value read back from the transceiver was different. This often is caused by a cabling problem, such as noise. | Value read back | Value transmitted | Received frame ID |
| Timeout (5) | Receiving the frame took longer than the LIN-specified timeout. | 0 (N/A) | 0 (N/A) | Received frame ID |
| Checksum (6) | The received checksum was different than the expected checksum. | Received checksum | Calculated checksum | Received frame ID |
| StateID = nxState_SessionInfo: |
StateValue must point to a u32. It contains the current session running state. The running states are:
nxSessionInfoState_Stopped (0)
All frames in the session are stopped.
nxSessionInfoState_Started (1)
All frames in the session are started.
nxSessionInfoState_Mix (2)
Some frames in the session are started while other frames are stopped. This state may occur when using nxStart or nxStop with the Session Only option.
StateID = nxState_J1939comm:
StateValue must point to an nxJ1939CommState_t buffer (defined in nixnet.h). It is filled with communication statistics values. The values are:
u32 PGN
Specifies the J1939 PGN that occurred the last error. You cannot assign a PGN to every error.
u32 SourceAddress
Specifies the source address that occurred the last error. You cannot assign a source address to every error.
u32 DestinationAddress
Specifies the destination address that occurred the last error. You cannot assign a destination address to every error.
u32 TransmitError
Indicates a transmit-related error occurred.
u32 ReceiveError
Indicates a receive-related error occurred.
u32 Reserved1
u32 Reserved2
StateID = nxStateTimeCurrent2:
StateValue must point to an nxTimeLocalNetwork_t buffer. It is filled with the current interface time. Both local and network timestamps are captured atomically. Each timestamp is expressed in 1 ns increments since 1 January 1970 00:00:00 International Atomic Time (TAI). Use this StateID with Ethernet devices.
StateID = nxStateTimeCommunicating2:
StateValue must point to an nxTimeLocalNetwork_t buffer. It is filled with the time the interface started communicating, measured in 1 ns increments since 1 January 1970 00:00:00 TAI. Use this StateID with Ethernet devices.
StateID = nxStateTimeStart2:
StateValue must point to an nxTimeLocalNetwork_t buffer. It is filled with the time the interface was started in 1 ns increments since 1 January 1970 00:00:00 TAI. If the interface is not started when this read is called, an invalid time is returned (0). Use this StateID with Ethernet devices.
nxStatus_t* Fault: Returns a numeric code you can use to obtain a description of the fault. If no fault occurred, the fault code is 0.
A fault is an error that occurs asynchronously to the NI-XNET application calls. The fault cause may be related to network communication, but it also can be related to XNET hardware, such as a fault in the onboard processor. Although faults are extremely rare, nxReadState provides a detection method distinct from the status of NI-XNET function calls, yet easy to use alongside the common practice of checking the communication state.
To obtain a fault description, pass the fault code to nxStatusToString.
nxStatus_t: The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
You can use nxReadState with any XNET session mode.
Your application can use nxReadState to check for problems on the network independently from other aspects of your application. For example, you intentionally may introduce noise into the CAN cables to test how your ECU behaves under these conditions. When you do this, you do not want the status of NI-XNET functions to return errors, because this may cause your application to stop. Your application can use nxReadState to read the network state quickly as data, so that it does not introduce errors into the flow of your code.
Alternately, to log bus errors, you can set the Interface:Bus Error Frames to Input Stream? property to cause CAN and LIN bus errors to be logged as a special frame (refer to Special Frames for more information) into a Frame Stream Input queue.
Reads the captured timestamp for an imported Time Trigger.
nxStatus_t _NXFUNC nxReadStateTimeTrigger ( nxSessionRef_t SessionRef, f64 Timeout, u32 StateSize, void * StateValue);
nxSessionRef_t SessionRef: The session to read. This session is returned from nxCreateSession.
f64 Timeout: The time to wait for the rising edge of Time Trigger. The timeout is a relative time, represented as 64-bit floating-point in units of seconds.
- If timeout is positive, nxReadStateTimeTrigger waits for the rising edge of Time Trigger, then returns the timestamps for that edge. If the edge does not occur prior to the timeout, an error is returned.
- If timeout is negative, nxReadFrame waits indefinitely for the rising edge of Time Trigger.
- If timeout is zero, nxReadFrame does not wait and immediately returns the timestamps, which are zero (invalid) if the rising edge of Time Trigger has not occurred.
This input is optional. The default value is 10 seconds.
u32 StateSize: Indicates the size of the buffer provided for StateValue, in bytes. StateSize must be equal to sizeof(nxTimeLocalNetwork_t).
void * StateValue: Returns the trigger timestamp value. StateValue must point to an nxTimeLocalNetwork_t buffer. This struct contains both the local and network timestamps of the first rising edge of the imported Time Trigger since it was armed. The two timestamps are captured atomically.
nxTimescale_LocalTime: Returns the timestamp of first rising edge of the imported Time Trigger since it was armed. The timestamp is an absolute time, using the local timescale. If Time Trigger has not encountered a rising edge since it was armed, local time trigger returns zero (an invalid timestamp).
nxTimescale_NetworkTime: Returns the timestamp of first rising edge of the imported Time Trigger since it was armed. The timestamp is an absolute time, using the network timescale. If Time Trigger has not encountered a rising edge since it was armed, network time trigger returns zero (an invalid timestamp).
IntfEnetTimePortSynced: Contains the value of the nxPropSession_IntfEnetTimePortSynced property at the time that both timestamps are acquired, to specify whether the network time trigger timestamp is synchronized to the network (true) or not (false).
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
When you use the nxConnectTerminals with destination terminal of TimeTrigger (i.e., imported), the Time Trigger captures absolute timestamps on the rising edge, and you read those timestamps using nxReadStateTimeTrigger.
The imported Time Trigger is armed when you invoke nxConnectTerminals, and Time Trigger is armed again on each subsequent invocation of nxReadStateTimeTrigger. After the Time Trigger is armed, the first rising edge after arming is captured for the subsequent nxReadStateTimeTrigger.
Sets an XNET session property.
nxStatus_t nxSetProperty ( nxSessionRef_t SessionRef, u32 PropertyID, u32 PropertySize, void * PropertyValue);
nxSessionRef_t SessionRef: The session to set the property for. This session is returned from nxCreateSession.
u32 PropertyID: The ID of the property to set. The appropriate constants are listed in the Properties section and defined in nixnet.h.
u32 PropertySize: The number of bytes provided for the buffer passed to PropertyValue. This can be a fixed-size (for example, 4 bytes for a u32 property) or variable-sized buffer (for example, for a string property).
void * PropertyValue: Contains the value to set for the desired property.
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
Refer to the following topics for information about properties you can use with this function:
XNET Device Properties
XNET Interface Properties
XNET Session Properties
XNET System Properties
Sets a property of a frame or signal within an XNET session.
nxStatus_t nxSetSubProperty ( nxSessionRef_t SessionRef, u32 ActiveIndex, u32 PropertyID, u32 PropertySize, void * PropertyValue);
nxSessionRef_t SessionRef: The session to set the property for. This session is returned from nxCreateSession.
u32 ActiveIndex: Identifies the frame or signal within the session. It is the index to the list given in nxCreateSession.
u32 PropertyID: The ID of the property to set. The properties to use with this function are listed in the Frame Properties topic for the session. Within your code, applicable PropertyID values begin with the prefix nxProp_SessionSub.
u32 PropertySize: The number of bytes provided for the buffer passed to PropertyValue. This can be a fixed-size (for example, 4 bytes for a u32 property) or variable-sized buffer (for example, for a string property).
void * PropertyValue: Contains the value to set for the desired property.
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
Starts communication for the specified XNET session.
nxStatus_t nxStart ( nxSessionRef_t SessionRef, u32 Scope);
nxSessionRef_t SessionRef: The session to start. This session is returned from nxCreateSession.
u32 Scope: Describes the impact of this operation on the underlying state models for the session and its interface.
| Normal (0) | The session is started followed by starting the interface. This is equivalent to calling nxStart with the Session Only Scope followed by calling nxStart with the Interface Only Scope. |
|---|---|
| Session Only (1) | The session is placed into the Started state (refer to State Models). If the interface is in the Stopped state before this function runs, the interface remains in the Stopped state, and no communication occurs with the bus. To have multiple sessions start at exactly the same time, start each session with the Session Only Scope. When you are ready for all sessions to start communicating on the associated interface, call nxStart with the Interface Only scope. Starting a previously started session is considered a no-op. This operation sends the command to start the session, but does not wait for the session to be started. It is ideal for a real-time application where performance is critical. |
| Interface Only (2) | If the underlying interface is not previously started, the interface is placed into the Started state (refer to State Models). After the interface starts communicating, all previously started sessions can transfer data to and from the bus. Starting a previously started interface is considered a no-op. |
| Session Only Blocking (3) | The session is placed in the Started state (refer to State Models). If the interface is in the Stopped state before this function runs, the interface remains in the Stopped state, and no communication occurs with the bus. To have multiple sessions start at exactly the same time, start each session with the Session Only Scope. When you are ready for all sessions to start communicating on the associated interface, call nxStart with the Interface Only Scope. Starting a previously started session is considered a no-op. This operation waits for the session to start before completing. |
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
Because the session is started automatically by default, this function is optional. This function is for more advanced applications to start multiple sessions in a specific order. For more information about the automatic start feature, refer to the Auto Start? property.
For each physical interface, the NI-XNET hardware is divided into two logical units:
- Sessions: You can create one or more sessions, each of which contains frames or signals to be transmitted (or received) on the bus.
- Interface: The interface physically connects to the bus and transmits (or receives) data for the sessions.
You can start each logical unit separately. When a session is started, all contained frames or signals are placed in a state where they are ready to communicate. When the interface is started, it takes data from all started sessions to communicate with other nodes on the bus. For a specification of the state models for the session and interface, refer to State Models.
If an output session starts before you write data, or you read an input session before it receives a frame, default data is used. For more information, refer to the XNET Frame Default Payload and XNET Signal Default Value properties.
Converts a status code returned from a function into a descriptive string.
void _NXFUNC nxStatusToString ( nxStatus_t Status, u32 SizeofString, char * StatusDescription);
nxStatus_t Status: The status code to be explained.
u32 SizeofString: The size of the string provided to store the explanation of the status code.
char * StatusDescription: The string in which the explanation of the status code will be stored.
This function converts a status code returned from a function into a descriptive string.
SizeofString is the size allocated for the string. The description is truncated to size SizeofString if needed, but a size of 2048 characters is large enough to hold any description. The text returned in StatusDescription is null-terminated, so it can be used with ANSI C functions such as printf.
Stops communication for the specified XNET session.
nxStatus_t nxStop ( nxSessionRef_t SessionRef, u32 Scope);
nxSessionRef_t SessionRef: The session to stop. This session is returned from nxCreateSession.
u32 Scope: Describes the impact of this operation on the underlying state models for the session and its interface.
| Normal (0) | The session is stopped. If this is the last session stopped on the interface, the interface is also stopped. If any other sessions are running on the interface, this call is treated just like the Session Only Scope, to avoid disruption of communication on the other sessions. |
|---|---|
| Session Only (1) | The session is placed in the Stopped state (refer to State Models). If the interface was in the Started or Running state before this function is called, the interface remains in that state and communication continues, but data from this session does not transfer. This Scope generally is not necessary, as the Normal Scope only stops the interface if there are no other running sessions. This operation sends the command to stop the session, but does not wait for the session to be stopped. It is ideal for a real-time application where performance is critical. |
| Interface Only (2) | The underlying interface is placed in the Stopped state (refer to State Models). This prevents all communication on the bus, for all sessions. This allows you modify certain properties that require the interface to be stopped (for example, CAN baud rate). All sessions remain in the Started state. To have multiple sessions stop at exactly the same time, first stop the interface with the Interface Only Scope and then stop each session with either the Normal or Session Only Scope. |
| Session Only Blocking (3) | The session is placed in the Stopped state (refer to State Models). If the interface was in the Started or Running state before this function is called, the interface remains in that state and communication continues, but data from this session does not transfer. This Scope generally is not necessary, as the Normal Scope stops the interface only if there are no other running sessions. This operation waits for the session to stop before completing. |
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
Because the session is stopped automatically when cleared (closed), this function is optional.
For each physical interface, the NI-XNET hardware is divided into two logical units:
- Sessions: You can create one or more sessions, each of which contains frames or signals to be transmitted (or received) on the bus.
- Interface: The interface physically connects to the bus and transmits (or receives) data for the sessions.
You can stop each logical unit separately. When a session is stopped, all contained frames or signals are placed in a state where they are no longer ready to communicate. When the interface is stopped, it no longer takes data from sessions to communicate with other nodes on the bus. For a specification of the state models for the session and interface, refer to State Models.
Closes a system session.
nxStatus_t _NXFUNC nxSystemClose ( nxSessionRef_t SystemRef);
nxSessionRef_t SystemRef: The reference to the system session to close.
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
This function is used to close a system session.
Opens a special system session.
nxStatus_t _NXFUNC nxSystemOpen ( nxSessionRef_t * SystemRef);
nxSessionRef_t * SystemRef: The reference to the opened system session.
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
This function opens a special system session.
The system session is not used to read/write on the network (as with sessions created using nxCreateSession). Use the system session to interact with the NI driver and interface hardware.
For example, you can traverse through properties to find all NI-XNET interfaces in your system.
The following functions are supported for the system session:
- nxGetProperty: Get a property with prefix nxPropSys_, nxPropDev_, or nxPropIntf_.
- nxGetPropertySize: Get a string property size.
- nxBlink: Blink LED(s) on the interface.
Waits for a certain condition to occur.
nxStatus_t _NXFUNC nxWait ( nxSessionRef_t SessionRef, u32 Condition, u32 ParamIn, f64 Timeout, u32 * ParamOut);
nxSessionRef_t SessionRef: The session to which the wait is applied.
u32 Condition: Specifies the condition to wait for.
u32 ParamIn: An optional parameter that provides simple data to qualify the condition.
f64 Timeout: Specifies the maximum amount of time in seconds to wait.
u32 * ParamOut: An optional parameter that provides simple data to qualify the condition that occurred.
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
This function waits for a condition to occur for the session.
The Condition parameter specifies to wait for one of the following conditions.
All frames written for the session have been transmitted on the bus. This condition applies to CAN, FlexRay, LIN, and Ethernet. This condition is state based, and the state is Boolean (true/false). The ParamIn and ParamOut parameters are ignored for this condition because nxWait simply waits for the state to become true.
Wait for the interface to begin communication on the network. If a start trigger is configured for the interface, this first waits for the trigger. Once the interface is started, this waits for the protocol's communication state to transition to a value that indicates communication with remote nodes.
After this wait succeeds, calls to nxReadState will return:
- nxState_CANComm: nxCANCommState_ErrorActive
- nxState_CANComm: nxCANCommState_ErrorPassive
- nxState_TimeCommunicating: Valid time for communication (invalid time of 0 prior)
This condition is state based. The ParamIn and ParamOut parameters are ignored for this condition because nxWait simply waits for a communicating state.
Wait for the interface to wakeup due to activity by a remote node on the network. This wait is used for CAN, when you set the nxPropSession_IntfCANTrState property to nxCANTrState_Sleep. Although the interface itself is ready to communicate, this places the transceiver into a sleep state. When a remote CAN node transmits a frame, the transceiver wakes up, and communication is restored. This wait detects that remote wakeup.
This wait is used for LIN when you set the nxPropSession_IntfLINSleep property to nxLINSleep_RemoteSleep or nxLINSleep_LocalSleep. When asleep, if a remote LIN ECU transmits the wakeup pattern (break), the XNET LIN interface detects this transmission and wakes up. This wait detects that remote wakeup.
This condition is state based. The ParamIn and ParamOut parameters are ignored for this condition, because nxWait simply waits for the remote wakeup to occur.
Waits for the clock of the Ethernet interface to successfully synchronize to other clocks in the network. This wait returns when the time synchronization protocol's Synced property becomes true.
Note Time synchronization occurs independently from start of the interface. For example, you can read and write Ethernet frames when time synchronization protocol is not enabled, or when the time sync protocol is not synced.
Writes data to a session as an array of raw bytes.
nxStatus_t nxWriteFrame ( nxSessionRef_t SessionRef, void * Buffer, u32 NumberOfBytesForFrames, f64 Timeout);
nxSessionRef_t SessionRef: The session to write. This session is returned from nxCreateSession. The session mode must be Frame Output Stream Mode, Frame Output Queued Mode, or Frame Output Single-Point Mode.
void * Buffer: Provides the array of bytes, representing frames to transmit.
The raw bytes encode one or more frames using the Raw Frame Format. This frame format is the same for read and write of raw data and also is used for log file examples.
If needed, you can write data for a partial frame. For example, if a complete raw frame is 24 bytes, you can write 12 bytes, then write the next 12 bytes. You typically do this when you are reading raw frame data from a logfile and want to avoid iterating through the data to detect the start and end of each frame.
Note For PDU sessions, the array of bytes represents the payload of the specified PDU only, not that of the entire frame. For information about which elements of the raw frame are applicable, refer to Raw Frame Format.
The data you write is queued up for transmit on the network. Using the default queue configuration for this mode, you can safely write 1536 frames if you have a sufficiently long timeout. To write more data, refer to the XNET Session Number of Values Unused property to determine the actual amount of queue space available for writing.
For an example of how this data applies to network traffic, refer to Frame Output Stream Mode, Frame Output Queued Mode, or Frame Output Single-Point Mode.
Additionally, you can use nxWriteFrame on any signal or frame input session if it contains CAN Event Remote frames (refer to CAN:TimingType). In this case, it signals an event to transmit those remote frames. The Buffer parameter is ignored, and you can set it to NULL in that case.
u32 NumberOfBytesForFrames: The size (in bytes) of the buffer passed to Buffer. This is used to calculate the number of frames to transmit.
f64 Timeout: The time to wait for the raw data to be queued up for transmit.
The timeout is represented as 64-bit floating-point in units of seconds.
If Timeout is positive, nxWriteFrame waits up to that timeout for space to become available in queues. If the space is not available prior to the timeout, a timeout error is returned.
If Timeout is negative, nxWriteFrame waits indefinitely for space to become available in queues.
If Timeout is 0, nxWriteFrame does not wait and immediately returns with a timeout error if all data cannot be queued. Regardless of the timeout used, if a timeout error occurs, none of the data is queued, so you can attempt to call nxWriteFrame again at a later time with the same data.
If the session mode is Frame Output Single-Point, you must set Timeout to 0.0. Because this mode writes the most recent value of each frame, Timeout does not apply.
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
The raw bytes encode one or more frames using the Raw Frame Format. The session must use a mode of Frame Output Stream, Frame Output Queued, or Frame Output Single-Point. The raw frame format is protocol independent.
The raw frames are associated to the session's list of frames as follows:
- Frame Output Stream Mode: Array of all frame values for transmit (list ignored). For LIN, if the payload length is 0, only the header part of the LIN frame is transmitted. If the payload length is nonzero, the header and response parts of the LIN frame are transmitted.
- Frame Output Queued Mode: Array of frame values to transmit for the single frame specified in the list.
- Frame Output Single-Point Mode: Array of single frame values, one for each frame specified in the list.
- Any signal or frame input mode: The Buffer parameter is ignored, and you can set it to NULL. The function transmits an event remote frame.
Writes data to a session of Signal Output Single-Point Mode.
nxStatus_t nxWriteSignalSinglePoint ( nxSessionRef_t SessionRef, f64 * ValueBuffer, u32 SizeOfValueBuffer);
nxSessionRef_t SessionRef: The session to write. This session is returned from nxCreateSession. The session mode must be Signal Output Single-Point.
f64 * ValueBuffer: Provides a one-dimensional array of signal values. Each signal value is scaled, 64-bit floating point.
Each array element corresponds to a signal configured for the session. The order of signals in the array corresponds to the order in the session list.
The data provides the value for the next transmit of each signal. If nxWriteSignalSinglePoint is called twice before the next transmit, the transmitted frame uses signal values from the second call to nxWriteSignalSinglePoint.
For an example of how this data applies to network traffic, refer to Signal Output Single-Point Mode.
A trigger signal written a value of 0.0 suppresses writing of its frame's data; writing a value not equal to 0.0 enables it. For more information about trigger signals, refer to Signal Output Single-Point Mode.
u32 SizeOfValueBuffer: Should be set to the size (in bytes) of the array passed to ValueBuffer. If this is too small to fit one element for each signal in the session, an error is returned.
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
Writes data to a session of Signal Output Waveform Mode. The data represents a waveform of resampled values for each signal in the session.
nxStatus_t nxWriteSignalWaveform ( nxSessionRef_t SessionRef, f64 Timeout, f64 * ValueBuffer, u32 SizeOfValueBuffer);
nxSessionRef_t SessionRef: The session to write. This session is returned from nxCreateSession. The session mode must be Signal Output Waveform.
f64 Timeout: The time to wait for the data to be queued for transmit. The timeout does not wait for frames to be transmitted on the network (refer to nxWait).
The timeout is represented as 64-bit floating-point in units of seconds.
If Timeout is positive, nxWriteSignalWaveform waits up to that timeout for space to become available in queues. If the space is not available prior to the timeout, a timeout error is returned.
If Timeout is negative, nxWriteSignalWaveform waits indefinitely for space to become available in queues.
If Timeout is 0, nxWriteSignalWaveform does not wait and immediately returns an error if all data cannot be queued. Regardless of the timeout used, if a timeout error occurs, none of the data is queued, so you can attempt to call nxWriteSignalWaveform again at a later time with the same data.
f64* ValueBuffer: Provides a two-dimensional array of f64 samples. First, N samples are reserved for the first signal in the session, then N samples for the second, and so on. N * (number of signals in the session) * sizeof (f64) should be passed in SizeOfValueBuffer to recalculate N.
The data you write is queued for transmit on the network. Using the default queue configuration for this mode, and assuming a 1000 Hz resample rate, you can safely write 64 elements if you have a sufficiently long timeout. To write more data, refer to the XNET Session Number of Values Unused property to determine the actual amount of queue space available for writing.
For an example of how this data applies to network traffic, refer to Signal Output Waveform Mode.
Each array element corresponds to a signal configured for the session. The order of signals in the array corresponds to the order in the session list.
u32 SizeOfValueBuffer: Should be set to the size (in bytes) of the array passed to ValueBuffer. The number of samples to be written (N) per signal is calculated from this size. Set this to (N) * (number of signals in the session) * sizeof (f64).
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
The data represents a waveform for each signal in the session.
Writes data to a session of Signal Output XY Mode. The data represents a sequence of signal values for transmit using each frame's timing as the database specifies.
nxStatus_t nxWriteSignalXY (nxSessionRef_t SessionRef, f64 Timeout, f64 * ValueBuffer, u32 SizeOfValueBuffer, nxTimestamp100ns_t * TimestampBuffer, u32 SizeOfTimestampBuffer, u32 * NumPairsBuffer, u32 SizeOfNumPairsBuffer);
nxSessionRef_t SessionRef: The session to write. This session is returned from nxCreateSession. The session mode must be Signal Output XY.
f64 Timeout: The time to wait for the data to be queued for transmit. The timeout does not wait for frames to be transmitted on the network (refer to nxWait).
The timeout is represented as 64-bit floating-point in units of seconds.
If Timeout is positive, nxWriteSignalXY waits up to that timeout for space to become available in queues. If the space is not available prior to the timeout, a timeout error is returned.
If Timeout is negative, nxWriteSignalXY waits indefinitely for space to become available in queues.
If Timeout is 0, nxWriteSignalXY does not wait and immediately returns with a timeout error if all data cannot be queued. Regardless of the timeout used, if a timeout error occurs, none of the data is queued, so you can attempt to call nxWriteSignalXY again at a later time with the same data.
f64* ValueBuffer: Provides a two-dimensional array of f64 samples. First, N samples are reserved for the first signal in the session, then N samples for the second, and so on. N * (number of signals in the session) * sizeof (f64) should be passed in SizeOfValueBuffer to recalculate N.
The data you write is queued for transmit on the network. Using the default queue configuration for this mode, you can safely write 64 elements if you have a sufficiently long timeout. To write more data, refer to the XNET Session Number of Values Unused property to determine the actual amount of queue space available for writing.
For an example of how this data applies to network traffic, refer to Signal Output XY Mode.
u32 SizeOfValueBuffer: The size (in bytes) of the array passed to ValueBuffer.
nxTimestamp100ns_t* TimestampBuffer: Provides a two-dimensional array of timestamps. First, N timestamps are reserved for the first signal in the session, then N timestamps for the second and so on. N * (number of signals in the session) * sizeof (f64) should be passed in SizeOfTimestampBuffer to recalculate N.
nxTimestamp100ns_t is an absolute timestamp in 100 nanosecond increments. This 64-bit type contains the number of 100 ns intervals that have elapsed since 1 January 1601 00:00:00 Coordinated Universal Time (UTC). In previous releases, this timestamp was called nxTimestamp_t.
This array is for future expansion; it is not used in the current implementation of NI-XNET. Pass NULL on input.
u32 SizeOfTimestampBuffer: The size (in bytes) of the array passed to TimestampBuffer.
This value is for future expansion; it is not used in the current implementation of NI-XNET. Pass 0 on input.
u32* NumPairsBuffer: Provides an one-dimensional array of signal/timestamp pair counts, one for each signal in the session. Upon input, the samples and timestamps for signal #(i) in the preceding arrays are valid up to, but not including, index NumPairsBuffer[i] (zero based) and are written up to that point.
u32 SizeOfNumPairsBuffer: The size (in bytes) of the array passed to NumPairsBuffer. For each signal in the session, an array element should be provided. If the buffer is too small, an error is returned.
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
The data represents an XY plot of timestamp/value pairs for each signal in the session.
Writes communication states of an XNET session.
nxStatus_t nxWriteState ( nxSessionRef_t SessionRef, u32 StateID, u32 StateSize, void * StateValue);
nxSessionRef_t SessionRef: The session to write. This session is returned from nxCreateSession.
u32 StateID: Indicates the state to be written. Possible values are:
nxState_LINScheduleChange: Changes the LIN schedule.
nxState_FlexRaySymbol: Transmits a FlexRay symbol.
nxState_LINDiagnosticScheduleChange: Changes the LIN diagnostic schedule.
nxState_EthernetSleep: Writes a request for the local Ethernet interface and its remote link partner to sleep.
nxState_EthernetWake: Writes a request for the local Ethernet interface and its remote link partner to wake up.
The value determines the format to be written to StateValue.
u32 StateSize: Indicates the size of the buffer provided for StateValue.
void * StateValue: Writes the desired state. Formats and values are:
StateID = nxState_LINScheduleChange: StateValue must point to a u32 buffer that contains the index to the schedule table that the LIN master executes. The schedule tables are sorted the way they are returned from the database with the XNET Cluster Schedules property.
According to the LIN protocol, only the master executes schedules, not slaves. If the XNET Session Interface:LIN:Master? property is false (slave), this write function implicitly sets that property to true (master). If the interface currently is running as a slave, this write returns an error, because it cannot change to master while running.
StateID = nxState_FlexRaySymbol
StateValue must point to a u32 buffer that contains the value 0.
StateID = nxState_LINDiagnosticScheduleChange
|
StateValue must point to a u32 buffer that contains the diagnostic schedule that the LIN master executes. Possible values are: - nxLINDiagnosticSchedule_NULL: The master does not execute any diagnostic schedule. No master request or slave response headers are transmitted on the LIN. - nxLINDiagnosticSchedule_MasterReq: The master executes a diagnostic master request schedule (transmits a master request header onto the LIN) if it can. First, a master request schedule must be defined for the LIN cluster in the imported or in-memory database. Otherwise, error nxErrDiagnosticScheduleNotDefined is returned when attempting to set this value. Second, the master must have a frame output queued session created for the master request frame, and there must be one or more new master request frames pending in the queue. If no new frames are pending in the output queue, no master request header is transmitted. This allows the timing of master request header transmission to be controlled by the timing of master request frame writes to the output queue. - nxLINDiagnosticSchedule_SlaveResp: The master executes a diagnostic slave response schedule (transmits a slave response header onto the LIN) if it is able to. A slave response schedule must be defined for the LIN cluster in the imported or in-memory database. Otherwise, error nxErrDiagnosticScheduleNotDefined is returned when attempting to set this value. |
|---|
| StateID = nxState_EthernetSleep or nxState_EthernetWake |
StateValue must point to a u32 buffer that contains the value 0.
nxStatus_t
The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.
Use nxWriteState with an XNET LIN master session to set the schedule that the LIN master executes.
Use nxWriteState with an XNET FlexRay session to transmit a symbol on the FlexRay bus.
Use nxWriteState with an XNET LIN master session to set the diagnostic schedule that the LIN master executes. Use this state to transmit master request messages and query for slave response messages after node configuration has been performed. Node configuration should be handled using nxState_LINScheduleChange. Write the node configuration schedule defined for the LIN cluster using nxState_LINScheduleChange, so that it is the first schedule executed for the LIN, with a run mode of once. The data for each node configuration service request entry in the node configuration schedule is automatically transmitted by the master. After the node configuration schedule has completed, use nxState_LINDiagnosticScheduleChange to run diagnostic schedules, or nxState_LINScheduleChange to run normal schedules.
Use nxWriteState with an XNET Ethernet session to send sleep or wakeup commands. The sleep/wake capability is based on the OPEN Alliance TC10 Sleep/Wake 2.0 specification, and it is only supported on the PXIe-8523. The port must be configured for a link speed of 100 Mbps and a port mode of Direct to use the sleep/wake capability.
Executing this function on any other type of session causes an error.
Creating and Setting Up a gRPC Server
Session Utilities API Reference
gRPC API Differences From C API
Sharing Driver Sessions Between Clients
C API Docs
NI-DAQmx
- gRPC API Differences From C API
- Task Configuration And Control
- Channel Configuration And Creation
- Timing
- Triggering
- Read Functions
- Write Functions
- Export Hardware Signals
- Scale Configuration
- Internal Buffer Configuration
- Advanced Functions
- System Configuration
- Error Handling
- Buffer Attributes
- Calibration Info Attributes
- Channel Attributes
- Device Attributes
- Export Signal Attributes
- Persisted Channel Attributes
- Persisted Scale Attributes
- Persisted Task Attributes
- Physical Channel Attributes
- Read Attributes
- Scale Attributes
- System Attributes
- Task Attributes
- Timing Attributes
- Trigger Attributes
- Watchdog Attributes
- Write Attributes
NI-DCPOWER
- Setup Functions
- Configure Functions
- Measurement Functions
- Control Functions
- Trigger And Event
- Attribute Functions
- Query Functions
- Calibration Functions
- Utility Functions
- Supported Device
- Source Attributes
- Transient Attributes
- Voltage Attributes
- Current Attributes
- Pulse Voltage Attributes
- Pulse Current Attributes
- Cutoff Attributes
- Measurement Attributes
- Trigger Attributes Functions
- Event Attributes
- Advanced Attributes
- Inherent Ivi Attributes
- Supported Device Attributes
NI-DIGITAL PATTERN DRIVER
- Init And Close Functions
- Session Locking Functions
- Utility Functions
- Error Handling Functions
- Calibration Functions
- Attributes Functions
- Pin Map Functions
- Low Level Functions
- Low Level Action Functions
- Pin Control Functions
- Static IO Functions
- Clock Generator Functions
- Levels And Timing Functions
- TDR Functions
- PPMU Configuration Functions
- DC Voltage Functions
- DC Current Functions
- PPMU Action Functions
- Pattern Configuration Functions
- Pattern Action Functions
- History Ram Functions
- Source Memory Functions
- Capture Memory Functions
- Triggers And Events Functions
- Conditional Jump Trigger Functions
- Sequencer Flag Functions
- Sequencer Register Functions
- Match Fail Combination Functions
- Pattern Results Functions
- Sort Results Functions
- Frequency Measurement Functions
- IVI Inherent Attributes
- Specific Driver Information Attributes, Read Only
- Driver Setup Information Attributes
- Device Attributes
- Pin Control Attributes
- Level Configuration Attributes
- Trigger Configuration Attributes
- PPMU Attributes
- Patterns Attributes
- Pattern Opcode Event Attributes
- Timing Offset Attributes
- Keep Alive Attributes
- Frequency Measurement Attributes
- Clock Generator Attributes
- History RAM
- Synchronization Attributes
- TDR Endpoint Termination Attributes
NI-FGEN
- Setup Functions
- Configuration Functions
- Standard Output Functions
- Arbitrary Waveform Output Functions
- Arbitrary Sequence Output Functions
- Incremental Waveform Write Functions
- Configure Clock Functions
- Trigger And Syncronizations Functions
- 5404 Routing Functions
- Script Output Functions
- Configure Onboard Signal Processing Functions
- Configure Peer To Peer Functions
- Attribute Functions
- Waveform Control Functions
- Error Functions
- Output Attributes
- Arbitrary Waveform Attributes
- Data Transfer Attributes
- Onboard Signal Processing Attributes
- Peer To Peer Attributes
- Standard Function Attributes
- Clock Attributes
- Event Attributes
- Triggering Attributes
- Instrument Specific Attributes
- Inherent IVI Attributes
- 5401 5411 5431
NI-RFmx Bluetooth
- gRPC API Differences From C API
- General Functions
- Configuration Functions
- Set And Get Attribute Functions
- Fetch Results Functions
- Utility Functions
- Build String Functions
- Advanced Functions
- General Attributes
- Trigger Attributes
- Packet Attributes
- Auto Detect Signal Attributes
- Modacc Attributes
- ACP Attributes
- Twenty dB Attributes
- Frequency Range Attributes
- TXP Attributes
- Advanced Attributes
NI-RFmx NR
- gRPC API Differences From C API
- General Functions
- Configuration Functions
- Set And Get Attributes Functions
- Fetch Results Functions
- Utility Functions
- Build String Functions
- Advanced Functions
- General Attributes
- Trigger Attributes
- Signal Detection Attributes
- Component Carrier Attributes
- List Attributes
- Modacc Attributes
- ACP Attributes
- CHP Attributes
- OBW Attributes
- SEM Attributes
- TXP Attributes
- Pvt Attributes
- Advanced Attributes
NI-RFmx LTE
- gRPC API Differences From C API
- General Functions
- Configuration Functions
- Ch Configuration Functions
- NB IoT Configuration Functions
- ModAcc Configuration Functions
- ACP Configuration Functions
- CHP Configuration Functions
- OBW Configuration Functions
- SEM Configuration Functions
- PVT Configuration Functions
- SlotPhase Configuration Functions
- SlotPower Configuration Functions
- Set And Get Attribute Functions
- ModAcc Fetch Functions
- ACP Fetch Functions
- CHP Fetch Functions
- OBW Fetch Functions
- SEM Fetch Functions
- PVT Fetch Functions
- SlotPhase Fetch Functions
- SlotPower Fetch Functions
- Utility Functions
- Build String Functions
- Advanced Functions
- General Attributes
- Trigger Attributes
- Component Carrier Attributes
- ModAcc Attributes
- ACP Attributes
- CHP Attributes
- OBW Attributes
- SEM Attributes
- PVT Attributes
- SlotPhase Attributes
- SlotPower Attributes
- Advanced Attributes
NI-RFmx SpecAn
- gRPC API Differences From C API
- General Functions
- Configuration Functions
- Set And Get Attribute Functions
- Read Functions
- Fetch Functions
- Utility Functions
- Marker Functions
- Build String Functions
- Advanced Functions
- General Attributes
- Trigger Attributes
- ACP Attributes
- Cdf Attributes
- CHP Attributes
- Fcnt Attributes
- Harm Attributes
- OBW Attributes
- SEM Attributes
- Spectrum Attributes
- Spur Attributes
- TXP Attributes
- AMPM Attributes
- Dpd Attributes
- IQ Attributes
- IM Attributes
- NF Attributes
- Phasenoise Attributes
- PAVT Attributes
- Advanced Attributes
NI-RFmx WLAN
- gRPC API Differences From C API
- General Functions
- Configuration Functions
- Set And Get Attribute Functions
- Fetch DSSS ModAcc Functions
- Fetch OFDM ModAcc Functions
- Fetch SEM Functions
- Fetch TXP Functions
- Fetch PowerRamp Functions
- Utility Functions
- Build String Functions
- Advanced Functions
- General Attributes
- Trigger Attributes
- OFDM Attributes
- Auto Detect Signal Attributes
- DSSS ModAcc Attributes
- OFDM ModAcc Attributes
- SEM Attributes
- TXP Attributes
- PowerRamp Attributes
- Advanced Attributes
NI-RFSA
- General Functions
- Configuration Functions
- Acquisition Functions
- Utility Functions
- Calibration Functions
- General Attributes
- Vertical Attributes
- Signal Path Attributes
- Acquisition Attributes
- Acquisition Attributes
- Triggers Attributes
- Events Attributes
- Device Characteristics Attributes
- Peer To Peer Streaming Attributes
- Configuration List Attributes
- Inherent IVI Properties Attributes
- De-embedding Attributes
- Self Calibration Attributes
- Factory Calibration Attributes
- External Alignment Attributes
- Device Specific Attributes
NI-RFSG
- General Functions
- Generation Configuration
- Utility Functions
- Calibration Functions
- Arb Attributes
- Clock Attributes
- Configuration List Attributes
- De-embedding Attributes
- Device Characteristics Attributes
- Device Specific Attributes
- Events Attributes
- External Calibration Attributes
- Inherent IVI Attributes Attributes
- IQ Impairment Attributes
- Load Configurations Attributes
- Modulation Attributes
- Obsolete Attributes
- Peer To Peer Attributes
- RF Attributes
- Self Calibration Attributes
- Triggers Attributes
NI-SCOPE
- Setup Functions
- Configure Functions
- Attribute Functions
- Acquisition Functions
- Measurement Functions
- Calibrate Functions
- Utility Funcitons
- Error Handling Functions
- IVI Compliance Or Obsolete Functions
- Vertical Attributes
- Horizontal Attributes
- Trigger Attributes
- Clocking Attributes
- Synchronization Attributes
- Acquisition Attributes
- Waveform Measurements Attributes
- Onboard Signal Processing Attributes
- Peer To Peer Streaming Attributes
- Device Attributes
- IVI Or Obsolete Attributes
- Instrument Capabilities Attributes
- If Digitizer Attributes
NI-XNET
- gRPC API differences from C APIs
- General Functions
- Cluster Properties
- Database Properties
- Device Properties
- ECU Properties
- Frame Properties
- Interface Properties
- LIN Schedule Entry Properties
- LIN Schedule Properties
- PDU Properties
- Session Ethernet Properties
- Session Frame Properties
- Session Interface Properties
- Session Properties
- Session SAE J1939 Properties
- Signal Properties
- Subframe Properties
- System Properties
- IP-Stack Functions
- Socket Options
- Socket Functions