- Python 94.7%
- Shell 4.8%
- Makefile 0.5%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
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. |
||
| docs | ||
| scripts | ||
| src/thinlinc_battery | ||
| systemd | ||
| tests | ||
| thinlinc | ||
| .gitignore | ||
| LICENSE | ||
| Makefile | ||
| pyproject.toml | ||
| README.md | ||
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
- On the client, a small daemon watches for a native ThinLinc connection.
- While connected, it writes a JSON battery snapshot to
~/.cache/thinlinc-battery/thinlinc-battery.json. - That directory is exported read-only through ThinLinc's local-drive channel (NFS over the SSH tunnel).
- On the Ubuntu server, a per-session agent reads the snapshot from the mounted drive and shows an Ayatana AppIndicator in the top bar.
- 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=1and an addedNFS_EXPORTSentry 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 /connectionstatusand/client_ipto 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=2tomount_argsin/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 -sfollowed bytl-mount-localdrivesto 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-appindicatoris 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.logon the server andjournalctl --user -u thinlinc-battery-client.serviceon the client. - No battery data: verify local drive export (
thinlinc-battery probe), checktl-session-param /connectionstatuson 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-localdrivesmanually. - Switching clients: detection is based on an established TCP socket owned
by
tlclientor 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_powerfor 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.