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.

The TUI will react to USB Serial and USB Storage device connections and can run usbipd-win commands on any device in its interface.

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

[!NOTE] If a device is disconnected when attached to WSL or a USB mass storage device is safely removed, it will remain in the connected device table. WM_DEVICECHANGE events under these circumstances are not granular enough, but a manual detach ('d' press) or refresh ('r' press) will trigger an update.

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-detect: Detects devices as they are connected & disconnected.
• Auto-attach (TODO): Auto-attachment of persisted devices on connection.

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, or see my Void Linux & Alpine Linux WSL repo guides for an example of a manual distro installation.

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

The TUI command palette can be opened with ctrl + p, which has options for theme changes and the full command help panel. Tabs can be navigated and switched to with the tab key and tables can be traversed with the arrow keys.

Key	Action
a	Attach
b	Bind
d	Detach
u	Unbind
r	Refresh

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

Development

Clone the repository and enter the picolynx directory.

git clone git@github.com:andyrids/picolynx.git

cd picolynx

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, which listens to a running textual app in --dev mode:

just console

Alias for:

uv run textual console -x EVENT -x SYSTEM

Running this command will run PicoLynx in development mode, with a logging level set to 'DEBUG'.

just dev

Alias for:

uv run textual run --dev src/picolynx/__main__.py --log-level DEBUG

The logging level can be modified in with a --log-level option, which takes the following choices; 'DEBUG', 'INFO', 'WARNING' (default), 'ERROR' & 'CRITICAL'.

uv run textual run --dev src/picolynx/__main__.py --log-level INFO

Acknowledgements

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