From 7ef9b6d3bd1e9f6cda6884de8ebd6ad7cef8da14 Mon Sep 17 00:00:00 2001 From: Pierre-Olivier Mercier Date: Thu, 9 Apr 2026 12:38:39 +0700 Subject: [PATCH] README: comprehensive rewrite Replaces the Phase 0 placeholder with a full project README covering features, architecture, build/install, runtime requirements, usage, configuration, and known gaps. Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 173 +++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 152 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 3079ea8..a4afce7 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,161 @@ -# e_iwd +# e_iwd — Enlightenment Wi-Fi module (iwd backend) -Enlightenment module for Wi-Fi management via [iwd](https://iwd.wiki.kernel.org/), -a native replacement for the ConnMan-based econnman gadget. +A native [Enlightenment](https://www.enlightenment.org/) gadget that +manages wireless connections through [iwd](https://iwd.wiki.kernel.org/), +the Intel Wireless Daemon. No NetworkManager, no ConnMan, no shelling +out to `iwctl` — everything goes over iwd's D‑Bus API. -See `CLAUDE.md` for the full PRD and implementation plan. +It is roughly the iwd-only equivalent of `econnman`. + +## Features + +- **Shelf gadget** with a signal-tier icon (off / acquiring / weak…excellent) + and a tooltip showing the current SSID, security type, and signal level. +- **Popup network browser** (left-click the gadget): + - status line: disabled / disconnected / scanning / connecting / connected + - sorted network list — connected first, then known networks, then by + signal strength; long SSIDs are truncated to keep the popup tidy + - per-row signal bars and security tag (`open` / `WPA` / `WEP` / `802.1X`) + - **Connect** by clicking a row, **Forget** (`✕`) on known networks + - **Rescan**, **Enable / Disable** Wi‑Fi + - **Disconnect** button visible while connected + - **Hidden…** button to join a non-broadcasting SSID +- **Authentication agent** registered with iwd: + - passphrase prompt for new protected networks (modal dialog window) + - cancel-on-`Agent.Cancel` so iwd-initiated cancellations close the + open prompt cleanly + - polite stubs for `RequestUserNameAndPassword`, `RequestUserPassword` + and `RequestPrivateKeyPassphrase` so iwd doesn't unregister us when + it tries them on EAP networks +- **Settings dialog** (right-click the gadget → Settings): + - auto-connect to known networks + - show hidden networks + - signal refresh interval + - preferred wireless adapter +- **Robust to iwd lifecycle**: tracks `net.connman.iwd` name owner, + re-binds objects on restart, clears state on departure. + +## Architecture + +``` +e_iwd/ +├── src/ +│ ├── e_mod_main.c module init/shutdown +│ ├── e_mod_gadget.c gadcon provider, icon + tooltip + menu +│ ├── e_mod_popup.c network list popup +│ ├── e_mod_config.c persistent settings + E_Config_Dialog +│ ├── iwd/ +│ │ ├── iwd_dbus.c system bus, name owner, ObjectManager +│ │ ├── iwd_manager.c top-level state aggregator + listeners +│ │ ├── iwd_adapter.c net.connman.iwd.Adapter (Powered) +│ │ ├── iwd_device.c Device + Station, scan/connect/disconnect, +│ │ │ GetOrderedNetworks → signal strength +│ │ ├── iwd_network.c Network.Connect, KnownNetwork.Forget +│ │ ├── iwd_agent.c net.connman.iwd.Agent (passphrase, cancel) +│ │ └── iwd_props.c a{sv} parsing helpers +│ └── ui/ +│ ├── wifi_auth.c passphrase dialog (floating elm_win) +│ └── wifi_hidden.c hidden-network SSID + passphrase dialog +└── meson.build +``` + +Data flow: + +``` +iwd (D-Bus) ──► iwd_dbus ──► iwd_manager ──► iwd_device / iwd_network + │ + ├──► listeners (gadget, popup) + └──► Iwd_Agent ──► UI passphrase prompt +``` + +The module uses **Eldbus** for all bus traffic and **Elementary** for +its widgets. Everything is async — no blocking calls on the UI thread. + +## Building + +Dependencies (development headers): + +- Enlightenment ≥ 0.25 (tested against 0.27) +- EFL ≥ 1.26 (Eldbus, Elementary, Edje, Ecore, Eina) +- meson + ninja +- a running `iwd` ≥ 1.0 (runtime, not build-time) + +Build and install: + +```sh +meson setup build +ninja -C build +sudo ninja -C build install +``` + +The module is installed to +`/enlightenment/modules/iwd//module.so`. The +`module_arch` and `libdir` are pulled from Enlightenment's pkg-config +file, so the install path matches whatever your distro packages. + +Once installed, enable it from **Settings → Modules → Extensions → +iwd**, then add the gadget to a shelf or the desktop via +**Settings → Gadgets**. + +## Runtime requirements + +- `iwd` running as a system service (`systemctl enable --now iwd`). +- Your user must be allowed to talk to `net.connman.iwd` on the system + bus. On most distros this means being in the `network` group, or + having a polkit rule for the `net.connman.iwd` interfaces. The module + degrades gracefully when permissions are missing — you'll just see an + empty list. +- A wireless adapter managed by iwd (i.e. not claimed by + NetworkManager / wpa_supplicant). + +## Usage + +| Action | How | +|---|---| +| Open the network list | Left-click the gadget | +| Open settings | Right-click the gadget → Settings | +| Connect to a known network | Click its row in the list | +| Connect to a new protected network | Click its row, enter the passphrase in the dialog | +| Forget a known network | Click the `✕` button on its row | +| Disconnect | Click **Disconnect** in the popup (visible while connected) | +| Join a hidden SSID | Click **Hidden…**, enter SSID and (optional) passphrase | +| Rescan | Click **Rescan** | +| Disable / enable Wi-Fi | Click **Disable** / **Enable** in the popup | + +Passphrases are sent straight to iwd over D-Bus. They are never logged, +never written to the module config, and are zeroed in memory once the +dialog closes. + +## Configuration + +Settings are persisted via Enlightenment's standard config system as +`module.iwd` (an `eet` file under your E config profile, e.g. +`~/.e/e/config//module.iwd.cfg`). Fields: + +| Field | Default | Meaning | +|---|---|---| +| `auto_connect` | on | Let iwd auto-connect to known networks | +| `show_hidden` | off | Reveal hidden networks in the list | +| `refresh_interval` | 5 | Signal-strength refresh interval (seconds) | +| `preferred_adapter` | — | Preferred wireless adapter (blank = auto) | ## Status -Phase 0 — scaffolding only. Nothing connects to D-Bus yet. +Phases 0–4 of the project are complete and the module builds cleanly +against EFL 1.28 / Enlightenment 0.27. Phase 5 (robustness) and Phase 6 +(packaging) are partially landed. -## Build +Known gaps: - meson setup build - ninja -C build - sudo ninja -C build install +- No custom theme `edj` — the gadget uses freedesktop icon names from + the active icon theme. +- No suspend / resume integration. +- No EAP UI (RequestUserName / RequestPrivateKey are stubbed to + refuse). +- Multi-adapter UX is auto-select-first; the preferred-adapter setting + is plumbed but not yet honored by the manager. +- Not yet tested by valgrind for leaks. -Requires: `enlightenment`, `elementary`, `eldbus` (pkg-config). +## License -## Layout - - src/ - e_mod_main.c module entry points - e_mod_gadget.c shelf gadget - e_mod_popup.c popup UI - e_mod_config.c persistent settings - iwd/ D-Bus client to net.connman.iwd - ui/ reusable EFL widgets - data/ - module.desktop +MIT-style, matching Enlightenment and EFL. See `LICENSE`.