Skip to content

Node Reference Sources

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

Node Reference — Sources

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

Output kinds: percent · celsius · number · text · category

System

CPU Usage — source.cpu_percent

Output percent
core enum — overall, cpu0…cpu7 (default overall)

RAM Usage — source.ram_percent

Output percent

Disk Usage — source.disk_percent

Output percent
mount_path path (default /)

Battery — source.battery_percent

Output percent
device string (default BAT0)
Notes Reports nothing (nil) on machines with no battery instead of a fake 0%/100%.

CPU Frequency (MHz) — source.cpu_freq

Output number
core enum — overall, cpu0…cpu7 (default overall)

RAM Used — source.ram_used

Output text (human-formatted, e.g. 3.2GiB)

RAM Total — source.ram_total

Output text (human-formatted, e.g. 16.0GiB)

Swap Usage — source.swap_percent

Output percent

Network

Network Download — source.net_down

Output number (KiB/s)
interface string — auto or iface name (e.g., wlan0, eth0)

Network Upload — source.net_up

Output number (KiB/s)
interface string — auto or iface name

Total Downloaded — source.net_total_down

Output text (cumulative, human-formatted)
interface string — auto or iface name

Total Uploaded — source.net_total_up

Output text (cumulative, human-formatted)
interface string — auto or iface name

Wi-Fi Network Name — source.wifi_ssid

Output text (SSID; empty when not wireless / not associated)
interface string — auto or iface name

Wi-Fi Signal Quality — source.wifi_signal

Output percent
interface string — auto or iface name

auto resolves the first “up” interface under /sys/class/net at runtime (same approach as batcomputer.lua).

System info

Uptime — source.uptime

Output text
format enum — short / long (default short)

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 (default 1)

Top Process (CPU %) — source.top_process_cpu

Output percent
rank enum 1…10 (default 1)

Top Process (RAM %) — source.top_process_mem

Output percent
rank enum 1…10 (default 1)

Conky ranks the top list by CPU regardless of which field you print; pair Name / CPU / RAM at the same rank for a “what’s eating my machine” row.

Time

Greeting — source.greeting

Output text
Notes Good Morning / Good Afternoon / Good Evening / Good Night from current hour (computed in Lua; no external script).

Date / Time — source.datetime

Output text
strftime_format string (default %A, %B %d %H:%M)

Sensors (external scripts; often need lm-sensors / GPU tools / smartctl)

All of these share Polling props:
poll_mode enum — execi (Conky ${execi}) or daemon (background loop + cache; zero-stutter)
poll_interval int seconds

CPU Temperature — source.cpu_temp

Output celsius
script_family cpu_sensors → key cpu_temp
chip_pattern regex for sensors -u chip names (default coretemp/k10temp/cpu_thermal/zenpower)
poll_interval default 3

GPU Utilization — source.gpu_util

Output percent
script_family gpu_stats → key gpu_util
amd_drm_card optional AMD DRM card override (blank = auto)
poll_interval default 2

GPU Temperature — source.gpu_temp

Output celsius
script_family gpu_stats → key gpu_temp
amd_drm_card optional AMD DRM card override
poll_interval default 2

GPU VRAM Used (MB) — source.gpu_vram_used

Output number
script_family gpu_stats → key gpu_vram_used
amd_drm_card optional AMD DRM card override
poll_interval default 2

GPU VRAM Total (MB) — source.gpu_vram_total

Output number
script_family gpu_stats → key gpu_vram_total
amd_drm_card optional AMD DRM card override
poll_interval default 2

NVIDIA via nvidia-smi; AMD via sysfs gpu_busy_percent / hwmon. Nodes in the same script_family share one generated script and one cache file.

Disk Temperature — source.disk_temp

Output celsius
script_family disk_sensors → key disk_temp
device path (default /dev/sda)
poll_interval default 30
Notes Usually needs permission to query the drive (smartctl).

Fan Speed (RPM) — source.fan_rpm

Output number
script_family fan_sensors → key fan_rpm
poll_interval default 3
Notes First non-zero hwmon*/fan1_input under /sys/class/hwmon.

Network (external)

Public IP Address — source.public_ip

Output text
script_family public_ip → key ip
poll_mode default daemon
poll_interval default 1800 (30 min; min 60)
Notes icanhazip.com, fallback ifconfig.me. Requires curl.

Weather (script + cache; needs network / curl)

Shared props on all three:
fallback_location string — city / airport / City+State if IP geolocation fails
poll_mode default daemon
poll_interval default 1800 (min 60)
script_family weather

Weather Condition — source.weather_condition

Output text (e.g. Partly cloudy)
key condition

Weather Category — source.weather_category

Output category
key category
Notes Token: clear / cloud / overcast / fog / wind / rain / storm / snow / cold / hot / dust / unknown. Wire into Weather Icon or image threshold swaps.

Weather Temp (F) — source.weather_temp_f

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

Media (needs playerctl + active player)

Shared props:
player string (default spotify — whatever playerctl -l lists)
poll_mode execi / daemon
poll_interval default 2
script_family nowplaying

Track Title — source.nowplaying_title → text (key title)

Track Artist — source.nowplaying_artist → text (key artist)

Track Album — source.nowplaying_album → text (key album)

Playback Status — source.nowplaying_status → category (key status: playing / paused / stopped)

Playback Progress % — source.nowplaying_progress → percent (key progress_pct)

Empty when nothing is playing (no stale data).

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; copied into the theme’s scripts/ at Build. Ignored when Inline script is non-empty
script_body Inline script (monospace editor). If non-empty, written to scripts/ at Build and wins over Script path
output_kind enum — how Studio treats the stdout value for binding
poll_mode execi or daemon
poll_interval default 5
Notes Print a single line to stdout (or simple key=value for structured use). Prefer Inline script when fixing a legacy import. Each instance is unique (not family-shared). In daemon mode the builder wraps it with the same flock + atomic cache harness.

Behaviour: Script stdout is the source value. Daemon mode uses background polling + cache; execi uses Conky-native intervals. Missing/failed scripts yield empty or zero depending on kind.

Wiring tips

Source kind Typical visual targets
percent Arc gauge, Bar, Segmented Gauge, LED Dot, History Graph, Sparkline
celsius Text (via format), gauges after Map Range / Scale to 0–100
text Text Label, String Format logic
category Conditional / Pick / image swaps / Weather Icon
number Bars after scaling, text via String Format or Scale

Native sources need no background script. External sources that share a script_family are deduplicated into one script + one cache file at build time. Daemon-mode families (and every Album Art node) get a polling loop in start.sh.

Clone this wiki locally