How Wi‑Fi QR Code Sharing Works with LocalSend in Omarchy: A Deep Dive into Network-to-Device Handoff

Omarchy generates a Wi‑Fi QR code from live network data via omarchy-network-qr, renders it through a shell panel plugin, and encodes credentials in a format that LocalSend‑compatible scanners can parse for automatic connection.

The omacom/omarchy repository implements Wi‑Fi QR code sharing as an integrated system service. This feature bridges Linux desktop network management with cross‑device file sharing by encoding active connection details into a machine‑readable format. This article examines the complete data flow—from network querying to QR rendering—and how LocalSend consumes this information.

Core Architecture: Three-Layer Pipeline

Wi‑Fi QR sharing in Omarchy operates through a generator → model → renderer pipeline. Each layer has a distinct responsibility and communicates via well‑defined data contracts.

Network Data Extraction in omarchy-network-qr

The entry point is bin/omarchy-network-qr, a shell script that interfaces with NetworkManager via nmcli. The script performs three operations:

• Identifies the active Wi‑Fi interface and associated connection profile
• Extracts SSID, security type (WPA2, WPA3, etc.), and password when stored
• Formats a QR payload string and pipes it to qrencode for matrix generation

The output is JSON‑structured matrix data: an array of binary rows representing black (1) and white (0) modules, plus a size field for dimension validation. This format decouples generation from rendering and enables multiple downstream consumers.

# Manual invocation for debugging or automation

omarchy-network-qr

# → {"rows":[[1,0,1,1,0,...],[0,1,0,0,1,...],...],"size":29}

The script handles edge cases such as missing passwords (open networks) and connection failures, emitting empty or error states that downstream components can detect.

Matrix Validation in Model.js

The JavaScript model at [shell/plugins/panels/wifiqr/Model.js](https://github.com/omacom/omarchy/blob/quattro/shell/plugins/panels/wifiqr/Model.js) consumes the raw matrix JSON. Its primary responsibilities are:

• Structural validation: Ensures the matrix is square (rows.length === size) and that all row lengths match the declared size
• Sanitization: Rejects malformed or ragged matrices before they reach the UI layer
• Property exposure: Provides a clean QML property interface (matrix, size, valid) for the panel component

This validation layer prevents crashes from corrupted qrencode output or permission‑denied scenarios where network data is inaccessible.

Visual Rendering in Panel.qml

The UI implementation at shell/plugins/panels/wifiqr/Panel.qml transforms validated matrix data into a visible QR code. Key implementation details:

// Simplified rendering logic from Panel.qml
Repeater {
    model: root.matrix.rows
    Row {
        Repeater {
            model: modelData
            Rectangle {
                width: cellSize
                height: cellSize
                color: modelData ? "#000000" : "#ffffff"
            }
        }
    }
}

The panel calculates cellSize dynamically based on available screen real estate, maintaining QR scannability across different display densities. It integrates with Omarchy's shell plugin system, enabling invocation via menu actions or keyboard shortcuts.

Menu Integration and User Activation

The Wi‑Fi QR panel is surfaced to users through default/omarchy/omarchy-menu.jsonc. This configuration adds a "QR Code" entry that triggers:

{
    "label": "QR Code",
    "action": "shell summon omarchy.wifiqr"
}

The summon command activates the panel plugin lifecycle: loading Model.js, executing omarchy-network-qr, and presenting the rendered result. This declarative menu system allows customization without code changes.

LocalSend Protocol Compatibility

The QR payload follows the LocalSend Wi‑Fi credential format, which encodes:

Field	Example	Purpose
T	WPA	Security type identifier
S	MyNetwork	SSID (network name)
P	hunter2	Password (omitted for open networks)
H	true	Hidden network flag (optional)

This format is recognized by the LocalSend mobile application and compatible scanners. When a device scans the Omarchy‑generated QR code, the app extracts these fields and initiates an automatic Wi‑Fi connection without manual entry.

Network Listener Context

While QR sharing itself requires no network communication, LocalSend's broader functionality depends on UDP port 53317. The security documentation notes this port for firewall configuration, enabling the discovery and transfer phases that follow initial connection establishment.

Nautilus Extension: File Manager Integration

Beyond Wi‑Fi sharing, Omarchy extends LocalSend into the file manager via [default/nautilus-python/extensions/localsend.py](https://github.com/omacom/omarchy/blob/quattro/default/nautilus-python/extensions/localsend.py). This Python extension adds a context menu action:

def _launch_localsend(self, paths):
    """
    Launch LocalSend with selected files for headless transfer.
    Prefers native binary; falls back to Flatpak installation.
    """
    localsend = shutil.which("localsend")
    if localsend:
        return [localsend, "--headless", "send", *paths]
    
    # Flatpak fallback with existence check

    if self._has_flatpak_app("org.localsend.localsend_app"):
        return [
            "flatpak", "run", "org.localsend.localsend_app",
            "--headless", "send", *paths
        ]
    return None

The --headless flag suppresses the GUI, streaming transfer progress through stdout/stderr for integration with desktop notifications. This implementation demonstrates Omarchy's progressive enhancement approach: native binary when available, sandboxed fallback when necessary.

Complete Usage Flow

A typical Wi‑Fi sharing session proceeds as follows:

1. User selects QR Code from the Omarchy menu
2. omarchy-network-qr queries NetworkManager and invokes qrencode
3. Model.js validates the returned matrix
4. Panel.qml renders the QR code at calculated cell size
5. Scanning device parses the LocalSend‑format payload and connects automatically

The entire sequence completes in under two seconds on typical hardware, with no persistent storage of sensitive credentials beyond NetworkManager's existing keyring.

Summary

• omarchy-network-qr extracts live Wi‑Fi data and generates a JSON matrix via qrencode
• Model.js validates matrix structure before UI exposure
• Panel.qml renders scannable QR codes with dynamic cell sizing
• Menu configuration in omarchy-menu.jsonc provides user activation
• QR format follows LocalSend protocol for cross‑platform compatibility
• localsend.py extends integration to Nautilus file manager operations

Frequently Asked Questions

What information does the Wi‑Fi QR code contain?

The QR code encodes SSID, security type, and password in LocalSend format—sufficient for automatic connection without manual entry. Open networks omit the password field.

Can I use this without LocalSend installed?

Yes. The QR code uses a standard Wi‑Fi credential format readable by any compatible scanner, including iOS Camera, Android Quick Settings, and dedicated QR apps.

Why does LocalSend need port 53317?

Port 53317 enables UDP‑based device discovery and file transfer after the Wi‑Fi connection is established. The QR code itself requires no network access.

How do I trigger the QR panel from the command line?

Run omarchy-shell shell summon omarchy.wifiqr or directly execute omarchy-network-qr to inspect the raw JSON output.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}