nixnet.database.frame

class nixnet.database._frame.Frame(**kwargs: int)

Bases: DatabaseObject

Database frame

property application_protocol: AppProtocol

Get or set the frame’s application protocol.

Type:

AppProtocol

property can_ext_id: bool

Get or set whether the Frame.id property in a CAN cluster is extended.

The frame identifier represents a standard 11-bit (False) or extended 29-bit (True) arbitration ID.

Type:

bool

property can_io_mode: CanIoMode

Get or set the frame’s I/O mode.

This property is used in ISO CAN FD+BRS mode only. In this mode, you can specify every frame to be transmitted in CAN 2.0, CAN FD, or CAN FD+BRS mode. CAN FD+BRS frames require the interface to be in CAN FD+BRS mode; otherwise, it is transmitted in CAN FD mode.

When the interface is in Non-ISO CAN FD or Legacy ISO CAN FD mode, this property is disregarded. In Non-ISO CAN FD and Legacy ISO CAN FD mode, you must use Interface.can_tx_io_mode to switch the transmit mode.

When the assigned database does not define the property in ISO CAN FD mode, the frames are transmitted with Interface.can_io_mode.

Type:

CanIoMode

property can_timing_type: FrmCanTiming

Get or set the CAN frame timing.

Because this property specifies the behavior of the frame’s transfer within the embedded system (for example, a vehicle), it describes the transfer between ECUs in the network. In the following description, transmitting ECU refers to the ECU that transmits the CAN data frame (and possibly receives the associated CAN remote frame). Receiving ECU refers to an ECU that receives the CAN data frame (and possibly transmits the associated CAN remote frame).

When you use the frame within an NI-XNET session, an output session acts as the transmitting ECU, and an input session acts as a receiving ECU. For a description of how these CAN timing types apply to the NI-XNET session mode, refer to CAN Timing Type and Session Mode.

If you are using a FIBEX or AUTOSAR database, this property is a required part of the XML schema for a frame, so the default (initial) value is obtained from the file.

If you are using a CANdb (.dbc) database, this property is an optional attribute in the file. If NI-XNET finds an attribute named GenMsgSendType, that attribute is the default value of this property. If the GenMsgSendType attribute begins with cyclic, this property’s default value is CYCLIC_DATA; otherwise, it is EVENT_DATA. If the CANdb file does not use the GenMsgSendType attribute, this property uses a default value of EVENT_DATA, which you can change in your application.

If you are using an .ncd database or an in-memory database, this property uses a default value of EVENT_DATA. Within your application, change this property to the desired timing type.

Type:

FrmCanTiming

property can_tx_time: float

Get or set the time between consecutive frames from the transmitting ECU.

The units are in seconds.

Although the fractional part of the float can provide resolution of picoseconds, the NI-XNET CAN transmit supports an accuracy of 500 microseconds. Therefore, when used within an NI-XNET output session, this property is rounded to the nearest 500 microsecond increment (0.0005).

For a Frame.can_timing_type of CYCLIC_DATA or CYCLIC_REMOTE, this property specifies the time between consecutive data/remote frames. A time of 0.0 is invalid.

For a Frame.can_timing_type of EVENT_DATA or EVENT_REMOTE, this property specifies the minimum time between consecutive data/remote frames when the event occurs quickly. This is also known as the debounce time or minimum interval. The time is measured from the end of previous frame (acknowledgment) to the start of the next frame. A time of 0.0 specifies no minimum (back to back frames allowed).

If you are using a FIBEX or AUTOSAR database, this property is a required part of the XML schema for a frame, so the default (initial) value is obtained from the file.

If you are using a CANdb (.dbc) database, this property is an optional attribute in the file. If NI-XNET finds an attribute named GenMsgCycleTime, that attribute is interpreted as a number of milliseconds and used as the default value of this property. If the CANdb file does not use the GenMsgCycleTime attribute, this property uses a default value of 0.1 (100 ms), which you can change in your application.

If you are using a .ncd database or an in-memory database, this property uses a default value of 0.1 (100 ms). Within your application, change this property to the desired time.

Type:

float

check_config_status() → None

Check this frame’s configuration status.

By default, incorrectly configured frames in the database are not returned from Cluster.frames because they cannot be used in the bus communication. You can change this behavior by setting Database.show_invalid_from_open to True. When a frame configuration status becomes invalid after the database is opened, the frame still is returned from Cluster.frames even if Database.show_invalid_from_open is False.

Raises:

XnetError – The frame is incorrectly configured.

property cluster: Cluster

Get the parent cluster in which the frame has been created.

You cannot change the parent cluster after the frame object has been created.

Type:

Cluster

property comment: str

Get or set a comment describing the frame object.

A comment is a string containing up to 65535 characters.

Type:

str

property dbc_attributes: DbcAttributeCollection

Access the frame’s DBC attributes.

Type:

DbcAttributeCollection

property default_payload: Iterable[int]

Get or set the frame default payload, specified as a list of ints.

Each int in the list represents a byte (U8). The number of bytes in the list must match the Frame.payload_len property.

This property’s initial value is an list of all 0, except the frame is located in a CAN cluster with J1939 application protocol, which uses 0xFF by default. For the database formats NI-XNET supports, this property is not provided in the database file.

When you use this frame within an NI-XNET session, this property’s use varies depending on the session mode. The following sections describe this property’s behavior for each session mode.

Frame Output Single-Point and Frame Output Queued Modes:

Use this property when a frame transmits prior to a call to write. This can occur when you set the SessionBase.auto_start property to False and start a session prior to writing. When SessionBase.auto_start is True (default), the first frame write also starts frame transmit, so this property is not used.

The following frame configurations potentially can transmit prior to a call to write:

• Frame.can_timing_type is CYCLIC_DATA.

• Frame.can_timing_type is CYCLIC_REMOTE. (for example, a remote frame received prior to a call to writing).

• Frame.can_timing_type is EVENT_REMOTE. (for example, a remote frame received prior to a call to writing).

• Frame.can_timing_type is CYCLIC_EVENT.

• LIN frame in a schedule entry where LinSchedEntry.type is UNCONDITIONAL.

The following frame configurations cannot transmit prior to writing, so this property is not used:

• Frame.can_timing_type is EVENT_DATA..

• LIN frame in a schedule entry where LinSchedEntry.type is SPORADIC or EVENT_TRIGGERED.

Frame Output Stream Mode:

This property is not used. Transmit is limited to frames provided to write.

Signal Output Single-Point, Signal Output Waveform, and Signal Output XY Modes:

Use this property when a frame transmits prior to a call to write. Refer to Frame Output Single-Point and Frame Output Queued Modes for a list of applicable frame configurations.

This property is used as the initial payload, then each XNET Signal Default Value is mapped into that payload, and the result is used for the frame transmit.

Frame Input Stream and Frame Input Queued Modes:

This property is not used. These modes do not return data prior to receiving frames.

Frame Input Single-Point Mode:

This property is used for frames read returns prior to receiving the first frame.

Signal Input Single-Point, Signal Input Waveform, and Signal Input XY Modes:

This property is not used. Each Signal.default is used when reading from a session prior to receiving the first frame.

Type:

list of int

find(object_class: Type[DatabaseObject], object_name: str) → DatabaseObject

Finds an object in the database.

This function finds a database object relative to this parent object. This object may be a grandparent or great-grandparent.

If this object is a direct parent (for example, Frame for Signal), the object_name to search for can be short, and the search proceeds quickly.

If this object is not a direct parent (for example, Database for Signal), the object_name to search for must be qualified such that it is unique within the scope of this object.

For example, if the class of this object is Cluster, and object_class is Signal, you can specify object_name of mySignal, assuming that signal name is unique to the cluster. If not, you must include the Frame name as a prefix, such as myFrameA.mySignal.

NI-XNET supports the following subclasses of DatabaseObject as arguments for object_class:

• nixnet.database.Cluster

• nixnet.database.Frame

• nixnet.database.Pdu

• nixnet.database.Signal

• nixnet.database.SubFrame

• nixnet.database.Ecu

• nixnet.database.LinSched

• nixnet.database.LinSchedEntry

Parameters:

• object_class (DatabaseObject) – The class of the object to find.

• object_name (str) – The name of the object to find.

Returns:

An instance of the found object.

Raises:

• ValueError – Unsupported value provided for argument object_class.

• XnetError – The object is not found.

property id: int

Get or set the frame identifier.

This property is required. If the property does not contain a valid value, and you create an XNET session that uses this frame, the session returns an error. To ensure that the property contains a valid value, you can do one of the following:

• Use a database file (or alias) to create the session.

  The file formats require a valid value in the text for this property.

• Set a value at runtime using this property.

  This is needed when you create your own in-memory database (:memory:) rather than use a file. The property does not contain a default in this case, so you must set a valid value prior to creating a session.

CAN:

For CAN frames, this is the Arbitration ID.

When Frame.can_ext_id is set to False, this is the standard CAN identifier with a size of 11 bits, which results in allowed range of 0-2047. However, the CAN standard disallows identifiers in which the first 7 bits are all recessive, so the working range of identifiers is 0-2031.

When Frame.can_ext_id is set to True, this is the extended CAN identifier with a size of 29 bits, which results in allowed range of 0-536870911.

LIN:

For LIN frames, this is the frame’s ID (unprotected). The valid range for a LIN frame ID is 0-63 (inclusive)

Type:

int

property lin_checksum: FrmLinChecksum

Returns whether the LIN frame transmitted checksum is classic or enhanced.

The enhanced checksum considers the protected identifier when it is generated.

The checksum is determined from the Ecu.lin_protocol_ver properties of the transmitting and receiving the frame. The lower version of both ECUs is significant. If the LIN version of both ECUs is 2.0 or higher, the checksum type is enhanced; otherwise, the checksum type is classic.

Diagnostic frames (with decimal identifier 60 or 61) always use classic checksum, even on LIN 2.x.

Type:

FrmLinChecksum

property mux_data_mux_sig: Signal

Returns a data multiplexer signal object in the frame.

Use the Frame.mux_is_muxed property to determine whether the frame contains a multiplexer signal.

You can create a data multiplexer signal by creating a signal and then setting the Signal.mux_is_data_mux property to True.

A frame can contain only one data multiplexer signal.

Raises:

XnetError – The data multiplexer signal is not defined in the frame

Type:

Signal

property mux_is_muxed: bool

Returns whether this frame is data multiplexed.

This property returns True if the frame contains a multiplexer signal. Frames containing a multiplexer contain subframes that allow using bits of the frame payload for different information (signals) depending on the multiplexer value.

Type:

bool

property mux_static_signals: DbCollection

Collection of static Signal objects in this frame.

Static signals are contained in every frame transmitted, as opposed to dynamic signals, which are transmitted depending on the multiplexer value.

If the frame is not multiplexed, this property returns the same objects as Frame.sigs.

Type:

DbCollection

property mux_subframes: DbCollection

Collection of SubFrame objects in this frame.

A subframe defines a group of signals transmitted using the same multiplexer value. Only one subframe at a time is transmitted in the frame.

A subframe is defined by creating a subframe object as a child of a frame.

Type:

DbCollection

property name: str

String identifying a frame object.

Lowercase letters, uppercase letters, numbers, and the underscore (_) are valid characters for the short name. The space ( ), period (.), and other special characters are not supported within the name. The short name must begin with a letter (uppercase or lowercase) or underscore, and not a number. The short name is limited to 128 characters.

A frame name must be unique for all frames in a cluster.

This short name does not include qualifiers to ensure that it is unique, such as the database and cluster name. It is for display purposes.

Type:

str

property payload_len: int

Get or set the number of bytes of data in the payload.

For CAN and LIN, this is 0-8.

This property is required. If the property does not contain a valid value, and you create an XNET session that uses this frame, the session returns an error. To ensure that the property contains a valid value, you can do one of the following:

• Use a database file (or alias) to create the session.

  The file formats require a valid value in the text for this property.

• Set a value at runtime using this property.

  This is needed when you create your own in-memory database (:memory:) rather than use a file. The property does not contain a default in this case, so you must set a valid value prior to creating a session.

Type:

int

property pdu_properties: Iterable[PduProperties]

Get or set a list that maps existing PDUs to a frame.

A mapped PDU is transmitted inside the frame payload when the frame is transmitted. You can map one or more PDUs to a frame and one PDU to multiple frames.

Mapping PDUs to a frame requires setting pdu_properties with a list of PduProperties tuples. Each tuple contains the following properties:

• PduProperties.pdu: Defines the sequence of values for the other two properties.

• PduProperties.start_bit: Defines the start bit of the PDU inside the frame.

• PduProperties.update_bit: Defines the update bit for the PDU inside the frame. If the update bit is not used, set the value to -1.

Databases imported from FIBEX prior to version 3.0, from DBC, NCD, or LDF files have a strong one-to-one relationship between frames and PDUs. Every frame has exactly one PDU mapped, and every PDU is mapped to exactly one frame.

To unmap PDUs from a frame, set this property to an empty list. A frame without mapped PDUs contains no signals.

For CAN and LIN, NI-XNET supports only a one-to-one relationship between frames and PDUs. For those interfaces, advanced PDU configuration returns raises an exception when calling Frame.check_config_status and when creating a session. If you do not use advanced PDU configuration, you can avoid using PDUs in the database API and create signals and subframes directly on a frame.

Type:

list of PduProperties

property sigs: Iterable[Signal]

Get a list of all Signal objects in the frame.

This property returns a list to all Signal objects in the frame, including static and dynamic signals and the multiplexer signal.

Type:

list of Signal