Back to Qt.io
Contact Us Blog Download Qt
Sur cette page

QCanSignalDescription Class

La classe QCanSignalDescription définit les règles permettant d'extraire une valeur d'une trame CAN et de la représenter dans un format défini par l'application. En savoir plus...

En-tête : #include <QCanSignalDescription>
CMake : find_package(Qt6 REQUIRED COMPONENTS SerialBus)
target_link_libraries(mytarget PRIVATE Qt6::SerialBus)
qmake : QT += serialbus
Depuis : Qt 6.5
Statut : Aperçu technologique

Cette classe est en avant-première technologique et est susceptible d'être modifiée.

Types publics

(since 6.5) struct MultiplexValueRange
MultiplexSignalValues
MultiplexValues

Fonctions publiques

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=(QCanSignalDescription &&other)
QCanSignalDescription &operator=(const QCanSignalDescription &other)

Description détaillée

La classe QCanSignalDescription permet de fournir une description de signal, puis de l'utiliser pour décoder une « QCanBusFrame » reçue ou pour encoder les données d'entrée en une « QCanBusFrame » pouvant être envoyée au récepteur.

Description générale

Chaque trame CAN peut contenir plusieurs valeurs. Les règles permettant d'extraire les valeurs d'une trame CAN sont les suivantes :

  • Source des données (ID de trame ou charge utile).
  • L'endianness des données. Voir la section « Data Endianness Processing » pour plus de détails.
  • Format des données.
  • Position du bit de départ.
  • Longueur des données en bits.
  • Options de multiplexage.

La position du bit de départ est spécifiée par rapport à la source de données sélectionnée. Les bits sont comptés à partir du LSB.

Une fois les données extraites, il peut être nécessaire de les convertir dans un format défini par l'application. Les paramètres suivants peuvent être utilisés à cet effet :

  • Divers paramètres permettant de convertir la valeur extraite en une valeur physique (facteur, décalage, échelle).
  • Plage de données attendue.
  • Unités de données.

La classe QCanSignalDescription fournit des méthodes permettant de contrôler tous ces paramètres.

Traitement de l'endianness des données

Les données « little endian » et « big endian » sont codées différemment. Pour les valeurs « big endian », les positions des bits de départ correspondent au bit le plus significatif. Pour les valeurs « little endian », la position de départ correspond au bit le moins significatif.

Prenons deux exemples. Dans les deux cas, nous allons encoder deux valeurs de 12 bits dans une charge utile de 3 octets.

Little-endian

Dans le cas du little endian, la disposition des données peut être représentée par l’image suivante :

Disposition des bits du signal CAN en « little endian » : les blocs bleus et orange indiquent deux valeurs sur les octets 0 à 2, avec les positions du LSB et du MSB

Ici, les colonnes représentent les numéros de bits et les lignes représentent les numéros d’octets. LSB indique le premier bit (le moins significatif) de la valeur, et MSB indique le dernier bit (le plus significatif) de la valeur. La couleur bleue correspond à la première valeur, et la couleur orange à la deuxième valeur.

Les informations relatives à ces valeurs seront encodées dans QCanSignalDescription de la manière suivante :

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

L’image suivante représente la disposition des valeurs pour le cas « big endian » :

Disposition des bits du signal CAN en mode « big-endian » : les blocs bleus et orange indiquent deux valeurs sur les octets 0 à 2, avec les positions du bit de poids fort (MSB) et du bit de poids faible (LSB)

Les valeurs peuvent être représentées dans `QCanSignalDescription` de la manière suivante :

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

Notez que les bits de départ diffèrent de ceux du cas « little endian ». De même, les valeurs sont alignées différemment.

Explication des signaux multiplexés

Il existe deux méthodes courantes pour encoder les données dans la charge utile CAN :

  • Chaque plage de bits représente toujours le même signal. Par exemple, Bytes 0-1 dans une charge utile peut représenter le régime moteur (en tr/min), et Bytes 2-3 peut représenter la vitesse du véhicule (en km/h).
  • Une même séquence de bits peut représenter des données différentes, en fonction des valeurs d’autres bits de la charge utile. Par exemple, si Byte 0 prend la valeur 0, les Bytes 1-2 représentent un régime moteur (en tr/min), et si Byte 0 prend la valeur 1, ces mêmes Bytes 1-2 représentent une vitesse du véhicule (en km/h).

Le deuxième cas utilise le multiplexage des signaux. Dans l’exemple fourni, nous aurons trois signaux. Le premier signal représente la valeur de Byte 0 et agit comme un signal de multiplexeur. Les deux autres signaux représentent respectivement le régime moteur et la vitesse du véhicule, mais un seul d’entre eux peut être extrait de la charge utile CAN à la fois. Le signal à extraire est déterminé par la valeur du signal de multiplexage.

Dans des cas plus complexes, la charge utile peut comporter plusieurs signaux de multiplexage. Dans ces cas-là, le signal ne peut être extrait de la charge utile que lorsque tous les multiplexeurs contiennent les valeurs attendues.

Conversions de valeurs

Dans de nombreux cas, les signaux transférés via le bus CAN ne peuvent pas couvrir toute la plage des valeurs physiques qu’ils représentent. Pour pallier ces limitations, les valeurs physiques sont converties dans une plage plus restreinte avant la transmission, puis peuvent être restaurées du côté récepteur.

Les formules suivantes sont utilisées pour effectuer la conversion entre la valeur physique et la valeur du signal :

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

Le facteur et les paramètres de mise à l’échelle ne peuvent pas être égaux à ` 0`.

Si l’un des paramètres est égal à qQNaN(), il n’est pas utilisé lors de la conversion. Si tous les paramètres sont égaux à qQNaN() (ce qui est la valeur par défaut), la conversion n’est pas effectuée.

Documentation sur les types de membres

[alias] QCanSignalDescription::MultiplexSignalValues

[alias] QCanSignalDescription::MultiplexValues

Documentation sur les fonctions des membres

QCanSignalDescription::QCanSignalDescription()

Crée une description de signal vide.

QCanSignalDescription::QCanSignalDescription(const QCanSignalDescription &other)

Crée une description de signal à partir des valeurs copiées depuis other.

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

Crée une description de signal à partir de other.

Remarque : l'objet `QCanSignalDescription` à partir duquel la description a été déplacée ne peut être que détruit ou affecté. L'effet de l'appel de fonctions autres que le destructeur ou l'un des opérateurs d'affectation est indéfini.

[constexpr noexcept default] QCanSignalDescription::~QCanSignalDescription()

Supprime cette description de signal.

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

Ajoute une nouvelle « multiplexor signal » pour ce signal. Le paramètre « name » contient le nom du signal du multiplexeur, et le paramètre « ranges » contient les plages de valeurs souhaitées.

Si ce signal dispose déjà de plages de valeurs souhaitées pour le signal de multiplexeur name, celles-ci sont écrasées.

Voir également multiplexState(), multiplexSignals(), clearMultiplexSignals() et setMultiplexSignals().

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

Il s'agit d'une surcharge de commodité destinée aux cas où le signal du multiplexeur ne doit prendre qu'une seule valeur spécifique, et non une plage de valeurs.

Le paramètre « name » contient le nom du signal du multiplexeur, et le paramètre « value » contient la valeur souhaitée.

Si ce signal dispose déjà de plages de valeurs souhaitées pour le signal du multiplexeur name, celles-ci sont écrasées.

Il s’agit d’une fonction surchargée.

Voir également multiplexState(), multiplexSignals(), clearMultiplexSignals() et setMultiplexSignals().

quint16 QCanSignalDescription::bitLength() const

Renvoie la longueur en bits de la valeur du signal.

Voir également setBitLength(), startBit() et setStartBit().

void QCanSignalDescription::clearMultiplexSignals()

Supprime toutes les « multiplexor signals » associées à ce signal.

Voir également multiplexSignals(), setMultiplexSignals() et addMultiplexSignal().

QString QCanSignalDescription::comment() const

Renvoie le commentaire associé au signal.

Ce paramètre est fourni uniquement à titre d'explication supplémentaire. Il n'est pas utilisé lors du traitement du signal.

Voir aussi setComment().

QSysInfo::Endian QCanSignalDescription::dataEndian() const

Renvoie l'endian des données correspondant à la valeur du signal.

Par défaut, la valeur BigEndian est utilisée.

Remarque : l'endian des données est ignoré si la fonction ` dataFormat()` est définie sur ` AsciiString`.

Voir également setDataEndian() et QSysInfo::Endian.

QtCanBus::DataFormat QCanSignalDescription::dataFormat() const

Renvoie le format des données de la valeur du signal.

Par défaut, la fonction « SignedInteger » est utilisée.

Voir également setDataFormat() et QtCanBus::DataFormat.

QtCanBus::DataSource QCanSignalDescription::dataSource() const

Renvoie la source de données de la valeur du signal.

Par défaut, la fonction ` Payload ` est utilisée.

Voir également setDataSource() et QtCanBus::DataSource.

double QCanSignalDescription::factor() const

Renvoie le facteur utilisé pour convertir la valeur du signal en une valeur physique, et inversement.

Par défaut, la fonction renvoie qQNaN(), ce qui signifie qu'aucun facteur n'est utilisé.

La section Value Conversions explique comment ce paramètre est utilisé.

Voir également setFactor(), offset() et scaling().

bool QCanSignalDescription::isValid() const

Renvoie ` true ` si la description du signal est valide et ` false ` dans le cas contraire.

Une description de signal valide doit remplir les conditions suivantes :

Voir également bitLength(), dataFormat() et name().

double QCanSignalDescription::maximum() const

Renvoie la valeur maximale prise en charge pour le signal.

Par défaut, la fonction renvoie qQNaN(), ce qui signifie qu’il n’y a pas de valeur maximale.

Voir également setRange() et minimum().

double QCanSignalDescription::minimum() const

Renvoie la valeur minimale prise en charge pour le signal.

Par défaut, la fonction renvoie qQNaN(), ce qui signifie qu’il n’y a pas de valeur minimale.

Voir également setRange() et maximum().

QCanSignalDescription::MultiplexSignalValues QCanSignalDescription::multiplexSignals() const

Renvoie les « multiplexor signals » et leurs valeurs souhaitées, qui permettent d'identifier correctement ce signal.

Le hachage renvoyé contient les noms des signaux en tant que clés et les plages de valeurs souhaitées correspondantes en tant que valeurs.

La valeur de ce signal ne peut être extraite de la charge utile que lorsque tous les signaux du hachage ont les valeurs attendues.

Voir également multiplexState(), clearMultiplexSignals(), setMultiplexSignals() et addMultiplexSignal().

QtCanBus::MultiplexState QCanSignalDescription::multiplexState() const

Renvoie l'état de multiplexage du signal.

Pour plus d'informations sur les signaux multiplexés, consultez la section « Multiplexed Signals Explained ».

Par défaut, cette méthode renvoie « None ».

Voir également ` setMultiplexState()` et ` QtCanBus::MultiplexState`.

QString QCanSignalDescription::name() const

Renvoie le nom du signal.

Voir aussi setName() et isValid().

double QCanSignalDescription::offset() const

Renvoie le décalage utilisé pour convertir la valeur du signal en une valeur physique, et inversement.

Par défaut, la fonction renvoie ` qQNaN()`, ce qui signifie qu'aucun décalage n'est utilisé.

La section « Value Conversions » explique comment ce paramètre est utilisé.

Voir également setOffset(), factor() et scaling().

QString QCanSignalDescription::physicalUnit() const

Renvoie l'unité physique (par exemple, km/h) de la valeur du signal ou une chaîne vide si l'unité n'est pas définie.

Ce paramètre est fourni uniquement à titre d'explication supplémentaire. Il n'est pas utilisé lors du traitement du signal.

Voir également setPhysicalUnit().

QString QCanSignalDescription::receiver() const

Renvoie le nœud récepteur correspondant à ce signal.

Ce paramètre est fourni à titre indicatif uniquement. Il n'est pas utilisé lors du traitement du signal.

Voir également setReceiver().

double QCanSignalDescription::scaling() const

Renvoie le facteur d'échelle utilisé pour convertir la valeur du signal en une valeur physique, et inversement.

Par défaut, la fonction renvoie ` qQNaN()` (), ce qui signifie qu'aucun facteur d'échelle n'est utilisé.

La section Value Conversions explique comment ce paramètre est utilisé.

Voir également setScaling(), offset() et factor().

void QCanSignalDescription::setBitLength(quint16 length)

Définit la longueur en bits de la valeur du signal sur length.

Voir également bitLength(), startBit() et setStartBit().

void QCanSignalDescription::setComment(const QString &text)

Définit le commentaire du signal sur « text ».

Ce paramètre est fourni uniquement à titre d'explication supplémentaire. Il n'est pas utilisé lors du traitement du signal.

Voir également comment().

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

Définit l'endian des données de la valeur du signal sur « endian ».

Voir également dataEndian() et QSysInfo::Endian.

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

Définit le format des données de la valeur du signal sur « format ».

Voir également dataFormat() et QtCanBus::DataFormat.

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

Définit la source de données de la valeur du signal sur source.

Voir également dataSource() et QtCanBus::DataSource.

void QCanSignalDescription::setFactor(double factor)

Définit le facteur utilisé pour convertir la valeur du signal en une valeur physique, puis pour la reconvertir en factor.

Passez ` qQNaN()` à cette méthode pour ignorer ce paramètre lors de la conversion.

Le facteur ne peut pas être égal à 0. Tenter de définir un facteur égal à zéro revient à le définir à qQNaN().

La section Value Conversions explique comment ce paramètre est utilisé.

Voir également factor(), setOffset() et setScaling().

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

Définit l'multiplexor signals pour ce signal sur multiplexorSignals.

Le hachage « multiplexorSignals » doit contenir les noms des signaux en tant que clés et les plages de valeurs souhaitées correspondantes en tant que valeurs.

Voir également multiplexState(), multiplexSignals(), clearMultiplexSignals() et addMultiplexSignal().

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

Définit l'état de multiplexage du signal sur « state ».

Consultez la section « Multiplexed Signals Explained » pour plus de détails sur les signaux multiplexés.

Voir également multiplexState() et QtCanBus::MultiplexState.

void QCanSignalDescription::setName(const QString &name)

Définit le nom du signal sur « name ».

Le nom du signal doit être unique au sein d'un message CAN.

Voir également name().

void QCanSignalDescription::setOffset(double offset)

Définit le décalage utilisé pour convertir la valeur du signal en une valeur physique, puis pour la reconvertir en offset.

Passez ` qQNaN()` à cette méthode pour ignorer ce paramètre lors de la conversion.

La section « Value Conversions » explique comment ce paramètre est utilisé.

Voir également offset(), setFactor() et setScaling().

void QCanSignalDescription::setPhysicalUnit(const QString &unit)

Définit l'unit e physique (par exemple, km/h) de la valeur du signal.

Ce paramètre est fourni à titre indicatif uniquement. Il n'est pas utilisé lors du traitement du signal.

Voir également physicalUnit().

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

Définit les paramètres minimum et maximum pour la valeur du signal.

Si l'un de ces paramètres, ou les deux, est défini sur qQNaN(), cela signifie que la limite correspondante ne sera pas utilisée.

Voir également minimum() et maximum().

void QCanSignalDescription::setReceiver(const QString &receiver)

Définit le nœud « receiver » pour ce signal.

Ce paramètre est fourni uniquement à titre d’information complémentaire. Il n’est pas utilisé lors du traitement du signal.

Voir également receiver().

void QCanSignalDescription::setScaling(double scaling)

Définit le facteur d'échelle utilisé pour convertir la valeur du signal en une valeur physique, puis de nouveau en scaling.

Transmettez ` qQNaN()` à cette méthode pour ignorer ce paramètre lors de la conversion.

Le facteur d'échelle ne peut pas être égal à 0. Tenter de définir un facteur d'échelle égal à zéro revient à le définir sur qQNaN().

La section Value Conversions explique comment ce paramètre est utilisé.

Voir également scaling(), setOffset() et setFactor().

void QCanSignalDescription::setStartBit(quint16 bit)

Définit le bit de départ de la valeur du signal dans la fonction dataSource() sur bit.

Voir également startBit(), bitLength() et setBitLength().

quint16 QCanSignalDescription::startBit() const

Renvoie le bit de départ de la valeur du signal dans la fonction ` dataSource()`.

Voir également setStartBit(), bitLength() et setBitLength().

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

Cette fonction transfère les valeurs de l'objet ` other ` vers cette description de signal.

Remarque : L'objet « QCanSignalDescription » d'origine ne peut être ni détruit ni affecté. L'effet de l'appel à des fonctions autres que le destructeur ou l'un des opérateurs d'affectation est indéfini.

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

Attribue les valeurs de other à la description de ce signal.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.