nixnet.database.frame¶
-
class
nixnet.database._frame.
Frame
(**kwargs)[source]¶ Bases:
nixnet.database._database_object.DatabaseObject
Database frame
-
application_protocol
¶ Get or set the frame’s application protocol.
Type: AppProtocol
-
can_ext_id
¶ 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
-
can_io_mode
¶ 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
-
can_timing_type
¶ 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 isEVENT_DATA
. If the CANdb file does not use the GenMsgSendType attribute, this property uses a default value ofEVENT_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
-
can_tx_time
¶ 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
ofCYCLIC_DATA
orCYCLIC_REMOTE
, this property specifies the time between consecutive data/remote frames. A time of 0.0 is invalid.For a
Frame.can_timing_type
ofEVENT_DATA
orEVENT_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
()[source]¶ 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 settingDatabase.show_invalid_from_open
to True. When a frame configuration status becomes invalid after the database is opened, the frame still is returned fromCluster.frames
even ifDatabase.show_invalid_from_open
is False.Raises: XnetError
– The frame is incorrectly configured.
-
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
-
comment
¶ Get or set a comment describing the frame object.
A comment is a string containing up to 65535 characters.
Type: str
-
dbc_attributes
¶ Access the frame’s DBC attributes.
Type: DbcAttributeCollection
-
default_payload
¶ 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 uses0xFF
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 toFalse
and start a session prior to writing. WhenSessionBase.auto_start
isTrue
(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
isCYCLIC_DATA
.Frame.can_timing_type
isCYCLIC_REMOTE
. (for example, a remote frame received prior to a call to writing).Frame.can_timing_type
isEVENT_REMOTE
. (for example, a remote frame received prior to a call to writing).Frame.can_timing_type
isCYCLIC_EVENT
.- LIN frame in a schedule entry where
LinSchedEntry.type
isUNCONDITIONAL
.
The following frame configurations cannot transmit prior to writing, so this property is not used:
Frame.can_timing_type
isEVENT_DATA
..- LIN frame in a schedule entry where
LinSchedEntry.type
isSPORADIC
orEVENT_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, object_name)[source]¶ 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
forSignal
), theobject_name
to search for can be short, and the search proceeds quickly.If this object is not a direct parent (for example,
Database
forSignal
), theobject_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
, andobject_class
isSignal
, you can specifyobject_name
ofmySignal
, assuming that signal name is unique to the cluster. If not, you must include theFrame
name as a prefix, such asmyFrameA.mySignal
.NI-XNET supports the following subclasses of
DatabaseObject
as arguments forobject_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 argumentobject_class
.XnetError
– The object is not found.
-
id
¶ 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 toFalse
, 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 toTrue
, 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
-
lin_checksum
¶ 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
-
mux_data_mux_sig
¶ 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 toTrue
.A frame can contain only one data multiplexer signal.
Raises: XnetError
– The data multiplexer signal is not defined in the frameType: Signal
-
mux_is_muxed
¶ 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
-
mux_static_signals
¶ 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
-
mux_subframes
¶ 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
-
name
¶ 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
-
payload_len
¶ 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
-
pdu_properties
¶ 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
-