pySerial API¶

class serial. Serial ¶ __init__ ( port=None, baudrate=9600, bytesize=EIGHTBITS, parity=PARITY_NONE, stopbits=STOPBITS_ONE, timeout=None, xonxoff=False, rtscts=False, write_timeout=None, dsrdtr=False, inter_byte_timeout=None, exclusive=None ) ¶

port – Device name or None .
baudrate (int) – Baud rate such as 9600 or 115200 etc.
bytesize – Number of data bits. Possible values: FIVEBITS , SIXBITS , SEVENBITS , EIGHTBITS
parity – Enable parity checking. Possible values: PARITY_NONE , PARITY_EVEN , PARITY_ODDPARITY_MARK , PARITY_SPACE
stopbits – Number of stop bits. Possible values: STOPBITS_ONE , STOPBITS_ONE_POINT_FIVE , STOPBITS_TWO
timeout (float) – Set a read timeout value in seconds.
xonxoff (bool) – Enable software flow control.
rtscts (bool) – Enable hardware (RTS/CTS) flow control.
dsrdtr (bool) – Enable hardware (DSR/DTR) flow control.
write_timeout (float) – Set a write timeout value in seconds.
inter_byte_timeout (float) – Inter-character timeout, None to disable (default).
exclusive (bool) – Set exclusive access mode (POSIX only). A port cannot be opened in exclusive access mode if it is already open in exclusive access mode.

ValueError – Will be raised when parameter are out of range, e.g. baud rate, data bits.
SerialException – In case the device can not be found or can not be configured.

The port is immediately opened on object creation, when a port is given. It is not opened when port is None and a successive call to open() is required.

port is a device name: depending on operating system. e.g. /dev/ttyUSB0 on GNU/Linux or COM3 on Windows.

The parameter baudrate can be one of the standard values: 50, 75, 110, 134, 150, 200, 300, 600, 1200, 1800, 2400, 4800, 9600, 19200, 38400, 57600, 115200. These are well supported on all platforms.

Standard values above 115200, such as: 230400, 460800, 500000, 576000, 921600, 1000000, 1152000, 1500000, 2000000, 2500000, 3000000, 3500000, 4000000 also work on many platforms and devices.

Non-standard values are also supported on some platforms (GNU/Linux, MAC OSX >= Tiger, Windows). Though, even on these platforms some serial ports may reject non-standard values.

Possible values for the parameter timeout which controls the behavior of read() :

timeout = None : wait forever / until requested number of bytes are received
timeout = 0 : non-blocking mode, return immediately in any case, returning zero or more, up to the requested number of bytes
timeout = x : set timeout to x seconds (float allowed) returns immediately when the requested number of bytes are available, otherwise wait until the timeout expires and return all bytes that were received until then.

write() is blocking by default, unless write_timeout is set. For possible values refer to the list for timeout above.

Note that enabling both flow control methods (xonxoff and rtscts) together may not be supported. It is common to use one of the methods at once, not both.

dsrdtr is not supported by all platforms (silently ignored). Setting it to None has the effect that its state follows rtscts.

Also consider using the function serial_for_url() instead of creating Serial instances directly.

Changed in version 2.5: dsrdtr now defaults to False (instead of None)

Changed in version 3.0: numbers as port argument are no longer supported

New in version 3.3: exclusive flag

Open port. The state of rts and dtr is applied.

Some OS and/or drivers may activate RTS and or DTR automatically, as soon as the port is opened. There may be a glitch on RTS/DTR when rts or dtr are set differently from their default value ( True / active).

For compatibility reasons, no error is reported when applying rts or dtr fails on POSIX due to EINVAL (22) or ENOTTY (25).

Close port immediately.

Destructor, close port when serial port instance is freed.

The following methods may raise SerialException when applied to a closed port.

Parameters:	size – Number of bytes to read.
Returns:	Bytes read from the port.
Return type:	bytes

Read size bytes from the serial port. If a timeout is set it may return fewer characters than requested. With no timeout it will block until the requested number of bytes is read.

Changed in version 2.5: Returns an instance of bytes when available (Python 2.6 and newer) and str otherwise.

read_until ( expected=LF, size=None ) ¶

Bytes read from the port.

Read until an expected sequence is found (‘\n’ by default), the size is exceeded or until timeout occurs. If a timeout is set it may return fewer characters than requested. With no timeout it will block until the requested number of bytes is read.

Changed in version 2.5: Returns an instance of bytes when available (Python 2.6 and newer) and str otherwise.

Changed in version 3.5: First argument was called terminator in previous versions.

write ( data ) ¶

Parameters:	data – Data to send.
Returns:	Number of bytes written.
Return type:	int
Raises:	SerialTimeoutException – In case a write timeout is configured for the port and the time is exceeded.

Write the bytes data to the port. This should be of type bytes (or compatible such as bytearray or memoryview ). Unicode strings must be encoded (e.g. 'hello'.encode('utf-8') .

Changed in version 2.5: Accepts instances of bytes and bytearray when available (Python 2.6 and newer) and str otherwise.

Changed in version 2.5: Write returned None in previous versions.

Flush of file like objects. In this case, wait until all data is written.

Getter:	Get the number of bytes in the input buffer
Type:	int

Return the number of bytes in the receive buffer.

Changed in version 3.0: changed to property from inWaiting()

out_waiting ¶

Getter:	Get the number of bytes in the output buffer
Type:	int
Platform:	Posix
Platform:	Windows

Return the number of bytes in the output buffer.

Changed in version 2.7: (Posix support added)

Changed in version 3.0: changed to property from outWaiting()

reset_input_buffer ( ) ¶

Flush input buffer, discarding all its contents.

Changed in version 3.0: renamed from flushInput()

reset_output_buffer ( ) ¶

Clear output buffer, aborting the current output and discarding all that is in the buffer.

Note, for some USB serial adapters, this may only flush the buffer of the OS and not all the data that may be present in the USB part.

Changed in version 3.0: renamed from flushOutput()

send_break ( duration=0.25 ) ¶

Parameters:	duration (float) – Time in seconds, to activate the BREAK condition.

Send break condition. Timed, returns to idle state after given duration.

Getter:	Get the current BREAK state
Setter:	Control the BREAK state
Type:	bool

When set to True activate BREAK condition, else disable. Controls TXD. When active, no transmitting is possible.

Setter:	Set the state of the RTS line
Getter:	Return the state of the RTS line
Type:	bool

Set RTS line to specified logic level. It is possible to assign this value before opening the serial port, then the value is applied upon open() (with restrictions, see open() ).

Setter:	Set the state of the DTR line
Getter:	Return the state of the DTR line
Type:	bool

Set DTR line to specified logic level. It is possible to assign this value before opening the serial port, then the value is applied upon open() (with restrictions, see open() ).

Getter:	Device name.
Type:	str

New in version 2.5.

Getter:	Get the state of the CTS line
Type:	bool

Return the state of the CTS line.

Getter:	Get the state of the DSR line
Type:	bool

Return the state of the DSR line.

Getter:	Get the state of the RI line
Type:	bool

Return the state of the RI line.

Getter:	Get the state of the CD line
Type:	bool

Return the state of the CD line

Getter:	Get the state of the serial port, whether it’s open.
Type:	bool

New values can be assigned to the following attributes (properties), the port will be reconfigured, even if it’s opened at that time:

Read or write port. When the port is already open, it will be closed and reopened with the new setting.

Getter:	Get current baud rate
Setter:	Set new baud rate
Type:	int

Read or write current baud rate setting.

Getter:	Get current byte size
Setter:	Set new byte size. Possible values: FIVEBITS , SIXBITS , SEVENBITS , EIGHTBITS
Type:	int

Read or write current data byte size setting.

Getter:	Get current parity setting
Setter:	Set new parity mode. Possible values: PARITY_NONE , PARITY_EVEN , PARITY_ODD PARITY_MARK , PARITY_SPACE

Read or write current parity setting.

Getter:	Get current stop bit setting
Setter:	Set new stop bit setting. Possible values: STOPBITS_ONE , STOPBITS_ONE_POINT_FIVE , STOPBITS_TWO

Read or write current stop bit width setting.

Getter:	Get current read timeout setting
Setter:	Set read timeout
Type:	float (seconds)

Read or write current read timeout setting.

Getter:	Get current write timeout setting
Setter:	Set write timeout
Type:	float (seconds)

Read or write current write timeout setting.

Changed in version 3.0: renamed from writeTimeout

inter_byte_timeout ¶

Getter:	Get current inter byte timeout setting
Setter:	Disable ( None ) or enable the inter byte timeout
Type:	float or None

Read or write current inter byte timeout setting.

Changed in version 3.0: renamed from interCharTimeout

Getter:	Get current software flow control setting
Setter:	Enable or disable software flow control
Type:	bool

Read or write current software flow control rate setting.

Getter:	Get current hardware flow control setting
Setter:	Enable or disable hardware flow control
Type:	bool

Read or write current hardware flow control setting.

Getter:	Get current hardware flow control setting
Setter:	Enable or disable hardware flow control
Type:	bool

Read or write current hardware flow control setting.

Getter:	Get the current RS485 settings
Setter:	Disable ( None ) or enable the RS485 settings
Type:	rs485.RS485Settings or None
Platform:	Posix (Linux, limited set of hardware)
Platform:	Windows (only RTS on TX possible)

Attribute to configure RS485 support. When set to an instance of rs485.RS485Settings and supported by OS, RTS will be active when data is sent and inactive otherwise (for reception). The rs485.RS485Settings class provides additional settings supported on some platforms.

New in version 3.0.

The following constants are also provided:

A list of valid baud rates. The list may be incomplete, such that higher and/or intermediate baud rates may also be supported by the device (Read Only).

A list of valid byte sizes for the device (Read Only).

A list of valid parities for the device (Read Only).

A list of valid stop bit widths for the device (Read Only).

The following methods are for compatibility with the io library.

Returns:	True

New in version 2.5.

Returns:	True