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.
picolynx_demo.mp4
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.
- 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
Textualfor 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.
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.
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 usbipdMicrosoft 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 --updateTo 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.
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 picolynxOr:
uv tool install "git+https://github.com/andyrids/picolynx.git"You can run PicoLynx without installing, by running the following command:
uvx picolynxOr:
uvx "git+https://github.com/andyrids/picolynx.git"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.
Clone the repository and enter the picolynx directory.
git clone [email protected]:andyrids/picolynx.gitcd picolynxThe 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 syncAlias for:
uv syncRunning the command below in one terminal, will activate the textual console, which listens to a running textual app in --dev mode:
just consoleAlias for:
uv run textual console -x EVENT -x SYSTEMRunning this command will run PicoLynx in development mode, with a logging level set to 'DEBUG'.
just devAlias for:
uv run textual run --dev src/picolynx/__main__.py --log-level DEBUGThe 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