A one-page hardware dashboard for the screen next to your machine.
hwdeck puts every sensor your Linux box exposes on a single screen: CPU cores, GPU, memory, disks, network, every temperature channel, every fan with its PWM duty, and every voltage rail. It shows hardware, not programs. It was made for old hardware brought back as a side screen: a tablet running Linux on its framebuffer console, a Raspberry Pi display, a spare laptop. So it asks very little:
- 16 colours and the stock console font. Everything is drawn from block and box-drawing characters in the VGA (CP437) set, so it renders on a bare Linux VT with the kernel's default font, over SSH, or in any terminal.
- Python 3 standard library only. No pip install. It reads
/procand/sys, needs no root, and usessensors -j(lm-sensors) andnvidia-smiwhen they are there. - One file. Copy it, run it.
┌─┐1cpu┌───────────────────────────────────────────────────┐02:42:57┌───────────────────────────────┐workstation up 0d 08:42┌─┐
│ 2% ┌─┐11th Gen Intel Core i5-11400┌───────────────────────┐│
│ │ CPU ■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■ 2% 47°C 2.5G ││
│ │ C0 ■■■■■■■■■■ 0% 46°C C6 ■■■■■■■■■■ 1% 46°C ││
│ │ C1 ■■■■■■■■■■ 0% 44°C C7 ■■■■■■■■■■ 4% 44°C ││
│ │ C2 ■■■■■■■■■■ 1% 42°C C8 ■■■■■■■■■■ 0% 42°C ││
│ │ C3 ■■■■■■■■■■ 4% 44°C C9 ■■■■■■■■■■ 3% 44°C ││
│ │ C4 ■■■■■■■■■■ 2% 43°C C10 ■■■■■■■■■■ 0% 43°C ││
On screen every meter and graph is coloured. The full frames are in
examples/screen-btop.txt and
examples/screen-bunker.txt.
The same data, five ways to draw it, plus a sixth that shows only heat and air. Pick one with --style or style = "..." in the config.
| Style | What it looks like |
|---|---|
btop (default) |
Coloured boxes with their titles in the top border, gradient graphs, ■ meters and per-core rows, in the visual language of btop. |
bunker |
One heavy chassis of LED meter columns with scale rails, stencil zone tags, amber readouts and a hazard-striped master alarm plate. |
eq |
Groups of equalizer bars with falling peak-hold caps, like an old media player's spectrum analyzer. |
panel |
A plant control panel: annunciator lamps that light by level, LED ladders and bracketed readouts. |
glance |
Three big numerals with load strips and heat tiles, for reading from across a room. |
thermal |
Every temperature sensor and every fan, one btop-style box per zone (CPU, fans, battery, board, skin & air, storage) with gradient meters and a history graph each. Channels that read nothing are listed raw in a "no sensor" strip. |
btop, bunker, eq and panel are laid out for 128×48 (a 1024×768 console with the
8×16 font); glance works from 100×40. A smaller terminal falls back to glance. thermal fits itself to
any size from 50×14: more columns on a wide screen, then it drops the summary box and trims
rows on a short one.
A view puts one part of the machine on the whole screen, for a hotkey or a Touch Bar tap.
Pick one with --view; each is one flag:
hwdeck --view cpu # per-core load and clock, the CPU split, temperatures, throttling
hwdeck --view memory # used / available / cached / buffers / swap, and the top memory users
hwdeck --view fans # every fan: rpm, % of max, target, min / max, mode, the CPU temperature it follows
hwdeck --view battery # charge, health, power in and out, the charge limit, battery temperatures
hwdeck --view power # what the machine draws: battery watts, RAPL domains, AC, who uses the CPU
hwdeck --view network # Wi-Fi SSID, band, signal and link rate, IPv4, live down / up, Tailscale
hwdeck --view thermal # every temperature sensor and fan by zone (the same as --style thermal)The views are drawn in the white of the Touch Bar strip's clock on deep black: the readouts, values, meters, rules and graphs in white and greys, labels in grey, one rounded grey frame per view. Under its top edge sits the hero: the view's key facts in two label-value columns, its rows and the history graph (no big single number: it only repeated the graph's label). Sections follow in columns, each with its own heading and graph where one says something.
Colour is kept for two things. Identity: each view's subject accent (CPU mint, thermal and fans cyan, network lime, memory violet, power yellow, battery green) wears its title icon at full strength, and at a calm, slightly desaturated strength the readout's unit, the icons beside its facts and in section headings (the heading text stays grey), and the one meter or graph that tells the view's story: cpu's load history, the hottest sensor's meter, network's down / up graphs, memory's "used" meter, power's system-watts graph, battery's charge meter and charge history. The digits stay white. Attention: a value turns amber or red only when it crosses a threshold, on its text and its meter, never a whole section:
| View | Amber | Red |
|---|---|---|
| thermal, fans | a temperature at 72 °C; a battery sensor at 45 °C; a skin, palm-rest or airflow sensor at 45 °C | at 90 °C; battery at 55 °C; skin at 50 °C |
| cpu | load above 85 % for 60 s (the readout) | a throttle event since boot |
| power | draw above 38 W for 30 s (the readout) | |
| battery | 20 % or less, or empty within the hour | 10 % or less |
| memory | pressure (PSI some avg10) at 10 %, swap over 64 MB in use | PSI full avg10 at 5 % |
| network | signal under 40 %, more than 5 failed transmissions in the last minute | signal at 20 % |
The cpu throttle section's cooling steps (ACPI passive, TCC offset, idle injection) show
amber while a step is active. A warning overrides the accent: the readout's unit takes the
warning's colour with the digits.
Together the views make a wall (cpu, thermal, network, memory, power and battery side by side), and each fact lives on exactly one of them: temperatures and fans in thermal, watts in power, charge in battery, the clock in cpu's frame, the host name in network's.
They want a terminal with 256 colours and a Nerd Font, and use 24-bit colour when
COLORTERM=truecolor (foot sets it); on the kernel console (TERM=linux) the icons are left
out. Outside --once a view also turns the terminal's own background black (OSC 11), so
foot's padding matches, and gives it back on exit.
| View | What it shows |
|---|---|
cpu |
Total load as the readout; beside it cores and threads, average clock, load average, running and total tasks, uptime. Per-core load and clock; the user / system / iowait / irq split; load history. programs: the busiest processes since the last frame, from /proc/*/stat, with % of all cores, threads and the core each last ran on. throttle: thermal-throttle event counts and time since boot (core and package), ACPI passive cooling steps, the TCC offset, idle injection. clock: turbo, the scaling cap, governor and energy preference, intel_pstate perf limits, min / max / base, driver, with clock history. The cpu view also carries the wall's one clock, in its frame. |
memory |
Used share as the readout; beside it used of total, committed of the commit limit, memory pressure (PSI avg10, some and full) and kernel memory (slab, stacks, page tables). Used, available, cached, buffers, free, shared and swap meters. top: resident memory per program name, summed over its processes, from /proc/*/statm. swap: swap cached, every swap device and zram's compression ratio, with history. cache: reclaimable slab, active / inactive file pages, dirty and writeback, with history. |
fans |
One section per fan, side by side: rpm, % of max, the SMC target, min and max, auto or manual mode, the CPU temperature the fan loop is answering to, and an rpm history. |
battery |
Charge as the readout, charge_now / charge_full (the kernel's capacity divides by the design capacity, which on a worn pack reads low; it is shown beside it). Beside it: status, time to full or empty or held at the limit, charge in Ah, and the trend in %/h since hwdeck started. Charge and charge-limit meters, and a charge history at a sample a minute (12 hours). health: charge_full against charge_full_design, cycle count, chemistry. events: each status change since hwdeck started, with the time and charge. Watts, current, voltage and the adapter are in power; battery temperatures are in thermal. |
power |
The whole system's draw as the readout, in whole watts: the Apple SMC's PSTR key, the mean of the last three samples, on AC or battery alike. It comes from a root service that writes the SMC's power keys every 2 s to /run/omk-smc-power.json (the smc-power module of omarchy-mac-kit, or anything else that writes that file) ({"t": unix, "watts": {key: W}}, world-readable; HWDECK_SMC_POWER points elsewhere); older than 10 s counts as stale. Without it the readout falls back to the battery's watts (current_now x voltage_now) and the view says "SMC power service not running" (or "stale") in one line. Beside it: the source (AC adapter or battery), the battery's watts in or out, the energy used since the view started (the draw integrated frame by frame), its average and its peak. where it goes, full width: system PSTR, adapter in PD0R, CPU package PCPT, CPU cores PCPC, graphics PCPG and battery / platform PPBR? (a guess), each named with its raw key and a meter, over the system's history. wakeups: interrupts and context switches per second, and the busiest interrupt sources from /proc/interrupts (what keeps waking the machine). rapl: the RAPL domains in watts, or "locked" while energy_uj is root-only. battery rail: current and voltage. |
network |
The Wi-Fi signal as the readout, the same number the Touch Bar strip shows: 2 x (dBm + 100) in whole %, clamped 0-100, the mean of the last three samples (-- and "no wifi" without a link). Beside it: the SSID and dBm; the link's load, max(down bits/s / rx bitrate, up bits/s / tx bitrate) from the smoothed rates and the bitrates iw reports ("0% of 360 Mb/s"); the IPv4 address, and the down and up rates, smoothed over about 5 s, each in a unit that changes only after the rate has wanted another one for 4 s and always ddd.d wide. Down / up graphs side by side under it (raw, not smoothed). Wi-Fi comes from iw dev <if> link (no root), else /proc/net/wireless and nmcli -t; the interface is the default route's (or net_interface in the config). On a taller window: wifi (band, channel, frequency, rx / tx rates, time connected and failed transmissions from iw station dump), tailscale (state, this node's tailnet address, peers online, exit node, from tailscale status --json at most every 15 s), ip (router, DNS via resolvectl dns behind systemd-resolved's stub, the IPv6 prefix, MAC) and since boot (bytes down / up per interface). The frame names the host. |
thermal |
Every temperature and the fans. The hottest live sensor as the readout, in whole °C, coloured by the strip's 50 / 72 / 90 °C (cyan, amber, red); beside it its friendly name and key, the live / no-sensor counts, and each fan's rpm, % of max and the temperature its loop follows (the SMC's TC0F on a Mac). Then one section per zone (CPU, battery, board, skin & air, storage) with a meter per sensor in its temperature colour, packed into the columns that leave the tallest one shortest; then a compact fans section and the channels that read nothing in a "no sensor" strip, which give way first on a short screen, so all 33 sensors of a MacBook Pro 14,2 show at 66 x 27. |
Burn-in protection. The views are meant to stay up for hours, and their frames and labels
do not move. So every 3 minutes the whole drawing shifts one cell, round (0,0), (1,0), (1,1),
(0,1) and back, inside a spare column and row kept free for it (every cell of a frame moves
together, so nothing jumps mid-frame). After 30 minutes the chrome (frame, headings, labels)
drops to about two thirds of its brightness; values, meters, readouts and graphs stay full.
Restarting the view brings it back. Both are on by default; --no-orbit or orbit = false
in the config turns them off. HWDECK_ORBIT_SECONDS and HWDECK_DIM_SECONDS override the
3 minutes and 30 minutes, for a quick check.
The charge limit is read from charge_control_end_threshold, on the battery or, on Intel
Macs, on the applesmc platform device. Batteries that report energy (energy_now,
power_now) work the same as those that report charge.
The views are laid out for a grid of equal windows on one laptop screen, about 66 x 27 each
(the fans live in thermal there; --view fans still works on its own and fits 66 x 12), and
use the space they get: cores and
meters pair up on a short window, sections pack into two columns, and thermal fits all its
sensors (33 on a MacBook Pro 14,2) in two columns at that size. They fit any size from
50 x 10: on a short screen the readout gives way to a plain row, long lists end in "+N more"
and the last sections drop. Graphs fill in as hwdeck runs; a --once frame has one sample.
| Group | Sources |
|---|---|
| CPU | per-core load and clock, user / system / iowait / irq split, load average, context switches and interrupts per second |
| GPU | AMD via amdgpu sysfs (busy, VRAM, power and cap, temperatures, fan and PWM, core and memory clocks, core voltage) or NVIDIA via nvidia-smi |
| Memory, disks | used / available / cached / swap, per-mount usage, read and write rates |
| Network | per-interface bytes and packets per second |
| Temperatures | every hwmon channel: CPU package and cores, GPU, NVMe, DIMMs, board inputs, chipset, Wi-Fi, NIC; on Intel Macs every applesmc key (CPU, battery, memory, PCH, heatpipes, palm rest, airflow, ambient, Thunderbolt, SSD) |
| Cooling | every fan header's rpm, PWM duty and control mode; applesmc fans with min, max and target rpm |
| Power | every voltage rail the board reports, GPU power history |
| Services | systemd units you list, shown as green or red |
Channels that read nothing (unwired board inputs) are left out.
The thermal style reads every hwmon chip straight from /sys/class/hwmon (no lm-sensors
needed), including applesmc on Intel Macs, whose files sit on the platform device. Each
4-character SMC key gets a friendly name and a zone, with the raw key kept beside it; names
marked ? are community guesses for that key. Readings of -127, -44, -0.25 or 0 are absent
sensors and are listed as "no sensor". Fans show rpm, % of max, min / max, the SMC target and
auto or manual mode. Alarm thresholds come from
the sensor's own critical value where it reports one.
curl -LO https://raw.githubusercontent.com/pnshad/hwdeck/main/hwdeck
chmod +x hwdeck
./hwdeckCtrl-C to quit. For fan speeds, voltages and board temperatures install lm-sensors
(sudo apt install lm-sensors, then sudo sensors-detect); some boards need a driver
module, for example nct6775.
Options: --style NAME (btop, bunker, eq, panel, glance, thermal), --view NAME
(cpu, memory, fans, battery, power, network, thermal; wins over --style), --no-orbit (views: no burn-in protection), --config FILE (default
~/.config/hwdeck/config.toml), --interval SECONDS, --once (draw one frame and exit). Every setting is optional; see
config.example.toml.
Run hwdeck in a tmux session on the machine and have the small screen attach to it read-only, so nothing on the display can type into your machine:
tmux new-session -d -s deck -x 128 -y 48 ./hwdeck
tmux set-option -t deck status off
# on the display (or over ssh from it):
tmux attach -r -t deckWith SSH you can go further and give the display a key that can only do that, in the
machine's ~/.ssh/authorized_keys:
restrict,pty,command="tmux attach -r -t deck" ssh-ed25519 AAAA... display
On a bare Linux console, setterm -blank 0 keeps the screen on, and
echo 1 > /sys/class/graphics/fbcon/rotate_all turns it to landscape.
- No braille. btop's braille graphs are beautiful, but most console fonts don't have braille. Half-block graphs give two levels per cell and render everywhere. The styles keep to 16 colours; only the views use 256 or 24-bit colour and Nerd Font icons.
- Read-only by design. hwdeck only reads
/proc,/sys,sensorsandsystemctl is-active, plus any[extra]commands you add to your own config. - Hardware, not programs, with two exceptions: the
memoryview lists the programs using the most memory (two small reads per process each refresh) and thepowerview the ones using the most CPU (one read per process). - CPU package power comes from the RAPL counter, which most kernels only let root read; without it that reading is left out.
| Machine | What works |
|---|---|
| Any Linux box (Pi, laptop, server, tablet console) | every style and view; fans and power where the kernel exposes them |
Intel Mac with applesmc |
SMC sensor names and zones, fans (rpm, target, mode), charge limit |
| MacBookPro14,2 (13" 2017, Touch Bar) | tested; all 33 sensors in thermal, SMC power keys in power (with the root service above) |
SMC key names marked ? are guesses for that key and may mean something else on other models.
- touchbar-strip: a Touch Bar renderer for T1 MacBooks whose slots open hwdeck views.
- omarchy-mac-kit: installs hwdeck as a wall of views on Omarchy, plus the SMC power service.
MIT. See CREDITS.md. The btop style borrows the look of btop by Aristocratos; hwdeck shares no code with it.