Le script d'installation va :

- ✅ Détecter automatiquement votre utilisateur
- ✅ Installer les dépendances système
- ✅ Copier tous les fichiers vers `/opt/Skull/`
- ✅ Configurer l'environnement Python pour votre utilisateur
- ✅ Installer les services systemd avec les bonnes permissions
- ✅ Configurer Mosquitto MQTT
- ✅ Définir les permissions sudoers pour votre utilisateur
- # 🏴‍☠️ Skull Pi - Guide de Déploiement

Ce document décrit la procédure complète d'installation et de déploiement du système Skull Pi sur un Raspberry Pi Zero 2 W.

## Pré-requis

### Matériel

- Raspberry Pi Zero 2 W
- Carte microSD (16GB minimum, 32GB recommandé)
- Caméra Raspberry Pi (optionnel)
- Microphone USB ou HAT audio
- Haut-parleur ou casque
- Servomoteurs (4x) avec connexions GPIO

### Logiciel

- Raspberry Pi OS Lite (version récente)
- Accès SSH configuré
- Utilisateur `pi` avec sudo
- Connexion Internet pour l'installation

## Installation

### 1. Préparation du système

```bash
# Mise à jour du système
sudo apt update && sudo apt upgrade -y

# Clone du repository
git clone https://github.com/votre-org/skull-pi.git
cd skull-pi
```

### 2. Installation automatique

```bash
# Lancement de l'installation complète
sudo bash install.sh
```

Le script d'installation va :

- ✅ Installer les dépendances système
- ✅ Créer l'arborescence `/opt/Skull/`
- ✅ Configurer l'environnement Python
- ✅ Installer les services systemd
- ✅ Configurer Mosquitto MQTT
- ✅ Définir les permissions sudoers
- ✅ Démarrer tous les services

### 3. Alternative avec Makefile

```bash
# Installation via Makefile
make install

# Autres commandes utiles
make status    # État des services
make logs      # Logs en temps réel
make restart   # Redémarrage
```

## Vérification de l'installation

### Services systemd

```bash
# Vérification du statut global
systemctl status skull.target

# Services individuels
systemctl status skull-orchestrator.service
systemctl status skull-motion.service
systemctl status skull-vision.service
systemctl status skull-voice.service
systemctl status skull-audioin.service
systemctl status skull-asr.service
systemctl status skull-ai.service
```

### Test MQTT

```bash
# Écoute des capabilities
mosquitto_sub -h 127.0.0.1 -t '+/capabilities' -v

# Test de publication
mosquitto_pub -h 127.0.0.1 -t 'test/deploy' -m 'Hello Skull Pi'
```

### Logs système

```bash
# Logs de l'orchestrator
tail -f /opt/Skull/logs/orchestrator.log

# Logs systemd
journalctl -f -u skull-orchestrator

# Tous les logs Skull Pi
journalctl -f -u skull-*
```

## Configuration

### Variables d'environnement

Éditez `/opt/Skull/config/.env` :

```bash
sudo nano /opt/Skull/config/.env
```

Configurez au minimum :

- `OPENAI_API_KEY` ou `ANTHROPIC_API_KEY`
- `CAMERA_INDEX` (si caméra présente)
- `AUDIO_DEVICE_INDEX`

### Configuration des servos

Ajustez `/opt/Skull/config/servos.json` selon votre montage :

```bash
sudo nano /opt/Skull/config/servos.json
```

### Redémarrage après configuration

```bash
sudo systemctl restart skull.target
```

## Structure des fichiers

```
/opt/Skull/
├── apps/                   # Modules Python
├── bin/                    # Scripts wrapper
│   ├── skull-orchestrator.sh
│   ├── skull-motion.sh
│   ├── skull-vision.sh
│   ├── skull-voice.sh
│   ├── skull-audioin.sh
│   ├── skull-asr.sh
│   └── skull-ai.sh
├── config/                 # Configuration
│   ├── .env
│   ├── servos.json
│   ├── greet.json
│   └── prompt.txt
├── logs/                   # Logs applicatifs
├── assets/                 # Assets (modèles, audio)
└── venv/                   # Environnement Python
```

## Commandes utiles

### Gestion des services

```bash
# Démarrer/arrêter tous les services
sudo systemctl start skull.target
sudo systemctl stop skull.target

# Redémarrer un service spécifique
sudo systemctl restart skull-vision.service

# Activer/désactiver au boot
sudo systemctl enable skull.target
sudo systemctl disable skull.target
```

### Debugging

```bash
# Statut détaillé
systemctl status skull.target -l

# Logs en temps réel
journalctl -f -u skull-orchestrator

# Test MQTT complet
mosquitto_sub -h 127.0.0.1 -t '#' -v

# Monitoring système
htop
iostat
```

### Maintenance

```bash
# Nettoyage des logs
make clean

# Sauvegarde de configuration
make backup

# Redémarrage complet
make reboot
```

## Dépannage

### Services qui ne démarrent pas

1. Vérifiez les logs : `journalctl -u skull-[service]`
2. Contrôlez les permissions : `ls -la /opt/Skull/`
3. Testez le script manuellement : `/opt/Skull/bin/skull-[service].sh`
4. Vérifiez l'environnement Python : `source /opt/Skull/venv/bin/activate && python --version`

### MQTT non fonctionnel

1. Statut Mosquitto : `systemctl status mosquitto`
2. Configuration : `cat /etc/mosquitto/conf.d/skull.conf`
3. Test de connexion : `mosquitto_pub -h 127.0.0.1 -t test -m hello`
4. Ports : `netstat -tlnp | grep 1883`

### Problèmes audio/vidéo

1. Périphériques détectés : `lsusb` et `arecord -l`
2. Permissions : groupes `audio` et `video`
3. Test caméra : `raspistill -t 1000 -o test.jpg` (si caméra Pi)
4. Test audio : `speaker-test -t sine -f 1000 -l 1`

### Erreurs GPIO/Servos

1. Permissions GPIO : utilisateur dans groupe `gpio`
2. Modules kernel : `lsmod | grep gpio`
3. Test basique : `gpio readall` (si wiringpi installé)
4. Configuration pins dans `servos.json`

### Problèmes mémoire

1. Usage mémoire : `free -h`
2. Processes : `ps aux | grep skull`
3. Ajustement des limites dans services systemd
4. Swap disponible : `swapon --show`

## Recette de validation

### ✅ Check-list installation

- [ ] Tous les services démarrent : `systemctl status skull.target`
- [ ] MQTT fonctionne : `mosquitto_sub -t '+/capabilities' -v`
- [ ] Logs créés dans `/opt/Skull/logs/`
- [ ] Configuration `.env` adaptée
- [ ] Permissions correctes : `ls -la /opt/Skull/`
- [ ] Redémarrage automatique après reboot

### ✅ Tests fonctionnels

- [ ] **Orchestrator** : capabilities publiées sur MQTT
- [ ] **Motion** : servos répondent aux commandes
- [ ] **Vision** : caméra capture des images
- [ ] **Voice** : synthèse vocale fonctionne
- [ ] **AudioIn** : microphone capture le son
- [ ] **ASR** : reconnaissance vocale active
- [ ] **AI** : réponses aux requêtes

### ✅ Tests d'intégration

- [ ] Commande vocale → ASR → AI → Voice → Motion
- [ ] Vision → Analysis → Response
- [ ] MQTT : tous les services communiquent
- [ ] Logs : pas d'erreurs critiques
- [ ] Performance : CPU/RAM acceptable

## Maintenance

### Mise à jour

```bash
# Arrêt des services
sudo systemctl stop skull.target

# Mise à jour du code
git pull origin main

# Réinstallation des dépendances si nécessaire
source /opt/Skull/venv/bin/activate
pip install -r requirements.txt --upgrade

# Redémarrage
sudo systemctl start skull.target
```

### Sauvegarde

```bash
# Sauvegarde complète
tar -czf skull-pi-backup-$(date +%Y%m%d).tar.gz \
  /opt/Skull/config \
  /etc/systemd/system/skull* \
  /etc/mosquitto/conf.d/skull.conf \
  /etc/sudoers.d/skull

# Restauration
tar -xzf skull-pi-backup-*.tar.gz -C /
sudo systemctl daemon-reload
```

### Monitoring

```bash
# Script de monitoring (à ajouter en crontab)
#!/bin/bash
if ! systemctl is-active --quiet skull.target; then
  echo "$(date): Skull Pi services down, restarting..." >> /var/log/skull-monitor.log
  systemctl restart skull.target
fi
```

## Performance et optimisation

### Ressources système

- **RAM minimale** : 512MB (1GB recommandé)
- **CPU** : ARM Cortex-A53 (Pi Zero 2 W)
- **Stockage** : 8GB utilisés, 16GB minimum
- **Réseau** : WiFi obligatoire pour APIs

### Optimisations Pi Zero 2 W

```bash
# Dans /boot/config.txt
gpu_mem=16          # Mémoire GPU minimale
disable_camera_led=1 # LED caméra
dtoverlay=disable-bt # Bluetooth si non utilisé

# Limite la fréquence CPU si surchauffe
arm_freq=1000
```

### Services optionnels

Vous pouvez désactiver certains services selon vos besoins :

```bash
# Désactiver un service non utilisé
sudo systemctl disable skull-vision.service
```

## Support

### Logs complets

Pour un diagnostic complet :

```bash
# Collecte des informations système
cat > skull-debug.txt << EOF
=== SYSTEM INFO ===
$(uname -a)
$(free -h)
$(df -h)

=== SERVICES STATUS ===
$(systemctl status skull.target --no-pager)

=== MQTT TEST ===
$(timeout 5 mosquitto_sub -h 127.0.0.1 -t '+/capabilities' -C 10)

=== RECENT LOGS ===
$(journalctl -u skull-* --since "1 hour ago" --no-pager)
EOF
```

### Contact

- **Repository** : https://github.com/votre-org/skull-pi
- **Issues** : Utilisez GitHub Issues
- **Documentation** : Wiki du projet

---

**🏴‍☠️ Skull Pi est maintenant opérationnel !**

_N'oubliez pas de configurer vos clés API dans `.env` pour une expérience complète._