pineNoteShell/pinenote-shell

PineNote Shell Widget

A fullscreen GTK widget designed for Pine64 PineNote running Arch Linux with Hyprland, controllable via hyprgrass gestures.

Overview

This Astal-based GTK application provides:

• Screen rotation (portrait/landscape)
• Display brightness control (100%, 75%, 25%, 0% steps)
• Power operations (suspend, shutdown, reboot)
• Quick launch shortcuts for terminal, browser, and e-reader
• Display refresh functionality
• Audio waveform switching

Requirements

• OS: Arch Linux with Hyprland
• Desktop Environment: Astal/GJS environment
• Dependencies: GJS, GTK 4, hyprgrass
• Display: Pine64 PineNote (or any compatible monitor)

Installation

Prerequisites

aur install ags-node
# or for Arch Linux:
sudo pacman -S gjs

Clone and Setup

cd ~/projects/pineNoteShell
# Project already set up in pinenote-shell/

# Install dependencies
npm install --prefix ./pinenote-shell
cd pinenote-shell && npm install

# Make widget executable
chmod +x ./src/main.js
gjs --set-mode=auto-start

Hyprland Configuration

Add the following to your ~/.config/hypr/hyprgrass.conf:

[gesture:toggle_widget]
hotkeys = [Mod1, T]
shorthand = "pinch open"
actions = [
    {
        command = "exec ags -t pinenote-shell",
        timeout = 300,
target = "window:pinenote-fullscreen"
    }
]

[gesture:brightness_up]
hotkeys = [Mod1, B]
shorthand = "swipe up"
actions = [
    {
        command = "exec ags --js-evaluate 'globalThis.widget.brightnessController.setBrightness(100)'",
        timeout = 300,
target = "window:pinenote-fullscreen"
    }
]

[gesture:brightness_down]
hotkeys = [Mod1, V]
shorthand = "swipe down"
actions = [
    {
        command = "exec ags --js-evaluate 'globalThis.widget.brightnessController.setBrightness(0)'",
        timeout = 300,
target = "window:pinenote-fullscreen"
    }
]

Additional Gestures

Add more gestures for other controls:

[gesture:rotate_landscape]
hotkeys = [Mod1, R]
shorthand = "swipe left"
actions = [
    {
        command = "exec ags --js-evaluate 'globalThis.widget.screenRotator.rotateTo(\"landscape\")'",
        timeout = 300,
target = "window:pinenote-fullscreen"
    }
]

[gesture:launch_terminal]
hotkeys = [Mod1, T]
shorthand = "double tap left"
actions = [
    {
        command = "exec ags --js-evaluate 'globalThis.widget.launcherManager.launch(\"terminal\")'",
        timeout = 300,
target = "window:pinenote-fullscreen"
    }
]

Usage

Basic Controls

1. Open/Close: Activate with hyprgrass gesture (see configuration)
2. Screen Rotation: Tap landscape/portrait icons to rotate display
3. Brightness: Click brightness level buttons or use gestures in config
4. System Actions: Use suspend/shutdown buttons for power operations
5. Launch Apps: Click terminal, browser, or e-reader shortcuts

Advanced Features

• Waveform Switching: Use the waveform control to switch between audio output modes
• Display Refresh: Force display refresh with the refresh button
• Status Display: Monitor rotation and brightness levels in footer

Configuration

Custom Applications

Edit src/main.js and modify the LauncherManager.launch() method:

const launchers = {
    terminal: "alacritty",           // Your preferred terminal
    browser: "brave-browser",       // Or chromium/firefox/edge
    "e-reader": "calibre",         // Your e-reader application
};

Hyprland Integration

The widget uses hyprctl commands to communicate with:

• Screen rotation: Monitors current rotation via hyprland.active.monitor.rotation
• Display refresh: Uses hyprctl keyword reload for display updates
• Brightness: Controls through /sys/class/backlight/ interface

Styling

The widget uses CSS styling loaded from $HOME/.config/ags/style.css. You can customize the appearance by modifying this file or creating your own theme.

Common customization options:

• background-color: Change widget background
• border-radius, margin: Adjust widget borders and spacing
• Icon sets: Use different icon themes for better visual consistency

Troubleshooting

Widget Won't Appear

1. Check Astal installation: Ensure gjs and ags are installed correctly
2. Verify hyprgrass config: Make sure your gesture bindings are correct
3. Debug output: Run with gjs -d src/main.js to see console errors

Controls Not Working

1. Permission issues: Some operations may require appropriate permissions
2. Missing applications: Ensure your preferred terminal/browser exist
3. Hyprland compatibility: Test basic hyprctl commands manually first

Performance Issues

• The widget is designed to be lightweight and efficient
• For best performance on PineNote, consider reducing animation frequency
• Monitor system resources with htop or similar tools

Future Enhancements

Potential features for future development:

• Multi-monitor support
• Advanced brightness curves (not just discrete steps)
• Custom app launcher configuration
• Audio waveform visualization
• System monitoring widgets
• Integration with PineNote-specific settings

License

This project is provided as-is for your PineNote setup. Use responsibly and test changes before deploying to production hardware.