{"id":7831,"library":"uart-devices","title":"UART Devices for Linux","description":"uart-devices is a Python library for interacting with UART (Universal Asynchronous Receiver-Transmitter) devices on Linux systems. It provides an asynchronous, structured way to define and communicate with serial devices, abstracting away some of the lower-level details. The current version is 0.1.1, with initial development starting in April 2024 and a low release cadence.","status":"active","version":"0.1.1","language":"en","source_language":"en","source_url":"https://github.com/bluetooth-devices/uart-devices","tags":["uart","serial","linux","hardware","asyncio"],"install":[{"cmd":"pip install uart-devices","lang":"bash","label":"Install stable release"}],"dependencies":[{"reason":"Provides the low-level serial port communication interface.","package":"pyserial","optional":false}],"imports":[{"symbol":"UARTDevice","correct":"from uart_devices import UARTDevice"}],"quickstart":{"code":"import asyncio\nimport logging\nimport os\nfrom uart_devices import UARTDevice\n\nlogging.basicConfig(level=logging.INFO)\n\n# Set UART_DEVICE_PORT environment variable before running, e.g.:\n# export UART_DEVICE_PORT=/dev/ttyUSB0\n# For demonstration, we use a common default like /dev/ttyS0 if not set.\n# Ensure this port exists and you have permissions.\nUART_PORT = os.environ.get(\"UART_DEVICE_PORT\", \"/dev/ttyS0\")\n\nclass MySimpleUARTDevice(UARTDevice):\n    port = UART_PORT\n    baudrate = 115200 # Common baud rate\n\n    async def _async_on_open(self) -> None:\n        logging.info(f\"UART device {self.port} opened successfully.\")\n\n    async def _async_on_close(self) -> None:\n        logging.info(f\"UART device {self.port} closed.\")\n\n    async def _async_read_data(self, data: bytes) -> None:\n        \"\"\"Called when data is received.\"\"\"\n        logging.info(f\"Received data: {data.hex()}\")\n\nasync def main():\n    device = MySimpleUARTDevice()\n    print(f\"Attempting to interact with UART device on port: {device.port}...\")\n    try:\n        await device.open()\n        # In a real application, you would perform async read/write operations here.\n        # For this example, we just keep it open briefly and then close.\n        await asyncio.sleep(0.5)\n        await device.close()\n        print(f\"Successfully interacted with and closed device on {device.port}.\")\n    except Exception as e:\n        logging.error(f\"Failed to interact with UART device on {device.port}: {type(e).__name__}: {e}\")\n        print(\"\\n--- Troubleshooting Tips ---\")\n        print(\"1. Check permissions: Ensure your user is in the 'dialout' or 'uucp' group. (e.g., `sudo usermod -a -G dialout $USER` then log out and back in).\")\n        print(\"2. Verify device path: Ensure `UART_DEVICE_PORT` (e.g., /dev/ttyUSB0, /dev/ttyS0) is correct and the device is connected.\")\n        print(\"3. Check baud rate: Ensure 115200 matches your device's baud rate.\")\n\nif __name__ == \"__main__\":\n    asyncio.run(main())","lang":"python","description":"This quickstart demonstrates how to initialize and interact with a UART device using `uart-devices`. It defines a simple device class, opens the port asynchronously, simulates a brief interaction, and then closes it. It includes common troubleshooting tips for permission and device path errors."},"warnings":[{"fix":"Add your user to the 'dialout' group (or 'uucp' on some systems) using `sudo usermod -a -G dialout $USER`. Then, log out and log back in for the changes to take effect.","message":"Accessing serial ports on Linux often requires specific user permissions. If your user is not part of the 'dialout' or 'uucp' group, you will encounter `PermissionError`.","severity":"gotcha","affected_versions":"All"},{"fix":"Verify the correct device path by checking `/dev/` directory after plugging in your device (e.g., `ls /dev/tty*`). Update the `port` attribute in your `UARTDevice` subclass accordingly.","message":"The specified UART device path (e.g., `/dev/ttyUSB0`) must exist and refer to an actual connected serial device. Incorrect paths will lead to `FileNotFoundError` or similar issues.","severity":"gotcha","affected_versions":"All"},{"fix":"Consult your device's documentation for the correct baud rate and set the `baudrate` attribute (e.g., `baudrate = 9600`) to match.","message":"Ensure the `baudrate` configured in your `UARTDevice` subclass matches the baud rate of your physical serial device. A mismatch will result in corrupted or unreadable data.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Add your user to the 'dialout' group (or 'uucp' on some systems) using `sudo usermod -a -G dialout $USER`. Then, log out and log back in for the changes to take effect.","cause":"The current user does not have read/write permissions for the specified serial port.","error":"[Errno 13] Permission denied: '/dev/ttyUSB0'"},{"fix":"Check if the serial device is properly connected and recognized by the system. Verify the correct device path (e.g., `/dev/ttyUSB0`, `/dev/ttyACM0`) using `ls /dev/tty*` and update your code.","cause":"The specified serial port path does not exist, or the device is not connected/enumerated.","error":"FileNotFoundError: [Errno 2] No such file or directory: '/dev/ttyS0'"},{"fix":"Ensure no other program (e.g., a terminal emulator, another script) is currently accessing the serial port. You might need to restart the device or your system in some cases.","cause":"The serial port is already in use by another application or process.","error":"serial.serialutil.SerialException: Cannot configure port, something went wrong. Original message: 'I/O operation in progress'"}]}