Skip to content

Node Reference Sources

Jump to bottom
Bobby Comet edited this page Aug 2, 2026 · 6 revisions

Node Reference — Sources

Every source has one output socket (kind below). Properties are usually constants (device names, formats), not bindable inputs.

System

CPU Usage — source.cpu_percent

Output percent
core enum — overall or a specific core

CPU Frequency (MHz) — source.cpu_freq

Output number
core enum — overall uses ${freq}; a specific core uses ${freq N}
Notes Free native read, no background script

RAM Usage — source.ram_percent

Output percent

RAM Used — source.ram_used

Output text
Notes ${mem} — Conky's own human-formatted string (e.g. 3.2GiB), not a raw number. Pair with RAM Total, or use RAM Usage (%) instead if you need a gauge value

RAM Total — source.ram_total

Output text
Notes ${memmax}, human-formatted (e.g. 16.0GiB)

Swap Usage — source.swap_percent

Output percent
Notes ${swapperc}

Disk Usage — source.disk_percent

Output percent
mount_path path (default /)

Battery — source.battery_percent

Output percent
device string (default BAT0)

Network

Network Download — source.net_down

Output number (rate; units as implemented in codegen)
interface string — auto or iface name (e.g. wlan0)

Network Upload — source.net_up

Output number
interface string — auto or iface name

Total Downloaded — source.net_total_down

Output text
interface string — auto or iface name
Notes ${totaldown}, human-formatted cumulative total (not the current speed — see Network Download for that)

Total Uploaded — source.net_total_up

Output text
interface string — auto or iface name
Notes ${totalup}, human-formatted cumulative total

Wi-Fi Network Name — source.wifi_ssid

Output text
interface string — auto or iface name
Notes ${wireless_essid}. Reads empty on a wired-only machine, or if auto resolves to a non-wireless interface — pin one explicitly (e.g. wlan0) if that happens

Wi-Fi Signal Quality — source.wifi_signal

Output percent
interface string — auto or iface name
Notes ${wireless_link_qual_perc}

System info

Uptime — source.uptime

Output text
format enum (e.g. short / long style)

Hostname — source.hostname

Output text

Kernel Version — source.kernel

Output text

Process Count — source.process_count

Output number

Top Process (Name) — source.top_process_name

Output text
rank enum 1–10 — 1 is the single busiest process by CPU, 2 the next, etc.
Notes ${top name N}

Top Process (CPU %) — source.top_process_cpu

Output percent
rank enum 1–10
Notes ${top cpu N} — pair with Top Process (Name) at the same rank for a "what's eating my CPU" row

Top Process (RAM %) — source.top_process_mem

Output percent
rank enum 1–10
Notes ${top mem N} — ranked by CPU like the other two Top Process sources, since Conky's top list is CPU-ranked regardless of which field you print from it

Time

Greeting — source.greeting

Output text (time-of-day phrase)

Date / Time — source.datetime

Output text
strftime_format string (strftime pattern, e.g. %A %H:%M)

Sensors (often need lm-sensors / GPU tools)

CPU Temperature — source.cpu_temp

Output celsius
chip_pattern regex for sensor chip names
amd_drm_card optional AMD DRM card hint

GPU Utilization — source.gpu_util

Output percent

GPU Temperature — source.gpu_temp

Output celsius

GPU VRAM Used (MB) — source.gpu_vram_used

Output number

GPU VRAM Total (MB) — source.gpu_vram_total

Output number

Disk Temperature — source.disk_temp

Output celsius
device path (e.g. /dev/sda)
poll_mode enum — execi vs daemon
poll_interval int seconds (daemon; typical min 60)
fallback_location optional fallback

Fan Speed (RPM) — source.fan_rpm

Output number
poll_mode enum — execi (default) vs daemon
poll_interval int seconds (default 3)
Notes Scans /sys/class/hwmon/hwmon*/fan1_input for the first non-zero reading — same sysfs-scan approach as the GPU family's AMD path. Works on most laptops/motherboards without needing lm-sensors configured specifically for fans

Weather (script + cache; needs network / curl as configured)

Weather Condition — source.weather_condition

Output text

Weather Category — source.weather_category

Output category (for icon / branch logic)

Weather Temp (F) — source.weather_temp_f

Output number (°F)
Notes Convert with plugin Temp Convert or Map Range / Scale for °C displays

Public IP (script + cache; needs network / curl)

Public IP Address — source.public_ip

Output text
poll_mode enum — execi vs daemon (default daemon, same reasoning as Weather: a network call is the poll type most likely to hang past its timeout)
poll_interval int seconds (default 1800)
Notes Looks up icanhazip.com, falling back to ifconfig.me if that fails. Useful for a remote-access / "is my VPN up" HUD row

Media (needs playerctl + active player)

Track Title — source.nowplaying_title → text

Track Artist — source.nowplaying_artist → text

Track Album — source.nowplaying_album → text

Playback Status — source.nowplaying_status → category

Playback Progress % — source.nowplaying_progress → percent

Optional player hint may appear on related props depending on build (e.g., player name).

Custom

Custom Script — source.custom_script

Output Controlled by Treat output as (output_kind): text, number, percent, celsius, category; must match what the script prints and what downstream sockets accept
Script path Optional path to an executable/script; copied into the theme's scripts/ at Build
Inline script Monospace editor in the property panel (same idea as Custom Lua). If non-empty, this body is written to scripts/ at Build, and wins over Script path
poll Polling mode: execi (Conky ${execi}) or daemon (background loop + cache); Refresh every (sec) sets the interval
Notes Escape hatch for legacy companion scripts and ad-hoc shell. Prefer Inline script when fixing a legacy import so you can edit without leaving Studio. Import preloads small theme scripts into Inline script when possible and may set daemon + self-caching for sensors/weather-style writers.

Behaviour:

  • Stdout-oriented scripts: print a single line (or simple key=value). Daemon mode writes a Studio cache that render.lua reads into SRC[] when the node is wired.
  • Self-caching scripts (body/path matches patterns like CACHE_FILE, sensors.cache, weather.cache, or importer sets self_caching): run under their original basename, no stdout-capture wrapper, so the cache name Custom Lua expects stays the same. Companion .conf files may be copied beside them.
  • Unwired daemons still run: pure-Lua imports often never wire sensors.sh into a Bar; start.sh still launches those Custom Script nodes so the Lua's own read_kv_cache keeps working.
  • Empty or failed scripts yield empty/zero depending on kind when consumed via SRC[].

Wiring tips

Source kind Typical visual targets
percent Arc gauge, segmented gauge, bar, LED threshold, history graph, sparkline
celsius Text (via format), gauges after Map Range to 0–100
text Text label, string-format logic
category Conditional / pick / image swaps
number Bars after scaling, text via Unit Format plugin
Escape hatch Typical use
Custom Script Legacy sensors/weather shells, one-off shell metrics
Custom Lua Inputs 1–12 Optional bridge from graph → hand-written Cairo (nil if unwired)

Clone this wiki locally