com2tty 0.2.0__tar.gz → 0.3.1__tar.gz

{com2tty-0.2.0/src/com2tty.egg-info → com2tty-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: com2tty
-Version: 0.2.0
+Version: 0.3.1
 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
@@ -116,7 +116,21 @@ The following options apply to both modes.
 --version              Print the com2tty version and exit.
 -l, --list             List the serial ports Windows can see (device name,
                        VID:PID, USB bus id, serial number, detected board,
-                       description) and exit.
+                       description) and exit. Supplying a COM port together
+                       with --list is an argument error.
+--json                 With --list: print the port list as a JSON array
+                       instead of an aligned table, for scripts and IDE
+                       integrations.
+--doctor               Run an environment self-check (WSL, python3, drive
+                       automounting, fuser, TCP port availability, leftovers
+                       from crashed sessions, /dev/uinput, the XInput DLL)
+                       and exit. Exit status 1 when a required check fails.
+--auto-respawn         Rebuild the bridge automatically when the WSL helper
+                       dies, for example after `wsl --shutdown` or a WSL
+                       servicing update: com2tty waits until WSL answers
+                       again and re-creates the same endpoint. In serial
+                       mode this implies --wait. Applies to serial and
+                       gamepad mode alike.
 -d, --debug            Enable verbose debug logging on standard error.
 --distro NAME          WSL distribution to use (default: the WSL default
                        distribution). Useful when the default distribution
@@ -138,6 +152,10 @@ port [port ...]        Windows COM port(s) to bridge, for example COM3, or
 --rfc2217-port PORT    TCP port for the in-WSL RFC 2217 forwarder
                        (default: 4000). The UF2 relay uses PORT + 1; with
                        multiple ports, each additional port uses PORT + 2i.
+--wait                 If the COM port is not present yet, wait for it to
+                       appear instead of failing, then bridge it. Useful
+                       when com2tty is started before the device is
+                       plugged in.
 --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).
@@ -155,7 +173,12 @@ port [port ...]        Windows COM port(s) to bridge, for example COM3, or
 
 ```text
 --gamepad              Select gamepad mode. No COM port is required.
---pad-index {0,1,2,3}  XInput controller slot to forward (default: 0).
+--pad-index {0,1,2,3} [...]
+                       XInput controller slot(s) to forward (default: 0).
+                       Several slots may be given (--pad-index 0 1) to
+                       forward multiple controllers at once; each gets its
+                       own WSL helper and endpoint (/tmp/com2pad0,
+                       /tmp/com2pad1, ...).
 --pad-name NAME        Device name advertised inside WSL
                        (default: "Microsoft X-Box 360 pad").
 --uinput               Create a real /dev/input device through /dev/uinput
@@ -218,7 +241,15 @@ stale Windows handle and waits for the device to come back, first under its
 original COM name and then by scanning for its USB serial number, because
 Windows may assign a different COM number after a replug. Once the device
 reappears the bridge resumes automatically; the WSL endpoint stays in place
-the whole time.
+the whole time. The waiting loops are event-driven: com2tty registers for
+Windows device-change notifications (`WM_DEVICECHANGE`), so a replugged
+device resumes the moment Windows enumerates it rather than on the next
+polling tick (plain polling remains as the fallback).
+
+The complementary case — WSL itself going away, for example through
+`wsl --shutdown` or a WSL update — is covered by `--auto-respawn`: instead
+of exiting when the WSL helper dies, com2tty waits until WSL answers again
+and rebuilds the bridge with the same endpoint paths.
 
 ### Bridging multiple ports
 
@@ -266,12 +297,18 @@ com2tty @myboard --baud 9600
 com2tty @pad
 ```
 
+A literal argument that must begin with `@` is written with a doubled marker:
+`@@value` is passed through as the literal `@value` and is never interpreted as
+a profile reference.
+
 ### 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`.
+rate that Windows has configured for the port and uses it. The rate is read
+directly from the Win32 `GetCommState` API, which works regardless of the
+Windows display language; parsing the `mode.com` output is kept only as a
+fallback. 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
@@ -316,9 +353,11 @@ when zsh is in use or that file exists, and to
 `~/.config/fish/conf.d/com2tty.fish` when fish is in use or its configuration
 directory exists. Open a new WSL shell or run `source ~/.bashrc` (or
 `source ~/.zshrc`; fish picks the snippet up automatically) after starting
-com2tty for them to take effect. The variables are removed when com2tty exits;
-if a session is killed before it can clean up, the next run removes the stale
-block on startup.
+com2tty for them to take effect. The variables are removed when com2tty exits,
+including when the console window is closed: the WSL helper is reaped together
+with the host process rather than left running, and it is given the chance to
+run its own cleanup before it is forced down. If a session is nonetheless killed
+before it can clean up, the next run removes the stale block on startup.
 
 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
@@ -341,10 +380,13 @@ 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; if a session is killed before it can restore it, the next run
-detects and reverses the leftover interception on startup, so PlatformIO uploads
-are not left broken.
+checksum, and writes the image to the drive. Subcommands that carry no firmware
+image, such as `picotool info`, `picotool reboot`, and `picotool help`, are
+forwarded to the real binary unchanged, so non-flashing uses of `picotool`
+continue to work while the interception is active. The original `picotool` is
+restored when com2tty exits; if a session is killed before it can restore it, the
+next run detects and reverses the leftover interception on startup, so PlatformIO
+uploads are not left broken.
 
 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
@@ -359,7 +401,15 @@ these ports during an upload. Run com2tty only on hosts you trust, and choose a
 non-default `--rfc2217-port` if another local service needs the default port. To
 reclaim a port left open by a previous com2tty session, the helper only
 terminates processes whose command line identifies them as a com2tty bridge; an
-unrelated service occupying the port is never killed.
+unrelated service occupying the port is never killed. A *running* com2tty
+session is never disturbed: before it touches any shared state, a new session
+checks whether its RFC 2217 and UF2 relay ports are already bound and, if so,
+refuses to start rather than overwrite the first session's shell configuration
+or steal its serial endpoint. As a further guard, the WSL helper refuses to
+replace a tty symlink that already points at another live session's pseudo
+terminal. Two sessions can run concurrently by giving the second one a different
+`--rfc2217-port` and `--wsl-tty`; each session removes only its own block from
+the shell startup files when it exits.
 
 ### Gamepad mode
 
@@ -385,7 +435,10 @@ 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.
+`/tmp/com2pad0`, and requires no privileged setup. This FIFO and its
+force-feedback companion (described below) are created with owner-only
+permissions, so another local user on the WSL instance cannot read the input
+stream or inject events into it.
 
 ```cmd
 com2tty --gamepad
@@ -396,6 +449,24 @@ 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.
 
+Force feedback is available in this tier through a second FIFO created at
+`<path>.ff` (by default `/tmp/com2pad0.ff`): the consumer writes 6-byte rumble
+frames into it — the bytes `0xFB 0xFE` followed by the strong (left,
+low-frequency) and weak (right, high-frequency) motor magnitudes as two
+little-endian unsigned 16-bit values — and com2tty forwards them to the
+physical controller's motors, exactly as the uinput tier does for kernel
+`FF_RUMBLE` effects.
+
+To forward several controllers at once, pass several slots:
+
+```cmd
+com2tty --gamepad --pad-index 0 1
+```
+
+Each slot gets its own WSL helper and its own endpoint (`/tmp/com2pad0`,
+`/tmp/com2pad1`, ...); in the uinput tier each helper creates its own
+`/dev/input` device, as if several physical controllers were attached.
+
 #### 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
@@ -472,8 +543,9 @@ feedback. When a game or emulator inside WSL plays a rumble effect, the
 effect's magnitudes travel back through the bridge to the Windows host, which
 drives the physical controller's motors through `XInputSetState`. The strong
 (left, low-frequency) and weak (right, high-frequency) motors map directly to
-their XInput counterparts. The `/tmp` stream tier has no reverse channel and
-therefore no force feedback.
+their XInput counterparts. In the `/tmp` stream tier the same reverse channel
+is reached by writing rumble frames into the `<path>.ff` FIFO, as described
+in [the default tier](#default-tier-the-tmp-event-stream).
 
 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
@@ -487,48 +559,68 @@ available. These differences are inherent to the approach.
 
 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.
+The code under `src/com2tty/` is split by where it runs: `cli/` is the
+command-line layer, `core/` holds the dependency-free definitions both sides
+share, `windows/` runs on the Windows interpreter, and `wsl/` runs on the
+Linux interpreter inside WSL.
 
-`cli.py` parses the command line (after `profiles.py` expands any `@profile`
-tokens) and dispatches to an entry function in `host.py`: `run_bridge` in
+`cli/` parses the command line (after `cli/profiles.py` expands any `@profile`
+tokens) and dispatches to an entry function in `windows/`: `run_bridge` in
 serial mode, `run_multi_bridge` when several ports are given, and
-`run_gamepad_bridge` in gamepad mode. `discovery.py` implements `--list`.
-`__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 hot-plug reconnect logic and the routine
-that writes a transferred UF2 image to the correct Windows drive. The board
-detection and reset sequences live in `boards.py`, the UF2 drive lookup and
-AutoPlay suppression in `uf2.py`, and the console colour handling in
-`banner.py`; `host.py` re-exports these names for backwards compatibility.
-
-`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` (preferring
-the `XInputGetStateEx` export so the Guide button is visible) 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. In the uinput sink the helper also
-services the kernel's force-feedback upload handshake and streams played
-rumble effects back over its stdout, where the host applies them to the
-physical controller with `XInputSetState`.
+`run_gamepad_bridge` in gamepad mode. `windows/discovery.py` implements
+`--list` and `windows/doctor.py` implements `--doctor`. `__main__.py` and the
+console entry point both call `cli.main`, and `__init__.py` holds the package
+version.
+
+`core/` defines the contracts both interpreters rely on: `core/protocol.py`
+holds the `[CONTROL]` message catalogue and the dispatcher the host routes
+stderr lines through, `core/frames.py` the binary gamepad frame codecs,
+`core/boards.py` the USB VID classification with the reset timing data, and
+`core/constants.py` the shared paths, ports, and marker strings.
+
+`windows/` is the Windows side. In serial mode `run_bridge` in
+`windows/bridge_app.py` opens the COM port with `pyserial`, spawns the WSL
+helper with `wsl python3 -u bridge.py` (through `windows/wsl_process.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]`; the handlers in `windows/control_handler.py` drive dynamic
+serial-setting changes, the RFC 2217 session lifecycle, and the UF2 upload
+sequence (including the routine that writes a transferred UF2 image to the
+correct Windows drive, via `windows/uf2_flash.py`). The hot-plug reconnect
+logic lives in `windows/serial_host.py` and the board reset sequences in
+`windows/board_reset.py`. The raw OS-level interventions -- AutoPlay
+suppression, Explorer window closing, `WM_DEVICECHANGE` wake-ups, and console
+VT mode -- are isolated under `windows/os_hacks/`.
+
+`wsl/` is the WSL side, restricted to the Python standard library.
+`wsl/serial_app.py` (launched through the `bridge.py` shim at the package
+root) creates a pseudo terminal with `openpty` via `wsl/pty_manager.py`,
+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 and UF2 relay
+threads (`wsl/servers/`), writes the PlatformIO environment variables into
+`~/.bashrc` (`wsl/integrations/shell_env.py`), and installs the `picotool`
+interceptor (`wsl/integrations/picotool.py`).
+`windows/rfc2217_redirector.py` provides the redirector that implements the
+RFC 2217 protocol for the forwarder.
+
+The gamepad path reuses the same spawn-and-pipe transport.
+`windows/gamepad_host.py` is the Windows side: it polls an XInput controller
+slot through `ctypes` (preferring the `XInputGetStateEx` export so the Guide
+button is visible) and packs each state snapshot into a fixed 16-byte frame,
+sending a frame only when the state changes. `wsl/gamepad_app.py` (launched
+through the `pad_bridge.py` shim) is the WSL side: it parses the frames,
+translates them into evdev events, and writes them to one of the two sinks in
+`wsl/evdev_sink.py`. 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. In the uinput sink the helper also services the kernel's
+force-feedback upload handshake and streams played rumble effects back over
+its stdout, where the host applies them to the physical controller with
+`XInputSetState`.
 
 For a detailed account of the control protocol, the board reset sequences, the
 reconnection model, the binary frame formats, and the known hardware-unverified
@@ -588,6 +680,11 @@ step, is documented in [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## Troubleshooting
 
+Run `com2tty --doctor` first: it probes the whole environment (WSL, the
+selected distribution's `python3`, drive automounting, `fuser`, the RFC 2217
+and UF2 relay TCP ports, leftovers from crashed sessions, `/dev/uinput`
+access, and the XInput DLL) and prints one actionable line per check.
+
 At startup com2tty verifies the WSL environment and reports a specific error if
 a prerequisite is missing. The checks and their remedies are:
 
@@ -609,6 +706,11 @@ package; on minimal distributions install it with `sudo apt install psmisc`, or
 select a different port with `--rfc2217-port` (the UF2 relay always uses that
 port plus one).
 
+If com2tty instead refuses to start with a message that a port is already in
+use, a second com2tty session is already bound to that port. Give the new session
+a different `--rfc2217-port`, and a different `--wsl-tty`, to run the two
+concurrently.
+
 The serial-mode environment variables are written to `~/.bashrc`, to `~/.zshrc`
 when zsh is detected or a `~/.zshrc` file exists, and to
 `~/.config/fish/conf.d/com2tty.fish` when fish is detected. Users of other