En esta página

QCanBusDevice Class

La clase QCanBusDevice es la clase de interfaz para el bus CAN. Más información...

Encabezado: #include <QCanBusDevice>
CMake: find_package(Qt6 REQUIRED COMPONENTS SerialBus)
target_link_libraries(mytarget PRIVATE Qt6::SerialBus)
qmake: QT += serialbus
Heredan: QObject

Tipos públicos

struct Filter
enum CanBusDeviceState { UnconnectedState, ConnectingState, ConnectedState, ClosingState }
enum CanBusError { NoError, ReadError, WriteError, ConnectionError, ConfigurationError, …, TimeoutError }
enum class CanBusStatus { Unknown, Good, Warning, Error, BusOff }
enum ConfigurationKey { RawFilterKey, ErrorFilterKey, LoopbackKey, ReceiveOwnKey, BitRateKey, …, UserKey }
enum Direction { Input, Output, AllDirections }
flags Directions

Funciones públicas

QCanBusDevice(QObject *parent = nullptr)
virtual QCanBusDevice::CanBusStatus busStatus()
void clear(QCanBusDevice::Directions direction = Direction::AllDirections)
QList<QCanBusDevice::ConfigurationKey> configurationKeys() const
QVariant configurationParameter(QCanBusDevice::ConfigurationKey key) const
bool connectDevice()
(since 6.2) virtual QCanBusDeviceInfo deviceInfo() const
void disconnectDevice()
QCanBusDevice::CanBusError error() const
QString errorString() const
qint64 framesAvailable() const
qint64 framesToWrite() const
virtual bool hasBusStatus() const
virtual QString interpretErrorFrame(const QCanBusFrame &frame) = 0
QList<QCanBusFrame> readAllFrames()
QCanBusFrame readFrame()
virtual void resetController()
virtual void setConfigurationParameter(QCanBusDevice::ConfigurationKey key, const QVariant &value)
QCanBusDevice::CanBusDeviceState state() const
virtual bool waitForFramesReceived(int msecs)
virtual bool waitForFramesWritten(int msecs)
virtual bool writeFrame(const QCanBusFrame &frame) = 0

Señales

void errorOccurred(QCanBusDevice::CanBusError)
void framesReceived()
void framesWritten(qint64 framesCount)
void stateChanged(QCanBusDevice::CanBusDeviceState state)

Funciones protegidas

void clearError()
virtual void close() = 0
QCanBusFrame dequeueOutgoingFrame()
void enqueueOutgoingFrame(const QCanBusFrame &newFrame)
void enqueueReceivedFrames(const QList<QCanBusFrame> &newFrames)
bool hasOutgoingFrames() const
virtual bool open() = 0
void setError(const QString &errorText, QCanBusDevice::CanBusError errorId)
void setState(QCanBusDevice::CanBusDeviceState newState)

Descripción detallada

QCanBusDevice se comunica con un complemento CAN, lo que proporciona a los usuarios una API práctica. El complemento CAN debe especificarse durante la creación del objeto.

Documentación sobre los tipos de miembros

enum QCanBusDevice::CanBusDeviceState

Esta enumeración describe todos los estados posibles del dispositivo.

ConstanteValorDescripción
QCanBusDevice::UnconnectedState0El dispositivo está desconectado.
QCanBusDevice::ConnectingState1El dispositivo se está conectando.
QCanBusDevice::ConnectedState2El dispositivo está conectado al bus CAN.
QCanBusDevice::ClosingState3El dispositivo se está cerrando.

enum QCanBusDevice::CanBusError

Esta enumeración describe todas las condiciones de error posibles.

ConstanteValorDescripción
QCanBusDevice::NoError0No se ha producido ningún error.
QCanBusDevice::ReadError1Se ha producido un error durante una operación de lectura.
QCanBusDevice::WriteError2Se ha producido un error durante una operación de escritura.
QCanBusDevice::ConnectionError3Se ha producido un error al intentar abrir el complemento.
QCanBusDevice::ConfigurationError4Se ha producido un error al intentar establecer un parámetro de configuración.
QCanBusDevice::UnknownError5Se ha producido un error desconocido.
QCanBusDevice::OperationError6Se intentó realizar una operación mientras el dispositivo se encontraba en un estado que no lo permitía. Esta enumeración se introdujo en Qt 5.14.
QCanBusDevice::TimeoutError7Se ha producido un tiempo de espera agotado mientras se esperaban tramas escritas o recibidas. Esta enumeración se introdujo en Qt 5.14.

enum class QCanBusDevice::CanBusStatus

Esta enumeración describe los posibles valores de estado del bus CAN.

ConstanteValorDescripción
QCanBusDevice::CanBusStatus::Unknown0Se desconoce el estado del bus CAN (por ejemplo, no es compatible con el complemento CAN).
QCanBusDevice::CanBusStatus::Good1El controlador CAN está plenamente operativo
QCanBusDevice::CanBusStatus::Warning2El controlador CAN se encuentra en estado de advertencia
QCanBusDevice::CanBusStatus::Error3El controlador CAN se encuentra en estado de error (ya no envía tramas CAN)
QCanBusDevice::CanBusStatus::BusOff4El controlador CAN se encuentra en estado de «bus desactivado» (desconectado del bus CAN)

enum QCanBusDevice::ConfigurationKey

Esta enumeración describe las posibles opciones de configuración para la conexión del bus CAN.

ConstanteValorDescripción
QCanBusDevice::RawFilterKey0Esta configuración determina el tipo de tramas del bus CAN que acepta el dispositivo actual. El valor esperado es QList<QCanBusDevice::Filter>. Si se pasa una lista vacía, se borran todos los filtros establecidos previamente, incluidos los filtros predeterminados. Para más detalles, véase QCanBusDevice::Filter.
QCanBusDevice::ErrorFilterKey1Esta clave define el tipo de error que debe reenviarse a través de la conexión actual. El valor asociado debe ser de tipo QCanBusFrame::FrameErrors.
QCanBusDevice::LoopbackKey2Esta clave define si el dispositivo de bus CAN debe funcionar en modo de bucle cerrado. El modo de bucle cerrado significa que, cada vez que se transmite una trama CAN por el bus CAN, se envía un eco local de dicha trama a todas las aplicaciones conectadas a este dispositivo CAN. El valor esperado para esta clave es bool.
QCanBusDevice::ReceiveOwnKey3Esta clave define si este dispositivo CAN recibe sus propias tramas de envío. Esto puede utilizarse para comprobar si la transmisión se ha realizado correctamente. El valor esperado para esta clave es bool.
QCanBusDevice::BitRateKey4Esta clave define la velocidad de transmisión CAN en bits por segundo. Con CAN FD, la carga útil puede transmitirse a una velocidad de datos mayor si se establece « QCanBusFrame::hasBitrateSwitch()». En este caso, « QCanBusDevice::BitRateKey » solo se utiliza para la fase de arbitraje del ID de CAN. Véase también QCanBusDevice::DataBitRateKey
QCanBusDevice::CanFdKey5Esta clave define si debe habilitarse el envío y la recepción de tramas CAN FD. El valor esperado para esta clave es bool.
QCanBusDevice::DataBitRateKey6Esta clave define la velocidad de transmisión de la carga útil de CAN FD en bits por segundo. CAN FD permite transmitir la carga útil de las tramas con el indicador QCanBusFrame::hasBitrateSwitch() a una velocidad de transmisión de datos más alta, una vez finalizada la fase de arbitraje a la velocidad de bits nominal. Este valor de enumeración se introdujo en Qt 5.9. Véase también QCanBusDevice::BitRateKey
QCanBusDevice::ProtocolKey7Esta clave permite especificar otro protocolo. Por el momento, este parámetro solo se puede configurar y utilizar en el complemento SocketCAN. Este valor de enumeración se introdujo en Qt 5.14.
QCanBusDevice::UserKey30Esta clave define el rango en el que comienzan las claves personalizadas. Su finalidad más habitual es permitir opciones de configuración específicas de cada plataforma.

Véase también configurationParameter().

enum QCanBusDevice::Direction
flags QCanBusDevice::Directions

Esta enumeración describe las posibles direcciones de transmisión de datos.

ConstanteValorDescripción
QCanBusDevice::Input1Dirección de entrada.
QCanBusDevice::Output2Dirección de salida.
QCanBusDevice::AllDirectionsInput | OutputAmbas direcciones, entrada y salida.

El tipo «Directions» es una definición de tipo (typedef) para QFlags<Direction>. Almacena una combinación OR de valores de «Direction».

Documentación de las funciones miembro

[explicit] QCanBusDevice::QCanBusDevice(QObject *parent = nullptr)

Crea un dispositivo de bus serie con el ` parent` especificado.

[virtual] QCanBusDevice::CanBusStatus QCanBusDevice::busStatus()

Devuelve el estado actual del bus CAN. Si no es posible solicitar el estado, se devuelve QCanBusDevice::UnknownStatus.

Nota: Es posible queesta función no esté implementada en todos los complementos CAN. Consulte las páginas de ayuda de los complementos para obtener más información. La función hasBusStatus() se puede utilizar en tiempo de ejecución para comprobar si el complemento CAN utilizado admite la solicitud del estado del bus CAN.

Véase también hasBusStatus() y resetController().

void QCanBusDevice::clear(QCanBusDevice::Directions direction = Direction::AllDirections)

Borra los búferes de entrada o salida del dispositivo, dependiendo de ` direction`.

Esta función solo actúa sobre los búferes de QCanBusDevice. Los tramas que ya se han escrito en el controlador CAN o en la capa de hardware CAN, o que aún no se han leído desde estas capas, no se borran con esta función.

Nota: El vaciado de los búferes de salida solo es posible en el caso de dispositivos con búfer.

Véanse también framesAvailable(), readFrame(), framesToWrite() y writeFrame().

[protected] void QCanBusDevice::clearError()

Borra el identificador de error y la descripción legible para el usuario del último error del dispositivo.

Las implementaciones del bus CAN deben utilizar esta función para actualizar el estado de error del dispositivo.

Véase también error(), errorOccurred() y setError().

[pure virtual protected] void QCanBusDevice::close()

Esta función se encarga de cerrar la conexión del bus CAN. La implementación debe garantizar que la función ` state()` de la instancia esté establecida en ` QCanBusDevice::UnconnectedState`.

La tarea más importante de esta función es cerrar el socket con el dispositivo CAN y llamar a QCanBusDevice::setState().

Véase también disconnectDevice().

QList<QCanBusDevice::ConfigurationKey> QCanBusDevice::configurationKeys() const

Devuelve la lista de claves utilizadas por la conexión del bus CAN.

El significado de las claves es equivalente al de ConfigurationKey. Si no se menciona explícitamente una clave, se utiliza la configuración predeterminada de la plataforma para la clave en cuestión.

QVariant QCanBusDevice::configurationParameter(QCanBusDevice::ConfigurationKey key) const

Devuelve el valor actual asignado a ` ConfigurationKey ` key; en caso contrario, devuelve un valor no válido ` QVariant`.

Véase también setConfigurationParameter() y configurationKeys().

bool QCanBusDevice::connectDevice()

Conecta el dispositivo al bus CAN. Devuelve ` true ` si la operación se realiza correctamente; en caso contrario, devuelve ` false`.

Esta función llama a ` open()` como parte de su implementación.

Véase también disconnectDevice().

[protected] QCanBusFrame QCanBusDevice::dequeueOutgoingFrame()

Devuelve el siguiente « QCanBusFrame » de la lista interna de tramas de salida; en caso contrario, devuelve un « QCanBusFrame » no válido. La trama devuelta se elimina de la lista interna.

[virtual, since 6.2] QCanBusDeviceInfo QCanBusDevice::deviceInfo() const

Devuelve un ` QCanBusDeviceInfo ` para el ` QCanBusDevice` actual. Si la función no está implementada por una subclase de ` QCanBusDevice`, se devuelve un objeto construido por defecto.

Esta función se introdujo en Qt 6.2.

void QCanBusDevice::disconnectDevice()

Desconecta el dispositivo del bus CAN.

Esta función llama a ` close()` como parte de su implementación.

Nota: Esta función solo debe llamarse si connectDevice() ha devuelto true.

Véase también connectDevice().

[protected] void QCanBusDevice::enqueueOutgoingFrame(const QCanBusFrame &newFrame)

Añade ` newFrame ` a la lista interna de tramas salientes, a la que se puede acceder mediante ` writeFrame()`.

Las subclases deben llamar a esta función cuando escriban una nueva trama.

[protected] void QCanBusDevice::enqueueReceivedFrames(const QList<QCanBusFrame> &newFrames)

Añade ` newFrames ` a la lista interna de fotogramas a la que se puede acceder mediante ` readFrame()` y emite la señal ` framesReceived()`.

Las subclases deben llamar a esta función cuando reciban tramas.

QCanBusDevice::CanBusError QCanBusDevice::error() const

Devuelve el último error que se ha producido. El valor del error siempre se establece en el último error ocurrido y nunca se restablece.

Véase también setError() y errorString().

[signal] void QCanBusDevice::errorOccurred(QCanBusDevice::CanBusError)

Esta señal se emite cuando se produce un error.

QString QCanBusDevice::errorString() const

Devuelve una descripción comprensible para el usuario del último error de dispositivo que se ha producido.

Véase también ` error()`.

qint64 QCanBusDevice::framesAvailable() const

Devuelve el número de fotogramas disponibles. Si no hay fotogramas disponibles, esta función devuelve 0.

Véase también clear(), readFrame() y readAllFrames().

[signal] void QCanBusDevice::framesReceived()

Esta señal se emite cuando se han recibido una o más tramas. Las tramas deben leerse mediante readFrame() y framesAvailable().

qint64 QCanBusDevice::framesToWrite() const

En el caso de los dispositivos con búfer, esta función devuelve el número de tramas en espera de ser escritas. En el caso de los dispositivos sin búfer, esta función siempre devuelve cero.

Nota: Puede haber almacenamiento en búfer adicional en el controlador CAN y en la capa de hardware CAN. Por lo tanto, si esta función devuelve cero, eso no significa que todas las tramas CAN ya se hayan escrito en el bus CAN.

Véase también clear() y writeFrame().

[signal] void QCanBusDevice::framesWritten(qint64 framesCount)

Esta señal se emite cada vez que se ha escrito una carga útil de tramas en el bus CAN. El argumento « framesCount » se establece en el número de tramas que se han escrito en dicha carga útil.

[virtual] bool QCanBusDevice::hasBusStatus() const

Devuelve «true» si el complemento CAN admite la solicitud del estado del bus CAN.

Véase también busStatus().

[protected] bool QCanBusDevice::hasOutgoingFrames() const

Devuelve ` true ` si la lista interna de tramas salientes no está vacía; en caso contrario, devuelve ` false`.

[pure virtual] QString QCanBusDevice::interpretErrorFrame(const QCanBusFrame &frame)

Interpreta « frame » como un marco de error y devuelve una descripción del error comprensible para el usuario.

Si frame no es un marco de error, la cadena devuelta estará vacía.

[pure virtual protected] bool QCanBusDevice::open()

Esta función es llamada por ` connectDevice()`. Las subclases deben proporcionar una implementación que devuelva ` true ` si se ha podido establecer la conexión al bus CAN; de lo contrario, ` false`. La implementación de ` QCanBusDevice ` garantiza, al entrar en esta función, que el método ` state()` del dispositivo ya esté establecido en ` QCanBusDevice::ConnectingState `.

La implementación debe garantizar que, en caso de éxito, el método state() de la instancia esté ya establecido en QCanBusDevice::ConnectedState; en caso contrario, en QCanBusDevice::UnconnectedState. Se debe utilizar setState() para establecer el nuevo estado del dispositivo.

La implementación personalizada se encarga de abrir el socket, instanciar un ` QSocketNotifier ` que pueda ser necesario y aplicar un ` QCanBusDevice::configurationParameter()` personalizado y predeterminado.

Véase también connectDevice().

QList<QCanBusFrame> QCanBusDevice::readAllFrames()

Devuelve todos los « QCanBusFrame» de la cola; en caso contrario, devuelve un « QList » vacío. Los «frames» devueltos se eliminan de la cola.

La cola funciona según el principio FIFO.

Véanse también clear(), framesAvailable() y readFrame().

QCanBusFrame QCanBusDevice::readFrame()

Devuelve el siguiente objeto « QCanBusFrame » de la cola; en caso contrario, devuelve un objeto « QCanBusFrame » vacío. El objeto devuelto se elimina de la cola.

La cola funciona según el principio FIFO.

Véanse también clear(), framesAvailable() y readAllFrames().

[virtual] void QCanBusDevice::resetController()

Realiza un reinicio del controlador CAN para sacar al controlador CAN del estado de desconexión del bus, si es posible.

Nota: Los reinicios del controladorCAN interrumpen la comunicación en curso y pueden tardar hasta un segundo en completarse. Solo se debe llamar a esta función para recuperarse de errores del bus.

Nota: Es posible queesta función no esté implementada en todos los complementos CAN. Consulta las páginas de ayuda de los complementos para obtener más información.

Véase también busStatus().

[virtual] void QCanBusDevice::setConfigurationParameter(QCanBusDevice::ConfigurationKey key, const QVariant &value)

Establece el parámetro de configuración « key » para la conexión del bus CAN en « value ». Las claves posibles se indican en « ConfigurationKey ».

Un parámetro puede desactivarse estableciendo un valor no válido para « QVariant ». Desactivar un parámetro implica que la configuración se restablece a su valor predeterminado.

Nota: En la mayoría de los casos, los cambios en la configuración solo surten efecto tras volver a conectarse.

Véase también configurationParameter().

[protected] void QCanBusDevice::setError(const QString &errorText, QCanBusDevice::CanBusError errorId)

Establece la descripción legible para el usuario del último error del dispositivo en « errorText ». « errorId » clasifica el tipo de error.

Las implementaciones del bus CAN deben utilizar esta función para actualizar el estado de error del dispositivo.

Véanse también error(), errorOccurred() y clearError().

[protected] void QCanBusDevice::setState(QCanBusDevice::CanBusDeviceState newState)

Establece el estado del dispositivo en « newState ». Las implementaciones del bus CAN deben utilizar esta función para actualizar el estado del dispositivo.

Véase también state().

QCanBusDevice::CanBusDeviceState QCanBusDevice::state() const

Devuelve el estado actual del dispositivo.

Véase también setState() y stateChanged().

[signal] void QCanBusDevice::stateChanged(QCanBusDevice::CanBusDeviceState state)

Esta señal se emite cada vez que cambia el estado del dispositivo. El nuevo estado viene representado por state.

Véanse también setState() y state().

[virtual] bool QCanBusDevice::waitForFramesReceived(int msecs)

Queda en espera hasta que haya nuevas tramas disponibles para su lectura y se haya emitido la señal framesReceived(), o hasta que hayan transcurrido msecs milisegundos. Si msecs es -1, esta función no agotará el tiempo de espera.

Devuelve true si hay nuevas tramas disponibles para su lectura y se emite la señal framesReceived(); en caso contrario, devuelve false (si la operación ha agotado el tiempo de espera o si se ha producido un error).

Nota: Esta función iniciará un bucle de eventos local. Esto puede dar lugar a situaciones en las que se llamen otros slots de la aplicación mientras la ejecución del ámbito de esta función está bloqueada. Para evitar problemas, las señales de esta clase no deben conectarse a slots. Del mismo modo, esta función nunca debe llamarse en respuesta a las señales ` framesReceived()` o ` errorOccurred()`.

Véase también waitForFramesWritten().

[virtual] bool QCanBusDevice::waitForFramesWritten(int msecs)

En el caso de los dispositivos con búfer, esta función espera hasta que todas las tramas almacenadas en el búfer se hayan escrito en el dispositivo y se haya emitido la señal ` framesWritten()`, o hasta que hayan transcurrido ` msecs ` milisegundos. Si ` msecs ` es -1, esta función no agotará el tiempo de espera. En el caso de los dispositivos sin búfer, devuelve el resultado inmediatamente con ` false `, ya que ` writeFrame()` no requiere un búfer de escritura.

Devuelve true si se emite la señal framesWritten(); en caso contrario, devuelve false (es decir, si la operación ha agotado el tiempo de espera o si se ha producido un error).

Nota: Esta función iniciará un bucle de eventos local. Esto puede dar lugar a situaciones en las que se llamen otros slots de la aplicación mientras la ejecución del ámbito de esta función está bloqueada. Para evitar problemas, las señales de esta clase no deben conectarse a slots. Del mismo modo, esta función nunca debe llamarse en respuesta a las señales framesWritten() o errorOccurred().

Véase también waitForFramesReceived().

[pure virtual] bool QCanBusDevice::writeFrame(const QCanBusFrame &frame)

Escribe « frame » en el bus CAN y devuelve « true » si la operación se realiza con éxito; en caso contrario, devuelve « false ».

En algunas plataformas, la trama puede colocarse en una cola y el valor de retorno puede indicar únicamente que se ha insertado correctamente en la cola. La trama real se enviará más adelante. Por lo tanto, la señal « framesWritten()» es la confirmación definitiva de que la trama se ha transferido a la capa de transporte. Si se produce un error, se emite « errorOccurred()».

Según la especificación del bus CAN, las tramas de tipo remote transfer request (RTR) no tienen carga útil, sino una longitud comprendida entre 0 y 8 (ambos inclusive). Esta longitud indica la longitud esperada de la carga útil de la respuesta de la parte remota. Por lo tanto, al enviar una trama RTR mediante esta función, puede que siga siendo necesario establecer una carga útil arbitraria en ` frame`. La longitud de dicha carga útil arbitraria es la que se establece como tamaño esperado para la trama RTR.

Véase también QCanBusFrame::setPayload().

© 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.