picolynx 0.1.0

Auto-attach microcontrollers to WSL.

PicoLynx - Attach Microcontrollers to WSL

PicoLynx is a Windows-only TUI (Text-based User Interface) application for attaching and detaching microcontroller devices to WSL (Windows Subsystem for Linux) distributions. It monitors Windows WM_DEVICECHANGE messages with pywin32 and leverages usbipd-win to manage device connections.

https://github.com/user-attachments/assets/d5382270-cae8-4eb4-90a6-28ccb96e5250

[!CAUTION] If a device is disconnected when attached, it will remain in the connected device table due to the way Windows only registers a DBT_DEVNODES_CHANGED event without any event-specific data and not a DBT_DEVICEREMOVECOMPLETE event. DBT_DEVNODES_CHANGED events usually occur before informative DBT_DEVICEARRIVAL or DBT_DEVICEREMOVECOMPLETE events, and reacting to these and updating, creates race conditions.

Features

• Manual control: Easily attach, bind, detach, or unbind devices using keyboard shortcuts.
• Live device table: View connected and persisted devices in real time.
• Windows message monitoring: Reacts instantly to hardware changes.
• Thread-safe: Ensures safe device operations even with concurrent events.
• Beautiful TUI: Built with Textual for a modern terminal experience & many theme options.
• Auto-attachment (TODO): Detects devices as they are connected & automatically attaches to WSL.

Requirements

Windows 10/11 is the only supported platform, given the nature of this package. PicoLynx requires administrator privileges to interact with USB/Serial devices. If not run as administrator, it will prompt for elevation.

Install usbipd-win

This tool enables sharing locally connected USB devices to other machines, including Hyper-V guests and WSL 2. Full instructions are available at usbipd-win Github. Window package manager can be used to install the tool:

winget install usbipd

Install WSL

Microsoft WSL documentation is available @ learn.microsoft.com. The following Windows features are required, which can be enabled by searching for 'Turn Windows features on or off' in the Start Menu:

• Virtual Machine Platform
• Windows Hypervisor Platform
• Windows Subsystem for Linux

Its worth updating WSL if newly enabled:

wsl --update

To install a Linux distribution, refer to the guide listed above.

PicoLynx Installation

Astral uv package manager is recommended for a fast, isolated, and reliable install. To install uv, use the following command:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

You can install PicoLynx globally with the following uv command:

uv tool install picolynx

Or:

uv tool install "git+https://github.com/andyrids/picolynx.git"

You can run PicoLynx without installing, by running the following command:

uvx picolynx

Or:

uvx "git+https://github.com/andyrids/picolynx.git"

Keyboard Shortcuts

Key	Action
a	Attach
b	Bind
d	Detach
u	Unbind

Select a device in the table and press the corresponding key to perform the action.

Development

The just command runner (GitHub page) is a handy way to save and run project-specific commands, which are written in a file called justfile.

If you use just, you can add use the commands below to run PicoLynx in development mode, with the textual console integration:

This command uses uv to sync the package dependencies and create a .venv:

just sync

Alias for:

uv sync

Running the command below in one terminal, will activate the textual console:

just console

Alias for:

uv run textual console -x EVENT -x SYSTEM

Running this command will run PicoLynx in development mode.

just dev

Alias for:

uv run textual run --dev src/picolynx/__main__.py

[!NOTE] Logging level can be modified in __main__.py by changing the LOG_LEVEL value.

Acknowledgements

• usbipd-win
• textual
• textual-cookbook
• transcendent-textual
• Astral uv
• just