From fa1ef980b1509761b1e3e78e40ae100a5ce21c09 Mon Sep 17 00:00:00 2001 From: nicholai Date: Mon, 8 Sep 2025 04:14:28 -0600 Subject: [PATCH] Add README with setup, dependencies, modules, and usage --- README.md | 149 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..9e24329 --- /dev/null +++ b/README.md @@ -0,0 +1,149 @@ +# Arch Waybar Configuration + +Opinionated Waybar setup tailored for Hyprland on Arch Linux. Includes: +- Hyprland workspaces/window modules +- Pywal-driven colors via a symlinked colors.css +- A weather widget powered by wttr.in (Python script) +- Multimedia controls (audio, mic), battery, temperature, network, bluetooth, and clock + +Repository: https://git.biohazardvfx.com/Nicholai/arch-waybar + +## Repository Structure + +``` +~/.config/waybar/ +├── colors.css # symlink to ~/.cache/wal/colors-waybar.css (generated by Pywal) +├── config.jsonc # main Waybar configuration +├── style.css # Waybar CSS (imports colors.css) +└── scripts/ + └── waybar-wttr.py # weather script (wttr.in) for custom/weather module +``` + +## Requirements + +Core: +- Waybar (with Hyprland module support) +- Hyprland (for `hyprland/*` modules) or adjust modules if using Sway/etc. +- JetBrainsMono Nerd Font (for glyphs/icons) +- Python 3 + `requests` (for weather) + - Install: `pip install --user requests` + +Utilities: +- pamixer (volume + mic controls) +- blueman (for `blueman-manager` launcher) +- pywal (to generate the wal CSS that colors.css links to) + +Optional (if enabling commented actions in config): +- asusctl (power profiles) +- brightnessctl (backlight block currently commented) + +## Installation + +1) Clone to your Waybar config directory: +``` +git clone https://git.biohazardvfx.com/Nicholai/arch-waybar.git ~/.config/waybar +``` + +2) Fonts +- Install JetBrainsMono Nerd Font and ensure Waybar can use it. + +3) Colors via Pywal +- This setup expects Pywal to generate `~/.cache/wal/colors-waybar.css`. +- `colors.css` in this repo is a symlink pointing to an absolute path (`/home/Nicholai/.cache/wal/colors-waybar.css`). + - On another machine or a different username, update the symlink: + ``` + cd ~/.config/waybar + rm -f colors.css + ln -s ~/.cache/wal/colors-waybar.css colors.css + ``` + - Or, edit `style.css` to import a different palette file. + +4) Python dependency for weather +``` +pip install --user requests +``` + +5) Launch or reload Waybar +- If Waybar is already running: + - Standard reload: `pkill -SIGUSR2 waybar` + - Or restart your session bar (depends on your launcher/service setup) + +## Modules Overview (config.jsonc) + +Enabled modules: +- Left: + - `clock` (12-hour format) + - `custom/weather` (from scripts/waybar-wttr.py; tooltip shows forecast) + - `custom/wallpaper` (on-click: ~/scripts/pywal/wallpapermenu.sh — external) + - `hyprland/window` (current window title) + +- Center: + - `hyprland/workspaces` + - Custom icons + - Persistent workspaces for output `Virtual-1` + +- Right: + - `network` + - `bluetooth` (left-click opens blueman-manager) + - `temperature` (thermal zone 1, Fahrenheit display; critical threshold set) + - `custom/power_profile` (watch + signal hook; on-click options commented) + - `battery` + - `backlight` (block fully commented out) + - `pulseaudio` (speakers: click toggles mute; scroll adjusts volume) + - `pulseaudio#microphone` (mic: click toggles mute; scroll adjusts gain) + +Notes: +- `custom/wallpaper` uses `~/scripts/pywal/wallpapermenu.sh`, which is not part of this repo. Provide your own script or remove/disable the module. +- `custom/power_profile` is configured to refresh on RTMIN+8 signal; changing profiles via `asusctl` is commented. Uncomment and install `asusctl` if needed. +- `temperature` uses thermal zone 1; adjust per your hardware. + +## Styling (style.css) + +- Imports `colors.css`, which is expected to be generated by Pywal. +- Uses JetBrainsMono Nerd Font; set globally in the CSS. +- Blocks have semi-transparent backgrounds and rounded corners. +- Active/hover/focused styles for workspaces customized. +- Theming expects Wal-provided variables like `@background`, `@colorX`. + +If you do not use Pywal, replace the import and variables with your preferred palette. + +## Weather Script (scripts/waybar-wttr.py) + +- Fetches JSON from `https://wttr.in/?format=j1` +- Outputs a JSON payload that Waybar consumes for the `custom/weather` module: + - `text`: compact current condition + feels-like + - `tooltip`: multi-line details: current, wind, humidity, plus daily and hourly forecast + +Manual test: +``` +python ~/.config/waybar/scripts/waybar-wttr.py +``` +If it prints a JSON string, the module should render in Waybar. + +Caveats: +- Network access to wttr.in is required and may be rate-limited. +- Python `requests` must be installed. +- The script currently references a `format_time()` helper in one place; ensure it exists or remove references if you customize the script. The shipped config works as-is on machines where this script is already in use. + +## Troubleshooting + +- Colors not applying: + - Ensure Pywal has generated `~/.cache/wal/colors-waybar.css`. + - Ensure `colors.css` symlink points to the correct wal file for your user. +- Missing icons: + - Verify Nerd Font install and that Waybar uses it. +- Weather not loading: + - Check `pip show requests` and network connectivity. + - Run the script manually to inspect any exceptions. +- Bluetooth manager not opening: + - Install `blueman` and verify `blueman-manager` is on PATH. + +## Customization Tips + +- To adjust the clock format, edit the `clock.format` string in `config.jsonc`. +- To change workspace icons or persistence, modify `hyprland/workspaces.format-icons` and `persistent-workspaces`. +- To enable volume/backlight/power-profile click actions, uncomment the relevant sections and install required tools. + +## License + +No license specified. Add one if you intend to share or redistribute.