giovannino
45f63962f4
Rewrites the README to match the navigation redesign in the last commit: - Status section reflects the touch-bar/scroll-section layout, replacing the outdated tab-based description - New Design Notes explain *why* navigation changed — untested touch-swipe fidelity on this hardware, and accessibility reasoning for the intended client base (small factories; many users may not have a full set of fingers/thumbs on either hand). Resistive touch and oversized, forgiving touch zones are framed as a deliberate choice, not a workaround, so the reasoning doesn't have to be reconstructed from memory later. - Known Issues trimmed to what's actually still open — the fixed items from the v0.0.1 review (unused import, dead sparkline, missing threshold colouring, stale class name) are removed; the Screen vs. Container note is reframed as intentional design, not a leftover - Roadmap updated with the touch-controller HID check (lsusb/dmesg/evtest) flagged during hardware research — some earlier Waveshare display revisions need a non-standard driver
153 lines
No EOL
6 KiB
Markdown
153 lines
No EOL
6 KiB
Markdown
# server-monitor-dash
|
||
|
||
A case-mounted touchscreen monitoring dashboard for Cervello Elettrico
|
||
servers — CPU, GPU, and memory telemetry rendered "supercar dash" style,
|
||
built in Python with [Textual](https://github.com/Textualize/textual).
|
||
|
||
---
|
||
|
||
## Status: v0.0.2 — functional dashboard, navigation redesigned
|
||
|
||
The Dashboard section is fully functional — live per-core CPU, memory,
|
||
and GPU telemetry, refreshed once per second, with threshold-driven
|
||
colour (green → amber → red) applied consistently across every gauge.
|
||
The **Request Assistance** and **Switch to X** sections are stubs,
|
||
wired for later completion.
|
||
|
||
Navigation moved from tabs to a fixed touch-bar sidebar with up/down
|
||
buttons controlling a scrollable stack of full-screen sections — see
|
||
Design Notes below for why.
|
||
|
||
This is not yet a CE OS-compliant script (no test gates, no cleanup
|
||
trap — see the CE OS Scripting Style Guide). It remains a prototype for
|
||
iterating look, feel, and navigation, not a production deployment.
|
||
|
||
---
|
||
|
||
## Requirements
|
||
|
||
- Python 3.10+
|
||
- [Textual](https://github.com/Textualize/textual) —
|
||
`pip install textual --break-system-packages` (or via `pipx`)
|
||
- Linux with `/proc/stat` and `/proc/meminfo` (CPU/memory stats — no
|
||
external dependency beyond the standard library for these)
|
||
- `nvidia-smi` on `PATH`, for GPU telemetry (gracefully degrades to zero
|
||
values if absent or if the query fails)
|
||
|
||
Target hardware: a 5" case-mounted touchscreen, e.g. the Waveshare 5"
|
||
HDMI LCD (800×480, resistive touch). See Design Notes for why resistive
|
||
touch specifically shaped this interface's navigation model.
|
||
|
||
---
|
||
|
||
## Running it
|
||
|
||
```bash
|
||
python3 server_dash.py
|
||
```
|
||
|
||
Designed to run under a dedicated, unprivileged monitoring user's
|
||
autologin session — no X server required for the dashboard itself. (The
|
||
**Switch to X** section, once wired up, is specifically for spinning up
|
||
X on demand for GPU tuning tools that do need it.)
|
||
|
||
---
|
||
|
||
## Design notes
|
||
|
||
### Navigation: touch-bar, not tabs, not free-scroll
|
||
|
||
Earlier drafts used `TabbedContent`/`TabPane`. This was replaced with a
|
||
fixed-width touch-bar sidebar (up/down buttons) controlling a
|
||
`VerticalScroll` of `min-height: 100vh` sections, for two reasons:
|
||
|
||
- **Touch-swipe fidelity on this specific hardware was never verified.**
|
||
Button-triggered navigation (`scroll_to_widget()`) removes the
|
||
dependency entirely rather than hoping raw swipe gestures arrive
|
||
cleanly from this touchscreen.
|
||
- **The client base includes people who may not have a full set of
|
||
fingers or thumbs on either hand** (small-factory environments). Touch
|
||
zones are deliberately oversized — roughly thumb-width, half the
|
||
screen's height — with a forgiving click margin extending past the
|
||
visible coloured bar, so an imprecise touch from any part of a hand
|
||
still registers. This is tested and confirmed working in the
|
||
assembled app, not just assumed.
|
||
|
||
### Resistive touch is the right technology here, not a compromise
|
||
|
||
Capacitive touch requires conductive bare skin and doesn't reliably
|
||
register gloves, prosthetics, or some scarred/grafted skin. Resistive
|
||
touch responds to pressure from anything — a knuckle, a gloved finger,
|
||
a stylus, a partial hand. Given the intended client base, resistive
|
||
touch and generously-sized, forgiving touch zones are a deliberate
|
||
accessibility choice, not a lesser alternative to capacitive.
|
||
|
||
### Threshold colours
|
||
|
||
Green → amber → red follows the same instinct as a car's tachometer
|
||
redline. Current GPU temperature thresholds (65°C amber, 75°C red) are
|
||
based on empirically observed thermal-error thresholds on constrained
|
||
hardware in this project — not arbitrary numbers. Applied consistently
|
||
to every gauge (GPU temp and util, all CPU cores, memory) — not just
|
||
one readout.
|
||
|
||
### Data sources
|
||
|
||
- **GPU stats** via `nvidia-smi`, same parsing approach as this
|
||
project's thermal-logging script — no Python NVIDIA-bindings
|
||
dependency.
|
||
- **CPU/memory stats** are pure standard library (`/proc/stat`,
|
||
`/proc/meminfo`) — the same low-level mechanism `btop` itself uses
|
||
under the hood, reimplemented in Python.
|
||
|
||
### Idle-blank after 15 minutes
|
||
|
||
Any keypress or click resets the timer; timeout shows a solid black
|
||
screen. A deliberate longevity choice — protects the physical display
|
||
from years of always-on burn-in — not just a power-saving nicety.
|
||
|
||
---
|
||
|
||
## Known issues
|
||
|
||
- `DashboardSection`, `RequestAssistanceSection`, and `SwitchToXSection`
|
||
are plain `Container`s, not `Screen`s — this is intentional (see
|
||
Design Notes in the code), not a leftover from the tab-based layout.
|
||
- Touch-bar width (currently 20 cells, visible bar 12 cells) was sized
|
||
by eye against real-world hand width, not calculated from the
|
||
display's physical dimensions — terminal UIs size in character cells,
|
||
not physical units, so this is expected to need on-hardware
|
||
calibration once mounted, not a precise spec.
|
||
- Raw touch-swipe (as opposed to button taps) has not been tested on
|
||
the actual touchscreen hardware — the design deliberately does not
|
||
depend on it working, but it hasn't been ruled in or out.
|
||
|
||
---
|
||
|
||
## Roadmap
|
||
|
||
- [ ] Wire up **Request Assistance** — scripted outbound email via
|
||
`smtplib` notifying the responsible admin, hostname included
|
||
automatically
|
||
- [ ] Wire up **Switch to X** — calls a narrowly-scoped, sudoers-gated
|
||
wrapper script that switches to a dedicated VT and drops to a
|
||
standard login prompt (password required) before X starts
|
||
- [ ] Confirm touch-bar sizing on real hardware once display is mounted
|
||
- [ ] Confirm touch controller reports as standard HID
|
||
(`lsusb`/`dmesg`/`evtest`) — some earlier Waveshare display
|
||
revisions used a non-standard protocol requiring a custom driver
|
||
- [ ] Bring the script up to full CE OS scripting style guide compliance
|
||
(test gates, cleanup handling)
|
||
|
||
---
|
||
|
||
## Licence
|
||
|
||
The Unlicense — see [LICENSE](./LICENSE). Commercial use explicitly
|
||
permitted, no attribution required — though if this is useful to you,
|
||
consider a mention.
|
||
|
||
---
|
||
|
||
*Built standing on the shoulders of billions of dwarves*
|
||
*Created by John A. Hoeven with the ethical assistance of Claude AI* |