com2tty 0.1.0__py3-none-any.whl

com2tty/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

com2tty/__main__.py

@@ -0,0 +1,4 @@
+from com2tty.cli import main
+
+if __name__ == "__main__": # pragma: no cover
+    main()

com2tty/bridge.py

@@ -0,0 +1,131 @@
+import sys
+import os
+import select
+import argparse
+import signal
+import traceback
+
+def cleanup_symlink(path):
+    if path and os.path.exists(path):
+        try:
+            os.unlink(path)
+            sys.stderr.write(f"Removed symlink: {path}\n")
+            sys.stderr.flush()
+        except Exception as e: # pragma: no cover
+            sys.stderr.write(f"Failed to remove symlink {path}: {e}\n")
+            sys.stderr.flush()
+
+def main():
+    parser = argparse.ArgumentParser(description="com2tty WSL Bridge Helper")
+    parser.add_argument(
+        "-s", "--symlink",
+        required=True,
+        help="Target symlink path for the pseudo-terminal device."
+    )
+    args = parser.parse_args()
+    
+    target_path = args.symlink
+    created_symlink = None
+    
+    # We must keep both master and slave descriptors open.
+    # Keeping slave_fd open prevents EIO errors on the master side when
+    # WSL clients open and close the virtual serial port.
+    master_fd = None
+    slave_fd = None
+    
+    try:
+        master_fd, slave_fd = os.openpty()
+        slave_name = os.ttyname(slave_fd)
+        
+        sys.stderr.write(f"Created pseudo-terminal: master_fd={master_fd}, slave={slave_name}\n")
+        sys.stderr.flush()
+        
+        # Attempt to create the symlink at target path
+        try:
+            if os.path.lexists(target_path):
+                os.unlink(target_path)
+            os.symlink(slave_name, target_path)
+            created_symlink = target_path
+            sys.stderr.write(f"Successfully symlinked {target_path} -> {slave_name}\n")
+            sys.stderr.flush()
+        except PermissionError:
+            # Fallback to /tmp if write permission to dev is denied
+            basename = os.path.basename(target_path)
+            fallback_path = f"/tmp/{basename}"
+            sys.stderr.write(f"Warning: Permission denied creating symlink at {target_path}.\n")
+            sys.stderr.write(f"Attempting fallback to user-writable path: {fallback_path}...\n")
+            sys.stderr.flush()
+            
+            if os.path.lexists(fallback_path):
+                os.unlink(fallback_path)
+            os.symlink(slave_name, fallback_path)
+            created_symlink = fallback_path
+            
+            sys.stderr.write(f"Fallback successful: {fallback_path} -> {slave_name}\n")
+            sys.stderr.write("--------------------------------------------------\n")
+            sys.stderr.write(f"To use the desired device path '{target_path}', please run this command ONCE in WSL:\n")
+            sys.stderr.write(f"  sudo ln -sf {fallback_path} {target_path}\n")
+            sys.stderr.write("--------------------------------------------------\n")
+            sys.stderr.flush()
+            
+        # Select loop
+        # 0 is stdin, master_fd is the pseudo-terminal master
+        sys.stderr.write("WSL bridge enter main loop.\n")
+        sys.stderr.flush()
+        
+        while True:
+            # select blocks until data is available on stdin or master_fd
+            r, w, x = select.select([0, master_fd], [], [])
+            
+            if 0 in r:
+                data = os.read(0, 4096)
+                if not data:
+                    sys.stderr.write("EOF on stdin. Exiting.\n")
+                    sys.stderr.flush()
+                    break
+                os.write(master_fd, data)
+                
+            if master_fd in r:
+                # Read from the virtual serial port
+                try:
+                    data = os.read(master_fd, 4096)
+                    if not data:
+                        # Should not happen typically while slave_fd is kept open,
+                        # but handle it gracefully if it does.
+                        sys.stderr.write("EOF on PTY master. Exiting.\n")
+                        sys.stderr.flush()
+                        break
+                    os.write(1, data)
+                except OSError as e:
+                    # In case of EIO (Input/output error) when slave closes,
+                    # just ignore it and continue since we keep slave_fd open.
+                    if e.errno == 5: # EIO
+                        continue
+                    else:
+                        raise e
+                        
+    except KeyboardInterrupt: # pragma: no cover
+        sys.stderr.write("WSL bridge interrupted by signal.\n")
+        sys.stderr.flush()
+    except Exception as e: # pragma: no cover
+        sys.stderr.write(f"WSL bridge error: {traceback.format_exc()}\n")
+        sys.stderr.flush()
+    finally:
+        # Clean up symlink and file descriptors
+        if created_symlink:
+            cleanup_symlink(created_symlink)
+        if slave_fd is not None:
+            try:
+                os.close(slave_fd)
+            except Exception:
+                pass
+        if master_fd is not None:
+            try:
+                os.close(master_fd)
+            except Exception:
+                pass
+        sys.stderr.write("WSL bridge shut down.\n")
+        sys.stderr.flush()
+
+if __name__ == "__main__": # pragma: no cover
+    main()

com2tty/cli.py

@@ -0,0 +1,112 @@
+import argparse
+import sys
+import logging
+from com2tty.host import run_bridge
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="com2tty: Forward Windows COM ports to WSL virtual ttyUSB devices."
+    )
+    
+    parser.add_argument(
+        "port",
+        help="Windows COM port to connect to (e.g. COM3 or COM1)."
+    )
+    
+    parser.add_argument(
+        "-b", "--baud",
+        type=int,
+        default=9600,
+        help="Baud rate for the serial port (default: 9600)."
+    )
+    
+    parser.add_argument(
+        "-w", "--wsl-tty",
+        default="/tmp/ttyUSB0",
+        help="Target symlink path inside WSL (default: /tmp/ttyUSB0)."
+    )
+    
+    parser.add_argument(
+        "--bytesize",
+        type=int,
+        choices=[5, 6, 7, 8],
+        default=8,
+        help="Serial byte size (default: 8)."
+    )
+    
+    parser.add_argument(
+        "--parity",
+        choices=["N", "E", "O", "S", "M"],
+        default="N",
+        help="Serial parity: None, Even, Odd, Space, Mark (default: N)."
+    )
+    
+    parser.add_argument(
+        "--stopbits",
+        type=float,
+        choices=[1, 1.5, 2],
+        default=1,
+        help="Serial stop bits: 1, 1.5, or 2 (default: 1)."
+    )
+    
+    parser.add_argument(
+        "--xonxoff",
+        action="store_true",
+        help="Enable software flow control (XON/XOFF)."
+    )
+    
+    parser.add_argument(
+        "--rtscts",
+        action="store_true",
+        help="Enable hardware flow control (RTS/CTS)."
+    )
+    
+    parser.add_argument(
+        "--dsrdtr",
+        action="store_true",
+        help="Enable hardware flow control (DSR/DTR)."
+    )
+    
+    parser.add_argument(
+        "-d", "--debug",
+        action="store_true",
+        help="Enable debug logging output."
+    )
+    
+    args = parser.add_argument_group("advanced")
+    
+    parsed_args = parser.parse_args()
+    
+    # Configure logging
+    log_level = logging.DEBUG if parsed_args.debug else logging.INFO
+    logging.basicConfig(
+        level=log_level,
+        format="[%(asctime)s] %(levelname)s: %(message)s",
+        datefmt="%H:%M:%S",
+        stream=sys.stderr
+    )
+    
+    try:
+        run_bridge(
+            port=parsed_args.port,
+            baud=parsed_args.baud,
+            wsl_tty=parsed_args.wsl_tty,
+            bytesize=parsed_args.bytesize,
+            parity=parsed_args.parity,
+            stopbits=parsed_args.stopbits,
+            xonxoff=parsed_args.xonxoff,
+            rtscts=parsed_args.rtscts,
+            dsrdtr=parsed_args.dsrdtr
+        )
+    except KeyboardInterrupt:
+        logging.info("Interrupted by user. Exiting.")
+        sys.exit(0)
+    except Exception as e:
+        logging.error(f"Fatal error: {e}")
+        if parsed_args.debug:
+            import traceback
+            traceback.print_exc()
+        sys.exit(1)
+
+if __name__ == "__main__": # pragma: no cover
+    main()

com2tty/host.py

@@ -0,0 +1,180 @@
+import os
+import sys
+import time
+import logging
+import subprocess
+import threading
+import serial
+
+def get_wsl_path(win_path):
+    cmd = ["wsl", "wslpath", "-u", win_path]
+    try:
+        res = subprocess.run(cmd, capture_output=True, text=True, check=True)
+        return res.stdout.strip()
+    except Exception as e:
+        logging.debug(f"wslpath failed: {e}. Using fallback conversion.")
+        # Fallback to mounting convention /mnt/<drive>/...
+        drive = win_path[0].lower()
+        path = win_path[2:].replace("\\", "/")
+        return f"/mnt/{drive}{path}"
+
+def get_serial_settings(bytesize, parity, stopbits):
+    bytesize_map = {
+        5: serial.FIVEBITS,
+        6: serial.SIXBITS,
+        7: serial.SEVENBITS,
+        8: serial.EIGHTBITS
+    }
+    parity_map = {
+        "N": serial.PARITY_NONE,
+        "E": serial.PARITY_EVEN,
+        "O": serial.PARITY_ODD,
+        "S": serial.PARITY_SPACE,
+        "M": serial.PARITY_MARK
+    }
+    stopbits_map = {
+        1: serial.STOPBITS_ONE,
+        1.5: serial.STOPBITS_ONE_POINT_FIVE,
+        2: serial.STOPBITS_TWO
+    }
+    
+    return (
+        bytesize_map.get(bytesize, serial.EIGHTBITS),
+        parity_map.get(parity, serial.PARITY_NONE),
+        stopbits_map.get(stopbits, serial.STOPBITS_ONE)
+    )
+
+def read_wsl_stdout(proc, ser, shutdown_event):
+    logging.debug("WSL-to-COM thread started.")
+    try:
+        while not shutdown_event.is_set():
+            data = proc.stdout.read(1024)
+            if not data:
+                logging.info("WSL process stdout reached EOF (exited).")
+                break
+            logging.debug(f"WSL -> COM: {len(data)} bytes")
+            ser.write(data)
+            ser.flush()
+    except Exception as e:
+        if not shutdown_event.is_set():
+            logging.error(f"Error in WSL-to-COM thread: {e}")
+    finally:
+        shutdown_event.set()
+
+def read_com_port(ser, proc, shutdown_event):
+    logging.debug("COM-to-WSL thread started.")
+    try:
+        while not shutdown_event.is_set():
+            # Short timeout allows periodic checking of shutdown_event
+            data = ser.read(1024)
+            if data:
+                logging.debug(f"COM -> WSL: {len(data)} bytes")
+                proc.stdin.write(data)
+                proc.stdin.flush()
+    except Exception as e:
+        if not shutdown_event.is_set():
+            logging.error(f"Error in COM-to-WSL thread: {e}")
+    finally:
+        shutdown_event.set()
+
+def read_wsl_stderr(proc, shutdown_event):
+    logging.debug("WSL stderr logging thread started.")
+    try:
+        while not shutdown_event.is_set():
+            line = proc.stderr.readline()
+            if not line:
+                break
+            line_str = line.decode("utf-8", errors="replace").strip()
+            if line_str:
+                logging.info(f"[WSL] {line_str}")
+    except Exception as e:
+        if not shutdown_event.is_set():
+            logging.debug(f"Error in WSL stderr thread: {e}")
+
+def run_bridge(port, baud, wsl_tty, bytesize, parity, stopbits, xonxoff, rtscts, dsrdtr):
+    # Resolve serial settings
+    ser_bytesize, ser_parity, ser_stopbits = get_serial_settings(bytesize, parity, stopbits)
+    
+    logging.info(f"Opening Windows serial port {port} at {baud} baud...")
+    ser = serial.Serial(
+        port=port,
+        baudrate=baud,
+        bytesize=ser_bytesize,
+        parity=ser_parity,
+        stopbits=ser_stopbits,
+        xonxoff=xonxoff,
+        rtscts=rtscts,
+        dsrdtr=dsrdtr,
+        timeout=0.2 # Enable timeout for shutdown check
+    )
+    
+    # Locate WSL bridge.py script
+    current_dir = os.path.dirname(os.path.abspath(__file__))
+    bridge_script = os.path.join(current_dir, "bridge.py")
+    if not os.path.exists(bridge_script):
+        raise FileNotFoundError(f"WSL bridge script not found at: {bridge_script}")
+    
+    wsl_bridge_path = get_wsl_path(bridge_script)
+    logging.info(f"WSL bridge script resolved to: {wsl_bridge_path}")
+    
+    cmd = ["wsl", "python3", "-u", wsl_bridge_path, "--symlink", wsl_tty]
+    logging.info(f"Spawning WSL process: {' '.join(cmd)}")
+    
+    # Use CREATE_NO_WINDOW to prevent wsl.exe from modifying the Windows console mode,
+    # which would otherwise disable Ctrl+C (ENABLE_PROCESSED_INPUT) for the Python CLI.
+    CREATE_NO_WINDOW = 0x08000000
+    proc = subprocess.Popen(
+        cmd,
+        stdin=subprocess.PIPE,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        bufsize=0,
+        creationflags=CREATE_NO_WINDOW
+    )
+    
+    shutdown_event = threading.Event()
+    
+    # Start thread routing
+    t_wsl_to_com = threading.Thread(target=read_wsl_stdout, args=(proc, ser, shutdown_event), daemon=True)
+    t_com_to_wsl = threading.Thread(target=read_com_port, args=(ser, proc, shutdown_event), daemon=True)
+    t_wsl_stderr = threading.Thread(target=read_wsl_stderr, args=(proc, shutdown_event), daemon=True)
+    
+    t_wsl_to_com.start()
+    t_com_to_wsl.start()
+    t_wsl_stderr.start()
+    
+    logging.info("Bridge is fully active. Press Ctrl+C to stop.")
+    
+    try:
+        while not shutdown_event.is_set():
+            # Wait and check if the WSL process is still running
+            if proc.poll() is not None:
+                logging.info("WSL subprocess exited unexpectedly.")
+                break
+            time.sleep(0.5)
+    except KeyboardInterrupt:
+        logging.info("Stopping bridge due to KeyboardInterrupt...")
+    finally:
+        shutdown_event.set()
+        
+        logging.info("Cleaning up resources...")
+        # Wait for threads to exit to avoid pyserial close() deadlock on Windows
+        t_com_to_wsl.join(timeout=0.5)
+        
+        # Close serial port first
+        try:
+            ser.close()
+            logging.info("Closed Windows serial port.")
+        except Exception as e:
+            logging.debug(f"Error closing serial port: {e}")
+            
+        # Terminate WSL subprocess
+        if proc.poll() is None:
+            logging.info("Terminating WSL process...")
+            proc.terminate()
+            try:
+                proc.wait(timeout=3.0)
+            except subprocess.TimeoutExpired:
+                logging.warning("WSL process did not exit. Killing it.")
+                proc.kill()
+        logging.info("Bridge stopped successfully.")

com2tty-0.1.0.dist-info/METADATA

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: com2tty
+Version: 0.1.0
+Summary: A Windows COM port to WSL ttyUSB forwarder
+Author-email: yichengs <yichengs.tw+com2tty@gmail.com>
+Project-URL: Homepage, https://github.com/Yi-Cheng-Wang/com2tty
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyserial>=3.5
+Dynamic: license-file
+
+# com2tty
+
+`com2tty` is a Python package designed to forward serial communications from a Windows COM port into a WSL (Windows Subsystem for Linux) instance, presenting it as a virtual `ttyUSB` (or similar) serial device in WSL. 
+
+It does this using a low-latency, firewall-resilient **process-pipe bridge** over standard input/output redirection. It requires **no network or firewall configuration**.
+
+## Architecture Overview
+
+1. The Windows host process opens the physical COM port (using `pyserial`).
+2. It spawns the WSL Python bridge helper in the background, redirecting its stdin/stdout.
+3. Inside WSL, the bridge helper opens a pseudo-terminal (PTY) and creates a symbolic link to the PTY's slave file.
+4. Data is piped bidirectionally between the physical Windows COM port and the WSL virtual device.
+
+```
+[Windows COM Port] <--> [com2tty host] <--> (stdin/stdout pipe) <--> [wsl bridge] <--> [PTY Slave /tmp/ttyUSB0]
+```
+
+## Requirements
+
+- **Windows Host**: Python 3.8+ and `pyserial` (installed automatically).
+- **WSL Guest**: Python 3.x (uses standard library modules only, no dependencies required).
+
+## Installation
+
+Install the package on the Windows host by running the following command in the project root:
+
+```cmd
+pip install .
+```
+
+For development, you can install it in editable mode:
+
+```cmd
+pip install -e .
+```
+
+## Usage
+
+Run `com2tty` from any Windows terminal (PowerShell or Command Prompt).
+
+```cmd
+com2tty <COM_PORT> [options]
+```
+
+### Examples
+
+Bridge **COM3** to the default WSL path `/tmp/ttyUSB0` at 115200 baud:
+```cmd
+com2tty COM3 --baud 115200
+```
+
+Bridge **COM5** to a custom WSL device path `/tmp/my_device`:
+```cmd
+com2tty COM5 --baud 9600 -w /tmp/my_device
+```
+
+### Options
+
+```
+positional arguments:
+  port                  Windows COM port to connect to (e.g. COM3).
+
+options:
+  -h, --help            show this help message and exit
+  -b BAUD, --baud BAUD  Baud rate for the serial port (default: 9600).
+  -w WSL_TTY, --wsl-tty WSL_TTY
+                        Target symlink path inside WSL (default: /tmp/ttyUSB0).
+  --bytesize {5,6,7,8}  Serial byte size (default: 8).
+  --parity {N,E,O,S,M}  Serial parity: None, Even, Odd, Space, Mark (default: N).
+  --stopbits {1,1.5,2}  Serial stop bits: 1, 1.5, or 2 (default: 1).
+  --xonxoff             Enable software flow control (XON/XOFF).
+  --rtscts              Enable hardware flow control (RTS/CTS).
+  --dsrdtr              Enable hardware flow control (DSR/DTR).
+  -d, --debug           Enable debug logging output.
+```
+
+---
+
+## Configuring `/dev/ttyUSB0` in WSL (Highly Recommended)
+
+In Linux, the `/dev` directory is owned by `root`. Running `com2tty` as a normal Windows user means the WSL subprocess cannot write directly to `/dev/ttyUSB0`.
+
+To work around this cleanly without requiring root permissions or passwordless `sudo` at runtime:
+
+1. Run `com2tty` with the default path (or any `/tmp/` path):
+   ```cmd
+   com2tty COM3 --wsl-tty /tmp/ttyUSB0
+   ```
+2. In your WSL terminal, run the following command **once** to create a permanent symlink pointing from `/dev/` to the stable `/tmp/` path:
+   ```bash
+   sudo ln -sf /tmp/ttyUSB0 /dev/ttyUSB0
+   ```
+3. Now, any WSL application (such as `minicom`, `screen`, `esp-idf`, or Python scripts) can read and write to `/dev/ttyUSB0`. 
+
+Whenever `com2tty` starts up, it updates `/tmp/ttyUSB0` to point to the active pseudo-terminal (`/dev/pts/N`), and `/dev/ttyUSB0` resolves to the correct endpoint automatically.
+
+---
+
+## Troubleshooting
+
+### WSL Bridge warns about Permission Denied
+If you specify `-w /dev/ttyUSB0` directly and see:
+`[WSL] Warning: Permission denied creating symlink at /dev/ttyUSB0.`
+This is expected behavior. The script will automatically fall back to `/tmp/ttyUSB0` and output instructions on how to link them.
+
+### Serial Port Busy / Access Denied
+Ensure that no other application on the Windows host (like PuTTY, Serial Monitor, or another instance of `com2tty`) is currently holding the COM port open.
+
+### Debugging
+Run `com2tty` with the `-d` or `--debug` flag to view detailed logs and data transfer statistics:
+```cmd
+com2tty COM3 --debug
+```
+
+## License
+
+MIT

com2tty-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+com2tty/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+com2tty/__main__.py,sha256=c3sfBf9CsB__uxUmojI786ZCfgagUGxqoJeIo2fP_Ag,87
+com2tty/bridge.py,sha256=nZaBv_ffVf2H0hw6ySUHiyHiF9q-SWlDAt5z4FobkYA,5067
+com2tty/cli.py,sha256=uYXOIg5Vu_Y3m8qHJxRDvnCag9lzyhxjakBmB9iLARE,2883
+com2tty/host.py,sha256=XTyThnAvfhSmob_uozvXsbe3c2ocJVYaSJy2BD3FhLE,6298
+com2tty-0.1.0.dist-info/licenses/LICENSE,sha256=ZaKMWSm_-7TSseqHEwfSFtvxHtG1x8FGXg6eYPPmKU0,1066
+com2tty-0.1.0.dist-info/METADATA,sha256=9L9TFJa0ra_tLhhxfjUiWDSqssW6E6wNlvwOtwDRQNs,4699
+com2tty-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+com2tty-0.1.0.dist-info/entry_points.txt,sha256=9NgquNy1sScY5NcZD2N2jmVYL0A7Nqy8OP_OkFUqzWQ,45
+com2tty-0.1.0.dist-info/top_level.txt,sha256=3fAwaVYRxXMqMp5XZwQFpMLGTHXuEJD4gfVJNb3Vcq8,8
+com2tty-0.1.0.dist-info/RECORD,,

com2tty-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

com2tty-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+com2tty = com2tty.cli:main

com2tty-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 王羿程
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

com2tty-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+com2tty