com2tty 0.1.2__tar.gz → 0.1.3__tar.gz

com2tty-0.1.3/PKG-INFO

@@ -0,0 +1,452 @@
+Metadata-Version: 2.4
+Name: com2tty
+Version: 0.1.3
+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 that runs on a Windows host and forwards a device
+attached to Windows into a Windows Subsystem for Linux (WSL) instance, where it
+appears as a native Linux device. It supports two kinds of forwarding. The first
+forwards a Windows COM port into WSL as a virtual serial device such as
+`/tmp/ttyUSB0`. The second forwards a Windows XInput game controller into WSL as
+a Linux evdev gamepad. Both kinds use the same transport: a low-latency,
+firewall-resilient bridge built on standard input and output redirection between
+the Windows host process and a helper process running inside WSL. No network
+configuration, port forwarding, or firewall change is required.
+
+The intended users are developers who work inside WSL but whose hardware is bound
+to the Windows host: embedded developers who flash and monitor microcontrollers
+over USB-to-serial adapters, and developers who need a game controller available
+to Linux tools running in WSL.
+
+## Table of contents
+
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Usage](#usage)
+  - [Bridging a serial port](#bridging-a-serial-port)
+  - [Automatic baud-rate detection](#automatic-baud-rate-detection)
+  - [Configuring /dev/ttyUSB0 in WSL](#configuring-devttyusb0-in-wsl)
+  - [Firmware upload through the bridge](#firmware-upload-through-the-bridge)
+  - [Gamepad mode](#gamepad-mode)
+- [Architecture overview](#architecture-overview)
+- [Development setup](#development-setup)
+- [Contributing](#contributing)
+- [Troubleshooting](#troubleshooting)
+- [License](#license)
+
+## Requirements
+
+The Windows host requires Python 3.8 or later. The `pyserial` package, version
+3.5 or later, is the only runtime dependency and is installed automatically with
+the package. A working WSL installation is required, and the WSL distribution
+must provide `python3` on its `PATH`. The WSL helper uses only the Python
+standard library and therefore needs no additional packages inside WSL.
+
+Serial forwarding requires a COM port that Windows can open. Gamepad forwarding
+requires a controller that the Windows XInput driver recognises, which is the
+standard case for Xbox and XInput-compatible controllers. The opt-in gamepad tier
+that creates a real Linux input device additionally requires a one-time
+privileged setup inside WSL, described in [Gamepad mode](#gamepad-mode).
+
+## Installation
+
+Install the released package from PyPI on the Windows host.
+
+```cmd
+pip install com2tty
+```
+
+Alternatively, install from a checkout of the source by running the following
+in the project root.
+
+```cmd
+pip install .
+```
+
+To work on the package itself, install it in editable mode.
+
+```cmd
+pip install -e .
+```
+
+Installation registers a console entry point named `com2tty`. If the entry point
+is not on your `PATH`, the package can also be invoked as a module with
+`python -m com2tty`.
+
+## Configuration
+
+`com2tty` is configured entirely through command-line arguments. There are no
+configuration files and no environment variables that the tool itself reads.
+Note that in serial mode the WSL helper writes environment variables into the
+WSL user's `~/.bashrc`; this behaviour is described in
+[Firmware upload through the bridge](#firmware-upload-through-the-bridge).
+
+The first positional argument is the COM port. It is required in serial mode and
+is omitted in gamepad mode, which is selected with `--gamepad`.
+
+### Options common to both modes
+
+The following option applies to both modes.
+
+```text
+-d, --debug            Enable verbose debug logging on standard error.
+```
+
+### Serial-mode options
+
+```text
+port                   Windows COM port to bridge, for example COM3. Required
+                       unless --gamepad is given.
+-b, --baud BAUD        Baud rate, or the literal value "auto" to detect the
+                       rate Windows has configured for the port
+                       (default: auto; falls back to 9600 if detection fails).
+-w, --wsl-tty PATH     Target symlink path created inside WSL
+                       (default: /tmp/ttyUSB0).
+--rfc2217-port PORT    TCP port for the in-WSL RFC 2217 forwarder
+                       (default: 4000). The UF2 relay uses PORT + 1.
+--bytesize {5,6,7,8}   Serial byte size (default: 8).
+--parity {N,E,O,S,M}   Parity: none, even, odd, space, or mark (default: N).
+--stopbits {1,1.5,2}   Stop bits (default: 1).
+--xonxoff              Enable software flow control (XON/XOFF).
+--rtscts               Enable hardware flow control (RTS/CTS).
+--dsrdtr               Enable hardware flow control (DSR/DTR).
+```
+
+### Gamepad-mode options
+
+```text
+--gamepad              Select gamepad mode. No COM port is required.
+--pad-index {0,1,2,3}  XInput controller slot to forward (default: 0).
+--pad-name NAME        Device name advertised inside WSL
+                       (default: "Microsoft X-Box 360 pad").
+--uinput               Create a real /dev/input device through /dev/uinput
+                       instead of the default /tmp event stream.
+--wsl-pad PATH         FIFO path for the default /tmp event stream
+                       (default: /tmp/com2pad0).
+--poll-hz HZ           XInput polling rate in hertz (default: 250). Frames are
+                       sent only when the controller state changes.
+```
+
+## Usage
+
+Run `com2tty` from any Windows terminal, either PowerShell or Command Prompt. The
+process runs in the foreground and is stopped with Ctrl+C.
+
+### Bridging a serial port
+
+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 at 9600 baud.
+
+```cmd
+com2tty COM5 --baud 9600 -w /tmp/my_device
+```
+
+While the bridge is active, a Linux program inside WSL opens the symlinked path
+and reads from and writes to it as if it were a local serial device. Data is
+relayed in both directions between the Windows COM port and the WSL pseudo
+terminal. Dynamic changes that a WSL program makes to the line settings, such as
+the baud rate, are detected and applied to the underlying Windows COM port.
+
+### Automatic baud-rate detection
+
+When the baud rate is left at its default value of `auto`, com2tty queries the
+rate that Windows has configured for the port and uses it. If detection fails,
+the bridge falls back to 9600 baud. To set the rate explicitly, pass a numeric
+value to `--baud`.
+
+```cmd
+com2tty COM3 --baud auto
+```
+
+### Configuring /dev/ttyUSB0 in WSL
+
+In Linux the `/dev` directory is owned by `root`. Running com2tty as an ordinary
+Windows user means the WSL helper cannot create a symlink directly under `/dev`.
+For this reason the default target is `/tmp/ttyUSB0`, which is user-writable, and
+com2tty never requires elevated privileges at run time. If a path under `/dev` is
+requested and permission is denied, the helper automatically falls back to the
+equivalent path under `/tmp` and prints instructions.
+
+To expose the device at a stable `/dev` path without granting com2tty privileges,
+create a one-time symlink inside WSL that points from `/dev` to the stable `/tmp`
+path.
+
+```bash
+sudo ln -sf /tmp/ttyUSB0 /dev/ttyUSB0
+```
+
+Each time com2tty starts, it repoints `/tmp/ttyUSB0` at the active pseudo
+terminal, so `/dev/ttyUSB0` continues to resolve correctly. After this one-time
+step, WSL programs such as `minicom`, `screen`, the ESP-IDF tools, or Python
+scripts can use `/dev/ttyUSB0` directly.
+
+### Firmware upload through the bridge
+
+In serial mode com2tty additionally supports flashing microcontroller firmware
+from build tools running inside WSL, so that a PlatformIO project in WSL can
+upload to a board attached to Windows. This support is enabled by default and
+involves three mechanisms.
+
+First, the WSL helper starts an RFC 2217 forwarder that listens on
+`127.0.0.1:<rfc2217-port>` inside WSL, where the port defaults to 4000. To make
+PlatformIO use it, the helper appends environment variables to the WSL user's
+`~/.bashrc`: `PLATFORMIO_UPLOAD_PORT` is set to
+`rfc2217://127.0.0.1:<rfc2217-port>` and `PLATFORMIO_MONITOR_PORT` is set to the
+serial symlink path. Because these variables are written to `~/.bashrc`, open a
+new WSL shell or run `source ~/.bashrc` after starting com2tty for them to take
+effect. The variables are removed when com2tty exits.
+
+Second, com2tty detects the connected board type from its USB vendor identifier
+and performs the appropriate hardware reset on the Windows side. For ESP32-class
+boards it performs the DTR and RTS auto-reset sequence to enter the download
+mode. For RP2040 and RP2350 boards it performs the 1200-baud touch that triggers
+the BOOTSEL mass-storage mode.
+
+Third, for RP2040 and RP2350 boards, com2tty intercepts the `picotool` invocation
+inside WSL. When PlatformIO calls `picotool` to flash a `.uf2` image, a wrapper
+transfers the image back to the Windows host over a relay that listens on
+`127.0.0.1:<rfc2217-port + 1>`. The host then triggers BOOTSEL mode, locates the
+board's mass-storage drive, verifies the transferred image against an MD5
+checksum, and writes the image to the drive. The original `picotool` is restored
+when com2tty exits.
+
+These mechanisms operate without any additional flags. The startup banner reports
+the detected board type, the RFC 2217 port, the UF2 relay port, and the board's
+USB serial number.
+
+### Gamepad mode
+
+Gamepad mode forwards a Windows XInput controller into WSL. It exists because
+forwarding a controller with `usbipd` does not work in a default WSL2 setup: the
+stock WSL2 kernel is built without the `xpad` driver, so an attached controller
+is enumerated but never produces a usable input device. Gamepad mode keeps the
+controller on Windows, where the native XInput driver handles it, reads its state
+on the Windows side, and streams that state through the same bridge used for
+serial forwarding. Inside WSL a helper, which uses only the Python standard
+library, turns the state into a Linux evdev `input_event` stream describing a
+Microsoft X-Box 360 pad, identified by USB vendor 0x045e and product 0x028e.
+
+The controller must be visible to Windows XInput. If the controller has been
+bound or attached with `usbipd`, Windows no longer owns it and XInput reports no
+controller; unbind it from `usbipd` so that Windows holds the controller before
+using gamepad mode.
+
+Gamepad mode provides two tiers. Both emit the identical evdev byte stream, so a
+single reader works against either, and com2tty itself never requires elevated
+privileges at run time.
+
+#### Default tier: the /tmp event stream
+
+The default tier writes the evdev event stream to a FIFO under `/tmp`, by default
+`/tmp/com2pad0`, and requires no privileged setup.
+
+```cmd
+com2tty --gamepad
+```
+
+A consumer inside WSL reads 24-byte Linux `input_event` records from the FIFO and
+interprets them using the device profile below. This tier is suited to programs
+that read the stream directly. Standard applications and game engines that
+enumerate `/dev/input` devices do not read a FIFO and require the uinput tier.
+
+#### Opt-in tier: a real device through /dev/uinput
+
+The opt-in tier creates a real system-wide device under `/dev/input` so that SDL2
+applications, emulators, and tools such as `evtest` recognise a normally attached
+controller.
+
+```cmd
+com2tty --gamepad --uinput
+```
+
+If `/dev/uinput` is not accessible, com2tty prints the one-time setup instructions
+and automatically falls back to the `/tmp` event stream so that forwarding
+continues to work.
+
+#### One-time setup for the uinput tier
+
+Creating a real input device requires access to `/dev/uinput`, which Linux
+restricts to `root`, and reading the resulting `/dev/input/event*` node requires
+membership of the `input` group. Both are granted once, inside WSL, and com2tty
+still runs without privileges thereafter. Either use `sudo`, or run the commands
+as root from Windows with `wsl -u root`, which requires no password.
+
+```bash
+sudo modprobe uinput
+sudo chmod 0666 /dev/uinput
+sudo usermod -aG input "$USER"
+```
+
+The permission granted by `chmod` does not survive `wsl --shutdown`. To make it
+persist, add a boot command to `/etc/wsl.conf`, which runs as root on every WSL
+start.
+
+```ini
+[boot]
+command = modprobe uinput && chmod 0666 /dev/uinput
+```
+
+After editing `/etc/wsl.conf`, run `wsl --shutdown` once from Windows. This also
+refreshes the group membership granted by `usermod`.
+
+The stock WSL2 kernel sets `CONFIG_INPUT_UINPUT` as a module, which works, but
+does not set `CONFIG_INPUT_JOYDEV`. As a result the legacy `/dev/input/js*` node
+is absent. This is not a problem for modern applications and SDL2, which read
+`/dev/input/event*` directly.
+
+#### Verifying the uinput tier
+
+With com2tty running in `--uinput` mode, confirm the device inside WSL with
+`evtest`.
+
+```bash
+sudo apt install evtest
+evtest
+```
+
+Select the Microsoft X-Box 360 pad device, then move the sticks and press buttons
+on Windows and observe the events appear in WSL.
+
+#### Device profile
+
+Both tiers emit the same evdev codes. Buttons are reported as `BTN_A`, `BTN_B`,
+`BTN_X`, `BTN_Y`, `BTN_TL`, `BTN_TR`, `BTN_SELECT`, `BTN_START`, `BTN_THUMBL`,
+and `BTN_THUMBR`. The sticks are reported as `ABS_X` and `ABS_Y` for the left
+stick and `ABS_RX` and `ABS_RY` for the right stick, each spanning the signed
+16-bit range. The triggers are reported as `ABS_Z` for the left trigger and
+`ABS_RZ` for the right trigger, each spanning 0 to 255. The directional pad is
+reported as `ABS_HAT0X` and `ABS_HAT0Y` with values of -1, 0, or 1. The stick Y
+axes are inverted to follow the Linux convention in which pushing up produces a
+negative value.
+
+The forwarded signal matches a real controller at the level of these event codes,
+ranges, and resolutions, but it is not bit-for-bit identical to a controller
+driven by the kernel `xpad` driver. The timing and latency differ because the
+path is polled and piped rather than delivered by a fixed USB interrupt interval.
+The Guide button is not reported, because the standard XInput state query does not
+expose it. Force feedback is not implemented. These differences are inherent to
+the approach.
+
+## Architecture overview
+
+The package is organised around a host process on Windows and a helper process
+inside WSL connected by the standard input and output streams of the helper.
+
+`cli.py` parses the command line and dispatches to one of two entry functions in
+`host.py`. In serial mode it calls `run_bridge`; in gamepad mode it calls
+`run_gamepad_bridge`. `__main__.py` and the console entry point both call
+`cli.main`, and `__init__.py` holds the package version.
+
+`host.py` is the Windows side. In serial mode `run_bridge` opens the COM port with
+`pyserial`, spawns the WSL helper with `wsl python3 -u bridge.py`, and runs three
+threads: one relays bytes from the COM port to the helper's standard input, one
+relays bytes from the helper's standard output to the COM port, and one reads the
+helper's standard error. The standard error stream carries a line-oriented control
+protocol whose messages are prefixed with `[CONTROL]`; these messages drive
+dynamic serial-setting changes, the RFC 2217 session lifecycle, and the UF2 upload
+sequence. `host.py` also contains the board detection and reset logic and the
+routine that writes a transferred UF2 image to the correct Windows drive.
+
+`bridge.py` is the WSL side for serial forwarding. It creates a pseudo terminal
+with `openpty`, symlinks the requested path to the pseudo-terminal slave, falling
+back to `/tmp` if the requested path is not writable, and runs a `select` loop
+that relays data between the helper's standard input and output and the
+pseudo-terminal master. It also starts the RFC 2217 forwarder thread and the UF2
+relay thread, writes the PlatformIO environment variables into `~/.bashrc`, and
+installs the `picotool` interceptor. `rfc2217_server.py` provides the redirector
+that implements the RFC 2217 protocol for the forwarder.
+
+The gamepad path reuses the same spawn-and-pipe transport. `xinput.py` is the
+Windows side: it polls an XInput controller slot through `ctypes` and packs each
+state snapshot into a fixed 16-byte frame, sending a frame only when the state
+changes. `pad_bridge.py` is the WSL side: it parses the frames, translates them
+into evdev events, and writes them to one of two sinks. The default sink writes to
+a `/tmp` FIFO, and the opt-in sink creates a real device through `/dev/uinput`
+using raw `ioctl` calls. Both sinks share the same event-encoding code, so the
+byte stream they produce is identical.
+
+## Development setup
+
+Install the package in editable mode together with the test tools.
+
+```bash
+pip install -e .
+pip install pytest pytest-cov
+```
+
+Run the test suite with coverage.
+
+```bash
+pytest --cov=src/com2tty --cov-report=term-missing tests/
+```
+
+A passing run reports all tests passing and full line coverage for the package.
+The test suite is cross-platform. The `tests/conftest.py` file substitutes a mock
+`termios` module on Windows so that the WSL-side modules import for testing, and
+the platform-specific system calls used by the gamepad sinks are mocked so that
+the suite runs on both Windows and Linux.
+
+Continuous integration is defined in `.github/workflows/ci.yml`. It runs the test
+suite on `windows-latest` and `ubuntu-latest` against Python 3.8, 3.9, 3.10,
+3.11, and 3.12, and it enforces 100 percent line coverage by running pytest with
+`--cov-fail-under=100`. A separate job publishes the package to PyPI on pushes to
+the `main` branch.
+
+## Contributing
+
+Base feature branches on the `develop` branch. Commit messages follow the
+Conventional Commits format, for example `feat(gamepad): ...` or
+`test(host): ...`, as established in the project history. Every change must keep
+the test suite passing with 100 percent line coverage on both Windows and Ubuntu
+across the supported Python versions, because continuous integration enforces
+this. Add or update tests for any behavioural change. Open pull requests against
+`develop`.
+
+## Troubleshooting
+
+If the WSL helper reports a permission error while creating the serial symlink,
+the requested path under `/dev` is not writable; the helper falls back to `/tmp`
+and prints the one-time command to link the `/dev` path to it.
+
+If the serial port reports that it is busy or access is denied, ensure no other
+Windows application, such as a serial monitor or a second com2tty instance, is
+holding the COM port open.
+
+If gamepad mode reports all values as zero, Windows XInput is not receiving the
+controller. Confirm the controller is not bound or attached through `usbipd`, so
+that Windows owns it, and confirm it is on the expected XInput slot, which can be
+changed with `--pad-index`.
+
+If the `--uinput` tier cannot open `/dev/uinput`, complete the one-time setup
+described in [Gamepad mode](#gamepad-mode). Until then, com2tty falls back to the
+`/tmp` event stream.
+
+For detailed logs and transfer statistics, run com2tty with `-d` or `--debug`.
+
+```cmd
+com2tty COM3 --debug
+```
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file
+for the full text.