nixnet.database.cluster

class nixnet.database._cluster.Cluster(**kwargs)

Bases: nixnet.database._database_object.DatabaseObject

Database cluster

application_protocol

Get or set the application protocol.

Type:AppProtocol

baud_rate

Get or set the buad rate all custer nodes use.

This baud rate represents the rate from the database, so it is read-only from the session. Use a session interface property (for example, Interface.baud_rate) to override the database baud rate with an application-specific baud rate.

CAN

For CAN, this rate can be 33333, 40000, 50000, 62500, 80000, 83333, 100000, 125000, 160000, 200000, 250000, 400000, 500000, 800000, or 1000000. Some transceivers may support only a subset of these values.

LIN

For LIN, this rate can be 2400-20000 inclusive.

If you need values other than these, use the custom settings as described in Interface.baud_rate.

Type:int

can_fd_baud_rate

Get or set the fast data baud rate when Cluster.can_io_mode is CanIoMode.CAN_FD_BRS.

Refer to the CanIoMode for a description of CanIoMode.CAN_FD_BRS. Use a session interface property (for example, Interface.can_fd_baud_rate) to override the database fast baud rate with an application-specific fast baud rate.

NI-XNET CAN hardware currently accepts the following numeric baud rates: 200000, 250000, 400000, 500000, 800000, 1000000, 1250000, 1600000, 2000000, 2500000, 4000000, 5000000, and 8000000. Some transceivers may support only a subset of these values.

If you need values other than these, use the custom settings as described in Interface.can_fd_baud_rate.

Type:int

can_fd_iso_mode

Returns the mode of a CAN FD cluster.

The default is CanFdIsoMode.ISO. You define the value in a dialog box that appears when you define an alias for the database.

Type:CanFdIsoMode

can_io_mode

Get or set the CAN I/O Mode of the cluster.

Type:CanIoMode

check_config_status()

Check this cluster’s configuration status.

By default, incorrectly configured clusters in the database are not returned from Database.clusters 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 cluster configuration status becomes invalid after the database is opened, the cluster still is returned from Database.clusters even if Database.show_invalid_from_open is False.

Raises:XnetError – The cluster is incorrectly configured.

comment

Get or set a comment describing the cluster object.

A comment is a string containing up to 65535 characters.

Type:str

dbc_attributes

Access the cluster’s DBC attributes.

Type:DbcAttributeCollection

ecus

Returns a collection of Ecu objects in this cluster.

An ECU is assigned to a cluster when the ECU object is created. You cannot change this assignment afterwards.

Type:DbCollection

export(db_filepath)

Exports this cluster to a CANdb++ or LIN database file format.

A CAN cluster is exported as a CANdb++ database file (.dbc). A LIN cluster is exported as a LIN database file (.ldf). If the target file exists, it is overwritten.

Exporting a cluster is not supported under Real-Time (RT).

Parameters:db_filepath (str) – Contains the pathname to the database file.

find(object_class, object_name)

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.

frames

Returns a collection of Frame objects in this cluster.

A frame is assigned to a cluster when the frame object is created. You cannot change this assignment afterwards.

Type:DbCollection

lin_schedules

Returns a collection of LinSched defined in this cluster.

You assign a LIN schedule to a cluster when you create the LIN schedule object. You cannot change this assignment afterwards. The schedules in this collection are sorted alphabetically by schedule name.

Type:DbCollection

lin_tick

Returns the relative time between LIN ticks (relative f64 in seconds).

The LinSchedEntry.delay property must be a multiple of this tick.

This tick is referred to as the “timebase” in the LIN specification.

The Ecu.lin_master property defines the Tick property in this cluster. You cannot use the Tick property when there is no LIN Master property defined in this cluster.

Type:float

merge(source_obj, copy_mode, prefix, wait_for_complete)

Merges database objects and related subobjects from the source to this cluster.

The source can be any of the following objects:

• Frame
• Pdu
• Ecu
• LinSched
• Cluster

All listed objects must have unique names in the cluster. They are referenced here as objects, as opposed to child objects (for example, a signal is a child of a frame).

If the source object name is not used in the target cluster, this function copies the source objects with the child objects to the target. If an object with the same name exists in this cluster, you can avoid name collisions by specifying the prefix to be added to the name.

If an object with the same name exists in this cluster, the merge behavior depends on the copy_mode input.

Example

Target frame F1(v1) has signals S1 and S2(v1). Source frame F1(v2) has signals S2(v2) and S3.

(v1) and (v2) are two versions of one object with same name, but with different properties.

• Result when copy_mode is COPY_USE_SOURCE: F1(v2), S2(v2), S3.
• Result when copy_mode is COPY_USE_TARGET: F1(v1), S1, S2(v1).
• Result when copy_mode is MERGE_USE_SOURCE: F1(v2), S1, S2(v2), S3.
• Result when copy_mode is MERGE_USE_TARGET: F1(v1), S1, S2(v1), S3.

If the source object is a cluster, this function copies all contained PDUs, ECUs, and LIN schedules with their child objects to this cluster.

Depending on the number of contained objects in the source and destination clusters, the execution can take a longer time. If wait_for_complete is True, this function waits until the merging process gets completed. If the execution completes without errors, perecent_complete returns 100. If wait_for_complete is False, the function returns quickly, and perecent_complete returns values less than 100. You must call Cluster.merge repeatedly until perecent_complete returns 100. You can use the time between calls to perform asynchronous tasks.

Parameters:

• source_obj (object) – The object to be merged into this cluster.
• copy_mode (Merge) – Defines the merging behavior if this cluster already contains an object with the same name.
• prefix (str) – The prefix to be added to the source object name if an object with the same name and type exists in this cluster.
• wait_for_complete (bool) – Determines whether the function returns directly or waits until the entire transmission is completed.

Returns:

A value which indicates the merging progress as a percentage. 100 indicates completion.

Return type:

int

name

Get or set the name of the cluster 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.

If you use a FIBEX file, the short name comes from the file. If you use a CANdb (.dbc), LDF (.ldf), or NI-CAN (.ncd) file, no cluster name is stored in the file, so NI-XNET uses the name Cluster. If you create the cluster yourself, the name that you provide is used.

A cluster name must be unique for all clusters in a database.

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

Type:str

pdus

Returns a collection of Pdu objects in this cluster.

A PDU is assigned to a cluster when the PDU object is created. You cannot change this assignment afterwards.

Type:DbCollection

pdus_reqd

Returns whether using PDUs in the database API is required for this cluster.

If this property returns False, it is safe to use signals as child objects of a frame without PDUs. This behavior is compatible with NI-XNET 1.1 or earlier. Clusters from .dbc, .ncd, or FIBEX 2 files always return False for this property, so using PDUs from those files is not required.

If this property returns True, the cluster contains PDU configuration, which requires reading the PDUs as frame child objects and then signals as PDU child objects, as shown in the following figure.

Internally, the database always uses PDUs, but shows the same signal objects also as children of a frame.

For this property to return False, the following conditions must be fulfilled for all frames in the cluster:

• Only one PDU is mapped to the frame.
• This PDU is not mapped to other frames.
• The PDU Start Bit in the frame is 0.
• The PDU Update Bit is not used.

If the conditions are not fulfilled for a given frame, signals from the frame are still returned, but reading the property returns a warning.

Type:bool

protocol

Get or set the cluster protocol.

Type:Protocol

sigs

Returns a list of all Signal objects in this cluster.

Type:list of Signal