PySerial

Warnings

• breaking Python 2.x vs. Python 3.x String Handling: PySerial 3.x requires `bytes` objects for write operations (e.g., `ser.write(b'data')`). Direct string literals (`'data'`) will cause errors in Python 3.x, unlike Python 2.x where strings were byte sequences.
  Fix: Ensure all data written to the serial port is encoded as `bytes` (e.g., `b'your data'` or `my_string.encode('utf-8')`). Data read from the port will also be `bytes` and may need to be decoded (`received_data.decode('utf-8')`).
• breaking Removal of `serial.aio`: Asynchronous I/O support (`serial.aio`) was removed from the core PySerial library in version 3.2.1.
  Fix: For asynchronous serial communication, install the separate `pyserial-asyncio` library (`pip install pyserial-asyncio`) and use its API.
• deprecated Deprecated methods `inWaiting()` and `isOpen()`: These methods were deprecated in favor of more Pythonic attribute names.
  Fix: Use `ser.in_waiting` (integer, number of bytes in input buffer) instead of `ser.inWaiting()` and `ser.is_open` (boolean) instead of `ser.isOpen()`.
• gotcha `readline()` without a timeout can block indefinitely: If a timeout is not set on the `Serial` object, `readline()` will block until a newline character is received, which can lead to unresponsive applications if the device does not send one.
  Fix: Always set a `timeout` parameter (e.g., `timeout=1`) when initializing `serial.Serial`. This will cause `readline()` to return after the specified duration if no data or newline is received.
• breaking Removal of `serial.device()`: The function `serial.device()` for listing ports was removed.
  Fix: Use `serial.tools.list_ports` module for port enumeration. For example, `from serial.tools import list_ports; ports = list_ports.comports()`.

Install

• pip install pyserial Install latest stable version

Imports

• Serial

  import serial
  ser = serial.Serial(...)

  The primary class for serial communication is `Serial`, typically imported from the `serial` module, not directly from `pyserial`.
• list_ports

  from serial.tools import list_ports

  Port listing utilities are located within `serial.tools.list_ports`.

Quickstart

This quickstart demonstrates how to open, configure, write to, and read from a serial port using PySerial. It includes error handling and ensures the port is closed. Remember to replace `'COM_PORT_HERE'` with your actual serial port name and adjust `baudrate` as needed for your device. Data sent and received must be handled as `bytes` in Python 3.

import serial
import time

# Configure the serial port
# Replace 'COM3' with your actual serial port ('/dev/ttyUSB0' on Linux, 'COMx' on Windows)
# Ensure baudrate matches your device
ser = serial.Serial(
    port='COM_PORT_HERE', 
    baudrate=9600, 
    bytesize=serial.EIGHTBITS, 
    parity=serial.PARITY_NONE, 
    stopbits=serial.STOPBITS_ONE,
    timeout=1 # Read timeout in seconds
)

try:
    if not ser.is_open:
        ser.open()
    print(f"Serial port {ser.name} opened successfully.")

    # Write data (must be bytes in Python 3)
    message_to_send = b"Hello, device!\n"
    ser.write(message_to_send)
    print(f"Sent: {message_to_send.decode().strip()}")

    time.sleep(0.1) # Give the device some time to respond

    # Read data
    received_data = ser.readline() # Reads until newline or timeout
    if received_data:
        print(f"Received: {received_data.decode().strip()}")
    else:
        print("No data received within timeout.")

except serial.SerialException as e:
    print(f"Serial port error: {e}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")
finally:
    if ser.is_open:
        ser.close()
        print("Serial port closed.")