# blueman

The Bluetooth tray applet on the workstations, as a module (novox/hq ADR 0208). It requires
`x11-display`, so it is assigned only where a display server is held on the same machine.

## Owns

| what | where |
|---|---|
| the applet, the manager window, send-to | package `blueman`, from the official repositories |

Nothing else. It holds no seat, makes no contribution and writes no file.

- **No AUR.** Both workstations run the official package (`extra`), installed explicitly.
- **The Bluetooth stack is not this module's.** `bluez`, `bluez-utils` and `bluetooth.service` belong
  to the `bluetooth` module. This module declares none of them (ADR 0210 §4: one package, one module).
  The devices, pairing and power are that module's tools (`bluetooth_*`). This module's tools are
  about the applet.
- **The operator's applet settings are found.** blueman keeps them in dconf (`org.blueman.*`): the
  plugin switches, the recent connections, auto-connect and auto-power-on. The module neither sets nor
  resets them. `blueman_status` shows the plugin switches.

## How it starts: the package's autostart entry, and nothing else

One process has one starter (the rule `picom` states for the desktop modules). The package ships
`/etc/xdg/autostart/blueman.desktop` (`blueman-applet`). The session runs it once at login through
the `i3` module's `dex --autostart --environment i3`. **That entry is the applet's one start.** The
module adds no `xinitrc` slot and no `node-display-session` exec, because either would start it a
second time.

- **Excluded:** the window manager's `exec … blueman-applet`, which the `i3` module's configuration
  dropped.
- **Not a start:** the package's user unit `blueman-applet.service` is static. It exists for D-Bus
  activation of `org.blueman.Applet`. A program that calls the applet's bus name while no applet runs
  starts one through it. The applet is single-instance on that name, so this never makes a second
  one. The tools always ask the bus with `--auto-start=no`, so asking never starts it.
- The applet starts its tray icon, `blueman-tray`, itself.

## Tools

They are served by the node's runtime as the operator account (ADR 0175).

| tool | does |
|---|---|
| `blueman_status` (r) | <ul><li>whether the applet and its tray icon run: pid, since, and the scope or unit they run in</li><li>the installed version, and what starts it at login</li><li>the plugins the running applet has loaded and those it has not (asked of the applet on the session bus)</li><li>the plugin switches in `org.blueman.general plugin-list`</li><li>whether the applet sees Bluetooth on</li></ul> |
| `blueman_restart` (a) | asks the applet and the tray icon to end (SIGTERM), forces them after 5 s, and starts `blueman-applet` in the operator's session. The start is a transient user unit `mesh-blueman-applet`, so it outlives the tools runtime. Answers the pids. Refused plainly when nobody is logged in to the desktop |
| `blueman_check` (r) | <ul><li>the package is installed</li><li>exactly one start: the package's entry is present and not hidden by an entry of the account, and `dex` is installed</li><li>no window-manager exec</li><li>one applet runs in a desktop session</li><li>`bluetooth.service` is active</li></ul>Each finding says what to do |

The tools find the session's `DISPLAY` and `XAUTHORITY` from the window manager's own environment,
as `clipmenu` and `screen-lock` do. Every command has a timeout and capped output. Everything runs
through an injected runner and a fake root in the tests.

## What changes when it is assigned

| | g14 | shanks |
|---|---|---|
| package | none: `blueman` 2.4.6 is installed, explicitly, from `extra` | the same |
| start | none: dex starts the applet from the package's entry, in the login session's scope; the tray icon with it | none on disk. **The applet running now came from the predecessor's window-manager line** (a child of i3, since the session of 2026-10-04 16:00). That session began before the `i3` module dropped the line and installed `dex`, so the next login is the first that starts it from the entry |
| settings (dconf) | defaults, no plugin switched; recent connections only | no plugin switched; auto-connect for one headset, auto-power-on set |

The workstations are already in the state this module describes.

## Migration (ADR 0182)

Nothing is required on either machine. On shanks, log out and in once, or run `blueman_restart`, and
the applet runs from its one start. `blueman_check` then answers `ok`.

## Leaves as found

- The applet's dconf settings (`/org/blueman/`).
- `/etc/xdg/autostart/blueman.desktop`, the package's own file.

## Relies on

- **The `bluetooth` module, for bluez and its daemon.** Without them the applet has nothing to
  manage. There is no dependency mechanism between two modules that hold no seat. So nothing refuses
  `blueman` on a node without `bluetooth`. `blueman_check` reports it instead, from
  `bluetooth.service`. **Assign both.** When the stack becomes a seat (`node-bluetooth`), this module
  depends on the seat.
- **`i3`'s `dex` line for the start**, which is equally undeclared: XDG autostart has no seat.
  Assigned without `i3`, the applet is installed and does not start. `blueman_check` says so.
- A display server on the same machine (`x11-display`, ADR 0208 §3).