nixnet.session

class nixnet.session.FrameInStreamSession(interface_name, database_name=':memory:', cluster_name='')[source]

Bases: nixnet._session.base.SessionBase

Frame Input Stream session.

This session reads all frames received from the network using a single stream.

The input data is returned as a list of frames. Because all frames are returned, your application must evaluate identification in each frame (such as a CAN identifier or FlexRay slot/cycle/channel) to interpret the frame payload data.

Previously, you could use only one Frame Input Stream session for a given interface. Now, multiple Frame Input Stream sessions can be open at the same time on CAN and LIN interfaces.

While using one or more Frame Input Stream sessions, you can use other sessions with different input modes. Received frames are copied to Frame Input Stream sessions in addition to any other applicable input session. For example, if you create a Frame Input Single-Point session for frame_a, then create a Frame Input Stream session, when frame_a is received, its data is returned from the call to read function of both sessions. This duplication of incoming frames enables you to analyze overall traffic while running a higher level application that uses specific frame or signal data.

When used with a FlexRay interface, frames from both channels are returned. For example, if a frame is received in a static slot on both channel A and channel B, two frames are returned from the read function.

Note

Typical use case: Analyzing and/or logging all frame traffic in the network.

application_protocol

This property returns the application protocol that the session uses.

The database used with the session determines the application protocol.

Type:nixnet._enums.AppProtocol
auto_start

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

For input sessions, start always is performed within the first call to the appropriate read function (if not already started using nixnet._session.base.SessionBase.start). This is done because there is no known use case for reading a stopped input session.

For output sessions, as long as the first call to the appropriate write function contains valid data, you can leave this property at its default value of true. If you need to call the appropriate write 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 write function as desired, you can call nixnet._session.base.SessionBase.start to start the session(s).

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

Type:bool
can_comm

CAN Communication state

Type:nixnet.types.CanComm
change_lin_diagnostic_schedule(schedule)

Writes communication states of an XNET session.

This function writes a request for the LIN interface to change the diagnostic schedule.

Parameters:schedule (nixnet._enums.LinDiagnosticSchedule) – Diagnostic schedule that the LIN master executes.
change_lin_schedule(sched_index)

Writes communication states of an XNET session.

This function writes a request for the LIN interface to change the running schedule.

According to the LIN protocol, only the master executes schedules, not slaves. If the nixnet._session.intf.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.

Parameters:sched_index (int) –

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 nixnet.database._cluster.Cluster.lin_schedules property.

check_fault()

Check for an asynchronous fault.

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.

close()

Close (clear) the XNET session.

This function stops communication for the session and releases all resources the session uses. It internally calls nixnet._session.base.SessionBase.stop with normal scope, so if this is the last session using the interface, communication stops.

You typically use ‘close’ when you need to close the existing session to create a new session that uses the same objects. For example, if you create a session for a frame named frame_a using Frame Output Single-Point mode, then you create a second session for frame_a using Frame Output Queued mode, the second call to the session constructor returns an error, because frame_a can be accessed using only one output mode. If you call ‘close’ before the second constructor call, you can close the previous use of frame_a to create the new session.

cluster_name

This property returns the cluster (network) name used with the session.

Type:str
connect_terminals(source, destination)

Connect terminals on the XNET interface.

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.

Parameters:
  • source (str) – Connection source name.
  • destination (str) – Connection destination name.
database_name

This property returns the database name used with the session.

Type:str
disconnect_terminals(source, destination)

Disconnect terminals on the XNET interface.

This function disconnects a specific pair of source/destination terminals previously connected with nixnet._session.base.SessionBase.connect_terminals.

When the final session for a given interface is cleared, NI-XNET automatically disconnects all terminal connections for that interface. Therefore, ‘disconnect_terminals’ 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 nixnet._session.base.SessionBase.stop with the Interface Only scope. Then you can call ‘disconnect_terminals’ and nixnet._session.base.SessionBase.connect_terminals to adjust terminal connections. Finally, you can call nixnet._session.base.SessionBase.start 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.

Parameters:
  • source (str) – Connection source name.
  • destination (str) – Connection destination name.
flush()

Flushes (empties) all XNET session queues.

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 the read function. For output sessions, the queues store frame values provided to write function, but not transmitted successfully.

nixnet._session.base.SessionBase.start and nixnet._session.base.SessionBase.stop have no effect on these queues. Use ‘flush’ to discard all values in the session’s queues.

For example, if you call a write function to write three frames, then immediately call nixnet._session.base.SessionBase.stop, then call nixnet._session.base.SessionBase.start a few seconds later, the three frames transmit. If you call ‘flush’ between nixnet._session.base.SessionBase.stop and nixnet._session.base.SessionBase.start, no frames transmit.

As another example, if you receive three frames, then call nixnet._session.base.SessionBase.stop, the three frames remains in the queue. If you call nixnet._session.base.SessionBase.start a few seconds later, then call a read function, you obtain the three frames received earlier, potentially followed by other frames received after calling nixnet._session.base.SessionBase.start. If you call ‘flush’ between nixnet._session.base.SessionBase.stop and nixnet._session.base.SessionBase.start, read function returns only frames received after the calling nixnet._session.base.SessionBase.start.

frames

Operate on session’s frames

Type:nixnet._session.frames.InFrames
intf

Returns the Interface configuration object for the session.

Type:nixnet._session.intf.Interface
j1939

Returns the J1939 configuration object for the session.

Type:nixnet._session.j1939.J1939
lin_comm

LIN Communication state

Type:nixnet.types.LinComm
mode

This property returns the mode associated with the session.

For more information, refer to nixnet._enums.CreateSessionMode.

Type:nixnet._enums.CreateSessionMode
num_pend

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 read function. If you call the appropriate read function with number to read of this number and timeout of 0.0, the appropriate read function should return this number of values successfully.

For output sessions, this is the number of frames/signal values provided to the appropriate write 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.

Type:int
num_unused

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 write function. If you call the appropriate write function with this number of values and timeout of 0.0, it should return success.

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.

Type:int
protocol

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

Type:nixnet._enums.Protocol
queue_size

Get or set queue size.

For output sessions, queues store data passed to the appropriate write 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 read 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 nixnet._session.base.SessionBase.stop.

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 read or write 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 read 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 write 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.

Type:int
start(scope=<StartStopScope.NORMAL: 0>)

Start communication for the XNET session.

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 nixnet._session.base.SessionBase.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.

Parameters:scope (nixnet._enums.StartStopScope) – Describes the impact of this operation on the underlying state models for the session and its interface.
state

Session running state.

Type:nixnet._enums.SessionInfoState
stop(scope=<StartStopScope.NORMAL: 0>)

Stop communication for the XNET session.

Because the session is stopped automatically when closed (cleared), 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.

Parameters:scope (nixnet._enums.StartStopScope) – Describes the impact of this operation on the underlying state models for the session and its interface.
time_communicating

Time the interface started communicating.

The time is usually later than time_start because the interface must undergo a communication startup procedure.

Type:int
time_current

Current interface time.

Type:int
time_start

Time the interface was started.

Type:int
wait_for_intf_communicating(timeout=10)

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 ‘read_state’ will return:

nixnet._enums.CanCommState: ‘constants.CAN_COMM.ERROR_ACTIVE’

nixnet._enums.CanCommState: ‘constants.CAN_COMM.ERROR_PASSIVE’

‘constants.ReadState.TIME_COMMUNICATING’: Valid time for communication (invalid time of 0 prior)

Parameters:timeout (float) – The maximum amount of time to wait in seconds.
wait_for_intf_remote_wakeup(timeout=10)

Wait for interface remote wakeup.

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 ‘can_tcvr_state’ property to ‘constants.CanTcvrState.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 ‘lin_sleep’ property to ‘constants.LinSleep.REMOTE_SLEEP’ or ‘constants.LinSleep.LOCAL_SLEEP’. 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.

Parameters:timeout (float) – The maximum amount of time to wait in seconds.
wait_for_transmit_complete(timeout=10)

Wait for transmition to complete.

All frames written for the session have been transmitted on the bus. This condition applies to CAN, LIN, and FlexRay. This condition is state based, and the state is Boolean (true/false).

Parameters:timeout (float) – The maximum amount of time to wait in seconds.
class nixnet.session.FrameOutStreamSession(interface_name, database_name=':memory:', cluster_name='')[source]

Bases: nixnet._session.base.SessionBase

Frame Output Stream session.

This session transmits an arbitrary sequence of frame values using a single stream. The values are not limited to a single frame in the database, but can transmit any frame.

The data passed to the write frame function is a list of frame values, each of which transmits as soon as possible. Frames transmit sequentially (one after another).

Like Frame Input Stream sessions, you can create more than one Frame Output Stream session for a given interface.

For CAN, frame values transmit on the network based entirely on the time when you call the write frame function. The timing of each frame as specified in the database is ignored. For example, if you provide four frame values to the the write frame function, the first frame value transmits immediately, followed by the next three values transmitted back to back. For this session, the CAN frame payload length in the database is ignored, and the write frame function is always used.

Similarly for LIN, frame values transmit on the network based entirely on the time when you call the write frame function. The timing of each frame as specified in the database is ignored. The LIN frame payload length in the database is ignored, and the write frame function is always used. For LIN, this session/mode is allowed only on the interface as master. If the payload for a frame is empty, only the header part of the frame is transmitted. For a nonempty payload, the header + response for the frame is transmitted. If a frame for transmit is defined in the database (in-memory or otherwise), it is transmitted using its database checksum type. If the frame for transmit is not defined in the database, it is transmitted using enhanced checksum.

This session is not supported for FlexRay.

The frame values for this session are stored in a queue, such that every value provided is transmitted.

application_protocol

This property returns the application protocol that the session uses.

The database used with the session determines the application protocol.

Type:nixnet._enums.AppProtocol
auto_start

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

For input sessions, start always is performed within the first call to the appropriate read function (if not already started using nixnet._session.base.SessionBase.start). This is done because there is no known use case for reading a stopped input session.

For output sessions, as long as the first call to the appropriate write function contains valid data, you can leave this property at its default value of true. If you need to call the appropriate write 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 write function as desired, you can call nixnet._session.base.SessionBase.start to start the session(s).

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

Type:bool
can_comm

CAN Communication state

Type:nixnet.types.CanComm
change_lin_diagnostic_schedule(schedule)

Writes communication states of an XNET session.

This function writes a request for the LIN interface to change the diagnostic schedule.

Parameters:schedule (nixnet._enums.LinDiagnosticSchedule) – Diagnostic schedule that the LIN master executes.
change_lin_schedule(sched_index)

Writes communication states of an XNET session.

This function writes a request for the LIN interface to change the running schedule.

According to the LIN protocol, only the master executes schedules, not slaves. If the nixnet._session.intf.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.

Parameters:sched_index (int) –

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 nixnet.database._cluster.Cluster.lin_schedules property.

check_fault()

Check for an asynchronous fault.

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.

close()

Close (clear) the XNET session.

This function stops communication for the session and releases all resources the session uses. It internally calls nixnet._session.base.SessionBase.stop with normal scope, so if this is the last session using the interface, communication stops.

You typically use ‘close’ when you need to close the existing session to create a new session that uses the same objects. For example, if you create a session for a frame named frame_a using Frame Output Single-Point mode, then you create a second session for frame_a using Frame Output Queued mode, the second call to the session constructor returns an error, because frame_a can be accessed using only one output mode. If you call ‘close’ before the second constructor call, you can close the previous use of frame_a to create the new session.

cluster_name

This property returns the cluster (network) name used with the session.

Type:str
connect_terminals(source, destination)

Connect terminals on the XNET interface.

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.

Parameters:
  • source (str) – Connection source name.
  • destination (str) – Connection destination name.
database_name

This property returns the database name used with the session.

Type:str
disconnect_terminals(source, destination)

Disconnect terminals on the XNET interface.

This function disconnects a specific pair of source/destination terminals previously connected with nixnet._session.base.SessionBase.connect_terminals.

When the final session for a given interface is cleared, NI-XNET automatically disconnects all terminal connections for that interface. Therefore, ‘disconnect_terminals’ 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 nixnet._session.base.SessionBase.stop with the Interface Only scope. Then you can call ‘disconnect_terminals’ and nixnet._session.base.SessionBase.connect_terminals to adjust terminal connections. Finally, you can call nixnet._session.base.SessionBase.start 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.

Parameters:
  • source (str) – Connection source name.
  • destination (str) – Connection destination name.
flush()

Flushes (empties) all XNET session queues.

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 the read function. For output sessions, the queues store frame values provided to write function, but not transmitted successfully.

nixnet._session.base.SessionBase.start and nixnet._session.base.SessionBase.stop have no effect on these queues. Use ‘flush’ to discard all values in the session’s queues.

For example, if you call a write function to write three frames, then immediately call nixnet._session.base.SessionBase.stop, then call nixnet._session.base.SessionBase.start a few seconds later, the three frames transmit. If you call ‘flush’ between nixnet._session.base.SessionBase.stop and nixnet._session.base.SessionBase.start, no frames transmit.

As another example, if you receive three frames, then call nixnet._session.base.SessionBase.stop, the three frames remains in the queue. If you call nixnet._session.base.SessionBase.start a few seconds later, then call a read function, you obtain the three frames received earlier, potentially followed by other frames received after calling nixnet._session.base.SessionBase.start. If you call ‘flush’ between nixnet._session.base.SessionBase.stop and nixnet._session.base.SessionBase.start, read function returns only frames received after the calling nixnet._session.base.SessionBase.start.

frames

Operate on session’s frames

Type:nixnet._session.frames.InFrames
intf

Returns the Interface configuration object for the session.

Type:nixnet._session.intf.Interface
j1939

Returns the J1939 configuration object for the session.

Type:nixnet._session.j1939.J1939
lin_comm

LIN Communication state

Type:nixnet.types.LinComm
mode

This property returns the mode associated with the session.

For more information, refer to nixnet._enums.CreateSessionMode.

Type:nixnet._enums.CreateSessionMode
num_pend

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 read function. If you call the appropriate read function with number to read of this number and timeout of 0.0, the appropriate read function should return this number of values successfully.

For output sessions, this is the number of frames/signal values provided to the appropriate write 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.

Type:int
num_unused

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 write function. If you call the appropriate write function with this number of values and timeout of 0.0, it should return success.

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.

Type:int
protocol

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

Type:nixnet._enums.Protocol
queue_size

Get or set queue size.

For output sessions, queues store data passed to the appropriate write 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 read 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 nixnet._session.base.SessionBase.stop.

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 read or write 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 read 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 write 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.

Type:int
start(scope=<StartStopScope.NORMAL: 0>)

Start communication for the XNET session.

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 nixnet._session.base.SessionBase.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.

Parameters:scope (nixnet._enums.StartStopScope) – Describes the impact of this operation on the underlying state models for the session and its interface.
state

Session running state.

Type:nixnet._enums.SessionInfoState
stop(scope=<StartStopScope.NORMAL: 0>)

Stop communication for the XNET session.

Because the session is stopped automatically when closed (cleared), 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.

Parameters:scope (nixnet._enums.StartStopScope) – Describes the impact of this operation on the underlying state models for the session and its interface.
time_communicating

Time the interface started communicating.

The time is usually later than time_start because the interface must undergo a communication startup procedure.

Type:int
time_current

Current interface time.

Type:int
time_start

Time the interface was started.

Type:int
wait_for_intf_communicating(timeout=10)

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 ‘read_state’ will return:

nixnet._enums.CanCommState: ‘constants.CAN_COMM.ERROR_ACTIVE’

nixnet._enums.CanCommState: ‘constants.CAN_COMM.ERROR_PASSIVE’

‘constants.ReadState.TIME_COMMUNICATING’: Valid time for communication (invalid time of 0 prior)

Parameters:timeout (float) – The maximum amount of time to wait in seconds.
wait_for_intf_remote_wakeup(timeout=10)

Wait for interface remote wakeup.

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 ‘can_tcvr_state’ property to ‘constants.CanTcvrState.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 ‘lin_sleep’ property to ‘constants.LinSleep.REMOTE_SLEEP’ or ‘constants.LinSleep.LOCAL_SLEEP’. 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.

Parameters:timeout (float) – The maximum amount of time to wait in seconds.
wait_for_transmit_complete(timeout=10)

Wait for transmition to complete.

All frames written for the session have been transmitted on the bus. This condition applies to CAN, LIN, and FlexRay. This condition is state based, and the state is Boolean (true/false).

Parameters:timeout (float) – The maximum amount of time to wait in seconds.
class nixnet.session.FrameInQueuedSession(interface_name, database_name, cluster_name, frame)[source]

Bases: nixnet._session.base.SessionBase

Frame Input Queued session.

This session reads data from a dedicated queue per frame. It enables your application to read a sequence of data specific to a frame (for example, a CAN identifier).

You specify only one frame for the session, and the read frame function returns values for that frame only. If you need sequential data for multiple frames, create multiple sessions, one per frame.

The input data is returned as a list of frame values. These values represent all values received for the frame since the previous call to the read frame function.

application_protocol

This property returns the application protocol that the session uses.

The database used with the session determines the application protocol.

Type:nixnet._enums.AppProtocol
auto_start

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

For input sessions, start always is performed within the first call to the appropriate read function (if not already started using nixnet._session.base.SessionBase.start). This is done because there is no known use case for reading a stopped input session.

For output sessions, as long as the first call to the appropriate write function contains valid data, you can leave this property at its default value of true. If you need to call the appropriate write 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 write function as desired, you can call nixnet._session.base.SessionBase.start to start the session(s).

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

Type:bool
can_comm

CAN Communication state

Type:nixnet.types.CanComm
change_lin_diagnostic_schedule(schedule)

Writes communication states of an XNET session.

This function writes a request for the LIN interface to change the diagnostic schedule.

Parameters:schedule (nixnet._enums.LinDiagnosticSchedule) – Diagnostic schedule that the LIN master executes.
change_lin_schedule(sched_index)

Writes communication states of an XNET session.

This function writes a request for the LIN interface to change the running schedule.

According to the LIN protocol, only the master executes schedules, not slaves. If the nixnet._session.intf.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.

Parameters:sched_index (int) –

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 nixnet.database._cluster.Cluster.lin_schedules property.

check_fault()

Check for an asynchronous fault.

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.

close()

Close (clear) the XNET session.

This function stops communication for the session and releases all resources the session uses. It internally calls nixnet._session.base.SessionBase.stop with normal scope, so if this is the last session using the interface, communication stops.

You typically use ‘close’ when you need to close the existing session to create a new session that uses the same objects. For example, if you create a session for a frame named frame_a using Frame Output Single-Point mode, then you create a second session for frame_a using Frame Output Queued mode, the second call to the session constructor returns an error, because frame_a can be accessed using only one output mode. If you call ‘close’ before the second constructor call, you can close the previous use of frame_a to create the new session.

cluster_name

This property returns the cluster (network) name used with the session.

Type:str
connect_terminals(source, destination)

Connect terminals on the XNET interface.

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.

Parameters:
  • source (str) – Connection source name.
  • destination (str) – Connection destination name.
database_name

This property returns the database name used with the session.

Type:str
disconnect_terminals(source, destination)

Disconnect terminals on the XNET interface.

This function disconnects a specific pair of source/destination terminals previously connected with nixnet._session.base.SessionBase.connect_terminals.

When the final session for a given interface is cleared, NI-XNET automatically disconnects all terminal connections for that interface. Therefore, ‘disconnect_terminals’ 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 nixnet._session.base.SessionBase.stop with the Interface Only scope. Then you can call ‘disconnect_terminals’ and nixnet._session.base.SessionBase.connect_terminals to adjust terminal connections. Finally, you can call nixnet._session.base.SessionBase.start 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.

Parameters:
  • source (str) – Connection source name.
  • destination (str) – Connection destination name.
flush()

Flushes (empties) all XNET session queues.

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 the read function. For output sessions, the queues store frame values provided to write function, but not transmitted successfully.

nixnet._session.base.SessionBase.start and nixnet._session.base.SessionBase.stop have no effect on these queues. Use ‘flush’ to discard all values in the session’s queues.

For example, if you call a write function to write three frames, then immediately call nixnet._session.base.SessionBase.stop, then call nixnet._session.base.SessionBase.start a few seconds later, the three frames transmit. If you call ‘flush’ between nixnet._session.base.SessionBase.stop and nixnet._session.base.SessionBase.start, no frames transmit.

As another example, if you receive three frames, then call nixnet._session.base.SessionBase.stop, the three frames remains in the queue. If you call nixnet._session.base.SessionBase.start a few seconds later, then call a read function, you obtain the three frames received earlier, potentially followed by other frames received after calling nixnet._session.base.SessionBase.start. If you call ‘flush’ between nixnet._session.base.SessionBase.stop and nixnet._session.base.SessionBase.start, read function returns only frames received after the calling nixnet._session.base.SessionBase.start.

frames

Operate on session’s frames

Type:nixnet._session.frames.InFrames
intf

Returns the Interface configuration object for the session.

Type:nixnet._session.intf.Interface
j1939

Returns the J1939 configuration object for the session.

Type:nixnet._session.j1939.J1939
lin_comm

LIN Communication state

Type:nixnet.types.LinComm
mode

This property returns the mode associated with the session.

For more information, refer to nixnet._enums.CreateSessionMode.

Type:nixnet._enums.CreateSessionMode
num_pend

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 read function. If you call the appropriate read function with number to read of this number and timeout of 0.0, the appropriate read function should return this number of values successfully.

For output sessions, this is the number of frames/signal values provided to the appropriate write 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.

Type:int
num_unused

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 write function. If you call the appropriate write function with this number of values and timeout of 0.0, it should return success.

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.

Type:int
protocol

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

Type:nixnet._enums.Protocol
queue_size

Get or set queue size.

For output sessions, queues store data passed to the appropriate write 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 read 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 nixnet._session.base.SessionBase.stop.

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 read or write 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 read 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 write 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.

Type:int
start(scope=<StartStopScope.NORMAL: 0>)

Start communication for the XNET session.

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 nixnet._session.base.SessionBase.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.

Parameters:scope (nixnet._enums.StartStopScope) – Describes the impact of this operation on the underlying state models for the session and its interface.
state

Session running state.

Type:nixnet._enums.SessionInfoState
stop(scope=<StartStopScope.NORMAL: 0>)

Stop communication for the XNET session.

Because the session is stopped automatically when closed (cleared), 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.

Parameters:scope (nixnet._enums.StartStopScope) – Describes the impact of this operation on the underlying state models for the session and its interface.
time_communicating

Time the interface started communicating.

The time is usually later than time_start because the interface must undergo a communication startup procedure.

Type:int
time_current

Current interface time.

Type:int
time_start

Time the interface was started.

Type:int
wait_for_intf_communicating(timeout=10)

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 ‘read_state’ will return:

nixnet._enums.CanCommState: ‘constants.CAN_COMM.ERROR_ACTIVE’

nixnet._enums.CanCommState: ‘constants.CAN_COMM.ERROR_PASSIVE’

‘constants.ReadState.TIME_COMMUNICATING’: Valid time for communication (invalid time of 0 prior)

Parameters:timeout (float) – The maximum amount of time to wait in seconds.
wait_for_intf_remote_wakeup(timeout=10)

Wait for interface remote wakeup.

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 ‘can_tcvr_state’ property to ‘constants.CanTcvrState.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 ‘lin_sleep’ property to ‘constants.LinSleep.REMOTE_SLEEP’ or ‘constants.LinSleep.LOCAL_SLEEP’. 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.

Parameters:timeout (float) – The maximum amount of time to wait in seconds.
wait_for_transmit_complete(timeout=10)

Wait for transmition to complete.

All frames written for the session have been transmitted on the bus. This condition applies to CAN, LIN, and FlexRay. This condition is state based, and the state is Boolean (true/false).

Parameters:timeout (float) – The maximum amount of time to wait in seconds.
class nixnet.session.FrameOutQueuedSession(interface_name, database_name, cluster_name, frame)[source]

Bases: nixnet._session.base.SessionBase

Frame Output Queued session.

This session provides a sequence of values for a single frame, for transmit using that frame’s timing as specified in the database.

The output data is provided as a list of frame values, to be transmitted sequentially for the frame specified in the session.

You can only specify one frame for this session. To transmit sequential values for multiple frames, use a different Frame Output Queued session for each frame or use the Frame Output Stream session.

The frame values for this session are stored in a queue, such that every value provided is transmitted.

For this session, NI-XNET transmits each frame according to its properties in the database. Therefore, when you call the write frame function, the number of payload bytes in each frame value must match that frame’s Payload Length property. The other frame value elements are ignored, so you can leave them uninitialized. For CAN interfaces, if the number of payload bytes you write is smaller than the Payload Length configured in the database, the requested number of bytes transmits. If the number of payload bytes is larger than the Payload Length configured in the database, the queue is flushed and no frames transmit. For other interfaces, transmitting a number of payload bytes different than the frame’s payload may cause unexpected results on the bus.

application_protocol

This property returns the application protocol that the session uses.

The database used with the session determines the application protocol.

Type:nixnet._enums.AppProtocol
auto_start

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

For input sessions, start always is performed within the first call to the appropriate read function (if not already started using nixnet._session.base.SessionBase.start). This is done because there is no known use case for reading a stopped input session.

For output sessions, as long as the first call to the appropriate write function contains valid data, you can leave this property at its default value of true. If you need to call the appropriate write 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 write function as desired, you can call nixnet._session.base.SessionBase.start to start the session(s).

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

Type:bool
can_comm

CAN Communication state

Type:nixnet.types.CanComm
change_lin_diagnostic_schedule(schedule)

Writes communication states of an XNET session.

This function writes a request for the LIN interface to change the diagnostic schedule.

Parameters:schedule (nixnet._enums.LinDiagnosticSchedule) – Diagnostic schedule that the LIN master executes.
change_lin_schedule(sched_index)

Writes communication states of an XNET session.

This function writes a request for the LIN interface to change the running schedule.

According to the LIN protocol, only the master executes schedules, not slaves. If the nixnet._session.intf.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.

Parameters:sched_index (int) –

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 nixnet.database._cluster.Cluster.lin_schedules property.

check_fault()

Check for an asynchronous fault.

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.

close()

Close (clear) the XNET session.

This function stops communication for the session and releases all resources the session uses. It internally calls nixnet._session.base.SessionBase.stop with normal scope, so if this is the last session using the interface, communication stops.

You typically use ‘close’ when you need to close the existing session to create a new session that uses the same objects. For example, if you create a session for a frame named frame_a using Frame Output Single-Point mode, then you create a second session for frame_a using Frame Output Queued mode, the second call to the session constructor returns an error, because frame_a can be accessed using only one output mode. If you call ‘close’ before the second constructor call, you can close the previous use of frame_a to create the new session.

cluster_name

This property returns the cluster (network) name used with the session.

Type:str
connect_terminals(source, destination)

Connect terminals on the XNET interface.

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.

Parameters:
  • source (str) – Connection source name.
  • destination (str) – Connection destination name.
database_name

This property returns the database name used with the session.

Type:str
disconnect_terminals(source, destination)

Disconnect terminals on the XNET interface.

This function disconnects a specific pair of source/destination terminals previously connected with nixnet._session.base.SessionBase.connect_terminals.

When the final session for a given interface is cleared, NI-XNET automatically disconnects all terminal connections for that interface. Therefore, ‘disconnect_terminals’ 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 nixnet._session.base.SessionBase.stop with the Interface Only scope. Then you can call ‘disconnect_terminals’ and nixnet._session.base.SessionBase.connect_terminals to adjust terminal connections. Finally, you can call nixnet._session.base.SessionBase.start 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.

Parameters:
  • source (str) – Connection source name.
  • destination (str) – Connection destination name.
flush()

Flushes (empties) all XNET session queues.

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 the read function. For output sessions, the queues store frame values provided to write function, but not transmitted successfully.

nixnet._session.base.SessionBase.start and nixnet._session.base.SessionBase.stop have no effect on these queues. Use ‘flush’ to discard all values in the session’s queues.

For example, if you call a write function to write three frames, then immediately call nixnet._session.base.SessionBase.stop, then call nixnet._session.base.SessionBase.start a few seconds later, the three frames transmit. If you call ‘flush’ between nixnet._session.base.SessionBase.stop and nixnet._session.base.SessionBase.start, no frames transmit.

As another example, if you receive three frames, then call nixnet._session.base.SessionBase.stop, the three frames remains in the queue. If you call nixnet._session.base.SessionBase.start a few seconds later, then call a read function, you obtain the three frames received earlier, potentially followed by other frames received after calling nixnet._session.base.SessionBase.start. If you call ‘flush’ between nixnet._session.base.SessionBase.stop and nixnet._session.base.SessionBase.start, read function returns only frames received after the calling nixnet._session.base.SessionBase.start.

frames

Operate on session’s frames

Type:nixnet._session.frames.OutFrames
intf

Returns the Interface configuration object for the session.

Type:nixnet._session.intf.Interface
j1939

Returns the J1939 configuration object for the session.

Type:nixnet._session.j1939.J1939
lin_comm

LIN Communication state

Type:nixnet.types.LinComm
mode

This property returns the mode associated with the session.

For more information, refer to nixnet._enums.CreateSessionMode.

Type:nixnet._enums.CreateSessionMode
num_pend

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 read function. If you call the appropriate read function with number to read of this number and timeout of 0.0, the appropriate read function should return this number of values successfully.

For output sessions, this is the number of frames/signal values provided to the appropriate write 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.

Type:int
num_unused

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 write function. If you call the appropriate write function with this number of values and timeout of 0.0, it should return success.

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.

Type:int
protocol

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

Type:nixnet._enums.Protocol
queue_size

Get or set queue size.

For output sessions, queues store data passed to the appropriate write 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 read 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 nixnet._session.base.SessionBase.stop.

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 read or write 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 read 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 write 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.

Type:int
start(scope=<StartStopScope.NORMAL: 0>)

Start communication for the XNET session.

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 nixnet._session.base.SessionBase.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.

Parameters:scope (nixnet._enums.StartStopScope) – Describes the impact of this operation on the underlying state models for the session and its interface.
state

Session running state.

Type:nixnet._enums.SessionInfoState
stop(scope=<StartStopScope.NORMAL: 0>)

Stop communication for the XNET session.

Because the session is stopped automatically when closed (cleared), 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.

Parameters:scope (nixnet._enums.StartStopScope) – Describes the impact of this operation on the underlying state models for the session and its interface.
time_communicating

Time the interface started communicating.

The time is usually later than time_start because the interface must undergo a communication startup procedure.

Type:int
time_current

Current interface time.

Type:int
time_start

Time the interface was started.

Type:int
wait_for_intf_communicating(timeout=10)

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 ‘read_state’ will return:

nixnet._enums.CanCommState: ‘constants.CAN_COMM.ERROR_ACTIVE’

nixnet._enums.CanCommState: ‘constants.CAN_COMM.ERROR_PASSIVE’

‘constants.ReadState.TIME_COMMUNICATING’: Valid time for communication (invalid time of 0 prior)

Parameters:timeout (float) – The maximum amount of time to wait in seconds.
wait_for_intf_remote_wakeup(timeout=10)

Wait for interface remote wakeup.

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 ‘can_tcvr_state’ property to ‘constants.CanTcvrState.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 ‘lin_sleep’ property to ‘constants.LinSleep.REMOTE_SLEEP’ or ‘constants.LinSleep.LOCAL_SLEEP’. 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.

Parameters:timeout (float) – The maximum amount of time to wait in seconds.
wait_for_transmit_complete(timeout=10)

Wait for transmition to complete.

All frames written for the session have been transmitted on the bus. This condition applies to CAN, LIN, and FlexRay. This condition is state based, and the state is Boolean (true/false).

Parameters:timeout (float) – The maximum amount of time to wait in seconds.
class nixnet.session.FrameInSinglePointSession(interface_name, database_name, cluster_name, frames)[source]

Bases: nixnet._session.base.SessionBase

Frame Input Single-Point session.

This session reads the most recent value received for each frame.

This session does not use queues to store each received frame. If the interface receives two frames prior to calling the read frame function, that read returns signals for the second frame.

The input data is returned as a list of frames, one for each frame specified for the session.

Note

Typical use case: Control or simulation applications that require lower level access to frames (not signals).

application_protocol

This property returns the application protocol that the session uses.

The database used with the session determines the application protocol.

Type:nixnet._enums.AppProtocol
auto_start

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

For input sessions, start always is performed within the first call to the appropriate read function (if not already started using nixnet._session.base.SessionBase.start). This is done because there is no known use case for reading a stopped input session.

For output sessions, as long as the first call to the appropriate write function contains valid data, you can leave this property at its default value of true. If you need to call the appropriate write 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 write function as desired, you can call nixnet._session.base.SessionBase.start to start the session(s).

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

Type:bool
can_comm

CAN Communication state

Type:nixnet.types.CanComm
change_lin_diagnostic_schedule(schedule)

Writes communication states of an XNET session.

This function writes a request for the LIN interface to change the diagnostic schedule.

Parameters:schedule (nixnet._enums.LinDiagnosticSchedule) – Diagnostic schedule that the LIN master executes.
change_lin_schedule(sched_index)

Writes communication states of an XNET session.

This function writes a request for the LIN interface to change the running schedule.

According to the LIN protocol, only the master executes schedules, not slaves. If the nixnet._session.intf.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.

Parameters:sched_index (int) –

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 nixnet.database._cluster.Cluster.lin_schedules property.

check_fault()

Check for an asynchronous fault.

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.

close()

Close (clear) the XNET session.

This function stops communication for the session and releases all resources the session uses. It internally calls nixnet._session.base.SessionBase.stop with normal scope, so if this is the last session using the interface, communication stops.

You typically use ‘close’ when you need to close the existing session to create a new session that uses the same objects. For example, if you create a session for a frame named frame_a using Frame Output Single-Point mode, then you create a second session for frame_a using Frame Output Queued mode, the second call to the session constructor returns an error, because frame_a can be accessed using only one output mode. If you call ‘close’ before the second constructor call, you can close the previous use of frame_a to create the new session.

cluster_name

This property returns the cluster (network) name used with the session.

Type:str
connect_terminals(source, destination)

Connect terminals on the XNET interface.

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.

Parameters:
  • source (str) – Connection source name.
  • destination (str) – Connection destination name.
database_name

This property returns the database name used with the session.

Type:str
disconnect_terminals(source, destination)

Disconnect terminals on the XNET interface.

This function disconnects a specific pair of source/destination terminals previously connected with nixnet._session.base.SessionBase.connect_terminals.

When the final session for a given interface is cleared, NI-XNET automatically disconnects all terminal connections for that interface. Therefore, ‘disconnect_terminals’ 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 nixnet._session.base.SessionBase.stop with the Interface Only scope. Then you can call ‘disconnect_terminals’ and nixnet._session.base.SessionBase.connect_terminals to adjust terminal connections. Finally, you can call nixnet._session.base.SessionBase.start 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.

Parameters:
  • source (str) – Connection source name.
  • destination (str) – Connection destination name.
flush()

Flushes (empties) all XNET session queues.

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 the read function. For output sessions, the queues store frame values provided to write function, but not transmitted successfully.

nixnet._session.base.SessionBase.start and nixnet._session.base.SessionBase.stop have no effect on these queues. Use ‘flush’ to discard all values in the session’s queues.

For example, if you call a write function to write three frames, then immediately call nixnet._session.base.SessionBase.stop, then call nixnet._session.base.SessionBase.start a few seconds later, the three frames transmit. If you call ‘flush’ between nixnet._session.base.SessionBase.stop and nixnet._session.base.SessionBase.start, no frames transmit.

As another example, if you receive three frames, then call nixnet._session.base.SessionBase.stop, the three frames remains in the queue. If you call nixnet._session.base.SessionBase.start a few seconds later, then call a read function, you obtain the three frames received earlier, potentially followed by other frames received after calling nixnet._session.base.SessionBase.start. If you call ‘flush’ between nixnet._session.base.SessionBase.stop and nixnet._session.base.SessionBase.start, read function returns only frames received after the calling nixnet._session.base.SessionBase.start.

frames

Operate on session’s frames

Type:nixnet._session.frames.InFrames
intf

Returns the Interface configuration object for the session.

Type:nixnet._session.intf.Interface
j1939

Returns the J1939 configuration object for the session.

Type:nixnet._session.j1939.J1939
lin_comm

LIN Communication state

Type:nixnet.types.LinComm
mode

This property returns the mode associated with the session.

For more information, refer to nixnet._enums.CreateSessionMode.

Type:nixnet._enums.CreateSessionMode
num_pend

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 read function. If you call the appropriate read function with number to read of this number and timeout of 0.0, the appropriate read function should return this number of values successfully.

For output sessions, this is the number of frames/signal values provided to the appropriate write 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.

Type:int
num_unused

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 write function. If you call the appropriate write function with this number of values and timeout of 0.0, it should return success.

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.

Type:int
protocol

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

Type:nixnet._enums.Protocol
queue_size

Get or set queue size.

For output sessions, queues store data passed to the appropriate write 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 read 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 nixnet._session.base.SessionBase.stop.

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 read or write 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 read 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 write 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.

Type:int
start(scope=<StartStopScope.NORMAL: 0>)

Start communication for the XNET session.

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 nixnet._session.base.SessionBase.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.

Parameters:scope (nixnet._enums.StartStopScope) – Describes the impact of this operation on the underlying state models for the session and its interface.
state

Session running state.

Type:nixnet._enums.SessionInfoState
stop(scope=<StartStopScope.NORMAL: 0>)

Stop communication for the XNET session.

Because the session is stopped automatically when closed (cleared), 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.

Parameters:scope (nixnet._enums.StartStopScope) – Describes the impact of this operation on the underlying state models for the session and its interface.
time_communicating

Time the interface started communicating.

The time is usually later than time_start because the interface must undergo a communication startup procedure.

Type:int
time_current

Current interface time.

Type:int
time_start

Time the interface was started.

Type:int
wait_for_intf_communicating(timeout=10)

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 ‘read_state’ will return:

nixnet._enums.CanCommState: ‘constants.CAN_COMM.ERROR_ACTIVE’

nixnet._enums.CanCommState: ‘constants.CAN_COMM.ERROR_PASSIVE’

‘constants.ReadState.TIME_COMMUNICATING’: Valid time for communication (invalid time of 0 prior)

Parameters:timeout (float) – The maximum amount of time to wait in seconds.
wait_for_intf_remote_wakeup(timeout=10)

Wait for interface remote wakeup.

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 ‘can_tcvr_state’ property to ‘constants.CanTcvrState.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 ‘lin_sleep’ property to ‘constants.LinSleep.REMOTE_SLEEP’ or ‘constants.LinSleep.LOCAL_SLEEP’. 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.

Parameters:timeout (float) – The maximum amount of time to wait in seconds.
wait_for_transmit_complete(timeout=10)

Wait for transmition to complete.

All frames written for the session have been transmitted on the bus. This condition applies to CAN, LIN, and FlexRay. This condition is state based, and the state is Boolean (true/false).

Parameters:timeout (float) – The maximum amount of time to wait in seconds.
class nixnet.session.FrameOutSinglePointSession(interface_name, database_name, cluster_name, frames)[source]

Bases: nixnet._session.base.SessionBase

Frame Output Single-Point session.

This session writes frame values for the next transmit.

This session does not use queues to store frame values. If the write frame function is called twice before the next transmit, the transmitted frame uses the value from the second call to the write frame function.

The output data is provided as a list of frames, one for each frame specified for the session.

For this session, NI-XNET transmits each frame according to its properties in the database. Therefore, when you call the write frame function, the number of payload bytes in each frame value must match that frame’s Payload Length property. The other frame value elements are ignored, so you can leave them uninitialized. For CAN interfaces, if the number of payload bytes you write is smaller than the Payload Length configured in the database, the requested number of bytes transmit. If the number of payload bytes is larger than the Payload Length configured in the database, the queue is flushed and no frames transmit. For other interfaces, transmitting a number of payload bytes different than the frame payload may cause unexpected results on the bus.

Note

Typical use case: Control or simulation applications that require lower level access to frames (not signals).

application_protocol

This property returns the application protocol that the session uses.

The database used with the session determines the application protocol.

Type:nixnet._enums.AppProtocol
auto_start

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

For input sessions, start always is performed within the first call to the appropriate read function (if not already started using nixnet._session.base.SessionBase.start). This is done because there is no known use case for reading a stopped input session.

For output sessions, as long as the first call to the appropriate write function contains valid data, you can leave this property at its default value of true. If you need to call the appropriate write 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 write function as desired, you can call nixnet._session.base.SessionBase.start to start the session(s).

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

Type:bool
can_comm

CAN Communication state

Type:nixnet.types.CanComm
change_lin_diagnostic_schedule(schedule)

Writes communication states of an XNET session.

This function writes a request for the LIN interface to change the diagnostic schedule.

Parameters:schedule (nixnet._enums.LinDiagnosticSchedule) – Diagnostic schedule that the LIN master executes.
change_lin_schedule(sched_index)

Writes communication states of an XNET session.

This function writes a request for the LIN interface to change the running schedule.

According to the LIN protocol, only the master executes schedules, not slaves. If the nixnet._session.intf.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.

Parameters:sched_index (int) –

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 nixnet.database._cluster.Cluster.lin_schedules property.

check_fault()

Check for an asynchronous fault.

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.

close()

Close (clear) the XNET session.

This function stops communication for the session and releases all resources the session uses. It internally calls nixnet._session.base.SessionBase.stop with normal scope, so if this is the last session using the interface, communication stops.

You typically use ‘close’ when you need to close the existing session to create a new session that uses the same objects. For example, if you create a session for a frame named frame_a using Frame Output Single-Point mode, then you create a second session for frame_a using Frame Output Queued mode, the second call to the session constructor returns an error, because frame_a can be accessed using only one output mode. If you call ‘close’ before the second constructor call, you can close the previous use of frame_a to create the new session.

cluster_name

This property returns the cluster (network) name used with the session.

Type:str
connect_terminals(source, destination)

Connect terminals on the XNET interface.

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.

Parameters:
  • source (str) – Connection source name.
  • destination (str) – Connection destination name.
database_name

This property returns the database name used with the session.

Type:str
disconnect_terminals(source, destination)

Disconnect terminals on the XNET interface.

This function disconnects a specific pair of source/destination terminals previously connected with nixnet._session.base.SessionBase.connect_terminals.

When the final session for a given interface is cleared, NI-XNET automatically disconnects all terminal connections for that interface. Therefore, ‘disconnect_terminals’ 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 nixnet._session.base.SessionBase.stop with the Interface Only scope. Then you can call ‘disconnect_terminals’ and nixnet._session.base.SessionBase.connect_terminals to adjust terminal connections. Finally, you can call nixnet._session.base.SessionBase.start 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.

Parameters:
  • source (str) – Connection source name.
  • destination (str) – Connection destination name.
flush()

Flushes (empties) all XNET session queues.

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 the read function. For output sessions, the queues store frame values provided to write function, but not transmitted successfully.

nixnet._session.base.SessionBase.start and nixnet._session.base.SessionBase.stop have no effect on these queues. Use ‘flush’ to discard all values in the session’s queues.

For example, if you call a write function to write three frames, then immediately call nixnet._session.base.SessionBase.stop, then call nixnet._session.base.SessionBase.start a few seconds later, the three frames transmit. If you call ‘flush’ between nixnet._session.base.SessionBase.stop and nixnet._session.base.SessionBase.start, no frames transmit.

As another example, if you receive three frames, then call nixnet._session.base.SessionBase.stop, the three frames remains in the queue. If you call nixnet._session.base.SessionBase.start a few seconds later, then call a read function, you obtain the three frames received earlier, potentially followed by other frames received after calling nixnet._session.base.SessionBase.start. If you call ‘flush’ between nixnet._session.base.SessionBase.stop and nixnet._session.base.SessionBase.start, read function returns only frames received after the calling nixnet._session.base.SessionBase.start.

frames

Operate on session’s frames

Type:nixnet._session.frames.InFrames
intf

Returns the Interface configuration object for the session.

Type:nixnet._session.intf.Interface
j1939

Returns the J1939 configuration object for the session.

Type:nixnet._session.j1939.J1939
lin_comm

LIN Communication state

Type:nixnet.types.LinComm
mode

This property returns the mode associated with the session.

For more information, refer to nixnet._enums.CreateSessionMode.

Type:nixnet._enums.CreateSessionMode
num_pend

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 read function. If you call the appropriate read function with number to read of this number and timeout of 0.0, the appropriate read function should return this number of values successfully.

For output sessions, this is the number of frames/signal values provided to the appropriate write 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.

Type:int
num_unused

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 write function. If you call the appropriate write function with this number of values and timeout of 0.0, it should return success.

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.

Type:int
protocol

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

Type:nixnet._enums.Protocol
queue_size

Get or set queue size.

For output sessions, queues store data passed to the appropriate write 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 read 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 nixnet._session.base.SessionBase.stop.

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 read or write 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 read 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 write 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.

Type:int
start(scope=<StartStopScope.NORMAL: 0>)

Start communication for the XNET session.

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 nixnet._session.base.SessionBase.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.

Parameters:scope (nixnet._enums.StartStopScope) – Describes the impact of this operation on the underlying state models for the session and its interface.
state

Session running state.

Type:nixnet._enums.SessionInfoState
stop(scope=<StartStopScope.NORMAL: 0>)

Stop communication for the XNET session.

Because the session is stopped automatically when closed (cleared), 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.

Parameters:scope (nixnet._enums.StartStopScope) – Describes the impact of this operation on the underlying state models for the session and its interface.
time_communicating

Time the interface started communicating.

The time is usually later than time_start because the interface must undergo a communication startup procedure.

Type:int
time_current

Current interface time.

Type:int
time_start

Time the interface was started.

Type:int
wait_for_intf_communicating(timeout=10)

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 ‘read_state’ will return:

nixnet._enums.CanCommState: ‘constants.CAN_COMM.ERROR_ACTIVE’

nixnet._enums.CanCommState: ‘constants.CAN_COMM.ERROR_PASSIVE’

‘constants.ReadState.TIME_COMMUNICATING’: Valid time for communication (invalid time of 0 prior)

Parameters:timeout (float) – The maximum amount of time to wait in seconds.
wait_for_intf_remote_wakeup(timeout=10)

Wait for interface remote wakeup.

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 ‘can_tcvr_state’ property to ‘constants.CanTcvrState.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 ‘lin_sleep’ property to ‘constants.LinSleep.REMOTE_SLEEP’ or ‘constants.LinSleep.LOCAL_SLEEP’. 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.

Parameters:timeout (float) – The maximum amount of time to wait in seconds.
wait_for_transmit_complete(timeout=10)

Wait for transmition to complete.

All frames written for the session have been transmitted on the bus. This condition applies to CAN, LIN, and FlexRay. This condition is state based, and the state is Boolean (true/false).

Parameters:timeout (float) – The maximum amount of time to wait in seconds.
class nixnet.session.SignalInSinglePointSession(interface_name, database_name, cluster_name, signals)[source]

Bases: nixnet._session.base.SessionBase

Signal Input Single-Point session.

This session reads the most recent value received for each signal.

This session does not use queues to store each received frame. If the interface receives two frames prior to calling nixnet._session.signals.SinglePointInSignals.read, that call to nixnet._session.signals.SinglePointInSignals.read returns signals for the second frame.

Use nixnet._session.signals.SinglePointInSignals.read for this session.

You also can specify a trigger signal for a frame. This signal name is :trigger:.<frame name>, and once it is specified in the __init__ signals list, it returns a value of 0.0 if the frame did not arrive since the last Read (or Start), and 1.0 if at least one frame of this ID arrived. You can specify multiple trigger signals for different frames in the same session. For multiplexed signals, a signal may or may not be contained in a received frame. To define a trigger signal for a multiplexed signal, use the signal name :trigger:.<frame name>.<signal name>. This signal returns 1.0 only if a frame with appropriate set multiplexer bit has been received since the last Read or Start.

Note

Typical use case: Control or simulation applications, such as Hardware In the Loop (HIL).

application_protocol

This property returns the application protocol that the session uses.

The database used with the session determines the application protocol.

Type:nixnet._enums.AppProtocol
auto_start

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

For input sessions, start always is performed within the first call to the appropriate read function (if not already started using nixnet._session.base.SessionBase.start). This is done because there is no known use case for reading a stopped input session.

For output sessions, as long as the first call to the appropriate write function contains valid data, you can leave this property at its default value of true. If you need to call the appropriate write 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 write function as desired, you can call nixnet._session.base.SessionBase.start to start the session(s).

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

Type:bool
can_comm

CAN Communication state

Type:nixnet.types.CanComm
change_lin_diagnostic_schedule(schedule)

Writes communication states of an XNET session.

This function writes a request for the LIN interface to change the diagnostic schedule.

Parameters:schedule (nixnet._enums.LinDiagnosticSchedule) – Diagnostic schedule that the LIN master executes.
change_lin_schedule(sched_index)

Writes communication states of an XNET session.

This function writes a request for the LIN interface to change the running schedule.

According to the LIN protocol, only the master executes schedules, not slaves. If the nixnet._session.intf.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.

Parameters:sched_index (int) –

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 nixnet.database._cluster.Cluster.lin_schedules property.

check_fault()

Check for an asynchronous fault.

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.

close()

Close (clear) the XNET session.

This function stops communication for the session and releases all resources the session uses. It internally calls nixnet._session.base.SessionBase.stop with normal scope, so if this is the last session using the interface, communication stops.

You typically use ‘close’ when you need to close the existing session to create a new session that uses the same objects. For example, if you create a session for a frame named frame_a using Frame Output Single-Point mode, then you create a second session for frame_a using Frame Output Queued mode, the second call to the session constructor returns an error, because frame_a can be accessed using only one output mode. If you call ‘close’ before the second constructor call, you can close the previous use of frame_a to create the new session.

cluster_name

This property returns the cluster (network) name used with the session.

Type:str
connect_terminals(source, destination)

Connect terminals on the XNET interface.

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.

Parameters:
  • source (str) – Connection source name.
  • destination (str) – Connection destination name.
database_name

This property returns the database name used with the session.

Type:str
disconnect_terminals(source, destination)

Disconnect terminals on the XNET interface.

This function disconnects a specific pair of source/destination terminals previously connected with nixnet._session.base.SessionBase.connect_terminals.

When the final session for a given interface is cleared, NI-XNET automatically disconnects all terminal connections for that interface. Therefore, ‘disconnect_terminals’ 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 nixnet._session.base.SessionBase.stop with the Interface Only scope. Then you can call ‘disconnect_terminals’ and nixnet._session.base.SessionBase.connect_terminals to adjust terminal connections. Finally, you can call nixnet._session.base.SessionBase.start 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.

Parameters:
  • source (str) – Connection source name.
  • destination (str) – Connection destination name.
flush()

Flushes (empties) all XNET session queues.

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 the read function. For output sessions, the queues store frame values provided to write function, but not transmitted successfully.

nixnet._session.base.SessionBase.start and nixnet._session.base.SessionBase.stop have no effect on these queues. Use ‘flush’ to discard all values in the session’s queues.

For example, if you call a write function to write three frames, then immediately call nixnet._session.base.SessionBase.stop, then call nixnet._session.base.SessionBase.start a few seconds later, the three frames transmit. If you call ‘flush’ between nixnet._session.base.SessionBase.stop and nixnet._session.base.SessionBase.start, no frames transmit.

As another example, if you receive three frames, then call nixnet._session.base.SessionBase.stop, the three frames remains in the queue. If you call nixnet._session.base.SessionBase.start a few seconds later, then call a read function, you obtain the three frames received earlier, potentially followed by other frames received after calling nixnet._session.base.SessionBase.start. If you call ‘flush’ between nixnet._session.base.SessionBase.stop and nixnet._session.base.SessionBase.start, read function returns only frames received after the calling nixnet._session.base.SessionBase.start.

intf

Returns the Interface configuration object for the session.

Type:nixnet._session.intf.Interface
j1939

Returns the J1939 configuration object for the session.

Type:nixnet._session.j1939.J1939
lin_comm

LIN Communication state

Type:nixnet.types.LinComm
mode

This property returns the mode associated with the session.

For more information, refer to nixnet._enums.CreateSessionMode.

Type:nixnet._enums.CreateSessionMode
num_pend

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 read function. If you call the appropriate read function with number to read of this number and timeout of 0.0, the appropriate read function should return this number of values successfully.

For output sessions, this is the number of frames/signal values provided to the appropriate write 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.

Type:int
num_unused

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 write function. If you call the appropriate write function with this number of values and timeout of 0.0, it should return success.

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.

Type:int
protocol

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

Type:nixnet._enums.Protocol
queue_size

Get or set queue size.

For output sessions, queues store data passed to the appropriate write 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 read 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 nixnet._session.base.SessionBase.stop.

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 read or write 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 read 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 write 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.

Type:int
signals

Operate on session’s signals

Type:nixnet._session.signals.SinglePointInSignals
start(scope=<StartStopScope.NORMAL: 0>)

Start communication for the XNET session.

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 nixnet._session.base.SessionBase.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.

Parameters:scope (nixnet._enums.StartStopScope) – Describes the impact of this operation on the underlying state models for the session and its interface.
state

Session running state.

Type:nixnet._enums.SessionInfoState
stop(scope=<StartStopScope.NORMAL: 0>)

Stop communication for the XNET session.

Because the session is stopped automatically when closed (cleared), 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.

Parameters:scope (nixnet._enums.StartStopScope) – Describes the impact of this operation on the underlying state models for the session and its interface.
time_communicating

Time the interface started communicating.

The time is usually later than time_start because the interface must undergo a communication startup procedure.

Type:int
time_current

Current interface time.

Type:int
time_start

Time the interface was started.

Type:int
wait_for_intf_communicating(timeout=10)

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 ‘read_state’ will return:

nixnet._enums.CanCommState: ‘constants.CAN_COMM.ERROR_ACTIVE’

nixnet._enums.CanCommState: ‘constants.CAN_COMM.ERROR_PASSIVE’

‘constants.ReadState.TIME_COMMUNICATING’: Valid time for communication (invalid time of 0 prior)

Parameters:timeout (float) – The maximum amount of time to wait in seconds.
wait_for_intf_remote_wakeup(timeout=10)

Wait for interface remote wakeup.

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 ‘can_tcvr_state’ property to ‘constants.CanTcvrState.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 ‘lin_sleep’ property to ‘constants.LinSleep.REMOTE_SLEEP’ or ‘constants.LinSleep.LOCAL_SLEEP’. 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.

Parameters:timeout (float) – The maximum amount of time to wait in seconds.
wait_for_transmit_complete(timeout=10)

Wait for transmition to complete.

All frames written for the session have been transmitted on the bus. This condition applies to CAN, LIN, and FlexRay. This condition is state based, and the state is Boolean (true/false).

Parameters:timeout (float) – The maximum amount of time to wait in seconds.
class nixnet.session.SignalOutSinglePointSession(interface_name, database_name, cluster_name, signals)[source]

Bases: nixnet._session.base.SessionBase

Signal Out Single-Point session.

This session writes signal values for the next frame transmit.

This session does not use queues to store signal values. If nixnet._session.signals.SinglePointOutSignals.write is called twice before the next transmit, the transmitted frame uses signal values from the second call to nixnet._session.signals.SinglePointOutSignals.write.

Use nixnet._session.signals.SinglePointOutSignals.write for this session.

You also can specify a trigger signal for a frame. This signal name is :trigger:.<frame name>, and once it is specified in the __init__ signals list, you can write a value of 0.0 to suppress writing of that frame, or any value not equal to 0.0 to write the frame. You can specify multiple trigger signals for different frames in the same session.

Note

Typical use case: Control or simulation applications, such as Hardware In the Loop (HIL).

application_protocol

This property returns the application protocol that the session uses.

The database used with the session determines the application protocol.

Type:nixnet._enums.AppProtocol
auto_start

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

For input sessions, start always is performed within the first call to the appropriate read function (if not already started using nixnet._session.base.SessionBase.start). This is done because there is no known use case for reading a stopped input session.

For output sessions, as long as the first call to the appropriate write function contains valid data, you can leave this property at its default value of true. If you need to call the appropriate write 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 write function as desired, you can call nixnet._session.base.SessionBase.start to start the session(s).

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

Type:bool
can_comm

CAN Communication state

Type:nixnet.types.CanComm
change_lin_diagnostic_schedule(schedule)

Writes communication states of an XNET session.

This function writes a request for the LIN interface to change the diagnostic schedule.

Parameters:schedule (nixnet._enums.LinDiagnosticSchedule) – Diagnostic schedule that the LIN master executes.
change_lin_schedule(sched_index)

Writes communication states of an XNET session.

This function writes a request for the LIN interface to change the running schedule.

According to the LIN protocol, only the master executes schedules, not slaves. If the nixnet._session.intf.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.

Parameters:sched_index (int) –

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 nixnet.database._cluster.Cluster.lin_schedules property.

check_fault()

Check for an asynchronous fault.

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.

close()

Close (clear) the XNET session.

This function stops communication for the session and releases all resources the session uses. It internally calls nixnet._session.base.SessionBase.stop with normal scope, so if this is the last session using the interface, communication stops.

You typically use ‘close’ when you need to close the existing session to create a new session that uses the same objects. For example, if you create a session for a frame named frame_a using Frame Output Single-Point mode, then you create a second session for frame_a using Frame Output Queued mode, the second call to the session constructor returns an error, because frame_a can be accessed using only one output mode. If you call ‘close’ before the second constructor call, you can close the previous use of frame_a to create the new session.

cluster_name

This property returns the cluster (network) name used with the session.

Type:str
connect_terminals(source, destination)

Connect terminals on the XNET interface.

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.

Parameters:
  • source (str) – Connection source name.
  • destination (str) – Connection destination name.
database_name

This property returns the database name used with the session.

Type:str
disconnect_terminals(source, destination)

Disconnect terminals on the XNET interface.

This function disconnects a specific pair of source/destination terminals previously connected with nixnet._session.base.SessionBase.connect_terminals.

When the final session for a given interface is cleared, NI-XNET automatically disconnects all terminal connections for that interface. Therefore, ‘disconnect_terminals’ 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 nixnet._session.base.SessionBase.stop with the Interface Only scope. Then you can call ‘disconnect_terminals’ and nixnet._session.base.SessionBase.connect_terminals to adjust terminal connections. Finally, you can call nixnet._session.base.SessionBase.start 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.

Parameters:
  • source (str) – Connection source name.
  • destination (str) – Connection destination name.
flush()

Flushes (empties) all XNET session queues.

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 the read function. For output sessions, the queues store frame values provided to write function, but not transmitted successfully.

nixnet._session.base.SessionBase.start and nixnet._session.base.SessionBase.stop have no effect on these queues. Use ‘flush’ to discard all values in the session’s queues.

For example, if you call a write function to write three frames, then immediately call nixnet._session.base.SessionBase.stop, then call nixnet._session.base.SessionBase.start a few seconds later, the three frames transmit. If you call ‘flush’ between nixnet._session.base.SessionBase.stop and nixnet._session.base.SessionBase.start, no frames transmit.

As another example, if you receive three frames, then call nixnet._session.base.SessionBase.stop, the three frames remains in the queue. If you call nixnet._session.base.SessionBase.start a few seconds later, then call a read function, you obtain the three frames received earlier, potentially followed by other frames received after calling nixnet._session.base.SessionBase.start. If you call ‘flush’ between nixnet._session.base.SessionBase.stop and nixnet._session.base.SessionBase.start, read function returns only frames received after the calling nixnet._session.base.SessionBase.start.

intf

Returns the Interface configuration object for the session.

Type:nixnet._session.intf.Interface
j1939

Returns the J1939 configuration object for the session.

Type:nixnet._session.j1939.J1939
lin_comm

LIN Communication state

Type:nixnet.types.LinComm
mode

This property returns the mode associated with the session.

For more information, refer to nixnet._enums.CreateSessionMode.

Type:nixnet._enums.CreateSessionMode
num_pend

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 read function. If you call the appropriate read function with number to read of this number and timeout of 0.0, the appropriate read function should return this number of values successfully.

For output sessions, this is the number of frames/signal values provided to the appropriate write 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.

Type:int
num_unused

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 write function. If you call the appropriate write function with this number of values and timeout of 0.0, it should return success.

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.

Type:int
protocol

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

Type:nixnet._enums.Protocol
queue_size

Get or set queue size.

For output sessions, queues store data passed to the appropriate write 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 read 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 nixnet._session.base.SessionBase.stop.

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 read or write 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 read 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 write 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.

Type:int
signals

Operate on session’s signals

Type:nixnet._session.signals.SinglePointInSignals
start(scope=<StartStopScope.NORMAL: 0>)

Start communication for the XNET session.

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 nixnet._session.base.SessionBase.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.

Parameters:scope (nixnet._enums.StartStopScope) – Describes the impact of this operation on the underlying state models for the session and its interface.
state

Session running state.

Type:nixnet._enums.SessionInfoState
stop(scope=<StartStopScope.NORMAL: 0>)

Stop communication for the XNET session.

Because the session is stopped automatically when closed (cleared), 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.

Parameters:scope (nixnet._enums.StartStopScope) – Describes the impact of this operation on the underlying state models for the session and its interface.
time_communicating

Time the interface started communicating.

The time is usually later than time_start because the interface must undergo a communication startup procedure.

Type:int
time_current

Current interface time.

Type:int
time_start

Time the interface was started.

Type:int
wait_for_intf_communicating(timeout=10)

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 ‘read_state’ will return:

nixnet._enums.CanCommState: ‘constants.CAN_COMM.ERROR_ACTIVE’

nixnet._enums.CanCommState: ‘constants.CAN_COMM.ERROR_PASSIVE’

‘constants.ReadState.TIME_COMMUNICATING’: Valid time for communication (invalid time of 0 prior)

Parameters:timeout (float) – The maximum amount of time to wait in seconds.
wait_for_intf_remote_wakeup(timeout=10)

Wait for interface remote wakeup.

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 ‘can_tcvr_state’ property to ‘constants.CanTcvrState.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 ‘lin_sleep’ property to ‘constants.LinSleep.REMOTE_SLEEP’ or ‘constants.LinSleep.LOCAL_SLEEP’. 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.

Parameters:timeout (float) – The maximum amount of time to wait in seconds.
wait_for_transmit_complete(timeout=10)

Wait for transmition to complete.

All frames written for the session have been transmitted on the bus. This condition applies to CAN, LIN, and FlexRay. This condition is state based, and the state is Boolean (true/false).

Parameters:timeout (float) – The maximum amount of time to wait in seconds.