Connectivity

Pearl manages networks through NetworkManager and Bluetooth devices through BlueZ. Both live in the control center flyout and as full Network and Bluetooth pages in Settings. The bar’s network widget and the optional Bluetooth widget (which shows the connected-device count) each open the matching compact page directly. Opening a page never starts a scan or a discovery on its own.

Both need a running system service and a supported adapter. NetworkManager and BlueZ are optional dependencies of Pearl’s Arch package.

Wi-Fi

The Network view shows the Wi-Fi switch, the current connection, nearby networks and an explicit Refresh button without expanding any adapter list; a selector appears when several wireless adapters are present. Internet status is separate from Wi-Fi power, so an active wired connection stays visible while Wi-Fi is off. Connection and scan controls are disabled while the radio is off or hardware-blocked, and the Wi-Fi gate never disables wired adapters.

The flyout shows up to three nearby networks and links to the full Settings list. Settings additionally shows Ethernet and your saved profiles. Nearby entries are grouped per network, and saved networks are recognized by their SSID and security even when they do not appear in the current scan.

Open, WPA/WPA2 personal and WPA3 SAE networks are supported. Selecting a new network asks for its password inline in the flyout, or in a dialog in the full Settings page, and connects. NetworkManager creates a persistent profile for the connection and stores the password itself; the profile then appears as a saved row you can activate later.

Connect to Wi-Fi

1. Open Settings → Network, turn Wi-Fi on and choose an adapter if needed.
2. Press Refresh, find the network under Nearby networks, then press Connect. Use Choose profile… if several saved profiles match.
3. Enter the password for a secured network and confirm.
4. Wait for Connected, then open a website. For Sign-in required, complete the network’s sign-in in your browser.

Use Saved networks in Settings to reconnect later. Use Cancel to stop an unfinished connection attempt.

Credentials handling

Pearl never writes credentials to its own configuration, and never reads stored secrets back out of NetworkManager: it only supplies the password you typed when NetworkManager asks during a connection you started.

• Password fields are masked except while you hold the peek icon. They clear on submit, cancel, popup close, loss of the NetworkManager service and session locking.
• A rejected password opens a fresh masked entry instead of reusing the previous one.
• Secrets never appear in logs, diagnostics, the on-screen display, the preferences file or CLI output.
• Pearl removes new profiles after a cancelled or failed connection. If the service disappears before profile creation finishes, a saved entry may remain; inspect that entry in the network editor before removing it.

Saved profiles and unsupported types

Saved profiles, including wired ones, are listed in Settings and can be activated there. Use Advanced network settings… to edit or remove profiles. New wired profiles, VPN, WEP, enterprise/802.1X and hidden networks use the external nm-connection-editor; unsupported nearby entries show Set up…. If the editor is missing, install it through your distribution’s package manager. A secured network is never treated as open as a fallback.

To add a VPN, open Advanced network settings… and enter your provider’s settings. Some VPN types also need a NetworkManager plugin from your distribution.

The native page shows signal and basic security labels. For frequency, band or IPv4/IPv6 details, use NetworkManager’s tools; Pearl has no detailed connection information card.

Network unavailable, no adapter or repeated passwords

Check the message in Settings → Network and the system state:

systemctl status NetworkManager.service --no-pager
nmcli device status
nmcli connection show
rfkill list

• Network service unavailable: check that NetworkManager is installed and running. Pearl does not start it.
• Wi-Fi off or software-blocked: turn Wi-Fi on. For a hardware block, check the laptop’s wireless switch or firmware setting.
• No Wi-Fi adapter found: check nmcli device status. If the adapter is also missing there, check its USB connection, driver and firmware.
• Connected with limited internet: check browser sign-in and the network’s internet connection.
• Password requested after every login or resume: check the saved profile’s autoconnect and password-storage settings in the editor. Also check whether the adapter disappeared or NetworkManager restarted during resume.

Keep working profiles while troubleshooting. Remove only a specific unwanted profile, and review logs for private details before sharing them.

Bluetooth

Pair and connect a device

1. Open Settings → Bluetooth, choose the adapter and turn it on. Put the device into pairing mode.
2. Press Discover, select the device by name and address, then choose Pair. Confirm the passkeys or enter its PIN.
3. Use Connect if needed. Trust is a separate choice.
4. Check for Connected. For headphones or a microphone, select the device in Sound settings.

If the device is missing, check its pairing mode and distance, then discover again. For an unavailable service or adapter, check:

systemctl status bluetooth.service --no-pager
rfkill list

If BlueZ is installed but inactive, start bluetooth.service through your distribution’s service manager. Enable it separately if you want it at boot. If it runs without showing an adapter, check the hardware and driver rather than deleting pairings.

Discovery, pairing and trust

The Bluetooth page lists adapters and devices with power, discovery, pair, connect/disconnect and trust controls. Device aliases are shown together with their addresses so identical names stay distinguishable, and the Paired, Connected, Trusted and Blocked states drive which actions are available. Device actions are disabled while the adapter is off.

• Discovery starts only on an explicit request and ends after 30 seconds, on Stop discovery, or when you close the panel. Discovery owned by other applications is left alone.
• Pairing prompts for PINs and passkey confirmation in the panel itself; codes never appear in status output or logs. Pairing has a 90-second deadline, and cancelling it sends a proper cancellation to BlueZ. A pairing BlueZ already completed cannot be undone by cancelling; use your system Bluetooth tools if you need to remove that pairing.
• Trust is separate from pairing: pairing never silently trusts a device.
• Cancelling a connect sends a disconnect, so a late successful reply cannot leave the device connected against your intent.

Locking the session revokes interactive operations such as prompts and discovery, but established network and device connections survive ordinary navigation, page closes and locking.

Cellular, SIM and GPS

Pearl has no dedicated cellular, APN, SIM-unlock or GPS/location pages. Use your distribution’s tools for supported modem or GPS hardware. Pairing a Bluetooth device does not set up mobile broadband or location services.

Command line

pearlctl connectivity status [--offset N]
pearlctl connectivity action --service network --action scan --generation N
pearlctl connectivity action --service bluetooth --action pair \
  --generation N --path /org/bluez/hci0/dev_XX_XX_XX_XX_XX_XX

Status pages through devices, access points, saved profiles and adapters four entries at a time, following next_offset. Actions need the --generation value from a current status call, and device actions need its --path object path.

Network actions are scan, connect, connect_saved, disconnect, enable, disable and cancel. Bluetooth actions are discover, stop_discovery, pair, connect, disconnect, trust, untrust, enable, disable and cancel. Accepted mutations return queued:true; read the actual outcome from a later status call.

Note

Scans, connections and pairings require the matching compact page to be open, for example after pearlctl control-center show --page network or --page bluetooth, and the CLI cannot answer or cancel another frontend’s prompt. Password entry and passkey confirmation are deliberately available only through the graphical interface, and connectivity actions are rejected while the session is locked.