NI XNET XNET Session Properties

XNET Session Properties

• Application Protocol
• Auto Start?
• ClusterName
• DatabaseName
• List
• Mode
• Number in List
• Number of Values Pending
• Number of Values Unused
• Payload Length Maximum
• Protocol
• Queue Size
• Resample Rate

Application Protocol

Data Type	Direction	Required?	Default
u32	Read/Write	No	Read from Database

Property Class

XNET Frame

Property ID

nxPropFrm_ApplicationProtocol

Description

This property specifies the frame's application protocol. It is an enumerated list of two values:

Enumeration	Value	Description
None	0	The default application protocol.
J1939	1	Indicates J1939 frames. The value enables the following features: - Sending/receiving long frames as the SAE J1939 specification specifies, using the J1939 transport protocol. - Using a special notation for J1939 identifiers.

Auto Start?

Data Type	Direction	Required?	Default
bool	Read/Write	No	True

Property Class

XNET Session

Property ID

nxPropSession_AutoStart

Description

Automatically starts the output session on the first call to the appropriate nxWrite function.

For output sessions, as long as the first call to the appropriate nxWrite function contains valid data, you can leave this property at its default value of true. If you need to call the appropriate nxWrite function multiple times prior to starting the session, or if you are starting multiple sessions simultaneously, you can set this property to false. After calling the appropriate nxWrite function as desired, you can call nxStart to start the session(s).

When automatic start is performed, it is equivalent to nxStart with scope set to Normal. This starts the session itself, and if the interface is not already started, it starts the interface also.

For input sessions, Auto Start? is implicitly set to True and cannot be set to False. Start always is performed within the first call to the appropriate nxRead function (if not already started using nxStart).

For Signal Input Waveform sessions, when calling nxReadSignalWaveform for the first time on the session, the session will be started if it was not already. Stopping the session after the first start requires the session to be explicitly started in the future. This permits reading of the pending signal values without an implicit state transition, which would result in more signal values. This behavior is shared with frame input stream sessions when used with Ethernet interfaces. Other input session types, when used with CAN, FlexRay, or LIN interfaces, will implicitly start upon any call to nxRead, not just the first; this behavior could be altered in a future release to match Signal Input Waveforms.

Payload Length Maximum

Data Type	Direction	Required?	Default
u32	Read Only	N/A	N/A

Property Class

XNET Session

Property ID

nxPropSession_PayldLenMax

Description

This property returns the maximum payload length of all frames in this session, expressed as bytes.

This property does not apply to Signal sessions (only Frame sessions).

For CAN Stream (Input and Output), this property depends on the XNET Cluster CAN:I/O Mode property. If the I/O mode is CAN, this property is 8 bytes. If the I/O mode is CAN FD or CAN FD+BRS, this property is 64 bytes.

For LIN Stream (Input and Output), this property always is 8 bytes. For FlexRay Stream (Input and Output), this property is the same as the XNET Cluster FlexRay:Payload Length Maximum property value. For Queued and Single-Point (Input and Output), this is the maximum payload of all frames specified in the List property.

For Ethernet Stream (Input and Output), this property is the maximum length of the frame data in each frame, which includes the Ethernet header in addition to the Ethernet payload (MSDU).

Protocol

Data Type	Direction	Required?	Default
u32	Read Only	N/A	N/A

Property Class

XNET Session

Property ID

nxPropSession_Protocol

Description

This property returns the protocol that the interface in the session uses.

The values (enumeration) for this property are:

0	CAN
1	FlexRay
2	LIN
3	Ethernet

Mode

Data Type	Direction	Required?	Default
u32	Read Only	N/A	N/A

Property Class

XNET Session

Property ID

nxPropSession_Mode

Description

This property returns the session mode. You provided this mode when you created the session. For more information, refer to Session Modes.

Number in List

Data Type	Direction	Required?	Default
u32	Read Only	N/A	N/A

Property Class

XNET Session

Property ID

nxPropSession_NumInList

Description

This property returns the number of frames or signals in the session's list. This is a quick way to get the size of the List property.

Number of Values Pending

Data Type	Direction	Required?	Default
u32	Read Only	N/A	N/A

Property Class

XNET Session

Property ID

nxPropSession_NumPend

Description

This property returns the number of values (frames or signals) pending for the session.

For input sessions, this is the number of frame/signal values available to the appropriate nxRead function. If you call the appropriate nxRead function with number to read of this number and timeout of 0.0, the appropriate nxRead function should return this number of values successfully.

For output sessions, this is the number of frames/signal values provided to the appropriate nxWrite function but not yet transmitted onto the network.

Stream frame sessions using FlexRay or CAN FD protocol may use a variable size of frames. In these cases, this property assumes the largest possible frame size. If you use smaller frames, the real number of pending values might be higher.

The largest possible frames sizes are:

• CAN FD: 64 byte payload.
• FlexRay: The higher value of the frame size in the static segment and the maximum frame size in the dynamic segment. The XNET Cluster FlexRay:Payload Length Maximum property provides this value.

Number of Values Unused

Data Type	Direction	Required?	Default
u32	Read Only	N/A	N/A

Property Class

XNET Session

Property ID

nxPropSession_NumUnused

Description

This property returns the number of values (frames or signals) unused for the session. If you get this property prior to starting the session, it provides the size of the underlying queue(s). Contrary to the Queue Size property, this value is in number of frames for Frame I/O, not number of bytes; for Signal I/O, it is the number of signal values in both cases. After start, this property returns the queue size minus the Number of Values Pending property.

For input sessions, this is the number of frame/signal values unused in the underlying queue(s).

For output sessions, this is the number of frame/signal values you can provide to a subsequent call to the appropriate nxWrite function. If you call the appropriate nxWrite function with this number of values and timeout of 0.0, it should return success.

Stream frame sessions using the FlexRay, CAN FD, or Ethernet protocol may use frames that vary in size. In these cases, this property assumes the largest possible frame size. If you use smaller frames, the real number of pending values might be higher.

The largest possible frames sizes are:

• CAN FD: 64 byte payload.
• FlexRay: The higher value of the frame size in the static segment and the maximum frame size in the dynamic segment. The XNET Cluster FlexRay:Payload Length Maximum property provides this value.
• Ethernet: The PayldLenMax property provides this value.

Resample Rate

Data Type	Direction	Required?	Default
f64	Read/Write	No	1000.0 (Sample Every Millisecond)

Property Class

XNET Session

Property ID

nxPropSession_ResampRate

Description

Rate used to resample frame data to/from signal data in waveforms.

This property applies only when the session mode is Signal Input Waveform or Signal Output Waveform. This property is ignored for all other modes.

The data type is 64-bit floating point (DBL). The units are in Hertz (samples per second).

Queue Size

Data Type	Direction	Required?	Default
u32	Read/Write	No	Refer to Description

Property Class

XNET Session

Property ID

nxPropSession_QueueSize

Description

For output sessions, queues store data passed to the appropriate nxWrite function and not yet transmitted onto the network. For input sessions, queues store data received from the network and not yet obtained using the appropriate nxRead function.

For most applications, the default queue sizes are sufficient. You can write to this property to override the default. When you write (set) this property, you must do so prior to the first session start. You cannot set this property again after calling nxStop.

For signal I/O sessions, this property is the number of signal values stored. This is analogous to the number of values you use with the appropriate nxRead or nxWrite function.

For frame I/O sessions, this property is the number of bytes of frame data stored.

For standard CAN or LIN frame I/O sessions, each frame uses exactly 24 bytes. You can use this number to convert the Queue Size (in bytes) to/from the number of frame values.

For CAN FD and FlexRay frame I/O sessions, each frame value size can vary depending on the payload length. For more information, refer to Raw Frame Format.

For Signal I/O XY sessions, you can use signals from more than one frame. Within the implementation, each frame uses a dedicated queue. According to the formulas below, the default queue sizes can be different for each frame. If you read the default Queue Size property for a Signal Input XY session, the largest queue size is returned, so that a call to the appropriate nxRead function of that size can empty all queues. If you read the default Queue Size property for a Signal Output XY session, the smallest queue size is returned, so that a call to the appropriate nxWrite function of that size can succeed when all queues are empty. If you write the Queue Size property for a Signal I/O XY session, that size is used for all frames, so you must ensure that it is sufficient for the frame with the fastest transmit time.

For Signal I/O Waveform sessions, you can use signals from more than one frame. Within the implementation, each frame uses a dedicated queue. The Queue Size property does not represent the memory in these queues, but rather the amount of time stored. The default queue allocations store Application Time worth of resampled signal values. If you read the default Queue Size property for a Signal I/O Waveform session, it returns Application Time multiplied by the time Resample Rate. If you write the Queue Size property for a Signal I/O Waveform session, that value is translated from a number of samples to a time, and that time is used to allocate memory for each queue.

For Single-Point sessions (signal or frame), this property is ignored. Single-Point sessions always use a value of 1 as the effective queue size.

Default Value

You calculate the default queue size based on the following assumptions:

• Application Time: The time between calls to the appropriate nxRead/nxWrite function in your application.
• Frame Time: The time between frames on the network for this session.

The following pseudo code describes the default queue size formula:

if (session is Signal I/O Waveform)

Queue_Size = (Application_Time * Resample_Rate);

else

Queue_Size = (Application_Time / Frame_Time);

if (Queue_Size < 64)

Queue_Size = 64;

if (session mode is Frame I/O)

Queue_Size = Queue_Size * Frame_Size;

For Signal I/O Waveform sessions, the initial formula calculates the number of resampled values that occur within the Application Time. This is done by multiplying Application Time by the XNET Session Resample Rate property.

For all other session modes, the initial formula divides Application Time by Frame Time.

The minimum for this formula is 64. This minimum ensures that you can read or write at least 64 elements. If you need to read or write more elements for a slow frame, you can set the Queue Size property to a larger number than the default. If you set a large Queue Size, this may limit the maximum number of frames you can use in all sessions.

For Frame I/O sessions, this formula result is multiplied by each frame value size to obtain a queue size in bytes.

For Signal I/O sessions, this formula result is used directly for the queue size property to provide the number of signal values for the appropriate nxRead or nxWrite function. Within the Signal I/O session, the memory allocated for the queue incorporates frame sizes, because the signal values are mapped to/from frame values internally.

Application Time

The target in which your application runs determines the Application Time:

• Windows: 400 ms (0.4 s)
• Real-Time (RT): 100 ms (0.1 s)

This works under the assumption that for Windows, more memory is available for input queues, and you have limited control over the application timing. RT targets typically have less available memory, but your application has better control over application timing.

Frame Time

Frame Time is calculated differently for Frame I/O Stream sessions compared to other modes. For Frame I/O Stream, you access all frames in the network (cluster), so the Frame Time is related to the average bus load on your network. For other modes, you access specific frames only, so the Frame Time is obtained from database properties for those frames.

The Frame Time used for the default varies by session mode and protocol, as described below.

CAN, Frame I/O Stream

Frame Time is 100 µs (0.0001 s).

This time assumes a baud rate of 1 Mbps, with frames back to back (100 percent busload).

For CAN sessions created for a standard CAN bus, the Frame Size is 24 bytes. For CAN sessions created for a CAN FD Bus (the cluster I/O mode is CAN FD or CAN FD+BRS), the frame size can vary up to 64 bytes. However, the default queue size is based on the 24-byte frame time. When connecting to a CAN FD bus, you may need to adjust this size as necessary.

When you create an application to stress test NI-XNET performance, it is possible to generate CAN frames faster than 100 µs. For this application, you must set the queue size to larger than the default.

FlexRay, Frame I/O Stream

Frame Time is 20 µs (0.00002 s).

This time assumes a baud rate of 10 Mbps, with a cycle containing static slots only (no minislots or NIT), and frames on channel A only.

Small frames at a fast rate require a larger queue size than large frames at a slow rate. Therefore, this default assumes static slots with 4 bytes, for a Frame Size of 24 bytes.

When you create an application to stress test NI-XNET performance, it is possible to generate FlexRay frames faster than 20 µs. For this application, you must set the queue size to larger than the default.

LIN, Frame I/O Stream

Frame Time is 2 ms (0.002 s).

This time assumes a baud rate of 20 kbps, with 1 byte frames back to back (100 percent busload).

For all LIN sessions, Frame Size is 24 bytes.

CAN, Other Modes

For Frame I/O Queued, Signal I/O XY, and Signal I/O Waveform, the Frame Time is different for each frame in the session (or frame within which signals are contained).

For CAN frames, Frame Time is the frame property CAN Transmit Time, which specifies the time between successive frames (in floating-point seconds).

If the frame's CAN Transmit Time is 0, this implies the possibility of back-to-back frames on the network. Nevertheless, this back-to-back traffic typically occurs in bursts, and the average rate over a long period of time is relatively slow. To keep the default queue size to a reasonable value, when CAN Transmit Time is 0, the formula uses a Frame Time of 50 ms (0.05 s).

For CAN sessions using a standard CAN cluster, the frame size is 24 bytes. For CAN sessions using a CAN FD cluster, the frame size may differ for each frame in the session. Each frame size is obtained from its XNET Frame Payload Length property in the database.

FlexRay, Other Modes

For Frame I/O Queued, Signal I/O XY, and Signal I/O Waveform, the Frame Time is different for each frame in the session (or frame within which signals are contained).

For FlexRay frames, Frame Time is the time between successive frames (in floating-point seconds), calculated from cluster and frame properties. For example, if a cluster Cycle (cycle duration) is 10000 µs, and the frame Base Cycle is 0 and Cycle Repetition is 1, the frame's Transmit Time is 0.01 (10 ms).

For these session modes, the Frame Size is different for each frame in the session. Each Frame Size is obtained from its XNET Frame Payload Length property in the database.

LIN, Other Modes

For LIN frames, Frame Time is a property of the schedule running in the LIN master node. It is assumed that the Frame Time for a single frame always is larger than 8 ms, so that the default queue size is set to 64 frames throughout.

For all LIN sessions, Frame Size is 24 bytes.

Examples

The following table lists example session configurations and the resulting default queue sizes.

Session Configuration	Default Queue Size	Formula
Frame Input Stream, CAN, Windows	96000	(0.4 / 0.0001) = 4000; 4000 x 24 bytes
Frame Output Stream, CAN, Windows	96000	(0.4 / 0.0001) = 4000; 4000 x 24 bytes; output is always same as input
Frame Input Stream, FlexRay, Windows	480000	(0.4 / 0.00002) = 20000; 20000 x 24 bytes
Frame Input Stream, CAN, RT	24000	(0.1 / 0.0001) = 1000; 1000 x 24 bytes
Frame Input Stream, FlexRay, RT	120000	(0.1 / 0.00002) = 5000; 5000 x 24 bytes
Frame Input Queued, CAN, Transmit Time 0.0, Windows	1536*	(0.4 / 0.05) = 8; Transmit Time 0 uses Frame Time 50 ms; use minimum of 64 frames (64 x 24)
Frame Input Queued, CAN, Transmit Time 0.0005, Windows	19200*	(0.4 / 0.0005) = 800; 800 x 24 bytes
Frame Input Queued, CAN, Transmit Time 1.0 (1 s), Windows	1536*	(0.4 / 1.0) = 0.4; use minimum of 64 frames (64 x 24)
Frame Input Queued, FlexRay, every 2 ms cycle, payload length 4, Windows	4800	(0.4 / 0.002) = 200; 200 x 24 bytes
Frame Input Queued, FlexRay, every 2 ms cycle, payload length 16, RT	2048	(0.1 / 0.002) = 50, use minimum of 64; payload length 16 requires 32 bytes; 64 x 32 bytes
Signal Input XY, two CAN frames, Transmit Time 0.0 and 0.0005, Windows	64* and 800* (read as 800)	(0.4 / 0.05) = 8, use minimum of 64; (0.4 / 0.0005) = 800; expressed as signal values
Signal Output XY, two CAN frames, Transmit Time 0.0 and 0.0005, Windows	64* and 800* (read as 64)	(0.4 / 0.05) = 8, use minimum of 64; (0.4 / 0.0005) = 800; expressed as signal values
Signal Output Waveform, two CAN frames, 1 ms and 400 ms, resample rate 1000 Hz, Windows	400*	Memory allocation is 400 and 64 frames to provide 0.4 sec of storage, queue size represents number of samples, or (0.4 x 1000.0)
* For a CAN FD cluster, the default queue size is based on the frame's database payload length, which may be larger than 24 bytes (up to 64 bytes).

ClusterName

Data Type	Direction	Required?	Default
string	Read Only	N/A	N/A

Property Class

XNET Session

Property ID

nxPropSession_ClusterName

Description

This property returns the cluster (network) used with nxCreateSession.

DatabaseName

Data Type	Direction	Required?	Default
string	Read Only	N/A	N/A

Property Class

XNET Session

Property ID

nxPropSession_DatabaseName

Description

This property returns the database used with nxCreateSession.

List

Data Type	Direction	Required?	Default
1Dstring	Read Only	N/A	N/A

Property Class

XNET Session

Property ID

nxPropSession_List

Description

This property returns a comma separated list of frames or signals in the session.

For a Frame Input or Frame Output session, this property returns a list of frames. For a Signal Input/Output session, it returns the list of signals.