nixnet.session.frames

class nixnet._session.frames.Frame(handle, index, name)[source]

Bases: nixnet._session.collection.Item

Frame configuration for a session.

set_can_start_time_off(offset)[source]

Set CAN Start Time Offset.

Use this function to have more control over the schedule of frames on the bus, to offer more determinism by configuring cyclic frames to be spaced evenly.

If you do not call this function or you set it to a negative number, NI-XNET chooses this start time offset based on the arbitration identifier and periodic transmit time.

offset takes effect whenever a session is started. If you stop a session and restart it, the start time offset is re-evaluated.

Parameters:offset (float) – The amount of time that must elapse between the session being started and the time that the first frame is transmitted across the bus. This is different than the cyclic rate, which determines the time between subsequent frame transmissions.
set_can_tx_time(time)[source]

Set CAN Transmit Time.

If you call this function while a frame object is currently started, the frame object is stopped, the cyclic rate updated, and then the frame object is restarted. Because of the stopping and starting, the frame’s start time offset is re-evaluated.

The first time a queued frame object is started, the XNET frame’s transmit time determines the object’s default queue size. Changing this rate has no impact on the queue size. Depending on how you change the rate, the queue may not be sufficient to store data for an extended period of time. You can mitigate this by setting the session Queue Size property to provide sufficient storage for all rates you use. If you are using a single-point session, this is not relevant.

Parameters:time (float) – Frame’s transmit time while the session is running. The transmit time is the amount of time that must elapse between subsequent transmissions of a cyclic frame. The default value of this property comes from the database (the XNET Frame CAN Transmit Time property).
set_j1939_addr_filter(address='')[source]

Set J1939 Address Filter.

Define a filter for the source address of the PGN transmitting node. You can use it when multiple nodes with different addresses are transmitting the same PGN.

If the filter is active, the session accepts only frames transmitted by a node with the defined address. All other frames with the same PGN but transmitted by other nodes are ignored.

Note

You can use this function in input sessions only.

Parameters:address (str or int) – Decimal value of the address. Leave blank to reset the filter.
set_lin_tx_n_corrupted_chksums(n)[source]

Set LIN Transmit N Corrupted Checksums.

When set to a nonzero value, this function causes the next N number of checksums to be corrupted. The checksum is corrupted by negating the value calculated per the database; (EnhancedValue * -1) or (ClassicValue * -1).

If the frame is transmitted in an unconditional or sporadic schedule slot, N is always decremented for each frame transmission. If the frame is transmitted in an event-triggered slot and a collision occurs, N is not decremented. In that case, N is decremented only when the collision resolving schedule is executed and the frame is successfully transmitted. If the frame is the only one to transmit in the event-triggered slot (no collision), N is decremented at event-triggered slot time.

This function is useful for testing ECU behavior when a corrupted checksum is transmitted.

Note

This function is valid only for output sessions.

Parameters:n (int) – Number of checksums to be corrupted.
set_skip_n_cyclic_frames(n)[source]

Set Skip N Cyclic Frames

When the frame’s transmission time arrives and the skip count is nonzero, a frame value is dequeued (if this is not a single-point session), and the skip count is decremented, but the frame actually is not transmitted across the bus. When the skip count decrements to zero, subsequent cyclic transmissions resume.

This function is useful for testing of ECU behavior when a cyclic frame is expected, but is missing for N cycles.

Note

Only CAN interfaces currently support this function.

Note

This property is valid only for output sessions and frames with cyclic timing (that is, not event-based frames).

Parameters:n (int) – Skip the next N cyclic frames when nonzero.
class nixnet._session.frames.Frames(handle)[source]

Bases: nixnet._session.collection.Collection

Frames in a session.

count(value) → integer -- return number of occurrences of value
get(index, default=None)

Access an item, returning default on failure.

Parameters:
  • index (str or int) – Item name or index
  • default – Value to return when lookup fails
index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

payld_len_max

Returns the maximum payload length of all frames in this session, expressed as bytes (0-254).

For CAN Stream (Input and Output), this property depends on the XNET Cluster CAN I/O Mode property. If the I/O mode is constants.CanIoMode.CAN, this property is 8 bytes. If the I/O mode is ‘constants.CanIoMode.CAN_FD’ or ‘constants.CanIoMode.CAN_FD_BRS’, this property is 64 bytes.

For LIN Stream (Input and Output), this property always is 8 bytes.

For FlexRay Stream (Input and Output), this property is the same as the XNET Cluster FlexRay Payload Length Maximum property value.

For Queued and Single-Point (Input and Output), this is the maximum payload of all frames specified in the List property.

Type:int
class nixnet._session.frames.InFrames(handle)[source]

Bases: nixnet._session.frames.Frames

Frames in a session.

count(value) → integer -- return number of occurrences of value
get(index, default=None)

Access an item, returning default on failure.

Parameters:
  • index (str or int) – Item name or index
  • default – Value to return when lookup fails
index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

payld_len_max

Returns the maximum payload length of all frames in this session, expressed as bytes (0-254).

For CAN Stream (Input and Output), this property depends on the XNET Cluster CAN I/O Mode property. If the I/O mode is constants.CanIoMode.CAN, this property is 8 bytes. If the I/O mode is ‘constants.CanIoMode.CAN_FD’ or ‘constants.CanIoMode.CAN_FD_BRS’, this property is 64 bytes.

For LIN Stream (Input and Output), this property always is 8 bytes.

For FlexRay Stream (Input and Output), this property is the same as the XNET Cluster FlexRay Payload Length Maximum property value.

For Queued and Single-Point (Input and Output), this is the maximum payload of all frames specified in the List property.

Type:int
read(num_frames, timeout=0, frame_type=<class 'nixnet.types.XnetFrame'>)[source]

Read frames.

Parameters:
  • num_frames (int) – Number of frames to read.
  • timeout (float) –

    The time in seconds to wait for number to read frame bytes to become available.

    If ‘timeout’ is positive, this function waits for ‘num_frames’ frames to be received, then returns complete frames up to that number. If the frames do not arrive prior to the ‘timeout’, an error is returned.

    If ‘timeout’ is ‘constants.TIMEOUT_INFINITE’, this function waits indefinitely for ‘num_frames’ frames.

    If ‘timeout’ is ‘constants.TIMEOUT_NONE’, this function does not wait and immediately returns all available frames up to the limit ‘num_frames’ specifies.

  • frame_type (nixnet.types.FrameFactory) – A factory for the desired frame formats.
Yields:

nixnet.types.Frame
read_bytes(num_bytes, timeout=0)[source]

Read data as a list of raw bytes (frame data).

The raw bytes encode one or more frames using the Raw Frame Format.

Parameters:
  • num_bytes (int) – The number of bytes to read.
  • timeout (float) –

    The time in seconds to wait for number to read frame bytes to become available.

    To avoid returning a partial frame, even when ‘num_bytes’ are available from the hardware, this read may return fewer bytes in buffer. For example, assume you pass ‘num_bytes’ 70 bytes and ‘timeout’ of 10 seconds. During the read, two frames are received, the first 24 bytes in size, and the second 56 bytes in size, for a total of 80 bytes. The read returns after the two frames are received, but only the first frame is copied to data. If the read copied 46 bytes of the second frame (up to the limit of 70), that frame would be incomplete and therefore difficult to interpret. To avoid this problem, the read always returns complete frames in buffer.

    If ‘timeout’ is positive, this function waits for ‘num_bytes’ frame bytes to be received, then returns complete frames up to that number. If the bytes do not arrive prior to the ‘timeout’, an error is returned.

    If ‘timeout’ is ‘constants.TIMEOUT_INFINITE’, this function waits indefinitely for ‘num_bytes’ frame bytes.

    If ‘timeout’ is ‘constants.TIMEOUT_NONE’, this function does not wait and immediately returns all available frame bytes up to the limit ‘num_bytes’ specifies.
Returns:

A list of raw bytes representing the data.
class nixnet._session.frames.OutFrames(handle)[source]

Bases: nixnet._session.frames.Frames

Frames in a session.

count(value) → integer -- return number of occurrences of value
get(index, default=None)

Access an item, returning default on failure.

Parameters:
  • index (str or int) – Item name or index
  • default – Value to return when lookup fails
index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

payld_len_max

Returns the maximum payload length of all frames in this session, expressed as bytes (0-254).

For CAN Stream (Input and Output), this property depends on the XNET Cluster CAN I/O Mode property. If the I/O mode is constants.CanIoMode.CAN, this property is 8 bytes. If the I/O mode is ‘constants.CanIoMode.CAN_FD’ or ‘constants.CanIoMode.CAN_FD_BRS’, this property is 64 bytes.

For LIN Stream (Input and Output), this property always is 8 bytes.

For FlexRay Stream (Input and Output), this property is the same as the XNET Cluster FlexRay Payload Length Maximum property value.

For Queued and Single-Point (Input and Output), this is the maximum payload of all frames specified in the List property.

Type:int
write(frames, timeout=10)[source]

Write frame data.

Parameters:
  • frames (list of float) – One or more nixnet.types.Frame objects to be written to the session.
  • timeout (float) –

    The time in seconds to wait for number to read frame bytes to become available.

    If ‘timeout’ is positive, this function waits up to that ‘timeout’ for space to become available in queues. If the space is not available prior to the ‘timeout’, a ‘timeout’ error is returned.

    If ‘timeout’ is ‘constants.TIMEOUT_INFINITE’, this functions waits indefinitely for space to become available in queues.

    If ‘timeout’ is ‘constants.TIMEOUT_NONE’, this function does not wait and immediately returns with a ‘timeout’ error if all data cannot be queued. Regardless of the ‘timeout’ used, if a ‘timeout’ error occurs, none of the data is queued, so you can attempt to call this function again at a later time with the same data.
write_bytes(frame_bytes, timeout=10)[source]

Write a list of raw bytes (frame data).

The raw bytes encode one or more frames using the Raw Frame Format.

Parameters:
  • frame_bytes (bytes) – Frames to transmit.
  • timeout (float) –

    The time in seconds to wait for number to read frame bytes to become available.

    If ‘timeout’ is positive, this function waits up to that ‘timeout’ for space to become available in queues. If the space is not available prior to the ‘timeout’, a ‘timeout’ error is returned.

    If ‘timeout’ is ‘constants.TIMEOUT_INFINITE’, this functions waits indefinitely for space to become available in queues.

    If ‘timeout’ is ‘constants.TIMEOUT_NONE’, this function does not wait and immediately returns with a ‘timeout’ error if all data cannot be queued. Regardless of the ‘timeout’ used, if a ‘timeout’ error occurs, none of the data is queued, so you can attempt to call this function again at a later time with the same data.
class nixnet._session.frames.SinglePointInFrames(handle)[source]

Bases: nixnet._session.frames.Frames

Frames in a session.

count(value) → integer -- return number of occurrences of value
get(index, default=None)

Access an item, returning default on failure.

Parameters:
  • index (str or int) – Item name or index
  • default – Value to return when lookup fails
index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

payld_len_max

Returns the maximum payload length of all frames in this session, expressed as bytes (0-254).

For CAN Stream (Input and Output), this property depends on the XNET Cluster CAN I/O Mode property. If the I/O mode is constants.CanIoMode.CAN, this property is 8 bytes. If the I/O mode is ‘constants.CanIoMode.CAN_FD’ or ‘constants.CanIoMode.CAN_FD_BRS’, this property is 64 bytes.

For LIN Stream (Input and Output), this property always is 8 bytes.

For FlexRay Stream (Input and Output), this property is the same as the XNET Cluster FlexRay Payload Length Maximum property value.

For Queued and Single-Point (Input and Output), this is the maximum payload of all frames specified in the List property.

Type:int
read(frame_type=<class 'nixnet.types.XnetFrame'>)[source]

Read frames.

Parameters:frame_type (nixnet.types.FrameFactory) – A factory for the desired frame formats.
Yields:nixnet.types.Frame
read_bytes(num_bytes)[source]

Read data as a list of raw bytes (frame data).

Parameters:num_bytes (int) – Number of bytes to read.
Returns:Raw bytes representing the data.
Return type:bytes
class nixnet._session.frames.SinglePointOutFrames(handle)[source]

Bases: nixnet._session.frames.Frames

Frames in a session.

count(value) → integer -- return number of occurrences of value
get(index, default=None)

Access an item, returning default on failure.

Parameters:
  • index (str or int) – Item name or index
  • default – Value to return when lookup fails
index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

payld_len_max

Returns the maximum payload length of all frames in this session, expressed as bytes (0-254).

For CAN Stream (Input and Output), this property depends on the XNET Cluster CAN I/O Mode property. If the I/O mode is constants.CanIoMode.CAN, this property is 8 bytes. If the I/O mode is ‘constants.CanIoMode.CAN_FD’ or ‘constants.CanIoMode.CAN_FD_BRS’, this property is 64 bytes.

For LIN Stream (Input and Output), this property always is 8 bytes.

For FlexRay Stream (Input and Output), this property is the same as the XNET Cluster FlexRay Payload Length Maximum property value.

For Queued and Single-Point (Input and Output), this is the maximum payload of all frames specified in the List property.

Type:int
write(frames)[source]

Write frame data.

Parameters:frames (list of float) – One or more nixnet.types.Frame objects to be written to the session.
write_bytes(frame_bytes)[source]

Write a list of raw bytes (frame data).

The raw bytes encode one or more frames using the Raw Frame Format.

Parameters:frame_bytes (bytes) – Frames to transmit.