PySide6.QtSerialBus.QCanSignalDescription¶

class QCanSignalDescription¶

The QCanSignalDescription class describes the rules to extract one value out of the CAN frame and represent it in an application-defined format. More…

Synopsis¶

Methods¶

def __init__()
def addMultiplexSignal()
def bitLength()
def clearMultiplexSignals()
def comment()
def dataEndian()
def dataFormat()
def dataSource()
def factor()
def isValid()
def maximum()
def minimum()
def multiplexSignals()
def multiplexState()
def name()
def offset()
def physicalUnit()
def receiver()
def scaling()
def setBitLength()
def setComment()
def setDataEndian()
def setDataFormat()
def setDataSource()
def setFactor()
def setMultiplexSignals()
def setMultiplexState()
def setName()
def setOffset()
def setPhysicalUnit()
def setRange()
def setReceiver()
def setScaling()
def setStartBit()
def startBit()
def swap()

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

Detailed Description¶

The QCanSignalDescription class can be used to provide a signal description and later use it to decode a received QCanBusFrame or encode the input data into a QCanBusFrame that can be sent to the receiver.

General Description¶

Each CAN frame can contain multiple values. The rules to extract the values from a CAN frame include the following:

Data source (frame ID or payload).

Data endianness. See Data Endianness Processing section for more details.

Data format.

Start bit position.

Data length in bits.

Multiplexing options.

Start bit position is specified relative to the selected data source. The bits are counted starting from the LSB.

Once the data is extracted, it might require conversion to an application-defined format. The following parameters can be used for that:

Various parameters for converting the extracted value to a physical value (factor, offset, scale).

Expected data range.

Data units.

The QCanSignalDescription class provides methods to control all those parameters.

Data Endianness Processing¶

Little endian and big endian data is encoded differently. For big endian values, start bit positions are given for the most significant bit. For little endian values, the start position is that of the least significant bit.

Let’s consider two examples. In both examples we will encode two 12-bit values in the 3-byte payload.

Little Endian¶

For the little endian case the data layout can be represented by the following image:

Here the columns represent bit numbers, and the rows represent byte numbers. LSB marks the first (least significant) bit of the value, and MSB marks the last (most significant) bit of the value. The blue color marks the first value, and the orange color marks the second value.

The information about these values will be encoded in QCanSignalDescription in the following way:

QCanSignalDescription signal1;
signal1.setDataEndian(QSysInfo::Endian::LittleEndian);
signal1.setStartBit(0);
signal1.setBitLength(12);
// other parameters for signal1

QCanSignalDescription signal2;
signal2.setDataEndian(QSysInfo::Endian::LittleEndian);
signal2.setStartBit(12);
signal2.setBitLength(12);
// other parameters for signal2

Big Endian¶

The following image represents the value layout for the big endian case:

The values can be represented in QCanSignalDescription in the following way:

QCanSignalDescription signal1;
signal1.setDataEndian(QSysInfo::Endian::BigEndian);
signal1.setStartBit(7);
signal1.setBitLength(12);
// other parameters for signal1

QCanSignalDescription signal2;
signal2.setDataEndian(QSysInfo::Endian::BigEndian);
signal2.setStartBit(11);
signal2.setBitLength(12);
// other parameters for signal2

Note how the start bits are different from the little endian case. Also the values are aligned differently.

Multiplexed Signals Explained¶

There are two common ways to encode the data in the CAN payload:

Each range of bits always represents the same signal. For example, Bytes 0-1 in a payload can represent an engine speed (in rpm), and Bytes 2-3 can represent the vehicle speed (in km/h).

The same range of bits can represent different data, depending on the values of some other bits in the payload. For example, if Byte 0 has the value 0, the Bytes 1-2 represent an engine speed (in rpm), and if Byte 0 has the value 1, the same Bytes 1-2 represent a vehicle speed (in km/h).

The second case uses signal multiplexing. In the provided example we will have three signals. The first signal represents the value of Byte 0 and acts like a multiplexor signal. The other two signals represent an engine speed and a vehicle speed respectively, but only one of them can be extracted from the CAN payload at a time. Which signal should be extracted is defined by the value of the multiplexor signal.

In more complicated cases the payload can have multiple multiplexor signals. In such cases the signal can be extracted from the payload only when all multiplexors contain the expected values.

Value Conversions¶

In many cases the signals transferred over CAN bus cannot hold the full range of the physical values that they represent. To overcome these limitations, the physical values are converted to a smaller range before transmission, and can be restored on the receiving end.

The following formulas are used to convert between the physical value and the signal’s value:

physicalValue = scaling * (signalValue * factor + offset);
signalValue = (physicalValue / scaling - offset) / factor;

The factor and scaling parameters cannot be equal to 0.

If any of the parameters equals to qQNaN(), it is not used during the conversion. If all of the parameters are equal to qQNaN() (which is the default), the conversion is not performed.

__init__()¶

Creates an empty signal description.

__init__(other)

Parameters:: other – QCanSignalDescription

Creates a signal description with the values copied from other.

addMultiplexSignal(name, ranges)¶

Parameters:

name – str
ranges – .list of QCanSignalDescription.MultiplexValueRange

addMultiplexSignal(name, value)

Parameters:

name – str
value – object

This is an overloaded function.

This is a convenience overload for the case when the multiplexor signal is expected to have only one specific value, not a range of values.

The name parameter contains the name of the multiplexor signal, and the value parameter contains the desired value.

If this signal already has desired value ranges for the multiplexor signal name, the ranges are overwritten.

See also

multiplexState() multiplexSignals() clearMultiplexSignals() setMultiplexSignals()

bitLength()¶

Return type:: int

Returns the bit length of the signal’s value.

See also

setBitLength() startBit() setStartBit()

clearMultiplexSignals()¶

Removes all multiplexor signals for this signal.

See also

multiplexSignals() setMultiplexSignals() addMultiplexSignal()

comment()¶

Return type:: str

Returns the comment for the signal.

This parameter is introduced only for extra description. It’s not used during signal processing.

See also

setComment()

dataEndian()¶

Return type:: Endian

Returns the data endian of the signal’s value.

By default, BigEndian is used.

Note

The data endian is ignored if the dataFormat() is set to AsciiString .