class QCanBusDevice#

The QCanBusDevice class is the interface class for CAN bus. More…

Inheritance diagram of PySide6.QtSerialBus.QCanBusDevice

Synopsis#

Methods#

Virtual methods#

Signals#

Static functions#

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#

QCanBusDevice communicates with a CAN plugin providing users with a convenient API. The CAN plugin must be specified during the object creation.

class CanBusError#

This enum describes all the possible error conditions.

Constant

Description

QCanBusDevice.NoError

No errors have occurred.

QCanBusDevice.ReadError

An error occurred during a read operation.

QCanBusDevice.WriteError

An error occurred during a write operation.

QCanBusDevice.ConnectionError

An error occurred when attempting to open the plugin.

QCanBusDevice.ConfigurationError

An error occurred when attempting to set a configuration parameter.

QCanBusDevice.UnknownError

An unknown error occurred.

QCanBusDevice.OperationError

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

An timeout occurred while waiting for frames written or received. This enum was introduced in Qt 5.14.
class CanBusDeviceState#

This enum describes all possible device states.

Constant

Description

QCanBusDevice.UnconnectedState

The device is disconnected.

QCanBusDevice.ConnectingState

The device is being connected.

QCanBusDevice.ConnectedState

The device is connected to the CAN bus.

QCanBusDevice.ClosingState

The device is being closed.
class CanBusStatus#

This enum describes possible CAN bus status values.

Constant

Description

QCanBusDevice.CanBusStatus.Unknown

The CAN bus status is unknown (e.g. not supported by the CAN plugin).

QCanBusDevice.CanBusStatus.Good

The CAN controller is fully operational

QCanBusDevice.CanBusStatus.Warning

The CAN controller is in warning status

QCanBusDevice.CanBusStatus.Error

The CAN controller is in error status (no longer sending CAN frames)

QCanBusDevice.CanBusStatus.BusOff

The CAN controller is in bus off status (disconnected from the CAN bus)
class ConfigurationKey#

This enum describes the possible configuration options for the CAN bus connection.

Constant

Description

QCanBusDevice.RawFilterKey

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

QCanBusDevice.ErrorFilterKey

This key defines the type of error that should be forwarded via the current connection. The associated value should be of type FrameErrors .

QCanBusDevice.LoopbackKey

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

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

This key defines the CAN bitrate in bits per second. With CAN FD, the payload can be transmitted at a higher data bitrate, if hasBitrateSwitch() is set. In this case, QCanBusDevice::BitRateKey is only used for the CAN ID arbitration phase. See also QCanBusDevice::DataBitRateKey

QCanBusDevice.CanFdKey

This key defines whether sending and receiving of CAN FD frames should be enabled. The expected value for this key is bool.

QCanBusDevice.DataBitRateKey

This key defines the CAN FD payload bitrate in bits per second. CAN FD allows to transmit the payload of frames with 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

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

This key defines the range where custom keys start. Its most common purpose is to permit platform-specific configuration options.

See also

configurationParameter()

class Direction#

(inherits enum.Flag) This enum describes possible data transmission directions.

Constant

Description

QCanBusDevice.Input

Input direction.

QCanBusDevice.Output

Output direction.

QCanBusDevice.AllDirections

Both directions, input and output.
__init__([parent=None])#
Parameters:

parent – QObject

Constructs a serial bus device with the specified parent.

busStatus()#
Return type:

CanBusStatus

Returns the current CAN bus status. If the status cannot be requested, QCanBusDevice::UnknownStatus is returned.

Note

This function may not be implemented in all CAN plugins. Please refer to the plugins help pages for more information. The function hasBusStatus() can be used at runtime to check if the used CAN plugin has support for requesting the CAN bus status.

See also

hasBusStatus() resetController()

clear([direction=QCanBusDevice.Direction.AllDirections])#
Parameters:

direction – Combination of Direction

Clears the devices input or output buffers, depending on direction.

This function only operates on QCanBusDevice buffers. Frames that are already written to the CAN driver or CAN hardware layer, or that are not yet read from these layers, are not cleared by this function.

Note

Clearing the output buffers is only possible for buffered devices.

See also

framesAvailable() readFrame() framesToWrite() writeFrame()

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.

abstract close()#

This function is responsible for closing the CAN bus connection. The implementation must ensure that the instance’s state() is set to UnconnectedState .

This function’s most important task is to close the socket to the CAN device and to call setState() .

configurationKeys()#
Return type:

.list of QCanBusDevice.ConfigurationKey

Returns the list of keys used by the CAN bus connection.

The meaning of the keys is equivalent to ConfigurationKey . If a key is not explicitly mentioned, the platform’s default setting for the relevant key is used.

configurationParameter(key)#
Parameters:

key – ConfigurationKey

Return type:

object

Returns the current value assigned to the ConfigurationKey key; otherwise an invalid QVariant.

connectDevice()#
Return type:

bool

Connects the device to the CAN bus. Returns true on success; otherwise false.

This function calls open() as part of its implementation.

static createDeviceInfo(plugin, name, isVirtual, isFlexibleDataRateCapable)#
Parameters:

  • plugin – str

  • name – str

  • isVirtual – bool

  • isFlexibleDataRateCapable – bool

Return type:

QCanBusDeviceInfo

static createDeviceInfo(plugin, name, serialNumber, description, alias, channel, isVirtual, isFlexibleDataRateCapable)
Parameters:

  • plugin – str

  • name – str

  • serialNumber – str

  • description – str

  • alias – str

  • channel – int

  • isVirtual – bool

  • isFlexibleDataRateCapable – bool

Return type:

QCanBusDeviceInfo

dequeueOutgoingFrame()#
Return type:

QCanBusFrame

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.

deviceInfo()#
Return type:

QCanBusDeviceInfo

Returns a QCanBusDeviceInfo for the current QCanBusDevice . If the function is not implemented by a sub-class of QCanBusDevice , a default constructed object is returned.

disconnectDevice()#

Disconnects the device from the CAN bus.

This function calls close() as part of its implementation.

Note

This function should only be called, if connectDevice() returned true.

See also

connectDevice()

enqueueOutgoingFrame(newFrame)#
Parameters:

newFrame – QCanBusFrame

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.

enqueueReceivedFrames(newFrames)#
Parameters:

newFrames – .list of QCanBusFrame

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.

error()#
Return type:

CanBusError

Returns the last error that has occurred. The error value is always set to last error that occurred and it is never reset.

errorOccurred(arg__1)#
Parameters:

arg__1 – CanBusError

This signal is emitted when an error occurs.

errorString()#
Return type:

str

Returns a human-readable description of the last device error that occurred.

See also

error()

framesAvailable()#
Return type:

int

Returns the number of available frames. If no frames are available, this function returns 0.

framesReceived()#

This signal is emitted when one or more frames have been received. The frames should be read using readFrame() and framesAvailable() .

framesToWrite()#
Return type:

int

For buffered devices, this function returns the number of frames waiting to be written. For unbuffered devices, this function always returns zero.

Note

There may be additional buffering in the CAN driver and CAN hardware layer. Therefore, if this function returns zero, that does not mean all CAN frames are already written to the CAN bus.

See also

clear() writeFrame()

framesWritten(framesCount)#
Parameters:

framesCount – int

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.

hasBusStatus()#
Return type:

bool

Return true, if the CAN plugin supports requesting the CAN bus status.

See also

busStatus()

hasOutgoingFrames()#
Return type:

bool

Returns true if the internal list of outgoing frames is not empty; otherwise returns false.

abstract interpretErrorFrame(errorFrame)#
Parameters:

errorFrame – QCanBusFrame

Return type:

str

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.

abstract open()#
Return type:

bool

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 ConnectingState already.

The implementation must ensure that upon success the instance’s state() is set to ConnectedState ; otherwise 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 configurationParameter() .

See also

connectDevice()

readAllFrames()#
Return type:

.list of QCanBusFrame

Returns all QCanBusFrame s from the queue; otherwise returns an empty QList. The returned frames are removed from the queue.

The queue operates according to the FIFO principle.

readFrame()#
Return type:

QCanBusFrame

Returns the next QCanBusFrame from the queue; otherwise returns an empty QCanBusFrame . The returned frame is removed from the queue.

The queue operates according to the FIFO principle.

resetController()#

Performs a CAN controller reset to release the CAN controller from bus off state, if possible.

Note

CAN controller resets disturb the running communication and may take up to one second to complete. Only call this function to recover from bus errors.

Note

This function may not be implemented in all CAN plugins. Please refer to the plugins help pages for more information.

See also

busStatus()

setConfigurationParameter(key, value)#
Parameters:

Sets the configuration parameter key for the CAN bus connection to value. The potential keys are represented by ConfigurationKey .

A parameter can be unset by setting an invalid QVariant. Unsetting a parameter implies that the configuration is reset to its default setting.

Note

In most cases, configuration changes only take effect after a reconnect.

See also

configurationParameter()

setError(errorText, arg__2)#
Parameters:

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.

setState(newState)#
Parameters:

newState – CanBusDeviceState

Sets the state of the device to newState. CAN bus implementations must use this function to update the device state.

See also

state()

state()#
Return type:

CanBusDeviceState

Returns the current state of the device.

stateChanged(state)#
Parameters:

state – CanBusDeviceState

This signal is emitted every time the state of the device changes. The new state is represented by state.

See also

setState() state()

waitForFramesReceived(msecs)#
Parameters:

msecs – int

Return type:

bool

Blocks until new frames are available for reading and the framesReceived() signal has been emitted, or until msecs milliseconds have passed. If msecs is -1, this function will not time out.

Returns true if new frames are available for reading and the framesReceived() signal is emitted; otherwise returns false (if the operation timed out or if an error occurred).

Note

This function will start a local event loop. This may lead to scenarios whereby other application slots may be called while the execution of this function scope is blocking. To avoid problems, the signals for this class should not be connected to slots. Similarly this function must never be called in response to the framesReceived() or errorOccurred() signals.

See also

waitForFramesWritten()

waitForFramesWritten(msecs)#
Parameters:

msecs – int

Return type:

bool

For buffered devices, this function waits until all buffered frames have been written to the device and the framesWritten() signal has been emitted, or until msecs milliseconds have passed. If msecs is -1, this function will not time out. For unbuffered devices, it returns immediately with false as writeFrame() does not require a write buffer.

Returns true if the framesWritten() signal is emitted; otherwise returns false (i.e. if the operation timed out, or if an error occurred).

Note

This function will start a local event loop. This may lead to scenarios whereby other application slots may be called while the execution of this function scope is blocking. To avoid problems, the signals for this class should not be connected to slots. Similarly this function must never be called in response to the framesWritten() or errorOccurred() signals.

See also

waitForFramesReceived()

abstract writeFrame(frame)#
Parameters:

frame – QCanBusFrame

Return type:

bool

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

setPayload()