Luigi Deployment Automation Skill

This skill helps agents create automation scripts for deploying Luigi project modules to a Raspberry Pi Zero W. The skill focuses on generating bash scripts that handle dependencies, file deployment, and service configuration for any type of Luigi module (motion detection, environmental sensors, automation, etc.).

Important: This skill guides script CREATION, not direct execution. Agents should generate deployment scripts that users can review and run.

Scope

In Scope

•Luigi application deployment scripts
•Project-specific dependency installation
•File copying and permissions
•Service configuration and management
•Module deployment from this repository

Out of Scope

•OS installation
•Initial host setup (user creation, SSH configuration)
•General system hardening
•Network configuration

Target Environment

•Hardware: Raspberry Pi Zero W
•OS: Raspberry Pi OS Lite (32-bit) based on Debian 13 "Trixie"
•Init System: systemd (primary) with init.d compatibility
•Python: Python 3.x (python3 command)
•Audio: ALSA (aplay command)

Luigi Project Structure

The current Luigi repository contains:

•
motion-detection/mario/: Mario-themed motion detector module (example implementation)
- •mario.py: Python script using RPi.GPIO for motion detection
- •mario: init.d service script
- •mario-sounds.tar.gz: Audio files archive (~1.3MB, 10 WAV files)

Future Expansion: The project structure supports adding more modules for various use cases:

•Additional motion detection behaviors
•Environmental monitoring (temperature, humidity, light)
•Automation (relays, motors, LEDs)
•Security sensors (door/window, cameras)
•IoT integrations

Each module follows similar deployment patterns (Python script + service + resources).

Deployment Script Patterns

1. Complete Deployment Script Template

Generate a comprehensive deployment script for a Luigi module. This template can be adapted for any module type:

bash

#!/bin/bash
# deploy_{module-name}.sh - Deploy {module-name} Luigi module
# Usage: sudo ./deploy_{module-name}.sh

set -e  # Exit on error

# Color output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color

log_info() {
    echo -e "${GREEN}[INFO]${NC} $1"
}

log_warn() {
    echo -e "${YELLOW}[WARN]${NC} $1"
}

log_error() {
    echo -e "${RED}[ERROR]${NC} $1"
}

# Check if running as root
if [ "$EUID" -ne 0 ]; then
    log_error "Please run as root (use sudo)"
    exit 1
fi

# 1. Update package list
log_info "Updating package list..."
apt-get update

# 2. Install dependencies
log_info "Installing dependencies..."
apt-get install -y python3-rpi.gpio alsa-utils git

# 3. Create directories
log_info "Creating directories..."
mkdir -p /usr/share/sounds/mario
mkdir -p /opt/luigi

# 4. Clone repository (if not already present)
if [ ! -d "/opt/luigi/.git" ]; then
    log_info "Cloning Luigi repository..."
    git clone https://github.com/pkathmann88/luigi.git /opt/luigi
else
    log_info "Repository already exists, pulling latest..."
    cd /opt/luigi
    git pull
fi

# 5. Extract and deploy sound files
log_info "Deploying sound files..."
tar -xzf /opt/luigi/motion-detection/mario/mario-sounds.tar.gz -C /usr/share/sounds/mario/
chmod 644 /usr/share/sounds/mario/*.wav

# 6. Deploy Python script
log_info "Deploying Python script..."
cp /opt/luigi/motion-detection/mario/mario.py /usr/local/bin/mario.py
chmod 755 /usr/local/bin/mario.py

# 7. Deploy init.d service
log_info "Deploying service script..."
cp /opt/luigi/motion-detection/mario/mario /etc/init.d/mario
chmod 755 /etc/init.d/mario

# 8. Enable service
log_info "Enabling mario service..."
update-rc.d mario defaults

# 9. Start service
log_info "Starting mario service..."
service mario start

# 10. Verify deployment
log_info "Verifying deployment..."
sleep 2
if service mario status > /dev/null 2>&1; then
    log_info "✓ Service is running"
else
    log_warn "Service may not be running, check logs"
fi

if [ -f "/var/log/motion.log" ]; then
    log_info "✓ Log file created"
else
    log_warn "Log file not yet created"
fi

log_info "Deployment complete!"
log_info "Check status: sudo service mario status"
log_info "View logs: tail -f /var/log/motion.log"

2. Modular Script Pattern

For more complex deployments, generate separate scripts for each concern:

install_dependencies.sh:

bash

#!/bin/bash
# Install Luigi dependencies

set -e

apt-get update
apt-get install -y \
    python3-rpi.gpio \
    alsa-utils \
    git

# Verify installations
python3 -c "import RPi.GPIO" || exit 1
which aplay > /dev/null || exit 1

echo "Dependencies installed successfully"

deploy_files.sh:

bash

#!/bin/bash
# Deploy Luigi files

set -e

REPO_DIR="/opt/luigi"
SOUND_DIR="/usr/share/sounds/mario"

# Create directories
mkdir -p "$SOUND_DIR"

# Extract sounds
tar -xzf "$REPO_DIR/motion-detection/mario/mario-sounds.tar.gz" -C "$SOUND_DIR"
chmod 644 "$SOUND_DIR"/*.wav

# Deploy script
cp "$REPO_DIR/motion-detection/mario/mario.py" /usr/local/bin/mario.py
chmod 755 /usr/local/bin/mario.py

echo "Files deployed successfully"

setup_service.sh:

bash

#!/bin/bash
# Set up Mario service

set -e

REPO_DIR="/opt/luigi"

# Deploy service script
cp "$REPO_DIR/motion-detection/mario/mario" /etc/init.d/mario
chmod 755 /etc/init.d/mario

# Enable and start
update-rc.d mario defaults
service mario start

echo "Service configured and started"

3. Service Management Script

Generate a helper script for service operations:

bash

#!/bin/bash
# manage_mario.sh - Service management helper

OPERATION="${1:-status}"

case "$OPERATION" in
    start)
        sudo service mario start
        echo "Mario service started"
        ;;
    stop)
        sudo service mario stop
        echo "Mario service stopped"
        ;;
    restart)
        sudo service mario restart
        echo "Mario service restarted"
        ;;
    status)
        sudo service mario status
        ;;
    logs)
        tail -f /var/log/motion.log
        ;;
    enable)
        sudo update-rc.d mario defaults
        echo "Mario service enabled at boot"
        ;;
    disable)
        sudo update-rc.d mario remove
        echo "Mario service disabled at boot"
        ;;
    *)
        echo "Usage: $0 {start|stop|restart|status|logs|enable|disable}"
        exit 1
        ;;
esac

4. Update Script

Generate script for updating Luigi deployment:

bash

#!/bin/bash
# update_luigi.sh - Update Luigi to latest version

set -e

REPO_DIR="/opt/luigi"

echo "Stopping service..."
service mario stop

echo "Pulling latest changes..."
cd "$REPO_DIR"
git pull

echo "Redeploying files..."
cp motion-detection/mario/mario.py /usr/local/bin/mario.py
cp motion-detection/mario/mario /etc/init.d/mario

echo "Restarting service..."
service mario start

echo "Update complete!"
service mario status

5. Uninstall Script

Generate cleanup script:

bash

#!/bin/bash
# uninstall_luigi.sh - Remove Luigi deployment

set -e

echo "Stopping service..."
service mario stop || true

echo "Disabling service..."
update-rc.d mario remove || true

echo "Removing files..."
rm -f /etc/init.d/mario
rm -f /usr/local/bin/mario.py
rm -rf /usr/share/sounds/mario
rm -rf /opt/luigi

echo "Removing log file..."
rm -f /var/log/motion.log

echo "Luigi uninstalled successfully"

Service Integration Patterns

Init.d Service Script Structure

The Mario service uses the traditional init.d format. When creating or modifying services:

bash

#!/bin/sh
### BEGIN INIT INFO
# Provides:          mario
# Required-Start:    $remote_fs $syslog
# Required-Stop:     $remote_fs $syslog
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# Short-Description: Mario motion detection service
# Description:       Motion detection with Mario sound effects
### END INIT INFO

# Service implementation here

Key points for init.d scripts:

•Include LSB (Linux Standard Base) headers
•Support standard actions: start, stop, restart, status
•Use proper exit codes (0=success, 1=error)
•Implement proper PID file management
•Handle stop gracefully (create stop file, wait for process)

Systemd Unit File (Alternative)

For modern systemd integration, generate a unit file instead:

ini

# /etc/systemd/system/mario.service
[Unit]
Description=Mario Motion Detection Service
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/usr/local/bin
ExecStart=/usr/bin/python3 /usr/local/bin/mario.py
Restart=on-failure
RestartSec=10
StandardOutput=append:/var/log/motion.log
StandardError=append:/var/log/motion.log

[Install]
WantedBy=multi-user.target

Deployment commands for systemd:

bash

# Install unit file
cp mario.service /etc/systemd/system/
chmod 644 /etc/systemd/system/mario.service

# Reload systemd
systemctl daemon-reload

# Enable and start
systemctl enable mario.service
systemctl start mario.service

# Check status
systemctl status mario.service

Dependency Management

Core Luigi Dependencies

Always include these in deployment scripts:

bash

# Python GPIO library
apt-get install -y python3-rpi.gpio

# Audio playback
apt-get install -y alsa-utils

# Version control (for cloning/updating)
apt-get install -y git

Optional Dependencies

For enhanced functionality:

bash

# For audio format conversion
apt-get install -y sox

# For better logging
apt-get install -y rsyslog

# For cron-based maintenance
# (already included in base OS)

Python Package Management

If using pip for Python packages:

bash

# Install pip if needed
apt-get install -y python3-pip

# Install packages
pip3 install RPi.GPIO  # Alternative to apt package

Note: Prefer system packages (apt) over pip when available for better integration.

File Deployment Best Practices

Directory Structure

Standard locations for Luigi files:

code

/opt/luigi/                      # Repository clone
/usr/local/bin/mario.py         # Python script (executable)
/usr/share/sounds/mario/        # Sound files (read-only)
/etc/init.d/mario               # Service script
/var/log/motion.log             # Log file
/tmp/stop_mario                 # Stop signal file
/tmp/mario_timer                # Cooldown timer file

File Permissions

Set appropriate permissions in deployment scripts:

bash

# Executable scripts
chmod 755 /usr/local/bin/mario.py
chmod 755 /etc/init.d/mario

# Read-only data
chmod 644 /usr/share/sounds/mario/*.wav

# Log file (will be created by service)
touch /var/log/motion.log
chmod 644 /var/log/motion.log

Sound File Deployment

Extract and deploy sound files:

bash

# Create directory
mkdir -p /usr/share/sounds/mario

# Extract archive
tar -xzf mario-sounds.tar.gz -C /usr/share/sounds/mario/

# Set permissions
chmod 644 /usr/share/sounds/mario/*.wav

# Verify files
ls -l /usr/share/sounds/mario/

Configuration Management

Configuration File Standard

All Luigi modules MUST use configuration files in /etc/luigi/{module-path}/.

The configuration path follows the repository module structure:

•Module at motion-detection/mario/ → Config at /etc/luigi/motion-detection/mario/
•Module at sensors/temperature/ → Config at /etc/luigi/sensors/temperature/
•Module at automation/relay/ → Config at /etc/luigi/automation/relay/

Configuration File Format

Use simple INI-style .conf files with key=value format:

ini

# /etc/luigi/motion-detection/mario/mario.conf
# Mario Motion Detection Configuration

[GPIO]
SENSOR_PIN=23

[Timing]
COOLDOWN_SECONDS=1800
MAIN_LOOP_SLEEP=100

[Files]
SOUND_DIR=/usr/share/sounds/mario/
TIMER_FILE=/tmp/mario_timer
LOG_FILE=/var/log/motion.log

[Logging]
LOG_LEVEL=INFO
LOG_MAX_BYTES=10485760
LOG_BACKUP_COUNT=5

Deployment Pattern

Always include config file deployment in setup scripts:

bash

#!/bin/bash
# Deploy configuration file for a Luigi module

MODULE_PATH="motion-detection/mario"  # Adjust for each module
CONFIG_DIR="/etc/luigi/${MODULE_PATH}"
CONFIG_FILE="${CONFIG_DIR}/mario.conf"

# Create config directory matching module path
log_info "Creating configuration directory..."
mkdir -p "${CONFIG_DIR}"

# Deploy config file (from repository or inline)
log_info "Deploying configuration file..."
cat > "${CONFIG_FILE}" << 'EOF'
# Mario Motion Detection Configuration

[GPIO]
SENSOR_PIN=23

[Timing]
COOLDOWN_SECONDS=1800

[Files]
SOUND_DIR=/usr/share/sounds/mario/
LOG_FILE=/var/log/motion.log

[Logging]
LOG_LEVEL=INFO
EOF

# Set permissions (readable by all, writable by root)
chmod 644 "${CONFIG_FILE}"

log_info "Configuration deployed to ${CONFIG_FILE}"

Config File in Complete Deployment

Update the complete deployment script template to include config deployment:

bash

#!/bin/bash
# deploy_{module-name}.sh - Deploy Luigi module with configuration

set -e

# ... (logging functions, root check) ...

MODULE_PATH="motion-detection/mario"  # Adjust for each module

# 1. Update package list
log_info "Updating package list..."
apt-get update

# 2. Install dependencies
log_info "Installing dependencies..."
apt-get install -y python3-rpi.gpio alsa-utils

# 3. Create directories
log_info "Creating directories..."
mkdir -p /usr/share/sounds/mario
mkdir -p "/etc/luigi/${MODULE_PATH}"

# 4. Deploy configuration file
log_info "Deploying configuration..."
cat > "/etc/luigi/${MODULE_PATH}/mario.conf" << 'EOF'
[GPIO]
SENSOR_PIN=23

[Timing]
COOLDOWN_SECONDS=1800

[Files]
SOUND_DIR=/usr/share/sounds/mario/
LOG_FILE=/var/log/motion.log
EOF
chmod 644 "/etc/luigi/${MODULE_PATH}/mario.conf"

# 5. Deploy sound files
log_info "Deploying sound files..."
tar -xzf mario-sounds.tar.gz -C /usr/share/sounds/mario/

# 6. Deploy Python script
log_info "Deploying Python script..."
cp mario.py /usr/local/bin/
chmod 755 /usr/local/bin/mario.py

# 7. Deploy and start service
log_info "Deploying service..."
cp mario.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable mario.service
systemctl start mario.service

log_info "Deployment complete!"
log_info "Config file: /etc/luigi/${MODULE_PATH}/mario.conf"
log_info "Edit config and restart service: sudo systemctl restart mario.service"

Configuration Verification

Add config verification to post-deployment checks:

bash

# verify_deployment.sh - Include config file checks

log_info "Checking configuration..."
CONFIG_FILE="/etc/luigi/motion-detection/mario/mario.conf"
if [ -f "${CONFIG_FILE}" ]; then
    log_info "✓ Configuration file exists"
    
    # Verify it's readable
    if [ -r "${CONFIG_FILE}" ]; then
        log_info "✓ Configuration file is readable"
    else
        log_error "✗ Configuration file is not readable"
        ERRORS=$((ERRORS + 1))
    fi
    
    # Show configuration summary
    log_info "Configuration settings:"
    grep -E "^[A-Z_]+=|^\[" "${CONFIG_FILE}" | head -10
else
    log_error "✗ Configuration file missing: ${CONFIG_FILE}"
    ERRORS=$((ERRORS + 1))
fi

User Configuration Instructions

When generating README or documentation, include config editing instructions:

markdown

## Configuration

The Mario module is configured via `/etc/luigi/motion-detection/mario/mario.conf`.

### Changing Settings

1. Edit the configuration file:
   ```bash
   sudo nano /etc/luigi/motion-detection/mario/mario.conf

•
Modify desired settings (e.g., change cooldown period):
ini
```
[Timing]
COOLDOWN_SECONDS=900  # 15 minutes instead of 30
```
•
Restart the service to apply changes:
bash
```
sudo systemctl restart mario.service
```

Configuration Options

GPIO Section:

•SENSOR_PIN: GPIO pin number (BCM numbering) for PIR sensor

Timing Section:

•COOLDOWN_SECONDS: Minimum seconds between motion triggers

Files Section:

•SOUND_DIR: Directory containing sound files
•LOG_FILE: Path to log file

Logging Section:

•LOG_LEVEL: Logging verbosity (DEBUG, INFO, WARNING, ERROR)

code


## Testing and Verification

### Post-Deployment Checks

Include verification in deployment scripts:

```bash
#!/bin/bash
# verify_deployment.sh

ERRORS=0

# Check files exist
echo "Checking files..."
for FILE in /usr/local/bin/mario.py /etc/init.d/mario; do
    if [ ! -f "$FILE" ]; then
        echo "✗ Missing: $FILE"
        ERRORS=$((ERRORS + 1))
    else
        echo "✓ Found: $FILE"
    fi
done

# Check sound files
echo "Checking sound files..."
SOUND_COUNT=$(ls /usr/share/sounds/mario/*.wav 2>/dev/null | wc -l)
if [ "$SOUND_COUNT" -eq 10 ]; then
    echo "✓ All 10 sound files present"
else
    echo "✗ Expected 10 sound files, found $SOUND_COUNT"
    ERRORS=$((ERRORS + 1))
fi

# Check service
echo "Checking service..."
if service mario status > /dev/null 2>&1; then
    echo "✓ Service is running"
else
    echo "✗ Service is not running"
    ERRORS=$((ERRORS + 1))
fi

# Check log file
echo "Checking log file..."
if [ -f "/var/log/motion.log" ]; then
    echo "✓ Log file exists"
    tail -5 /var/log/motion.log
else
    echo "✗ Log file missing"
    ERRORS=$((ERRORS + 1))
fi

# Summary
echo ""
if [ $ERRORS -eq 0 ]; then
    echo "✓ All checks passed!"
    exit 0
else
    echo "✗ $ERRORS error(s) found"
    exit 1
fi

Hardware Testing

Generate hardware test scripts:

bash

#!/bin/bash
# test_hardware.sh - Test GPIO and audio

echo "Testing audio..."
if aplay /usr/share/sounds/mario/callingmario1.wav; then
    echo "✓ Audio working"
else
    echo "✗ Audio failed"
fi

echo "Testing GPIO (requires hardware)..."
python3 << 'EOF'
import RPi.GPIO as GPIO
import time

GPIO.setmode(GPIO.BCM)
GPIO.setup(23, GPIO.IN)

print(f"GPIO 23 state: {GPIO.input(23)}")
print("Wave your hand near the PIR sensor...")

start = time.time()
while time.time() - start < 5:
    if GPIO.input(23):
        print("✓ Motion detected!")
        GPIO.cleanup()
        exit(0)
    time.sleep(0.1)

print("✗ No motion detected in 5 seconds")
GPIO.cleanup()
EOF

Error Handling

Robust Deployment Scripts

Include error handling in generated scripts:

bash

#!/bin/bash

set -e  # Exit on error
set -u  # Exit on undefined variable

# Trap errors
trap 'echo "Error on line $LINENO"; exit 1' ERR

# Function to check command success
check_command() {
    if ! command -v "$1" &> /dev/null; then
        echo "Error: $1 not found"
        exit 1
    fi
}

# Verify prerequisites
check_command python3
check_command aplay
check_command git

# Continue with deployment...

Rollback Support

Generate scripts with rollback capability:

bash

#!/bin/bash
# deploy_with_rollback.sh

BACKUP_DIR="/tmp/luigi_backup_$(date +%s)"

# Backup existing installation
if [ -d "/opt/luigi" ]; then
    echo "Backing up existing installation..."
    mkdir -p "$BACKUP_DIR"
    cp -r /opt/luigi "$BACKUP_DIR/"
    cp /usr/local/bin/mario.py "$BACKUP_DIR/" 2>/dev/null || true
    cp /etc/init.d/mario "$BACKUP_DIR/" 2>/dev/null || true
fi

# Deploy new version
if ./deploy_luigi.sh; then
    echo "Deployment successful!"
    rm -rf "$BACKUP_DIR"
else
    echo "Deployment failed! Rolling back..."
    if [ -d "$BACKUP_DIR" ]; then
        cp -r "$BACKUP_DIR/luigi" /opt/
        cp "$BACKUP_DIR/mario.py" /usr/local/bin/ 2>/dev/null || true
        cp "$BACKUP_DIR/mario" /etc/init.d/ 2>/dev/null || true
        service mario restart
    fi
    exit 1
fi

Multi-Module Deployment

Extensible Deployment Pattern

When the Luigi project contains multiple modules (e.g., motion detection, environmental sensors, automation):

bash

#!/bin/bash
# deploy_all_modules.sh - Deploy all Luigi modules
# Usage: sudo ./deploy_all_modules.sh

set -e

# Define all available modules (extend this array as new modules are added)
MODULES=("mario" "temperature-sensor" "relay-controller")

log_info() {
    echo -e "\033[0;32m[INFO]\033[0m $1"
}

for MODULE in "${MODULES[@]}"; do
    log_info "Deploying module: $MODULE"
    
    # Determine module directory (support different categories)
    MODULE_PATH=""
    for CATEGORY in motion-detection sensors automation; do
        if [ -d "$CATEGORY/$MODULE" ]; then
            MODULE_PATH="$CATEGORY/$MODULE"
            break
        fi
    done
    
    if [ -z "$MODULE_PATH" ]; then
        log_info "Module $MODULE not found, skipping..."
        continue
    fi
    
    # Deploy Python script
    if [ -f "$MODULE_PATH/$MODULE.py" ]; then
        cp "$MODULE_PATH/$MODULE.py" "/usr/local/bin/"
        chmod 755 "/usr/local/bin/$MODULE.py"
    fi
    
    # Deploy service (support both init.d and systemd)
    if [ -f "$MODULE_PATH/$MODULE.service" ]; then
        # Systemd service
        cp "$MODULE_PATH/$MODULE.service" "/etc/systemd/system/"
        systemctl daemon-reload
        systemctl enable "$MODULE"
        systemctl start "$MODULE"
    elif [ -f "$MODULE_PATH/$MODULE" ]; then
        # init.d service
        cp "$MODULE_PATH/$MODULE" "/etc/init.d/"
        chmod 755 "/etc/init.d/$MODULE"
        update-rc.d "$MODULE" defaults
        service "$MODULE" start
    fi
    
    # Deploy additional resources (sounds, config files, etc.)
    if [ -f "$MODULE_PATH/$MODULE-resources.tar.gz" ]; then
        mkdir -p "/usr/share/$MODULE"
        tar -xzf "$MODULE_PATH/$MODULE-resources.tar.gz" -C "/usr/share/$MODULE/"
    fi
    
    log_info "✓ $MODULE deployed successfully"
done

log_info "All modules deployed!"

Selective Module Deployment

Allow deployment of specific modules only:

bash

#!/bin/bash
# deploy_modules.sh - Deploy selected Luigi modules
# Usage: sudo ./deploy_modules.sh mario temperature-sensor

set -e

if [ $# -eq 0 ]; then
    echo "Usage: $0 <module1> [module2] [module3] ..."
    echo ""
    echo "Available modules:"
    find motion-detection sensors automation -maxdepth 1 -type d 2>/dev/null | grep -v "^motion-detection$\|^sensors$\|^automation$" | sed 's|.*/||' | sort
    exit 1
fi

MODULES=("$@")

for MODULE in "${MODULES[@]}"; do
    echo "Deploying $MODULE..."
    # Call module-specific deployment if it exists
    if [ -f "deploy_$MODULE.sh" ]; then
        bash "deploy_$MODULE.sh"
    else
        echo "Warning: No deployment script for $MODULE found"
    fi
done

Troubleshooting Scripts

Service Troubleshooting

Generate diagnostic scripts:

bash

#!/bin/bash
# troubleshoot_mario.sh

echo "=== Mario Service Diagnostics ==="
echo ""

echo "Service Status:"
service mario status || echo "Service not running"
echo ""

echo "Recent Logs:"
tail -20 /var/log/motion.log 2>/dev/null || echo "No logs found"
echo ""

echo "Process Check:"
ps aux | grep mario.py | grep -v grep || echo "No mario process found"
echo ""

echo "File Permissions:"
ls -l /usr/local/bin/mario.py 2>/dev/null || echo "Script not found"
ls -l /etc/init.d/mario 2>/dev/null || echo "Service script not found"
echo ""

echo "Sound Files:"
ls -l /usr/share/sounds/mario/ 2>/dev/null || echo "Sound directory not found"
echo ""

echo "GPIO Test:"
python3 -c "import RPi.GPIO; print('GPIO library OK')" || echo "GPIO library error"
echo ""

echo "Audio Test:"
aplay --version > /dev/null && echo "Audio system OK" || echo "Audio system error"

Home Assistant MQTT Integration

Deploying Sensor Modules with ha-mqtt Integration

When deploying sensor modules that should integrate with Home Assistant via MQTT, include sensor descriptor installation in the deployment script:

bash

#!/bin/bash
# deploy_motion_sensor.sh - Deploy motion sensor with HA integration
# Usage: sudo ./deploy_motion_sensor.sh

set -e

MODULE_NAME="mario"
SENSOR_ID="mario_motion"

# ... (standard deployment steps for Python script, service, etc.)

# Install sensor descriptor for ha-mqtt integration (if ha-mqtt is installed)
deploy_ha_mqtt_descriptor() {
    local descriptor_dir="/etc/luigi/ha-mqtt/sensors.d"
    
    if [ ! -d "$descriptor_dir" ]; then
        log_info "ha-mqtt not installed, skipping sensor registration"
        return 0
    fi
    
    log_info "Installing sensor descriptor for Home Assistant..."
    
    # Create sensor descriptor JSON
    cat > "$descriptor_dir/${SENSOR_ID}.json" <<EOF
{
  "sensor_id": "${SENSOR_ID}",
  "name": "Mario Motion Sensor",
  "module": "motion-detection/mario",
  "device_class": "motion",
  "icon": "mdi:motion-sensor"
}
EOF
    
    chmod 644 "$descriptor_dir/${SENSOR_ID}.json"
    
    # Register sensor with Home Assistant (if luigi-discover is available)
    if [ -x "/usr/local/bin/luigi-discover" ]; then
        log_info "Registering sensor with Home Assistant..."
        /usr/local/bin/luigi-discover || log_warn "Sensor registration failed (MQTT broker may not be configured)"
    fi
    
    log_info "Sensor descriptor installed: ${SENSOR_ID}"
}

# Deploy descriptor (optional, graceful if ha-mqtt not installed)
deploy_ha_mqtt_descriptor

log_info "Deployment complete!"
log_info "Module will publish sensor data to MQTT if ha-mqtt is configured"

Multi-Sensor Module Deployment

For modules with multiple sensors:

bash

deploy_sensor_descriptors() {
    local descriptor_dir="/etc/luigi/ha-mqtt/sensors.d"
    
    if [ ! -d "$descriptor_dir" ]; then
        return 0
    fi
    
    # Temperature sensor descriptor
    cat > "$descriptor_dir/dht22_temperature.json" <<EOF
{
  "sensor_id": "dht22_temperature",
  "name": "Living Room Temperature",
  "module": "sensors/dht22",
  "device_class": "temperature",
  "unit_of_measurement": "°C",
  "state_class": "measurement"
}
EOF
    
    # Humidity sensor descriptor
    cat > "$descriptor_dir/dht22_humidity.json" <<EOF
{
  "sensor_id": "dht22_humidity",
  "name": "Living Room Humidity",
  "module": "sensors/dht22",
  "device_class": "humidity",
  "unit_of_measurement": "%",
  "state_class": "measurement"
}
EOF
    
    chmod 644 "$descriptor_dir"/*.json
    
    if [ -x "/usr/local/bin/luigi-discover" ]; then
        /usr/local/bin/luigi-discover
    fi
}

ha-mqtt Dependencies

When creating deployment scripts for modules that use ha-mqtt:

bash

install_ha_mqtt_dependencies() {
    log_info "Checking ha-mqtt dependencies..."
    
    # Check if mosquitto-clients is installed (required for MQTT publishing)
    if ! command -v mosquitto_pub > /dev/null; then
        log_info "Installing mosquitto-clients for MQTT support..."
        apt-get install -y mosquitto-clients
    fi
    
    # Check if jq is installed (required for JSON processing)
    if ! command -v jq > /dev/null; then
        log_info "Installing jq for JSON processing..."
        apt-get install -y jq
    fi
}

# Call during dependency installation phase (only if ha-mqtt integration desired)
install_ha_mqtt_dependencies

Testing ha-mqtt Integration

Add verification steps for MQTT integration:

bash

verify_ha_mqtt_integration() {
    log_info "Verifying ha-mqtt integration..."
    
    # Check if descriptor was installed
    if [ -f "/etc/luigi/ha-mqtt/sensors.d/${SENSOR_ID}.json" ]; then
        log_info "✓ Sensor descriptor installed"
    else
        log_warn "Sensor descriptor not found (ha-mqtt may not be installed)"
        return 0
    fi
    
    # Check if sensor can be published
    if command -v luigi-publish > /dev/null; then
        log_info "Testing MQTT publish..."
        if /usr/local/bin/luigi-publish --sensor "${SENSOR_ID}" --value "ON" --binary 2>/dev/null; then
            log_info "✓ MQTT publish successful"
        else
            log_warn "MQTT publish failed (broker may not be configured)"
        fi
    fi
}

Uninstall with ha-mqtt Cleanup

Include sensor descriptor removal in uninstall scripts:

bash

uninstall_ha_mqtt_integration() {
    local descriptor_dir="/etc/luigi/ha-mqtt/sensors.d"
    
    if [ -f "$descriptor_dir/${SENSOR_ID}.json" ]; then
        log_info "Removing sensor descriptor..."
        rm -f "$descriptor_dir/${SENSOR_ID}.json"
        
        # Optionally remove sensor from Home Assistant
        # (would require MQTT retain message removal - advanced)
        log_warn "Note: Sensor may still appear in Home Assistant until manually removed"
    fi
}

# Call during uninstall
uninstall_ha_mqtt_integration

Key Principles for ha-mqtt Integration

•Optional integration - Module must work without ha-mqtt installed
•Graceful checking - Test for ha-mqtt directories before accessing
•Non-blocking - MQTT failures should not prevent module deployment
•Clear feedback - Log whether ha-mqtt integration succeeded or was skipped
•Clean uninstall - Remove sensor descriptors when uninstalling module

For complete ha-mqtt integration guide, see iot/ha-mqtt/examples/integration-guide.md.

Best Practices for Script Generation

When generating deployment scripts, agents should:

•Use descriptive comments: Explain each step clearly
•Include error handling: Use set -e, check exit codes
•Provide feedback: Echo progress messages for users
•Make scripts idempotent: Safe to run multiple times
•Check prerequisites: Verify dependencies before deployment
•Test verification: Include post-deployment checks
•Document usage: Add help text and examples
•Use standard paths: Follow FHS (Filesystem Hierarchy Standard)
•Set proper permissions: Ensure security and functionality
•Support updates: Make it easy to update deployments

Script Template

Use this template for new deployment scripts:

bash

#!/bin/bash
# script_name.sh - Brief description
# Usage: sudo ./script_name.sh [options]

set -e  # Exit on error

# Configuration
readonly SCRIPT_NAME="$(basename "$0")"
readonly LOG_FILE="/var/log/luigi_deployment.log"

# Color codes
readonly RED='\033[0;31m'
readonly GREEN='\033[0;32m'
readonly YELLOW='\033[1;33m'
readonly NC='\033[0m'

# Logging functions
log() {
    echo -e "$@" | tee -a "$LOG_FILE"
}

log_info() {
    log "${GREEN}[INFO]${NC} $1"
}

log_warn() {
    log "${YELLOW}[WARN]${NC} $1"
}

log_error() {
    log "${RED}[ERROR]${NC} $1"
}

# Check root
check_root() {
    if [ "$EUID" -ne 0 ]; then
        log_error "Please run as root (use sudo)"
        exit 1
    fi
}

# Main function
main() {
    log_info "Starting $SCRIPT_NAME"
    
    # Script logic here
    
    log_info "Completed successfully"
}

# Run main
check_root
main "$@"

Quick Reference

Essential Commands

bash

# Install dependencies
sudo apt-get update
sudo apt-get install -y python3-rpi.gpio alsa-utils git

# Deploy service
sudo cp mario /etc/init.d/
sudo chmod 755 /etc/init.d/mario
sudo update-rc.d mario defaults

# Manage service
sudo service mario start
sudo service mario stop
sudo service mario restart
sudo service mario status

# View logs
tail -f /var/log/motion.log

# Test audio
aplay /usr/share/sounds/mario/callingmario1.wav

# Test GPIO
python3 -c "import RPi.GPIO; print('OK')"

File Locations

code

/opt/luigi/                        # Repository
/usr/local/bin/mario.py           # Script
/etc/init.d/mario                 # Service
/usr/share/sounds/mario/          # Sounds
/var/log/motion.log               # Logs

Luigi Deployment Automation Skill

Scope

In Scope

Out of Scope

Target Environment

Luigi Project Structure

Deployment Script Patterns

1. Complete Deployment Script Template

2. Modular Script Pattern

3. Service Management Script

4. Update Script

5. Uninstall Script

Service Integration Patterns

Init.d Service Script Structure

Systemd Unit File (Alternative)

Dependency Management

Core Luigi Dependencies

Optional Dependencies

Python Package Management

File Deployment Best Practices

Directory Structure

File Permissions

Sound File Deployment

Configuration Management

Configuration File Standard

Configuration File Format

Deployment Pattern

Config File in Complete Deployment

Configuration Verification

User Configuration Instructions

Configuration Options

Hardware Testing

Error Handling

Robust Deployment Scripts

Rollback Support

Multi-Module Deployment

Extensible Deployment Pattern

Selective Module Deployment

Troubleshooting Scripts

Service Troubleshooting

Home Assistant MQTT Integration

Deploying Sensor Modules with ha-mqtt Integration

Multi-Sensor Module Deployment

ha-mqtt Dependencies

Testing ha-mqtt Integration

Uninstall with ha-mqtt Cleanup

Key Principles for ha-mqtt Integration

Best Practices for Script Generation

Script Template

Quick Reference

Essential Commands

File Locations

Additional Resources