QSerialPort

Provides functions to access serial ports. More

Inheritance diagram of PySide6.QtSerialPort.QSerialPort

Synopsis

Functions

Signals

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

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

directionsDirections

Return type

qint32

See also

setBaudRate()

PySide6.QtSerialPort.QSerialPort.baudRateChanged(baudRate, directions)
Parameters
  • baudRateqint32

  • directionsDirections

PySide6.QtSerialPort.QSerialPort.breakEnabledChanged(set)
Parameters

set – bool

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

directionsDirections

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

dataBitsDataBits

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

errorSerialPortError

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

flowControlFlowControl

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

parityParity

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.

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
  • baudRateqint32

  • directionsDirections

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

dataBitsDataBits

Return type

bool

See also

dataBits()

PySide6.QtSerialPort.QSerialPort.setDataTerminalReady(set)
Parameters

set – bool

Return type

bool

PySide6.QtSerialPort.QSerialPort.setFlowControl(flowControl)
Parameters

flowControlFlowControl

Return type

bool

See also

flowControl()

PySide6.QtSerialPort.QSerialPort.setParity(parity)
Parameters

parityParity

Return type

bool

See also

parity()

PySide6.QtSerialPort.QSerialPort.setPort(info)
Parameters

infoPySide6.QtSerialPort.QSerialPortInfo

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

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.

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

PySide6.QtSerialPort.QSerialPort.setStopBits(stopBits)
Parameters

stopBitsStopBits

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

stopBitsStopBits