No description
  • Python 94.7%
  • Shell 4.8%
  • Makefile 0.5%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Yarrith Devos 01d6d143cb Add ThinLinc client battery indicator for Ubuntu
Sidecar implementation: a client daemon writes the local battery snapshot
into the ThinLinc local-drive export while a native ThinLinc session is
active, and a per-session server agent reads it over the NFS channel and
shows an Ayatana AppIndicator.

- Client: UPower D-Bus with sysfs fallback, /proc-based tlclient detection,
  atomic snapshot writes, systemd user unit, config merge for NFS_EXPORTS
  (flat path,permission syntax) and NFS_SERVER_ENABLED.
- Server: per-session agent started from xstartup.d under tl-while-x11,
  waits for the GNOME session bus/StatusNotifierWatcher, uses
  tl-session-param for connection status/client IP, safe timed NFS reads
  with stale-handle remount recovery, AppIndicator UI and optional
  session-bus D-Bus service.
- Tests: 108 stdlib unittest cases including a real dbus-run-session smoke
  test, plus installer/uninstaller scripts, README, architecture and
  troubleshooting docs.
2026-11-02 18:14:29 +00:00
docs Add ThinLinc client battery indicator for Ubuntu 2026-11-02 18:14:29 +00:00
scripts Add ThinLinc client battery indicator for Ubuntu 2026-11-02 18:14:29 +00:00
src/thinlinc_battery Add ThinLinc client battery indicator for Ubuntu 2026-11-02 18:14:29 +00:00
systemd Add ThinLinc client battery indicator for Ubuntu 2026-11-02 18:14:29 +00:00
tests Add ThinLinc client battery indicator for Ubuntu 2026-11-02 18:14:29 +00:00
thinlinc Add ThinLinc client battery indicator for Ubuntu 2026-11-02 18:14:29 +00:00
.gitignore Add ThinLinc client battery indicator for Ubuntu 2026-11-02 18:14:29 +00:00
LICENSE Add ThinLinc client battery indicator for Ubuntu 2026-11-02 18:14:29 +00:00
Makefile Add ThinLinc client battery indicator for Ubuntu 2026-11-02 18:14:29 +00:00
pyproject.toml Add ThinLinc client battery indicator for Ubuntu 2026-11-02 18:14:29 +00:00
README.md Add ThinLinc client battery indicator for Ubuntu 2026-11-02 18:14:29 +00:00

ThinLinc Battery Indicator for Ubuntu

Show the client device's battery in the ThinLinc session's Ubuntu top bar, without modifying ThinLinc.

This is a sidecar, not a ThinLinc plugin. The native ThinLinc client is closed source and provides no plugin API, so the project works around it by re-using ThinLinc's existing local drive export feature. The export uses ThinLinc's flat, alternating path/permission syntax, e.g. NFS_EXPORTS=/home/alice/share,rw,/home/alice/.cache/thinlinc-battery,ro.

What it does

  1. On the client, a small daemon watches for a native ThinLinc connection.
  2. While connected, it writes a JSON battery snapshot to ~/.cache/thinlinc-battery/thinlinc-battery.json.
  3. That directory is exported read-only through ThinLinc's local-drive channel (NFS over the SSH tunnel).
  4. On the Ubuntu server, a per-session agent reads the snapshot from the mounted drive and shows an Ayatana AppIndicator in the top bar.
  5. When the session disconnects, the icon hides automatically.
┌─────────────────┐         ThinLinc SSH tunnel          ┌──────────────────┐
│  Ubuntu client  │  ══════════════════════════════════► │  Ubuntu server   │
│                 │   local drive export (NFS, read-only)│  (24.04, GNOME)  │
│  tlclient       │                                    │                  │
│  battery daemon │ ── JSON snapshot ──► thinlinc-       │  tl-session-param│
│                 │        battery.json                   │       │          │
│                 │                                    │       ▼          │
│                 │                                    │  AppIndicator in │
│                 │                                    │  top bar         │
└─────────────────┘                                    └──────────────────┘

Requirements

  • Server: Ubuntu 24.04, ThinLinc 4.x, GNOME with the AppIndicator extension (gnome-shell-extension-appindicator, default on Ubuntu).
  • Client: Ubuntu 24.04+ / 26.04 / 26.10, native ThinLinc client.
  • Both: Python 3.10+ (standard library only on the client; python3-gi, GTK3 and AyatanaAppIndicator3 on the server).

Web Access and non-native clients are not supported.

Install

Client (run as the desktop user)

cd Thinlinc-battery-indicator-ubuntu
make install-client

Or manually:

bash scripts/install-client.sh

The installer runs thinlinc-battery setup-client, which refuses to write while a tlclient process is running. Quit the ThinLinc client first, run the install, then restart the client so it picks up the new NFS_EXPORTS setting. If you already installed without quitting, run:

thinlinc-battery setup-client

Server (run as root)

sudo bash scripts/install-server.sh

The server side is started automatically for each ThinLinc session by an xstartup hook (/opt/thinlinc/etc/xstartup.d/90-thinlinc-battery.sh) under tl-while-x11. There is no system-wide systemd unit for the agent.

How it works

  • Transport: a tiny JSON file is carried over ThinLinc's local-drive export. NFS_SERVER_ENABLED=1 and an added NFS_EXPORTS entry are required on the client. The export line uses ThinLinc's flat syntax with absolute paths: NFS_EXPORTS=/home/alice/share,rw,/home/alice/.cache/thinlinc-battery,ro.
  • Server authority: the agent uses tl-session-param /connectionstatus and /client_ip to decide whether the indicator should be visible. If those commands fail, it falls back to data freshness.
  • Freshness: snapshots older than 30 seconds are considered stale.
  • NFS attribute cache: by default the server may cache the mounted file's attributes for up to 60 seconds, so updates can lag. For near-real-time updates, add actimeo=2 to mount_args in /opt/thinlinc/etc/conf.d/tl-mount-localdrives.hconf (Hiveconf /utils/tl-mount-localdrives/mount_args). This affects all local-drive mounts and slightly increases NFS attribute traffic; it is optional.
  • Remount: if a read times out or returns a stale NFS handle while connected, the agent may run tl-umount-localdrives -s followed by tl-mount-localdrives to recover. This briefly unmounts the user's other local drives. The agent does not remount for missing, invalid, or merely old-but-readable data.
  • No data: if the client has no battery or the snapshot is unreadable, the indicator shows "AC/online" or hides.

Configuration

Setting Default Description
Client export path ~/.cache/thinlinc-battery Where the snapshot is written and exported.
Snapshot file thinlinc-battery.json Read by the server agent.
Client poll 2 s How often the daemon checks for a ThinLinc connection.
Client write interval 10 s How often the battery is re-read and written.
Server poll 1 s (indicator refresh) / 2 s (drive reads) How often the agent updates.
Stale threshold 30 s Age after which the snapshot is considered stale.
Wait for desktop 120 s Time the agent waits for the session bus / AppIndicator host.

Use thinlinc-battery setup-client --dry-run to preview the ThinLinc client configuration changes.

Troubleshooting

  • No icon in the top bar: ensure gnome-shell-extension-appindicator is enabled and the session bus is available. The agent waits up to 120 s for the AppIndicator host (org.kde.StatusNotifierWatcher). Check $TLSESSIONDATA/thinlinc-battery.log on the server and journalctl --user -u thinlinc-battery-client.service on the client.
  • No battery data: verify local drive export (thinlinc-battery probe), check tl-session-param /connectionstatus on the server, and look for stale NFS handles.
  • Stale data: the agent logs remount attempts for timeout/stale NFS handles. You can also run tl-umount-localdrives -s; tl-mount-localdrives manually.
  • Switching clients: detection is based on an established TCP socket owned by tlclient or its helpers. The server is authoritative, so the indicator hides on disconnect regardless of client state.
  • No battery / desktop client: the snapshot reports present=false; the indicator shows an AC adapter icon or hides.

Known limitations

  • NFS semantics can leave stale handles when the client changes; the agent remounts local drives only on timeout/stale reads, which briefly affects other exported drives.
  • Web Access is unsupported.
  • Only native ThinLinc clients are detected.
  • No battery or desktop clients show an AC-style indicator.
  • There is no real GNOME battery menu integration (future work: a GNOME Shell extension, or test_power for development).
  • Client clock skew affects freshness calculations.

Development

python3 -m compileall -q src tests
PYTHONPATH=src python3 -m unittest discover -s tests -v
PYTHONPATH=src python3 -m thinlinc_battery --help

See also docs/ARCHITECTURE.md and docs/TROUBLESHOOTING.md.

License

MIT — see LICENSE.