QSerialPort¶

Provides functions to access serial ports. More…

Synopsis¶

Functions¶

def baudRate ([directions=QSerialPort.Direction.AllDirections])
def clear ([directions=QSerialPort.Direction.AllDirections])
def clearError ()
def dataBits ()
def error ()
def flowControl ()
def flush ()
def handle ()
def isBreakEnabled ()
def isDataTerminalReady ()
def isRequestToSend ()
def parity ()
def pinoutSignals ()
def portName ()
def readBufferSize ()
def setBaudRate (baudRate[, directions=QSerialPort.Direction.AllDirections])
def setBreakEnabled ([set=true])
def setDataBits (dataBits)
def setDataTerminalReady (set)
def setFlowControl (flowControl)
def setParity (parity)
def setPort (info)
def setPortName (name)
def setReadBufferSize (size)
def setRequestToSend (set)
def setStopBits (stopBits)
def stopBits ()

Signals¶

def baudRateChanged (baudRate, directions)
def breakEnabledChanged (set)
def dataBitsChanged (dataBits)
def dataTerminalReadyChanged (set)
def errorOccurred (error)
def flowControlChanged (flowControl)
def parityChanged (parity)
def requestToSendChanged (set)
def stopBitsChanged (stopBits)

Detailed Description¶

You can get information about the available serial ports using the QSerialPortInfo helper class, which allows an enumeration of all the serial ports in the system. This is useful to obtain the correct name of the serial port you want to use. You can pass an object of the helper class as an argument to the setPort() or setPortName() methods to assign the desired serial device.

After setting the port, you can open it in read-only (r/o), write-only (w/o), or read-write (r/w) mode using the open() method.

Note

The serial port is always opened with exclusive access (that is, no other process or thread can access an already opened serial port).

Use the close() method to close the port and cancel the I/O operations.

Having successfully opened, QSerialPort tries to determine the current configuration of the port and initializes itself. You can reconfigure the port to the desired setting using the setBaudRate() , setDataBits() , setParity() , setStopBits() , and setFlowControl() methods.

There are a couple of properties to work with the pinout signals namely: dataTerminalReady , requestToSend . It is also possible to use the pinoutSignals() method to query the current pinout signals set.

Once you know that the ports are ready to read or write, you can use the read() or write() methods. Alternatively the readLine() and readAll() convenience methods can also be invoked. If not all the data is read at once, the remaining data will be available for later as new incoming data is appended to the QSerialPort ‘s internal read buffer. You can limit the size of the read buffer using setReadBufferSize() .

QSerialPort provides a set of functions that suspend the calling thread until certain signals are emitted. These functions can be used to implement blocking serial ports:

waitForReadyRead() blocks calls until new data is available for reading.

waitForBytesWritten() blocks calls until one payload of data has been written to the serial port.

See the following example:

int numRead = 0, numReadTotal = 0;
char buffer[50];

for (;;) {
    numRead  = serial.read(buffer, 50);

    // Do whatever with the array

    numReadTotal += numRead;
    if (numRead == 0 && !serial.waitForReadyRead())
        break;
}

If waitForReadyRead() returns false, the connection has been closed or an error has occurred.

If an error occurs at any point in time, QSerialPort will emit the errorOccurred() signal. You can also call error() to find the type of error that occurred last.

Programming with a blocking serial port is radically different from programming with a non-blocking serial port. A blocking serial port does not require an event loop and typically leads to simpler code. However, in a GUI application, blocking serial port should only be used in non-GUI threads, to avoid freezing the user interface.

For more details about these approaches, refer to the example applications.

The QSerialPort class can also be used with QTextStream and QDataStream ‘s stream operators (operator<<() and operator>>()). There is one issue to be aware of, though: make sure that enough data is available before attempting to read by using the operator>>() overloaded operator.

See also

QSerialPortInfo

class PySide6.QtSerialPort.QSerialPort([parent=None])¶

PySide6.QtSerialPort.QSerialPort(info[, parent=None])

PySide6.QtSerialPort.QSerialPort(name[, parent=None])

Parameters

info – PySide6.QtSerialPort.QSerialPortInfo
parent – PySide6.QtCore.QObject
name – str

Constructs a new serial port object with the given parent.

Constructs a new serial port object with the given parent to represent the serial port with the specified helper class serialPortInfo.

Constructs a new serial port object with the given parent to represent the serial port with the specified name.

The name should have a specific format; see the setPort() method.

PySide6.QtSerialPort.QSerialPort.Direction¶

This enum describes the possible directions of the data transmission.

Note

This enumeration is used for setting the baud rate of the device separately for each direction on some operating systems (for example, POSIX-like).

Constant	Description
QSerialPort.Input	Input direction.
QSerialPort.Output	Output direction.
QSerialPort.AllDirections	Simultaneously in two directions.

PySide6.QtSerialPort.QSerialPort.BaudRate¶

This enum describes the baud rate which the communication device operates with.

Note

Only the most common standard baud rates are listed in this enum.

Constant	Description
QSerialPort.Baud1200	1200 baud.
QSerialPort.Baud2400	2400 baud.
QSerialPort.Baud4800	4800 baud.
QSerialPort.Baud9600	9600 baud.
QSerialPort.Baud19200	19200 baud.
QSerialPort.Baud38400	38400 baud.
QSerialPort.Baud57600	57600 baud.
QSerialPort.Baud115200	115200 baud.

See also

baudRate

PySide6.QtSerialPort.QSerialPort.DataBits¶

This enum describes the number of data bits used.

Constant

Description

QSerialPort.Data5

The number of data bits in each character is 5. It is used for Baudot code. It generally only makes sense with older equipment such as teleprinters.

QSerialPort.Data6

The number of data bits in each character is 6. It is rarely used.

QSerialPort.Data7

The number of data bits in each character is 7. It is used for true ASCII. It generally only makes sense with older equipment such as teleprinters.

QSerialPort.Data8

The number of data bits in each character is 8. It is used for most kinds of data, as this size matches the size of a byte. It is almost universally used in newer applications.

See also

dataBits

PySide6.QtSerialPort.QSerialPort.Parity¶

This enum describes the parity scheme used.

Constant

Description

QSerialPort.NoParity

No parity bit it sent. This is the most common parity setting. Error detection is handled by the communication protocol.

QSerialPort.EvenParity

The number of 1 bits in each character, including the parity bit, is always even.

QSerialPort.OddParity

The number of 1 bits in each character, including the parity bit, is always odd. It ensures that at least one state transition occurs in each character.

QSerialPort.SpaceParity

Space parity. The parity bit is sent in the space signal condition. It does not provide error detection information.

QSerialPort.MarkParity

Mark parity. The parity bit is always set to the mark signal condition (logical 1). It does not provide error detection information.

See also

parity

PySide6.QtSerialPort.QSerialPort.StopBits¶

This enum describes the number of stop bits used.

Constant

Description

QSerialPort.OneStop

1 stop bit.

QSerialPort.OneAndHalfStop

1.5 stop bits. This is only for the Windows platform.

QSerialPort.TwoStop

2 stop bits.

See also

stopBits

PySide6.QtSerialPort.QSerialPort.FlowControl¶

This enum describes the flow control used.

Constant

Description

QSerialPort.NoFlowControl

No flow control.

QSerialPort.HardwareControl

Hardware flow control (RTS/CTS).

QSerialPort.SoftwareControl

Software flow control (XON/XOFF).

See also

flowControl

PySide6.QtSerialPort.QSerialPort.PinoutSignal¶

This enum describes the possible RS-232 pinout signals.

Constant

Description

QSerialPort.NoSignal

No line active

QSerialPort.DataTerminalReadySignal

DTR (Data Terminal Ready).

QSerialPort.DataCarrierDetectSignal

DCD (Data Carrier Detect).

QSerialPort.DataSetReadySignal

DSR (Data Set Ready).

QSerialPort.RingIndicatorSignal

RNG (Ring Indicator).

QSerialPort.RequestToSendSignal

RTS (Request To Send).

QSerialPort.ClearToSendSignal

CTS (Clear To Send).

QSerialPort.SecondaryTransmittedDataSignal

STD (Secondary Transmitted Data).

QSerialPort.SecondaryReceivedDataSignal

SRD (Secondary Received Data).

See also

pinoutSignals() dataTerminalReady requestToSend

PySide6.QtSerialPort.QSerialPort.SerialPortError¶

This enum describes the errors that may be contained by the error property.

Constant

Description

QSerialPort.NoError

No error occurred.

QSerialPort.DeviceNotFoundError

An error occurred while attempting to open an non-existing device.

QSerialPort.PermissionError

An error occurred while attempting to open an already opened device by another process or a user not having enough permission and credentials to open.

QSerialPort.OpenError

An error occurred while attempting to open an already opened device in this object.

QSerialPort.NotOpenError

This error occurs when an operation is executed that can only be successfully performed if the device is open. This value was introduced in QtSerialPort 5.2.

QSerialPort.WriteError

An I/O error occurred while writing the data.

QSerialPort.ReadError

An I/O error occurred while reading the data.

QSerialPort.ResourceError

An I/O error occurred when a resource becomes unavailable, e.g. when the device is unexpectedly removed from the system.

QSerialPort.UnsupportedOperationError

The requested device operation is not supported or prohibited by the running operating system.

QSerialPort.TimeoutError

A timeout error occurred. This value was introduced in QtSerialPort 5.2.

QSerialPort.UnknownError

An unidentified error occurred.

See also

error

PySide6.QtSerialPort.QSerialPort.baudRate([directions=QSerialPort.Direction.AllDirections])¶

Parameters: directions – Directions
Return type: qint32

See also

setBaudRate()

PySide6.QtSerialPort.QSerialPort.baudRateChanged(baudRate, directions)¶

Parameters

baudRate – qint32
directions – Directions

PySide6.QtSerialPort.QSerialPort.breakEnabledChanged(set)¶

Parameters: set – bool

PySide6.QtSerialPort.QSerialPort.clear([directions=QSerialPort.Direction.AllDirections])¶

Parameters: directions – Directions
Return type: bool

Discards all characters from the output or input buffer, depending on given directions directions. This includes clearing the internal class buffers and the UART (driver) buffers. Also terminate pending read or write operations. If successful, returns true; otherwise returns false.

Note

The serial port has to be open before trying to clear any buffered data; otherwise returns false and sets the NotOpenError error code.

PySide6.QtSerialPort.QSerialPort.clearError()¶

This property holds the error status of the serial port.

The I/O device status returns an error code. For example, if open() returns false, or a read/write operation returns -1, this property can be used to figure out the reason why the operation failed.

The error code is set to the default NoError after a call to

PySide6.QtSerialPort.QSerialPort.dataBits()¶

Return type: DataBits

This property holds the data bits in a frame.

If the setting is successful or set before opening the port, returns true; otherwise returns false and sets an error code which can be obtained by accessing the value of the error property.

Note

If the setting is set before opening the port, the actual serial port setting is done automatically in the open() method right after that the opening of the port succeeds.

The default value is Data8, i.e. 8 data bits.

PySide6.QtSerialPort.QSerialPort.dataBitsChanged(dataBits)¶

Parameters: dataBits – DataBits

PySide6.QtSerialPort.QSerialPort.dataTerminalReadyChanged(set)¶

Parameters: set – bool

PySide6.QtSerialPort.QSerialPort.error()¶

Return type: SerialPortError

This property holds the error status of the serial port.

The I/O device status returns an error code. For example, if open() returns false, or a read/write operation returns -1, this property can be used to figure out the reason why the operation failed.

The error code is set to the default NoError after a call to

PySide6.QtSerialPort.QSerialPort.errorOccurred(error)¶

Parameters: error – SerialPortError

PySide6.QtSerialPort.QSerialPort.flowControl()¶

Return type: FlowControl

This property holds the desired flow control mode.

If the setting is successful or set before opening the port, returns true; otherwise returns false and sets an error code which can be obtained by accessing the value of the error property.

Note

If the setting is set before opening the port, the actual serial port setting is done automatically in the open() method right after that the opening of the port succeeds.

The default value is NoFlowControl , i.e. no flow control.

PySide6.QtSerialPort.QSerialPort.flowControlChanged(flowControl)¶

Parameters: flowControl – FlowControl

PySide6.QtSerialPort.QSerialPort.flush()¶

Return type: bool

This function writes as much as possible from the internal write buffer to the underlying serial port without blocking. If any data was written, this function returns true; otherwise returns false.

Call this function for sending the buffered data immediately to the serial port. The number of bytes successfully written depends on the operating system. In most cases, this function does not need to be called, because the QSerialPort class will start sending data automatically once control is returned to the event loop. In the absence of an event loop, call waitForBytesWritten() instead.

Note

The serial port has to be open before trying to flush any buffered data; otherwise returns false and sets the NotOpenError error code.

See also

write() waitForBytesWritten()

PySide6.QtSerialPort.QSerialPort.handle()¶

Return type: int

If the platform is supported and the serial port is open, returns the native serial port handle; otherwise returns -1.

Warning

This function is for expert use only; use it at your own risk. Furthermore, this function carries no compatibility promise between minor Qt releases.

PySide6.QtSerialPort.QSerialPort.isBreakEnabled()¶

Return type: bool

This property holds the state of the transmission line in break.

Returns true on success, false otherwise. If the flag is true then the transmission line is in break state; otherwise is in non-break state.

Note

The serial port has to be open before trying to set or get this property; otherwise returns false and sets the NotOpenError error code. This is a bit unusual as opposed to the regular Qt property settings of a class. However, this is a special use case since the property is set through the interaction with the kernel and hardware. Hence, the two scenarios cannot be completely compared to each other.

PySide6.QtSerialPort.QSerialPort.isDataTerminalReady()¶

Return type: bool

This property holds the state (high or low) of the line signal DTR.

Returns true on success, false otherwise. If the flag is true then the DTR signal is set to high; otherwise low.

Note

The serial port has to be open before trying to set or get this property; otherwise false is returned and the error code is set to NotOpenError .

See also

pinoutSignals()

PySide6.QtSerialPort.QSerialPort.isRequestToSend()¶

Return type: bool

This property holds the state (high or low) of the line signal RTS.

Returns true on success, false otherwise. If the flag is true then the RTS signal is set to high; otherwise low.

Note

The serial port has to be open before trying to set or get this property; otherwise false is returned and the error code is set to NotOpenError .

Note

An attempt to control the RTS signal in the HardwareControl mode will fail with error code set to UnsupportedOperationError , because the signal is automatically controlled by the driver.

See also

pinoutSignals()

PySide6.QtSerialPort.QSerialPort.parity()¶

Return type: Parity

This property holds the parity checking mode.

If the setting is successful or set before opening the port, returns true; otherwise returns false and sets an error code which can be obtained by accessing the value of the error property.

Note

If the setting is set before opening the port, the actual serial port setting is done automatically in the open() method right after that the opening of the port succeeds.

The default value is NoParity , i.e. no parity.

PySide6.QtSerialPort.QSerialPort.parityChanged(parity)¶

Parameters: parity – Parity

PySide6.QtSerialPort.QSerialPort.pinoutSignals()¶

Return type: PinoutSignals

Returns the state of the line signals in a bitmap format.

From this result, it is possible to allocate the state of the desired signal by applying a mask “AND”, where the mask is the desired enumeration value from PinoutSignals .

Note

This method performs a system call, thus ensuring that the line signal states are returned properly. This is necessary when the underlying operating systems cannot provide proper notifications about the changes.

Note

The serial port has to be open before trying to get the pinout signals; otherwise returns NoSignal and sets the NotOpenError error code.

See also

dataTerminalReady requestToSend

PySide6.QtSerialPort.QSerialPort.portName()¶

Return type: str

Returns the name set by setPort() or passed to the QSerialPort constructor. This name is short, i.e. it is extracted and converted from the internal variable system location of the device. The conversion algorithm is platform specific:

Platform

Brief Description

Windows

Removes the prefix “\\.\” or “//./” from the system location and returns the remainder of the string.

Unix, BSD

Removes the prefix “/dev/” from the system location and returns the remainder of the string.

See also

setPortName() setPort() portName()

PySide6.QtSerialPort.QSerialPort.readBufferSize()¶

Return type: int

Returns the size of the internal read buffer. This limits the amount of data that the client can receive before calling the read() or readAll() methods.

A read buffer size of 0 (the default) means that the buffer has no size limit, ensuring that no data is lost.

See also

setReadBufferSize() read()

PySide6.QtSerialPort.QSerialPort.requestToSendChanged(set)¶

Parameters: set – bool

PySide6.QtSerialPort.QSerialPort.setBaudRate(baudRate[, directions=QSerialPort.Direction.AllDirections])¶

Parameters

baudRate – qint32
directions – Directions

Return type

bool

See also

baudRate()

PySide6.QtSerialPort.QSerialPort.setBreakEnabled([set=true])¶

Parameters: set – bool
Return type: bool

See also

isBreakEnabled()

PySide6.QtSerialPort.QSerialPort.setDataBits(dataBits)¶

Parameters: dataBits – DataBits
Return type: bool

See also

dataBits()

PySide6.QtSerialPort.QSerialPort.setDataTerminalReady(set)¶

Parameters: set – bool
Return type: bool

See also

isDataTerminalReady()

PySide6.QtSerialPort.QSerialPort.setFlowControl(flowControl)¶

Parameters: flowControl – FlowControl
Return type: bool

See also

flowControl()

PySide6.QtSerialPort.QSerialPort.setParity(parity)¶

Parameters: parity – Parity
Return type: bool

See also

parity()

PySide6.QtSerialPort.QSerialPort.setPort(info)¶

Parameters: info – PySide6.QtSerialPort.QSerialPortInfo

Sets the port stored in the serial port info instance serialPortInfo.

See also

portName() QSerialPortInfo

PySide6.QtSerialPort.QSerialPort.setPortName(name)¶

Parameters: name – str

Sets the name of the serial port.

The name of the serial port can be passed as either a short name or the long system location if necessary.

See also

portName() QSerialPortInfo

PySide6.QtSerialPort.QSerialPort.setReadBufferSize(size)¶

Parameters: size – int

Sets the size of QSerialPort ‘s internal read buffer to be size bytes.

If the buffer size is limited to a certain size, QSerialPort will not buffer more than this size of data. The special case of a buffer size of 0 means that the read buffer is unlimited and all incoming data is buffered. This is the default.

This option is useful if the data is only read at certain points in time (for instance in a real-time streaming application) or if the serial port should be protected against receiving too much data, which may eventually cause the application to run out of memory.

See also

readBufferSize() read()

PySide6.QtSerialPort.QSerialPort.setRequestToSend(set)¶

Parameters: set – bool
Return type: bool

See also

isRequestToSend()

PySide6.QtSerialPort.QSerialPort.setStopBits(stopBits)¶

Parameters: stopBits – StopBits
Return type: bool

See also

stopBits()

PySide6.QtSerialPort.QSerialPort.stopBits()¶

Return type: StopBits

This property holds the number of stop bits in a frame.

If the setting is successful or set before opening the port, returns true; otherwise returns false and sets an error code which can be obtained by accessing the value of the error property.

Note

If the setting is set before opening the port, the actual serial port setting is done automatically in the open() method right after that the opening of the port succeeds.

The default value is OneStop , i.e. 1 stop bit.

PySide6.QtSerialPort.QSerialPort.stopBitsChanged(stopBits)¶

Parameters: stopBits – StopBits

Table of Contents

Previous topic

Next topic

QSerialPort¶

Synopsis¶

Functions¶

Signals¶

Detailed Description¶

Constant	Description
QSerialPort.Data5	The number of data bits in each character is 5. It is used for Baudot code. It generally only makes sense with older equipment such as teleprinters.
QSerialPort.Data6	The number of data bits in each character is 6. It is rarely used.
QSerialPort.Data7	The number of data bits in each character is 7. It is used for true ASCII. It generally only makes sense with older equipment such as teleprinters.
QSerialPort.Data8	The number of data bits in each character is 8. It is used for most kinds of data, as this size matches the size of a byte. It is almost universally used in newer applications.

Constant	Description
QSerialPort.NoParity	No parity bit it sent. This is the most common parity setting. Error detection is handled by the communication protocol.
QSerialPort.EvenParity	The number of 1 bits in each character, including the parity bit, is always even.
QSerialPort.OddParity	The number of 1 bits in each character, including the parity bit, is always odd. It ensures that at least one state transition occurs in each character.
QSerialPort.SpaceParity	Space parity. The parity bit is sent in the space signal condition. It does not provide error detection information.
QSerialPort.MarkParity	Mark parity. The parity bit is always set to the mark signal condition (logical 1). It does not provide error detection information.

Constant	Description
QSerialPort.OneStop	1 stop bit.
QSerialPort.OneAndHalfStop	1.5 stop bits. This is only for the Windows platform.
QSerialPort.TwoStop	2 stop bits.

Constant	Description
QSerialPort.NoFlowControl	No flow control.
QSerialPort.HardwareControl	Hardware flow control (RTS/CTS).
QSerialPort.SoftwareControl	Software flow control (XON/XOFF).

Constant	Description
QSerialPort.NoSignal	No line active
QSerialPort.DataTerminalReadySignal	DTR (Data Terminal Ready).
QSerialPort.DataCarrierDetectSignal	DCD (Data Carrier Detect).
QSerialPort.DataSetReadySignal	DSR (Data Set Ready).
QSerialPort.RingIndicatorSignal	RNG (Ring Indicator).
QSerialPort.RequestToSendSignal	RTS (Request To Send).
QSerialPort.ClearToSendSignal	CTS (Clear To Send).
QSerialPort.SecondaryTransmittedDataSignal	STD (Secondary Transmitted Data).
QSerialPort.SecondaryReceivedDataSignal	SRD (Secondary Received Data).

Constant	Description
QSerialPort.NoError	No error occurred.
QSerialPort.DeviceNotFoundError	An error occurred while attempting to open an non-existing device.
QSerialPort.PermissionError	An error occurred while attempting to open an already opened device by another process or a user not having enough permission and credentials to open.
QSerialPort.OpenError	An error occurred while attempting to open an already opened device in this object.
QSerialPort.NotOpenError	This error occurs when an operation is executed that can only be successfully performed if the device is open. This value was introduced in QtSerialPort 5.2.
QSerialPort.WriteError	An I/O error occurred while writing the data.
QSerialPort.ReadError	An I/O error occurred while reading the data.
QSerialPort.ResourceError	An I/O error occurred when a resource becomes unavailable, e.g. when the device is unexpectedly removed from the system.
QSerialPort.UnsupportedOperationError	The requested device operation is not supported or prohibited by the running operating system.
QSerialPort.TimeoutError	A timeout error occurred. This value was introduced in QtSerialPort 5.2.
QSerialPort.UnknownError	An unidentified error occurred.

Platform	Brief Description
Windows	Removes the prefix “\\.\” or “//./” from the system location and returns the remainder of the string.
Unix, BSD	Removes the prefix “/dev/” from the system location and returns the remainder of the string.