就业培训     下载中心     Wiki     联络 登录   注册
  1. 首页
  2. Qt 6.7.2
  3. Qt Serial Bus
  4. C++ 类
  5. QCanSignalDescription

QCanSignalDescription Class

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

头： #include <QCanSignalDescription>
CMake: find_package(Qt6 REQUIRED COMPONENTS SerialBus)
target_link_libraries(mytarget PRIVATE Qt6::SerialBus)
qmake: QT += serialbus
Since: Qt 6.5
状态： Preliminary

该类在开发且可能改变。

公共类型

(从 6.5 起) struct MultiplexValueRange
MultiplexSignalValues
MultiplexValues

公共函数

QCanSignalDescription ()
QCanSignalDescription (const QCanSignalDescription & other )
QCanSignalDescription (QCanSignalDescription && other )
~QCanSignalDescription ()
void addMultiplexSignal (const QString & name , const QCanSignalDescription::MultiplexValues & ranges )
void addMultiplexSignal (const QString & name , const QVariant & value )
quint16 bitLength () const
void clearMultiplexSignals ()
QString comment () const
QSysInfo::Endian dataEndian () const
QtCanBus::DataFormat dataFormat () const
QtCanBus::DataSource dataSource () const
double factor () const
bool isValid () const
double maximum () const
double minimum () const
QCanSignalDescription::MultiplexSignalValues multiplexSignals () const
QtCanBus::MultiplexState multiplexState () const
QString name () const
double offset () const
QString physicalUnit () const
QString receiver () const
double scaling () const
void setBitLength (quint16 length )
void setComment (const QString & text )
void setDataEndian (QSysInfo::Endian endian )
void setDataFormat (QtCanBus::DataFormat format )
void setDataSource (QtCanBus::DataSource source )
void setFactor (double factor )
void setMultiplexSignals (const QCanSignalDescription::MultiplexSignalValues & multiplexorSignals )
void setMultiplexState (QtCanBus::MultiplexState state )
void setName (const QString & name )
void setOffset (double offset )
void setPhysicalUnit (const QString & unit )
void setRange (double minimum , double maximum )
void setReceiver (const QString & receiver )
void setScaling (double scaling )
void setStartBit (quint16 bit )
quint16 startBit () const
QCanSignalDescription & operator= (const QCanSignalDescription & other )
QCanSignalDescription & operator= (QCanSignalDescription && other )

详细描述

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 章节了解更多细节。
  • 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 ， Bytes 1-2 represent an engine speed (in rpm), and if Byte 0 has the value 1 ，相同 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.

成员类型文档编制

[alias] QCanSignalDescription:: MultiplexSignalValues

[alias] QCanSignalDescription:: MultiplexValues

成员函数文档编制

QCanSignalDescription:: QCanSignalDescription ()

Creates an empty signal description.

QCanSignalDescription:: QCanSignalDescription (const QCanSignalDescription & other )

Creates a signal description with the values copied from other .

[noexcept] QCanSignalDescription:: QCanSignalDescription ( QCanSignalDescription && other )

Creates a signal description by moving from other .

注意： The moved-from QCanSignalDescription object can only be destroyed or assigned to. The effect of calling other functions than the destructor or one of the assignment operators is undefined.

[noexcept] QCanSignalDescription:: ~QCanSignalDescription ()

Destroys this signal description.

void QCanSignalDescription:: addMultiplexSignal (const QString & name , const QCanSignalDescription::MultiplexValues & ranges )

Adds a new multiplexor signal for this signal. The name parameter contains the name of the multiplexor signal, and the ranges parameter contains the desired value ranges.

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

另请参阅 multiplexState (), multiplexSignals (), clearMultiplexSignals ()，和 setMultiplexSignals ().

void QCanSignalDescription:: addMultiplexSignal (const QString & name , const QVariant & value )

这是重载函数。

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.

另请参阅 multiplexState (), multiplexSignals (), clearMultiplexSignals ()，和 setMultiplexSignals ().

quint16 QCanSignalDescription:: bitLength () const

Returns the bit length of the signal's value.

另请参阅 setBitLength (), startBit ()，和 setStartBit ().

void QCanSignalDescription:: clearMultiplexSignals ()

Removes all multiplexor signals for this signal.

另请参阅 multiplexSignals (), setMultiplexSignals ()，和 addMultiplexSignal ().

QString QCanSignalDescription:: comment () const

Returns the comment for the signal.

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

另请参阅 setComment ().

QSysInfo::Endian QCanSignalDescription:: dataEndian () const

Returns the data endian of the signal's value.

默认情况下， BigEndian 被使用。

注意： The data endian is ignored if the dataFormat () 被设为 AsciiString .

另请参阅 setDataEndian () 和 QSysInfo::Endian .

QtCanBus::DataFormat QCanSignalDescription:: dataFormat () const

Returns the data format of the signal's value.

默认情况下， SignedInteger 被使用。

另请参阅 setDataFormat () 和 QtCanBus::DataFormat .

QtCanBus::DataSource QCanSignalDescription:: dataSource () const

Returns the data source of the signal's value.

默认情况下， Payload 被使用。

另请参阅 setDataSource () 和 QtCanBus::DataSource .

double QCanSignalDescription:: factor () const

Returns the factor that is used to convert the signal's value to a physical value and back.

By default the function returns qQNaN (), which means that a factor is not used.

The Value Conversions section explains how this parameter is used.

另请参阅 setFactor (), offset ()，和 scaling ().

bool QCanSignalDescription:: isValid () const

返回 true when the signal description is valid and false 否则。

A valid signal description must fulfill the following conditions:

另请参阅 bitLength (), dataFormat ()，和 name ().

double QCanSignalDescription:: maximum () const

Returns the maximum supported value for the signal.

By default the function returns qQNaN (), which means that there is no maximum value.

另请参阅 setRange () 和 minimum ().

double QCanSignalDescription:: minimum () const

Returns the minimum supported value for the signal.

By default the function returns qQNaN (), which means that there is no minimum value.

另请参阅 setRange () 和 maximum ().

QCanSignalDescription::MultiplexSignalValues QCanSignalDescription:: multiplexSignals () const

返回 multiplexor signals and their desired values that are used to properly identify this signal.

The returned hash contains signal names as keys and respective desired ranges of values as values.

This signal's value can be extracted from the payload only when all the signals from the hash have the expected values.

另请参阅 multiplexState (), clearMultiplexSignals (), setMultiplexSignals ()，和 addMultiplexSignal ().

QtCanBus::MultiplexState QCanSignalDescription:: multiplexState () const

Returns the multiplex state of the signal.

见 Multiplexed Signals Explained section for more details on multiplexed signals.

By default this method returns None .

另请参阅 setMultiplexState () 和 QtCanBus::MultiplexState .

QString QCanSignalDescription:: name () const

Returns the name of the signal.

另请参阅 setName () 和 isValid ().

double QCanSignalDescription:: offset () const

Returns the offset that is used to convert the signal's value to a physical value and back.

By default the function returns qQNaN (), which means that an offset is not used.

The Value Conversions section explains how this parameter is used.

另请参阅 setOffset (), factor ()，和 scaling ().

QString QCanSignalDescription:: physicalUnit () const

Returns the physical unit (e.g. km/h) of the signal's value or an empty string if the unit is not set.

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

另请参阅 setPhysicalUnit ().

QString QCanSignalDescription:: receiver () const

Returns the receiver node for this signal.

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

另请参阅 setReceiver ().

double QCanSignalDescription:: scaling () const

Returns the scaling that is used to convert the signal's value to a physical value and back.

By default the function returns qQNaN (), which means that scaling is not used.

The Value Conversions section explains how this parameter is used.

另请参阅 setScaling (), offset ()，和 factor ().

void QCanSignalDescription:: setBitLength ( quint16 length )

Sets the bit length of the signal's value to length .

另请参阅 bitLength (), startBit ()，和 setStartBit ().

void QCanSignalDescription:: setComment (const QString & text )

Sets the comment for the signal to text .

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

另请参阅 comment ().

void QCanSignalDescription:: setDataEndian ( QSysInfo::Endian endian )

Sets the data endian of the signal's value to endian .

另请参阅 dataEndian () 和 QSysInfo::Endian .

void QCanSignalDescription:: setDataFormat ( QtCanBus::DataFormat format )

Sets the data format of the signal's value to format .

另请参阅 dataFormat () 和 QtCanBus::DataFormat .

void QCanSignalDescription:: setDataSource ( QtCanBus::DataSource source )

Sets the data source of the signal's value to source .

另请参阅 dataSource () 和 QtCanBus::DataSource .

void QCanSignalDescription:: setFactor ( double factor )

Sets the factor that is used to convert the signal's value to a physical value and back to factor .

Pass qQNaN () to this method to skip this parameter during the conversion.

The factor cannot be 0. An attempt to set a zero factor is equivalent to setting it to qQNaN ().

The Value Conversions section explains how this parameter is used.

另请参阅 factor (), setOffset ()，和 setScaling ().

void QCanSignalDescription:: setMultiplexSignals (const QCanSignalDescription::MultiplexSignalValues & multiplexorSignals )

设置 multiplexor signals for this signal to multiplexorSignals .

The multiplexorSignals hash must contain signal names as keys and respective desired value ranges as values.

另请参阅 multiplexState (), multiplexSignals (), clearMultiplexSignals ()，和 addMultiplexSignal ().

void QCanSignalDescription:: setMultiplexState ( QtCanBus::MultiplexState state )

Sets the multiplex state of the signal to state .

见 Multiplexed Signals Explained section for more details on multiplexed signals.

另请参阅 multiplexState () 和 QtCanBus::MultiplexState .

void QCanSignalDescription:: setName (const QString & name )

Sets the name of the signal to name .

The signal's name must be unique within a CAN message.

另请参阅 name ().

void QCanSignalDescription:: setOffset ( double offset )

Sets the offset that is used to convert the signal's value to a physical value and back to offset .

Pass qQNaN () to this method to skip this parameter during the conversion.

The Value Conversions section explains how this parameter is used.

另请参阅 offset (), setFactor ()，和 setScaling ().

void QCanSignalDescription:: setPhysicalUnit (const QString & unit )

Sets the physical unit (e.g. km/h) of the signal's value.

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

另请参阅 physicalUnit ().

void QCanSignalDescription:: setRange ( double minimum , double maximum )

设置 minimum and maximum for the signal's value.

Setting one or both of the parameters to qQNaN () means that the corresponding limit will not be used.

另请参阅 minimum () 和 maximum ().

void QCanSignalDescription:: setReceiver (const QString & receiver )

设置 receiver node for this signal.

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

另请参阅 receiver ().

void QCanSignalDescription:: setScaling ( double scaling )

Sets the scaling that is used to convert the signal's value to a physical value and back to scaling .

Pass qQNaN () to this method to skip this parameter during the conversion.

The scaling cannot be 0. An attempt to set zero scaling is equivalent to setting it to qQNaN ().

The Value Conversions section explains how this parameter is used.

另请参阅 scaling (), setOffset ()，和 setFactor ().

void QCanSignalDescription:: setStartBit ( quint16 bit )

Sets the start bit of the signal's value in the dataSource () 到 bit .

另请参阅 startBit (), bitLength ()，和 setBitLength ().

quint16 QCanSignalDescription:: startBit () const

Returns the start bit of the signal's value in the dataSource ().

另请参阅 setStartBit (), bitLength ()，和 setBitLength ().

QCanSignalDescription &QCanSignalDescription:: operator= (const QCanSignalDescription & other )

Assigns the values from other to this signal description.

[noexcept] QCanSignalDescription &QCanSignalDescription:: operator= ( QCanSignalDescription && other )

Move-assigns the values from other to this signal description.

注意： The moved-from QCanSignalDescription object can only be destroyed or assigned to. The effect of calling other functions than the destructor or one of the assignment operators is undefined.

内容