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
bitLength()
def
comment()
def
dataEndian()
def
dataFormat()
def
dataSource()
def
factor()
def
isValid()
def
maximum()
def
minimum()
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
setName()
def
setOffset()
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 receivedQCanBusFrame
or encode the input data into aQCanBusFrame
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, andMSB
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), andBytes 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 value0
, theBytes 1-2
represent an engine speed (in rpm), and ifByte 0
has the value1
, the sameBytes 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 thevalue
parameter contains the desired value.If this signal already has desired value ranges for the multiplexor signal
name
, the ranges are overwritten.- bitLength()¶
- Return type:
int
Returns the bit length of the signal’s value.
See also
- clearMultiplexSignals()¶
Removes all
multiplexor signals
for this signal.- 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
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 toAsciiString
.See also
setDataEndian()
Endian
- dataFormat()¶
- Return type:
Returns the data format of the signal’s value.
By default,
SignedInteger
is used.See also
- dataSource()¶
- Return type:
Returns the data source of the signal’s value.
By default,
Payload
is used.See also
- factor()¶
- Return type:
float
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.See also
- isValid()¶
- Return type:
bool
Returns
true
when the signal description is valid andfalse
otherwise.A valid signal description must fulfill the following conditions:
have a non-empty
name()
have
bitLength()
== 32
if thedataFormat()
isFloat
have
bitLength()
== 64
if thedataFormat()
isDouble
the
bitLength()
must be a multiple of8
if thedataFormat()
isAsciiString
the
bitLength()
must be greater than0
and less than or equal to64
.
See also
- maximum()¶
- Return type:
float
Returns the maximum supported value for the signal.
By default the function returns qQNaN(), which means that there is no maximum value.
See also
- minimum()¶
- Return type:
float
Returns the minimum supported value for the signal.
By default the function returns qQNaN(), which means that there is no minimum value.
See also
- multiplexSignals()¶
- Return type:
.QHashQString,list of QCanSignalDescription.MultiplexValueRange
Returns the
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()¶
- Return type:
Returns the multiplex state of the signal.
See the
Multiplexed Signals Explained
section for more details on multiplexed signals.By default this method returns
None
.See also
- name()¶
- Return type:
str
Returns the name of the signal.
- offset()¶
- Return type:
float
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.See also
- physicalUnit()¶
- Return type:
str
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.
See also
- receiver()¶
- Return type:
str
Returns the receiver node for this signal.
This parameter is introduced only for extra description. It’s not used during signal processing.
See also
- scaling()¶
- Return type:
float
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.See also
- setBitLength(length)¶
- Parameters:
length – int
Sets the bit length of the signal’s value to
length
.See also
- setComment(text)¶
- Parameters:
text – str
Sets the comment for the signal to
text
.This parameter is introduced only for extra description. It’s not used during signal processing.
See also
Sets the data endian of the signal’s value to
endian
.See also
dataEndian()
Endian
- setDataFormat(format)¶
- Parameters:
format –
DataFormat
Sets the data format of the signal’s value to
format
.See also
- setDataSource(source)¶
- Parameters:
source –
DataSource
Sets the data source of the signal’s value to
source
.See also
- setFactor(factor)¶
- Parameters:
factor – float
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.See also
- setMultiplexSignals(multiplexorSignals)¶
- Parameters:
multiplexorSignals – .QHashQString,list of QCanSignalDescription.MultiplexValueRange
Sets the
multiplexor signals
for this signal tomultiplexorSignals
.The
multiplexorSignals
hash must contain signal names as keys and respective desired value ranges as values.- setMultiplexState(state)¶
- Parameters:
state –
MultiplexState
Sets the multiplex state of the signal to
state
.See the
Multiplexed Signals Explained
section for more details on multiplexed signals.See also
- setName(name)¶
- Parameters:
name – str
Sets the name of the signal to
name
.The signal’s name must be unique within a CAN message.
See also
- setOffset(offset)¶
- Parameters:
offset – float
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.See also
- setPhysicalUnit(unit)¶
- Parameters:
unit – str
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.
See also
- setRange(minimum, maximum)¶
- Parameters:
minimum – float
maximum – float
Sets the
minimum
andmaximum
for the signal’s value.Setting one or both of the parameters to qQNaN() means that the corresponding limit will not be used.
- setReceiver(receiver)¶
- Parameters:
receiver – str
Sets the
receiver
node for this signal.This parameter is introduced only for extra description. It’s not used during signal processing.
See also
- setScaling(scaling)¶
- Parameters:
scaling – float
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.See also
- setStartBit(bit)¶
- Parameters:
bit – int
Sets the start bit of the signal’s value in the
dataSource()
tobit
.See also
- startBit()¶
- Return type:
int
Returns the start bit of the signal’s value in the
dataSource()
.See also
- swap(other)¶
- Parameters:
other –
QCanSignalDescription
- class MultiplexValueRange¶
Synopsis¶
Methods¶
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¶
- PySide6.QtSerialBus.QCanSignalDescription.MultiplexValueRange.minimum¶
- PySide6.QtSerialBus.QCanSignalDescription.MultiplexValueRange.maximum¶
- __ne__(rhs)¶
- Parameters:
rhs –
MultiplexValueRange
- Return type:
bool
- __eq__(rhs)¶
- Parameters:
rhs –
MultiplexValueRange
- Return type:
bool