QCanBusDevice Class
The QCanBusDevice class is the interface class for CAN bus. More...
| Header: | #include <QCanBusDevice> |
| qmake: | QT += serialbus |
| Since: | Qt 5.8 |
| Inherits: | QObject |
This class was introduced in Qt 5.8.
Public Types
| 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 |
Public Functions
| QCanBusDevice(QObject *parent = nullptr) | |
| virtual QString | interpretErrorFrame(const QCanBusFrame &frame) = 0 |
| virtual bool | writeFrame(const QCanBusFrame &frame) = 0 |
Signals
| void | errorOccurred(QCanBusDevice::CanBusError) |
| void | framesReceived() |
| void | framesWritten(qint64 framesCount) |
| void | stateChanged(QCanBusDevice::CanBusDeviceState state) |
Protected Functions
| void | clearError() |
| virtual void | close() = 0 |
| QCanBusFrame | dequeueOutgoingFrame() |
| void | enqueueOutgoingFrame(const QCanBusFrame &newFrame) |
| void | enqueueReceivedFrames(const QVector<QCanBusFrame> &newFrames) |
| bool | hasOutgoingFrames() const |
| virtual bool | open() = 0 |
| void | setError(const QString &errorText, QCanBusDevice::CanBusError errorId) |
Detailed Description
QCanBusDevice communicates with a CAN plugin providing users with a convenient API. The CAN plugin must be specified during the object creation.
Member Type Documentation
enum QCanBusDevice::CanBusDeviceState
This enum describes all possible device states.
| Constant | Value | Description |
|---|---|---|
QCanBusDevice::UnconnectedState | 0 | The device is disconnected. |
QCanBusDevice::ConnectingState | 1 | The device is being connected. |
QCanBusDevice::ConnectedState | 2 | The device is connected to the CAN bus. |
QCanBusDevice::ClosingState | 3 | The device is being closed. |
enum QCanBusDevice::CanBusError
This enum describes all the possible error conditions.
| Constant | Value | Description |
|---|---|---|
QCanBusDevice::NoError | 0 | No errors have occurred. |
QCanBusDevice::ReadError | 1 | An error occurred during a read operation. |
QCanBusDevice::WriteError | 2 | An error occurred during a write operation. |
QCanBusDevice::ConnectionError | 3 | An error occurred when attempting to open the plugin. |
QCanBusDevice::ConfigurationError | 4 | An error occurred when attempting to set a configuration parameter. |
QCanBusDevice::UnknownError | 5 | An unknown error occurred. |
QCanBusDevice::OperationError | 6 | An operation was attempted while the device was in a state that did not permit it. This enum was introduced in Qt 5.14. |
QCanBusDevice::TimeoutError | 7 | An timeout occurred while waiting for frames written or received. This enum was introduced in Qt 5.14. |
enum class QCanBusDevice::CanBusStatus
This enum describes possible CAN bus status values.
| Constant | Value | Description |
|---|---|---|
QCanBusDevice::CanBusStatus::Unknown | 0 | The CAN bus status is unknown (e.g. not supported by the CAN plugin). |
QCanBusDevice::CanBusStatus::Good | 1 | The CAN controller is fully operational |
QCanBusDevice::CanBusStatus::Warning | 2 | The CAN controller is in warning status |
QCanBusDevice::CanBusStatus::Error | 3 | The CAN controller is in error status (no longer sending CAN frames) |
QCanBusDevice::CanBusStatus::BusOff | 4 | The CAN controller is in bus off status (disconnected from the CAN bus) |
This enum was introduced or modified in Qt 5.14.
enum QCanBusDevice::ConfigurationKey
This enum describes the possible configuration options for the CAN bus connection.
| Constant | Value | Description |
|---|---|---|
QCanBusDevice::RawFilterKey | 0 | This configuration determines the type of CAN bus frames that the current device accepts. The expected value is QList<QCanBusDevice::Filter>. Passing an empty list clears all previously set filters including default filters. For more details see QCanBusDevice::Filter. |
QCanBusDevice::ErrorFilterKey | 1 | This key defines the type of error that should be forwarded via the current connection. The associated value should be of type QCanBusFrame::FrameErrors. |
QCanBusDevice::LoopbackKey | 2 | This key defines whether the CAN bus device should operate in loopback mode. Loopback means, whenever a CAN frame is transmitted on the CAN bus, a local echo of this frame is sent to all applications connected to this CAN device. The expected value for this key is bool. |
QCanBusDevice::ReceiveOwnKey | 3 | This key defines whether this CAN device receives its own send frames. This can be used to check if the transmission was successful. The expected value for this key is bool. |
QCanBusDevice::BitRateKey | 4 | This key defines the CAN bitrate in bits per second. With CAN FD, the payload can be transmitted at a higher data bitrate, if QCanBusFrame::hasBitrateSwitch() is set. In this case, QCanBusDevice::BitRateKey is only used for the CAN ID arbitration phase. See also QCanBusDevice::DataBitRateKey |
QCanBusDevice::CanFdKey | 5 | This key defines whether sending and receiving of CAN FD frames should be enabled. The expected value for this key is bool. |
QCanBusDevice::DataBitRateKey | 6 | This key defines the CAN FD payload bitrate in bits per second. CAN FD allows to transmit the payload of frames with QCanBusFrame::hasBitrateSwitch() flag at a higher data bitrate, after the arbitration phase at the nominal bitrate is finished. This enum value was introduced in Qt 5.9. See also QCanBusDevice::BitRateKey |
QCanBusDevice::ProtocolKey | 7 | This key allows to specify another protocol. For now, this parameter can only be set and used in the SocketCAN plugin. This enum value was introduced in Qt 5.14. |
QCanBusDevice::UserKey | 30 | This key defines the range where custom keys start. Its most common purpose is to permit platform-specific configuration options. |
See also configurationParameter().
enum QCanBusDevice::Direction
flags QCanBusDevice::Directions
This enum describes possible data transmission directions.
| Constant | Value | Description |
|---|---|---|
QCanBusDevice::Input | 1 | Input direction. |
QCanBusDevice::Output | 2 | Output direction. |
QCanBusDevice::AllDirections | Input | Output | Both directions, input and output. |
This enum was introduced or modified in Qt 5.12.
The Directions type is a typedef for QFlags<Direction>. It stores an OR combination of Direction values.
Member Function Documentation
QCanBusDevice::QCanBusDevice(QObject *parent = nullptr)
Constructs a serial bus device with the specified parent.
[signal] void QCanBusDevice::errorOccurred(QCanBusDevice::CanBusError)
This signal is emitted when an error occurs.
[signal] void QCanBusDevice::framesReceived()
This signal is emitted when one or more frames have been received. The frames should be read using readFrame() and framesAvailable().
[signal] void QCanBusDevice::framesWritten(qint64 framesCount)
This signal is emitted every time a payload of frames has been written to the CAN bus. The framesCount argument is set to the number of frames that were written in this payload.
[signal] void QCanBusDevice::stateChanged(QCanBusDevice::CanBusDeviceState state)
This signal is emitted every time the state of the device changes. The new state is represented by state.
See also setState() and state().
[protected] void QCanBusDevice::clearError()
Clears the error id and the human readable description of the last device error.
CAN bus implementations must use this function to update the device's error state.
This function was introduced in Qt 5.14.
See also error(), errorOccurred(), and setError().
[pure virtual protected] void QCanBusDevice::close()
This function is responsible for closing the CAN bus connection. The implementation must ensure that the instance's state() is set to QCanBusDevice::UnconnectedState.
This function's most important task is to close the socket to the CAN device and to call QCanBusDevice::setState().
See also disconnectDevice().
[protected] QCanBusFrame QCanBusDevice::dequeueOutgoingFrame()
Returns the next QCanBusFrame from the internal list of outgoing frames; otherwise returns an invalid QCanBusFrame. The returned frame is removed from the internal list.
[protected] void QCanBusDevice::enqueueOutgoingFrame(const QCanBusFrame &newFrame)
Appends newFrame to the internal list of outgoing frames which can be accessed by writeFrame().
Subclasses must call this function when they write a new frame.
[protected] void QCanBusDevice::enqueueReceivedFrames(const QVector<QCanBusFrame> &newFrames)
Appends newFrames to the internal list of frames which can be accessed using readFrame() and emits the framesReceived() signal.
Subclasses must call this function when they receive frames.
[protected] bool QCanBusDevice::hasOutgoingFrames() const
Returns true if the internal list of outgoing frames is not empty; otherwise returns false.
[pure virtual] QString QCanBusDevice::interpretErrorFrame(const QCanBusFrame &frame)
Interprets frame as error frame and returns a human readable description of the error.
If frame is not an error frame, the returned string is empty.
[pure virtual protected] bool QCanBusDevice::open()
This function is called by connectDevice(). Subclasses must provide an implementation which returns true if the CAN bus connection could be established; otherwise false. The QCanBusDevice implementation ensures upon entry of this function that the device's state() is set to QCanBusDevice::ConnectingState already.
The implementation must ensure that upon success the instance's state() is set to QCanBusDevice::ConnectedState; otherwise QCanBusDevice::UnconnectedState. setState() must be used to set the new device state.
The custom implementation is responsible for opening the socket, instanciation of a potentially required QSocketNotifier and the application of custom and default QCanBusDevice::configurationParameter().
See also connectDevice().
[protected] void QCanBusDevice::setError(const QString &errorText, QCanBusDevice::CanBusError errorId)
Sets the human readable description of the last device error to errorText. errorId categorizes the type of error.
CAN bus implementations must use this function to update the device's error state.
See also error(), errorOccurred(), and clearError().
[pure virtual] bool QCanBusDevice::writeFrame(const QCanBusFrame &frame)
Writes frame to the CAN bus and returns true on success; otherwise false.
On some platforms, the frame may be put into a queue and the return value may only indicate a successful insertion into the queue. The actual frame will be send later on. Therefore the framesWritten() signal is the final confirmation that the frame has been handed off to the transport layer. If an error occurs the errorOccurred() is emitted.
As per CAN bus specification, frames of type remote transfer request (RTR) do not have a payload, but a length from 0 to 8 (including). This length indicates the expected response payload length from the remote party. Therefore when sending a RTR frame using this function it may still be required to set an arbitrary payload on frame. The length of the arbitrary payload is what is set as size expectation for the RTR frame.
See also QCanBusFrame::setPayload().
© 2025 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.
