================================================================================
UNIFIED TECHNICAL DOSSIER: DEPLOYMENT & CUSTOMIZATION OF PEPPYMETER
================================================================================
TARGET: Orange Pi Zero 2W (Allwinner aarch64 Architecture)
OS: DietPi (Debian 13 Minimal)
USER: root (No sudo privileges required)
PRIMARY DISPLAY: Wide HDMI Screen (1280x400 / Waveshare 7.9" Touchscreen)
VALIDATED CONFIGURATION: Player 2 (Pure Audio without Kodi, Material Skin Control)
================================================================================

--------------------------------------------------------------------------------
SECTION 1: AUDIO PIPELINE PREPARATION AND COMPILATION (PEPPYALSA)
--------------------------------------------------------------------------------
Step 1.1: Installation of core dependencies (Debian 13 PEP 668 Workaround)
Native OS Python and graphical packages are installed directly via 'apt' 
to bypass the PEP 668 security restriction and secure the console execution:
apt update
apt install -y git build-essential autoconf libtool libasound2-dev libfftw3-dev python3-pygame python3-requests python3-pip python3-pil python3-urllib3 xserver-xorg xinit xinput x11-xserver-utils

Step 1.2: Downloading and compiling PeppyALSA
cd /home/dietpi
git clone https://github.com/project-owner/peppyalsa.git
cd peppyalsa
aclocal && libtoolize
autoconf && automake --add-missing
./configure && make
make install

Step 1.3: Creation of the named pipe (FIFO)
mkfifo /var/tmp/peppyfifo
chmod 777 /var/tmp/peppyfifo

--------------------------------------------------------------------------------
SECTION 2: AUDIO CONFIGURATION AND CONSOLE VALIDATION
--------------------------------------------------------------------------------
Step 2.1: Deployment of the ALSA matrix (/etc/asound.conf)
File: /etc/asound.conf

pcm.softvol_master {
type softvol
slave.pcm "peppyalsa_output"
control {
name "Master"
card 0 
}
}

pcm.peppyalsa_output {
type meter
slave.pcm "hw:0,0" 
scopes.0 peppyalsa 
}

pcm.!default {
type plug
slave.pcm "softvol_master"
}

ctl.!default {
type hw
card 0
}

pcm_scope.peppyalsa {
type peppyalsa
decay_ms 250 
meter "/var/tmp/peppyfifo" 
meter_max 100
meter_show 1
}

pcm_scope_type.peppyalsa {
lib /usr/local/lib/libpeppyalsa.so
}

Step 2.2: Squeezelite Routing (Standard DietPi Setup)
File: /etc/default/squeezelite
ARGS='-W -C 5 -n DietPi-Squeezelite -o default'

Apply the changes:
systemctl restart squeezelite

Step 2.3: Audio validation test via console
cd /home/dietpi/peppyalsa/src
gcc peppyalsa-client.c -o peppyalsa-client
./peppyalsa-client /var/tmp/peppyfifo
(Exit with Ctrl+C after confirming the animation of L and R level lines)

--------------------------------------------------------------------------------
SECTION 3: VISUAL CONFIGURATION & HARDWARE SETTINGS (config.txt)
--------------------------------------------------------------------------------
Step 3.1: Deployment of PeppyMeter
cd /home/dietpi
git clone https://github.com/project-owner/PeppyMeter.git

Step 3.2: Main validated configuration file (Initial Random Mode)
File: /home/dietpi/PeppyMeter/config.txt

[current]
meter = random
random.meter.interval = 20
base.folder =
meter.folder = 1280x400
screen.width = 1280
screen.height = 400
exit.on.touch = True
stop.display.on.touch = False
output.display = True
output.serial = False
output.i2c = False
output.pwm = False
output.http = False
use.logging = False
use.cache = True
cache.size = 20
frame.rate = 30

[data.source]
type = pipe
polling.interval = 0.04
pipe.name = /var/tmp/peppyfifo
volume.constant = 80.0
volume.min = 0.0
volume.max = 100.0
volume.max.in.pipe = 100.0
step = 6
mono.algorithm = average
stereo.algorithm = new
smooth.buffer.size = 4

[sdl.env]
framebuffer.device = /dev/fb0
mouse.device = /dev/input/event0
mouse.driver = TSLIB
mouse.enabled = True
video.driver = dummy
video.display = :0
double.buffer = False
no.frame = False

[serial.interface]
device.name = /dev/serial0
baud.rate = 9600
include.time = False
update.period = 0.1

[i2c.interface]
port = 1
left.channel.address = 0x21
right.channel.address = 0x20
output.size = 10
update.period = 0.1

[pwm.interface]
frequency = 500
gpio.pin.left = 24
gpio.pin.right = 25
update.period = 0.1

[http.interface]
target.url = http://localhost:8000/vumeter
update.period = 0.033

[web.server]
http.port = 8001

--------------------------------------------------------------------------------
SECTION 4: AUTOMATED SCRIPT AND SOCKET CLI SWITCH LOGIC (PORT 9090)
--------------------------------------------------------------------------------
Step 4.1: Creation of the background monitoring script (Watcher)
This script uses the direct Socket CLI protocol (Port 9090) of LMS to query the 
real identifier '00:00:00:00:00:00' generated by DietPi-Squeezelite, decodes the 
hexadecimal web string 'mode%3Aplay', and injects itself directly into the active X11 session (:0).

File: /home/dietpi/PeppyMeter/fda_startpeppy.py

#!/usr/bin/env python3
import os
import subprocess
import time
import socket
from urllib.parse import unquote

LMS_IP = "192.168.1.53"
LMS_CLI_PORT = 9090
SQUEEZELITE_PLAYER_ID = "00:00:00:00:00:00"
PROG_PATH = "/home/dietpi/PeppyMeter/peppymeter.py"

prevstat = "OFF"

def get_squeezelite_info_cli():
try:
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
s.settimeout(1.5)
s.connect((LMS_IP, LMS_CLI_PORT))

cmd = f"{SQUEEZELITE_PLAYER_ID} status\n"
s.sendall(cmd.encode('utf-8'))
response = s.recv(4096).decode('utf-8').strip()
s.close()

response_clean = response.lower()

if "mode%3aplay" in response_clean or "mode:play" in response_clean:
mode = "play"
else:
mode = "pause"

power = 1
if "power%3a0" in response_clean or "power:0" in response_clean:
power = 0

print(f"[DEBUG CLI] Real Analysis -> Mode : '{mode}' | Power : {power}")
return {"play_status": mode, "power": power}

except Exception as e:
print(f"[DEBUG CLI] CLI Communication Error: {e}")
return None

def graph_monitor():
global prevstat
player_info = get_squeezelite_info_cli()

if player_info is not None:
status = player_info['play_status']
power = player_info['power']

if status == "play" and power == 1 and prevstat != "ON":
print("[ACTION] -> PLAY DETECTED! Immediate launch of PeppyMeter...")
prevstat = "ON"
time.sleep(0.5)
cmd = "DISPLAY=:0 XAUTHORITY=/root/.Xauthority /usr/bin/python3 /home/dietpi/PeppyMeter/peppymeter.py"
subprocess.Popen(cmd, shell=True)

elif (status != "play" or power == 0) and prevstat == "ON":
print("[ACTION] -> PAUSE DETECTED! Closing and returning to Material Skin...")
prevstat = "OFF"
subprocess.run(["pkill", "-f", "peppymeter.py"])

def main():
print("[SYSTEM] Active monitoring synchronized with your LMS status...")
while True:
graph_monitor()
time.sleep(1.0)

if __name__ == "__main__":
try:
main()
except KeyboardInterrupt:
pass

Step 4.2: Secure script execution permissions
chmod +x /home/dietpi/PeppyMeter/fda_startpeppy.py

--------------------------------------------------------------------------------
SECTION 5: SYSTEMD AUTOMATION & X11 GRAPHICAL PERMISSIONS
--------------------------------------------------------------------------------
Step 5.1: Declaration of graphical environment variables (DISPLAY)
File: /etc/systemd/system/fda_startpeppy.service

[Unit]
Description=LMS Monitor for Auto PeppyMeter Switch (Pure Audio)
After=network-online.target dietpi-postboot.target squeezelite.service
Wants=network-online.target

[Service]
Type=simple
User=root
Group=root
WorkingDirectory=/home/dietpi/PeppyMeter
Environment=DISPLAY=:0
Environment=XAUTHORITY=/root/.Xauthority
ExecStart=/usr/bin/python3 /home/dietpi/PeppyMeter/fda_startpeppy.py
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Step 5.2: Registering and enabling the system service
systemctl daemon-reload
systemctl enable fda_startpeppy.service
systemctl restart fda_startpeppy.service

Step 5.3: Authorize local access to the X11 server (Mandatory for root display)
Execute once in the console:
DISPLAY=:0 xhost +local:

--------------------------------------------------------------------------------
SECTION 6: CUSTOMIZATION AND NEEDLE TUNING
--------------------------------------------------------------------------------
To adjust sensitivity:
Modify 'meter_max 100' in /etc/asound.conf (pcm_scope.peppyalsa section).
* Increase needle height: Decrease the value (e.g., 80)
* Decrease needle height: Increase the value (e.g., 120)
Apply changes via: systemctl restart squeezelite

To adjust speed and smoothness:
1. Return-to-zero speed (in /etc/asound.conf):
Modify 'decay_ms 250' (time in ms). Lower = more responsive/snappy.
Apply changes via: systemctl restart squeezelite
2. Graphical smoothing (in /home/dietpi/PeppyMeter/config.txt):
Modify 'smooth.buffer.size = 4' ([data.source] section). Lower = more raw.

--------------------------------------------------------------------------------
SECTION 7: CUSTOM THEME INTEGRATION (DAVUMETER VINTAGE CHAMPAGNE)
--------------------------------------------------------------------------------
Step 7.1: Image transfer from a Linux PC (Raw Dropbear Protocol)
Execute this command from your Linux PC terminal (inside your images folder) 
to push your asset files straight into the PeppyMeter catalogue on the Orange Pi:
tar cf - davumeter-*.png | ssh root@192.168.1.53 "tar xf - -C /home/dietpi/PeppyMeter/1280x400/"

Step 7.2: Declaration of the needle pivot geometric matrix
Add to the very end of the Orange Pi themes description file:
nano /home/dietpi/PeppyMeter/1280x400/meters.txt

[davumeter]
meter.type = circular
channels = 2
ui.refresh.period = 0.033
bgr.filename = davumeter-bgr.png
fgr.filename = davumeter-fgr.png
indicator.filename = davumeter-needle.png
steps.per.degree = 2
start.angle = 42
stop.angle = -42
distance = 160
left.origin.x = 312
left.origin.y = 380
right.origin.x = 952
right.origin.y = 380
meter.x = 0
meter.y = 0
screen.bgr =

Step 7.3: Lock the interface to your custom creation
Modify the main configuration file:
nano /home/dietpi/PeppyMeter/config.txt

In the [current] section, replace 'random' mode with your VU-meter name:
meter = davumeter

Step 7.4: Restart the monitoring service to validate the layout display
systemctl restart fda_startpeppy.service
================================================================================