LEDSpicer can be installed using several methods:

1. Interactive Install Script (recommended) - Guided setup with automatic dependency handling
2. Install from Repository - Pre-built packages for supported distributions
3. Manual CMake Build - For advanced users who need full control over the build

Note: Regardless of installation method, you will need to configure ledspicer.conf and set up profiles for your hardware. You can do this manually (see Configuration) or use LEDSpicer UI (under development).

The install script provides a guided installation experience with whiptail dialogs.

• ✅ Choose exactly which device plugins to enable
• ✅ Customize installation paths
• ✅ Handles dependencies automatically
• ⏱️ Requires compilation time

• whiptail (pre-installed on Debian/Ubuntu)
• git (to clone the repository)

git clone https://github.com/meduzapat/LEDSpicer.git
cd LEDSpicer
./install.sh

The script guides you through:

1. Platform Selection - x86_64, ARM32, ARM64, or MiSTer FPGA
2. Device Selection - Choose which LED controllers to enable
3. Audio Backend - PulseAudio and/or ALSA for audio-reactive animations
4. Installation Paths - Customize prefix and config directories
5. Dependency Installation - Automatically detects and installs missing packages
6. Post-Install Configuration:
   • Creates skeleton configuration file
   • Installs udev rules for USB permissions (if requested)
   • Updates systemd service with correct user ID (if running as non-root)

The script automatically translates package names for:

• apt (Debian/Ubuntu/Raspbian)
• dnf (Fedora/RHEL)
• pacman (Arch Linux/Manjaro)
• zypper (openSUSE)

To upgrade an existing installation:

cd LEDSpicer
git pull
./install.sh

The script detects existing CMake settings and offers to reuse them.

Pre-built packages are available for several Linux distributions through community repositories.

• ✅ Fastest installation (pre-built binaries)
• ✅ Automatic updates with system
• ⚠️ Raspberry Pi GPIO plugin not available (missing pigpio library)

Available plugins:

The PPA provides packages for Ubuntu and compatible Debian-based systems.

Supported distributions: Ubuntu (all active LTS releases), Linux Mint, Pop!_OS, Raspbian/Raspberry Pi OS

sudo add-apt-repository ppa:meduzapat/ledspicer
sudo apt update
sudo apt install ledspicer ledspicer-<plugin>

Example installing with Ultimate I/O and PacLed64:

sudo apt install ledspicer ledspicer-ultimateio ledspicer-pacled64

For systems without add-apt-repository:

echo "deb https://ppa.launchpadcontent.net/meduzapat/ledspicer/ubuntu $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/ledspicer.list
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 
sudo apt update
sudo apt install ledspicer

For more information, visit the PPA page.

Note: On Raspbian/Raspberry Pi OS, the RaspberryPi GPIO device plugin is included if libpigpio is available.

The COPR repository provides packages for Fedora and compatible RPM-based distributions.

Supported distributions: Fedora 39+, CentOS Stream, RHEL

sudo dnf copr enable meduzapat/ledspicer
sudo dnf install ledspicer ledspicer-<plugin>

Example installing with Ultimate I/O and PacLed64:

sudo dnf install ledspicer ledspicer-ultimateio ledspicer-pacled64

For more information, visit the COPR page.

Note: The RaspberryPi device plugin is not available on Fedora COPR due to libpigpio availability.

LEDSpicer is available in the Arch User Repository (AUR).

Supported distributions: Arch Linux, Manjaro, EndeavourOS, Garuda Linux

Using an AUR helper (e.g., yay, paru):

yay -S ledspicer ledspicer-<plugin>

Example installing with Ultimate I/O and PacLed64:

yay -S ledspicer ledspicer-ultimateio ledspicer-pacled64

Or manually:

git clone https://aur.archlinux.org/ledspicer.git
git clone https://aur.archlinux.org/ledspicer-ultimateio.git
git clone https://aur.archlinux.org/ledspicer-pacled64.git
cd ledspicer && makepkg -si && cd ..
cd ledspicer-ultimateio && makepkg -si && cd ..
cd ledspicer-pacled64 && makepkg -si

For more information, visit the AUR package page.

Note: On Arch Linux ARM, the RaspberryPi GPIO plugin is available when pigpio is installed.

For users who prefer direct control over the build process or need custom configurations.

• ✅ Full control over all build options
• ✅ Can enable development/debug modes
• ✅ Required for contributing to the project
• ⏱️ Requires compilation time
• ⚠️ Manual dependency management

Debian/Ubuntu:

sudo apt install build-essential cmake pkg-config libtinyxml2-dev libusb-1.0-0-dev
# Optional:
sudo apt install libpulse-dev libasound2-dev

git clone https://github.com/meduzapat/LEDSpicer.git
cd LEDSpicer

Or download from releases.

mkdir build && cd build
cmake .. [OPTIONS]

Installation Paths:

Build Flags:

LED Controllers:

Audio Backends:

Special Modes:

Example:

cmake .. \
  -DCMAKE_INSTALL_PREFIX=/usr \
  -DCMAKE_INSTALL_SYSCONFDIR=/etc \
  -DENABLE_ULTIMATEIO=ON \
  -DENABLE_PACLED64=ON \
  -DENABLE_PULSEAUDIO=ON

Production Example:

cmake .. \
  -DCMAKE_INSTALL_PREFIX=/usr \
  -DCMAKE_INSTALL_SYSCONFDIR=/etc \
  -DCMAKE_CXX_FLAGS='-g0 -O3' \
  -DENABLE_ULTIMATEIO=ON \
  -DENABLE_PULSEAUDIO=ON

Development Example:

cmake .. \
  -DCMAKE_INSTALL_PREFIX=/usr/local \
  -DCMAKE_INSTALL_SYSCONFDIR=/etc \
  -DCMAKE_CXX_FLAGS='-g3 -O0 -Wall' \
  -DENABLE_ULTIMATEIO=ON \
  -DENABLE_TESTS=ON \
  -DENABLE_DRY_RUN=ON

make -j$(nproc)
sudo make install
sudo ldconfig

Note: If you used the interactive install script, most of these steps are handled automatically based on your selections. The information below is provided for advanced users and those who installed from repositories or built manually.

Only required if running the daemon as a non-root user.

Add your user to required groups:

# USB device access
sudo usermod -aG users $USER
sudo usermod -aG input $USER

# Serial devices (Adalight)
sudo usermod -aG dialout $USER

# Raspberry Pi GPIO
sudo usermod -aG gpio $USER

Log out and back in for group changes to take effect.

Only required if running the daemon as a non-root user.

The interactive install script configures udev rules if requested. For manual installation or repository packages, the rules file is located at:

• Installed location: /usr/share/doc/ledspicer/examples/21-ledspicer.rules

To install manually:

sudo cp /usr/share/doc/ledspicer/examples/21-ledspicer.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules
sudo udevadm trigger

Back up any existing configuration first:

sudo cp /etc/ledspicer.conf /etc/ledspicer.conf.bak

Create or copy the configuration file:

sudo cp /usr/share/doc/ledspicer/examples/ledspicer.conf /etc/

Edit /etc/ledspicer.conf with your hardware configuration. See Configuration for details.

The installation process creates a systemd service file ready to use. The service file is located at:

• /usr/lib/systemd/system/ledspicerd.service (or /lib/systemd/system/ on some systems)

Managing the service:

# Start the daemon
sudo systemctl start ledspicerd

# Stop the daemon
sudo systemctl stop ledspicerd

# Restart the daemon
sudo systemctl restart ledspicerd

# Enable at boot
sudo systemctl enable ledspicerd

# Disable at boot
sudo systemctl disable ledspicerd

# Check status
sudo systemctl status ledspicerd

PulseAudio users: If using PulseAudio, you may need to update the user ID in the service file if your UID differs from 1000:

# Check your user ID
id -u

# Edit service file if UID differs from 1000
sudo nano /usr/lib/systemd/system/ledspicerd.service
# Change /run/user/1000/ to /run/user/YOUR_UID/

sudo systemctl daemon-reload

Verify installation:

# Version info
ledspicerd -v

# Dump configuration
ledspicerd -d

# Test a profile
ledspicerd -p default

From source build (in the build directory):

sudo make uninstall

From PPA (Ubuntu/Debian):

sudo apt remove ledspicer
sudo add-apt-repository --remove ppa:meduzapat/ledspicer

From COPR (Fedora):

sudo dnf remove ledspicer
sudo dnf copr remove meduzapat/ledspicer

From AUR (Arch Linux):

sudo pacman -R ledspicer

LEDSpicer requires TinyXML2 version 6.0 or higher:

pkg-config --modversion tinyxml2

If your distribution provides an older version, compile TinyXML2 from source.

The PulseAudio plugin requires access to the user's PulseAudio socket. The systemd service file includes configuration for this, but ensure:

1. The userId in ledspicer.conf matches your user
2. The service file references the correct /run/user/UID/pulse/native path

If you encounter permission errors:

Sorry, you don't have permission to run this program.
Try running as root, e.g. precede the command with sudo.

Create a udev rule for /dev/mem access:

sudo nano /etc/udev/rules.d/99-dev-mem.rules

Add:

SUBSYSTEM=="mem", KERNEL=="mem", GROUP="gpio", MODE="0660"

Reload rules:

sudo udevadm control --reload-rules
sudo udevadm trigger

1. Verify udev rules are installed
2. Check device is connected: lsusb
3. Verify permissions: ls -la /dev/bus/usb/
4. Try replugging the device after installing udev rules

Missing CMake:

sudo apt install cmake

Missing pkg-config:

sudo apt install pkg-config

Library not found:

Check that all required development packages are installed. The interactive install script handles this automatically.