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

> Discover how Omarchy enables seamless Wi-Fi QR code sharing with LocalSend. Learn how this innovative network-to-device handoff simplifies secure connections.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: deep-dive
- Published: 2026-09-06

---

**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](https://github.com/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`](https://github.com/omacom/omarchy/blob/quattro/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.

```bash

# 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`](https://github.com/omacom/omarchy/blob/main/Model.js)

The JavaScript model at [[`shell/plugins/panels/wifiqr/Model.js`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/quattro/shell/plugins/panels/wifiqr/Panel.qml) transforms validated matrix data into a visible QR code. Key implementation details:

```qml
// 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`](https://github.com/omacom/omarchy/blob/quattro/default/omarchy/omarchy-menu.jsonc). This configuration adds a **"QR Code"** entry that triggers:

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

```

The `summon` command activates the panel plugin lifecycle: loading [`Model.js`](https://github.com/omacom/omarchy/blob/main/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](https://github.com/omacom/omarchy/blob/quattro/manual/48-security.md) 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/main/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:

```python
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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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.