# Préparer le Raspberry Pi, pas à pas

Ce guide part d'une carte SD vide et va jusqu'à la matrice qui s'allume.
Comptez **une heure** la première fois, dont beaucoup d'attente.

> **Système plus ancien ?** Le projet fonctionne aussi sur **Raspbian 11
> « Bullseye »** (cartes préparées avant fin 2023, testé sur un Pi 3 Model B).
> Seule différence : la partie de la carte SD lisible par tous les
> ordinateurs s'appelle **`/boot`** au lieu de **`/boot/firmware`**. Partout
> où ce guide écrit `/boot/firmware`, lisez `/boot`. Le script d'installation
> et le lecteur s'en rendent compte tout seuls.

On utilise le Pi **« sans écran »** (on dit *headless*) : pas de clavier, pas
d'écran, pas de souris. On lui parle **depuis son ordinateur portable**, par
le Wi-Fi. C'est comme ça qu'il vivra dans la vitrine.

---

## Sommaire

1. [Ce qu'il faut](#1-ce-quil-faut)
2. [Installer le système sur la carte SD](#2-installer-le-système-sur-la-carte-sd)
3. [Premier démarrage](#3-premier-démarrage)
4. [Se connecter au Pi (SSH)](#4-se-connecter-au-pi-ssh)
5. [Copier le projet sur le Pi](#5-copier-le-projet-sur-le-pi)
6. [Installation automatique](#6-installation-automatique)
7. [Ce que fait l'installation (pour comprendre)](#7-ce-que-fait-linstallation-pour-comprendre)
8. [Tester](#8-tester)
9. [Les commandes de survie du terminal](#9-les-commandes-de-survie-du-terminal)
10. [Problèmes fréquents](#10-problèmes-fréquents)

---

## 1. Ce qu'il faut

- Un Raspberry Pi **3B+, 4 ou Zero 2 W** et son bloc secteur.
- Une carte micro-SD de 16 Go ou plus, et un lecteur de carte pour l'ordinateur.
- Un ordinateur (Windows, macOS ou Linux) **sur le même réseau Wi-Fi** que le Pi.
- Le nom et le mot de passe de ce réseau Wi-Fi.

> **Réseau de l'école** : les réseaux avec identifiant personnel (type
> *eduroam*) sont compliqués à configurer sur un Pi. Le plus simple : utiliser
> le **partage de connexion d'un téléphone** (point d'accès), auquel on
> connecte le Pi **et** l'ordinateur. Notez son nom et son mot de passe.
> Attention : le Pi 3B+ et le Zero 2 W ne voient que le Wi-Fi **2,4 GHz**
> (sur iPhone : activer « Maximiser la compatibilité »).

---

## 2. Installer le système sur la carte SD

On utilise le logiciel officiel **Raspberry Pi Imager**.

1. Téléchargez-le et installez-le : <https://www.raspberrypi.com/software/>
2. Insérez la carte SD dans l'ordinateur et lancez Raspberry Pi Imager.
3. **Modèle** : choisissez votre Raspberry Pi.
4. **Système d'exploitation** : *Raspberry Pi OS (other)* →
   **Raspberry Pi OS Lite (64-bit)**.
   « Lite » = sans bureau graphique : plus léger, démarre plus vite, et on
   n'a pas d'écran de toute façon.
5. **Stockage** : votre carte SD. ⚠️ **Tout son contenu sera effacé.**
6. Quand Imager propose de **personnaliser** le système (*customisation*,
   *Modifier réglages*), dites **oui** et remplissez :

| Réglage | Valeur conseillée | Pourquoi |
|---|---|---|
| Nom d'hôte (*hostname*) | `vitrine` | le nom du Pi sur le réseau : on le trouvera à l'adresse `vitrine.local` |
| Nom d'utilisateur | `pixel` (par exemple) | votre compte sur le Pi |
| Mot de passe | à choisir, **à noter** | |
| Wi-Fi : nom (SSID) et mot de passe | ceux du réseau ou du téléphone | pour que le Pi se connecte tout seul |
| Pays du Wi-Fi | `FR` | obligatoire pour activer le Wi-Fi |
| Fuseau horaire / clavier | `Europe/Paris` / `fr` | pour que l'heure soit juste |
| **SSH** (onglet *Services*) | **activer**, avec mot de passe | pour se connecter depuis l'ordinateur |

7. Lancez l'écriture et patientez (5 à 15 minutes). Imager vérifie la carte
   à la fin, puis l'éjecte.

> **Si vous avez plusieurs Pi**, donnez-leur des noms différents
> (`vitrine1`, `vitrine2`…), sinon ils se gêneront sur le réseau.

---

## 3. Premier démarrage

1. Insérez la carte SD dans le Pi (contacts vers la carte).
2. Branchez le bloc secteur. La LED rouge s'allume, la verte clignote :
   le Pi travaille.
3. **Attendez 3 à 5 minutes** : au premier démarrage, le Pi s'installe,
   redémarre une ou deux fois, puis se connecte au Wi-Fi.

Pas besoin de brancher la matrice pour l'instant.

---

## 4. Se connecter au Pi (SSH)

**SSH** permet de taper des commandes sur le Pi depuis son ordinateur, comme
si on avait un clavier branché dessus.

Ouvrez un **terminal** :

- **Windows** : menu Démarrer → tapez `PowerShell` → Entrée ;
- **macOS** : Applications → Utilitaires → **Terminal** ;
- **Linux** : le terminal habituel.

Tapez (en remplaçant `pixel` par votre nom d'utilisateur) :

```bash
ssh pixel@vitrine.local
```

- La première fois, il demande si vous faites confiance à cet ordinateur :
  tapez `yes` puis Entrée.
- Puis votre **mot de passe**. ⚠️ **Rien ne s'affiche quand on le tape**, pas
  même des étoiles : c'est normal. Tapez-le et faites Entrée.

Vous êtes connecté quand la ligne commence par `pixel@vitrine:~ $`.
Tout ce que vous tapez maintenant s'exécute **sur le Pi**.

Pour se déconnecter : `exit`.

---

## 5. Copier le projet sur le Pi

Ouvrez un **deuxième terminal sur votre ordinateur** (pas dans la session
SSH), placez-vous dans le dossier qui contient `8x32 PI`, puis :

```bash
scp -r "8x32 PI" pixel@vitrine.local:~/vitrine
```

`scp` = copie par SSH. Le dossier s'appellera simplement `vitrine` sur le Pi
(sans espace dans le nom, c'est plus pratique dans un terminal).

> **Plutôt à la souris ?** Les logiciels gratuits **WinSCP** (Windows),
> **Cyberduck** (macOS) ou **FileZilla** (tous) permettent de glisser-déposer
> des fichiers sur le Pi. Choisissez le protocole **SFTP**, serveur
> `vitrine.local`, votre nom d'utilisateur et votre mot de passe.

---

## 6. Installation automatique

Dans la **session SSH** (sur le Pi) :

```bash
cd ~/vitrine
```

```bash
bash installation/installer.sh
```

Le script installe tout ce qu'il faut (5 à 15 minutes). Il demande parfois
votre mot de passe (pour `sudo`). À la fin, **redémarrez le Pi** :

```bash
sudo reboot
```

La connexion SSH se coupe. Attendez une minute et reconnectez-vous
(`ssh pixel@vitrine.local`).

---

## 7. Ce que fait l'installation (pour comprendre)

Le script [`installation/installer.sh`](installation/installer.sh) est
commenté ligne par ligne. Voici ses 5 étapes, et les commandes qu'on taperait
à la main :

**1. Installer des logiciels du système.** `apt` est le « magasin
d'applications » de Raspberry Pi OS :

```bash
sudo apt-get install -y python3-venv python3-pil python3-dev gcc
```

**2. Créer un environnement Python** et y installer la bibliothèque qui
parle aux LED. Un *environnement virtuel* est une boîte réservée au projet :
on peut y installer des bibliothèques sans risquer d'abîmer le système.

```bash
python3 -m venv --system-site-packages ~/vitrine-env
```

```bash
~/vitrine-env/bin/pip install rpi_ws281x
```

C'est pour ça qu'on lance ensuite les programmes avec `~/vitrine-env/bin/python`
et pas simplement `python3` : seul ce Python-là connaît `rpi_ws281x`.

**3. Désactiver la sortie son.** Sur le Pi, le son analogique et le signal des
LED utilisent le **même circuit interne** (le générateur « PWM »). On ne peut
pas avoir les deux. Dans le fichier de réglages `/boot/firmware/config.txt`,
la ligne `dtparam=audio=on` devient `dtparam=audio=off`.

**4. Créer le dossier des animations** `/boot/firmware/animations` et y
copier les exemples. Pourquoi là ? Voir [MODE_VITRINE.md](MODE_VITRINE.md) :
c'est la partie de la carte SD que **tous les ordinateurs** savent ouvrir.

**5. Installer le service** de démarrage automatique (sans l'activer).
Voir [MODE_VITRINE.md](MODE_VITRINE.md).

---

## 8. Tester

Branchez la matrice (voir [README, partie 6](README.md#6-brancher-étape-par-étape)),
**alimentation d'établi allumée**, puis dans la session SSH :

```bash
cd ~/vitrine
```

```bash
sudo ~/vitrine-env/bin/python test_matrice.py
```

Puis, si le test est bon :

```bash
sudo ~/vitrine-env/bin/python lecteur.py
```

**Ctrl + C** pour arrêter. Pour que le lecteur démarre tout seul à chaque
allumage, voir [MODE_VITRINE.md](MODE_VITRINE.md).

---

## 9. Les commandes de survie du terminal

| Commande | Effet |
|---|---|
| `pwd` | « où suis-je ? » : affiche le dossier courant |
| `ls` | liste les fichiers du dossier courant |
| `cd vitrine` | entre dans le dossier `vitrine` |
| `cd ..` | remonte d'un dossier |
| `cd ~` | revient au dossier personnel |
| `nano matrice.py` | ouvre un fichier dans un éditeur de texte simple (**Ctrl + O** puis Entrée : enregistrer ; **Ctrl + X** : quitter) |
| **Ctrl + C** | arrête le programme en cours |
| **Tab** | complète automatiquement un nom de fichier (gain de temps énorme !) |
| **↑** | rappelle la commande précédente |
| `sudo reboot` | redémarre le Pi |
| `sudo poweroff` | éteint proprement le Pi (attendre que la LED verte ne clignote plus avant de débrancher) |
| `exit` | quitte la session SSH |

---

## 10. Problèmes fréquents

| Symptôme | Cause probable | Solution |
|---|---|---|
| `ssh: Could not resolve hostname vitrine.local` | Le Pi n'a pas encore fini de démarrer | Attendre 2 minutes de plus |
| | Pi et ordinateur sur deux réseaux différents | Les connecter au même Wi-Fi |
| | Réseau qui bloque les noms `.local` (fréquent à l'école) | Trouver l'**adresse IP** du Pi (dans l'interface du téléphone en point d'accès, liste des appareils connectés) et faire `ssh pixel@192.168.x.x` |
| | Mauvais Wi-Fi saisi dans Imager | Refaire la carte SD (partie 2) |
| `Permission denied, please try again.` | Mauvais mot de passe ou nom d'utilisateur | Retaper ; attention au clavier (QWERTY / AZERTY) |
| `WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!` | La carte SD a été refaite : le Pi a une nouvelle « empreinte » | `ssh-keygen -R vitrine.local`, puis se reconnecter |
| `externally-managed-environment` lors d'un `pip install` | Installation hors de l'environnement virtuel | Utiliser `~/vitrine-env/bin/pip`, pas `pip` |
| Erreur de compilation pendant l'installation de `rpi_ws281x` | Outils de compilation manquants | `sudo apt-get install -y python3-dev gcc`, puis relancer le script |
| `config.txt introuvable` | Système qui n'est pas Raspberry Pi OS | Refaire la carte SD avec Raspberry Pi OS |