# Matrice LED 8 × 32 (WS2812B) avec un Raspberry Pi

Workshop « Vitrine pixels » : la même matrice de **256 pixels** que dans le
dossier [`matrice_8x32`](../matrice_8x32/README.md), mais pilotée par un
**Raspberry Pi**. L'avantage : le Pi sait **lire des images**. Les animations
dessinées dans **Krita** sont jouées telles quelles, sans les traduire en code.

![De Krita à la matrice](schemas/chaine_krita_matrice.svg)

> **À qui s'adresse ce dossier ?**
> - **L'équipe électronique** : ce README (montage, test, dépannage), puis
>   [INSTALLATION_PI.md](INSTALLATION_PI.md) (préparer le Pi).
> - **L'équipe design** : [GUIDE_KRITA.md](GUIDE_KRITA.md) (dessiner et exporter
>   pour la matrice). Pas besoin de toucher au matériel !
> - **Pour la vitrine** : [MODE_VITRINE.md](MODE_VITRINE.md) (démarrage
>   automatique, changer les animations, coupures de courant).
> - **Pour déposer et choisir les animations depuis un navigateur** :
>   [INTERFACE_WEB.md](INTERFACE_WEB.md) (adresse en Wi-Fi : `http://172.16.50.27`).
> - **Pour qui veut coder** : [CODER_EN_PYTHON.md](CODER_EN_PYTHON.md).

---

## Sommaire

1. [Arduino ou Raspberry Pi ?](#1-arduino-ou-raspberry-pi-)
2. [Le matériel](#2-le-matériel)
3. [Comment ça marche ?](#3-comment-ça-marche-)
4. [Le problème des 3,3 V et le 74AHCT125](#4-le-problème-des-33-v-et-le-74ahct125)
5. [Les 5 règles d'or](#5-les-5-règles-dor)
6. [Brancher, étape par étape](#6-brancher-étape-par-étape)
7. [Préparer le Raspberry Pi](#7-préparer-le-raspberry-pi)
8. [Premier allumage : le test](#8-premier-allumage--le-test)
9. [Jouer les animations](#9-jouer-les-animations)
10. [L'interface web : piloter la vitrine depuis un navigateur](#10-linterface-web--piloter-la-vitrine-depuis-un-navigateur)
11. [Ça ne marche pas ?](#11-ça-ne-marche-pas-)
12. [Petit lexique](#12-petit-lexique)
13. [Les fichiers du dossier](#13-les-fichiers-du-dossier)

---

## 1. Arduino ou Raspberry Pi ?

Ce sont deux cartes très différentes :

- L'**Arduino** est un **microcontrôleur** : une petite puce qui exécute un
  seul programme, en boucle, dès qu'on l'alimente. Il est simple et robuste,
  mais minuscule : 2 Ko de mémoire de travail et 32 Ko pour le programme.
- Le **Raspberry Pi** est un vrai **ordinateur**, de la taille d'une carte de
  crédit, avec un système (Linux), des fichiers, le Wi-Fi, une carte SD de
  plusieurs gigaoctets…

| | Arduino Uno | Raspberry Pi |
|---|---|---|
| Passer d'un dessin Krita à la matrice | dessin → script de conversion → code C → téléversement | copier le GIF dans un dossier |
| Nombre d'images possibles | ≈ 30 (une image = 768 octets, la mémoire est pleine très vite) | des milliers (carte SD) |
| Changer les animations | ordinateur + câble USB + IDE Arduino | carte SD, ou par le réseau |
| Démarrage | instantané | ≈ 30 secondes |
| Coupure de courant brutale | aucun problème | risque d'abîmer la carte SD (solution : [MODE_VITRINE.md](MODE_VITRINE.md)) |
| Langage | C++ | Python |
| Niveau électrique de la broche de données | 5 V : parfait pour les LED | **3,3 V : trop faible**, il faut un adaptateur (partie 4) |

**Conclusion** : pour **apprendre** (comprendre les bits, le multiplexage, la
chaîne de LED), l'Arduino est idéal. Pour **diffuser les créations d'une
équipe design** dans une vitrine, le Raspberry Pi est beaucoup plus pratique.

---

## 2. Le matériel

| Quoi | Combien | Remarque |
|---|---|---|
| Matrice LED WS2812B 8 × 32, souple | 1 | la même que dans `matrice_8x32` |
| **Raspberry Pi 3B+, 4 ou Zero 2 W** | 1 | ⚠️ **pas le Pi 5** (voir encadré) |
| Bloc secteur USB **officiel** du Pi | 1 | micro-USB 2,5 A (3B+, Zero 2 W) ou USB-C 3 A (Pi 4) |
| Carte micro-SD 16 Go ou plus | 1 | « classe 10 » / « A1 » |
| Puce **74AHCT125** (boîtier DIP 14 pattes) | 1 | l'adaptateur 3,3 V → 5 V (partie 4). Le **74HCT125** convient aussi. **Pas de puce ?** Voir les solutions de dépannage, partie 4 |
| Alimentation d'établi | 1 | réglée sur **5,0 V**, limite ≈ 3 A |
| 2 cordons banane → pince crocodile | 1 rouge + 1 noir | |
| Résistance **330 Ω** | 1 | orange-orange-marron |
| Condensateur électrolytique **1000 µF**, 10 V ou plus | 1 | |
| Plaque d'essai (breadboard) | 1 | obligatoire cette fois, pour la puce |
| Fils Dupont **mâle-mâle** | 6 | sur la plaque d'essai |
| Fils Dupont **femelle-mâle** | 2 | du connecteur du Pi vers la plaque d'essai |
| Lecteur de carte SD pour l'ordinateur | 1 | pour préparer la carte |

> **Pourquoi pas le Raspberry Pi 5 ?** Sur le Pi 5, les broches sont gérées
> par une nouvelle puce (« RP1 »), et la bibliothèque `rpi_ws281x` que nous
> utilisons ne sait pas encore lui parler. Il existe d'autres bibliothèques
> pour le Pi 5, mais elles sont moins simples. Le Pi 4, le Pi 3B+ et le petit
> Pi Zero 2 W (≈ 20 €, largement assez puissant) fonctionnent parfaitement.

---

## 3. Comment ça marche ?

Côté **matrice**, rien ne change par rapport à l'Arduino (relisez la
[partie 2 du README Arduino](../matrice_8x32/README.md#2-comment-ça-marche-)) :
les 256 LED forment une **chaîne**, et on leur envoie une longue liste de
couleurs par **un seul fil** de données. L'énergie vient de l'alimentation
d'établi.

Côté **cerveau**, le Raspberry Pi fait tourner le programme
[`lecteur.py`](lecteur.py), qui :

1. regarde ce qu'il y a dans le dossier `animations` ;
2. ouvre chaque fichier (GIF, PNG…) et le découpe en images de 8 × 32
   (la matrice est posée debout, voir partie 8) ;
3. pour chaque image, **corrige les couleurs** pour que la matrice ressemble
   à l'écran de Krita (la « correction gamma »), applique la luminosité et la
   limite de courant ;
4. remet les pixels dans l'**ordre de la chaîne** (le serpentin, avec la
   même fonction `XY()` que sur l'Arduino) ;
5. envoie les 256 couleurs dans le fil, attend la durée prévue, passe à
   l'image suivante ;
6. recommence avec l'animation suivante, et ainsi de suite, en boucle.

---

## 4. Le problème des 3,3 V et le 74AHCT125

### Le problème

Les broches du Raspberry Pi fonctionnent en **3,3 V** : un « 1 » envoyé dans le
fil de données vaut 3,3 V. Mais une LED WS2812B alimentée en 5 V ne comprend
un « 1 » qu'à partir d'environ **3,5 V** (70 % de 5 V).

3,3 V, c'est juste en dessous. Souvent ça marche quand même… et parfois les
couleurs deviennent aléatoires, ou ça scintille, selon la température, la
longueur du fil, le lot de LED. Pour une vitrine qui doit tourner des
semaines, on ne joue pas à pile ou face.

> ⚠️ **Ne jamais relier directement le 5 V à une broche du Pi** : les broches du
> Pi supportent au maximum 3,3 V. Au-delà, elles grillent, et souvent le Pi
> avec. Le courant ne doit circuler que **du Pi vers la matrice**, jamais
> l'inverse.

### La solution : un adaptateur de niveau

Le **74AHCT125** est une petite puce qui « répète » un signal en le
renforçant : elle écoute un 3,3 V faible et ressort un vrai 5 V propre. Elle
contient 4 répéteurs (des « portes »). On n'en utilise qu'un seul.

![Brochage du 74AHCT125](schemas/brochage_74ahct125.svg)

| Patte | Nom | Rôle | Branchée sur |
|---|---|---|---|
| **14** | VCC | alimentation de la puce | **5 V** (fil rouge de la fiche DIN) |
| **7** | GND | masse | **GND** |
| **1** | 1OE | « marche/arrêt » du répéteur n° 1 (actif quand il est à 0 V) | **GND** (= toujours en marche) |
| **2** | 1A | **entrée** du répéteur | **GPIO 18** du Pi (patte 12) |
| **3** | 1Y | **sortie** du répéteur | résistance 330 Ω → fil **vert** (DIN) |
| 4 à 6, 8 à 13 | | répéteurs 2, 3, 4 | rien (on peut relier 4, 10 et 13 au 5 V pour les éteindre) |

**Repérer la patte 1** : le boîtier a une **encoche** (demi-lune) à une
extrémité, et souvent un petit **point** à côté de la patte 1. Encoche à
gauche, la patte 1 est **en bas à gauche**. On compte ensuite dans le sens
inverse des aiguilles d'une montre : 1 à 7 en bas, de gauche à droite, puis
8 à 14 en haut, de droite à gauche.

### Pas de 74AHCT125 sous la main ? Deux solutions de dépannage

**Solution A : baisser la tension de la matrice (conseillée, aucun composant).**
Le seuil du « 1 » vaut 70 % de la tension d'alimentation **des LED**. Si on
alimente la matrice en **4,4 V** au lieu de 5 V, le seuil tombe à
0,7 × 4,4 ≈ **3,1 V**, et les 3,3 V du Pi suffisent. Les WS2812B fonctionnent
entre 3,5 et 5,3 V : 4,4 V ne les gêne pas, elles sont juste un peu moins
lumineuses.

![Branchement sans puce, solution A](schemas/branchement_sans_puce.svg)

En résumé :

```
  Pi patte 12 (GPIO 18) ──[ 330 Ω ]── fil VERT de la fiche DIN
  Pi patte 6  (GND)     ───────────── fil BLANC de la fiche DIN
  fil ROUGE de la fiche DIN : NON branché, isolé (comme avec l'Arduino)
  alimentation d'établi : 4,4 V (au lieu de 5,0 V) sur les fils du milieu
```

- Réglez l'alimentation d'établi sur **4,4 V** (entre 4,2 et 4,5 V) ; ne
  descendez pas sous 4,0 V, les couleurs se dérègleraient (le bleu et le vert
  faiblissent en premier).
- ⚠️ Le fil **rouge** de la fiche reste **isolé** : il porte la tension de la
  matrice, et ne doit **jamais** toucher une patte du Pi.
- Gardez le fil de données **court** (moins de 30 cm).

**Solution B : un transistor « inverseur » (si la solution A scintille).**
Avec un transistor NPN du kit, de préférence un **2N3904** (le plus rapide du
kit ; un BC337 ou un S8050 peuvent convenir), on fabrique un adaptateur 5 V.
Le transistor **inverse** le signal (un 1 devient un 0) : il faut le dire au
programme avec `INVERSER_SIGNAL = True` dans [`matrice.py`](matrice.py).

![Branchement avec un transistor, solution B](schemas/branchement_transistor.svg)

Le même montage, en schéma électrique :

```
                         fil ROUGE de la fiche (5 V)
                                  │
                                [ 1 kΩ ]   ← résistance de « tirage »
                                  │
                                  ├────────── fil VERT de la fiche (DIN)
                                  │
  Pi patte 12 ──[ 1 kΩ ]──── B   C          transistor NPN 2N3904
                                \│/         (vérifier l'ordre E-B-C
                                  E          sur la datasheet !)
                                  │
  Pi patte 6 (GND) ───────────────┴───────── fil BLANC de la fiche (GND)
```

Ici l'alimentation d'établi reste à **5,0 V**. Le 5 V n'atteint jamais le Pi :
il s'arrête au collecteur du transistor. Ce montage est plus lent qu'un
74AHCT125 : il marche souvent bien, mais c'est un dépannage.

> Dans les deux cas, le reste (logiciel, installation, Krita) ne change pas.

> **Pourquoi « AHCT » et pas « HC » ?** Les lettres **T** (comme dans HCT,
> AHCT) veulent dire que la puce accepte des entrées « faibles » de 3,3 V même
> quand elle est alimentée en 5 V. Un 74**HC**125, lui, ne serait pas plus
> malin que les LED. Vérifiez bien les lettres écrites sur la puce.

---

## 5. Les 5 règles d'or

1. **5 volts, pas plus.** Au-delà de 5,5 V, les LED grillent. On règle
   l'alimentation d'établi **avant** de brancher.
2. **Jamais le 5 V du Pi vers la matrice.** Les pattes 2 et 4 du Pi (5 V)
   ne sont reliées à **rien**. La matrice est alimentée **uniquement** par
   l'alimentation d'établi.
3. **Jamais de 5 V sur une broche du Pi.** Seule la patte 12 (GPIO 18) et la
   patte 6 (GND) sont branchées. Le 5 V arrive à la puce, pas au Pi.
4. **Toutes les masses (GND) reliées ensemble** : Pi, puce, matrice et
   alimentation d'établi.
5. **On câble hors tension**, Pi éteint, et on fait vérifier avant d'allumer.

---

## 6. Brancher, étape par étape

![Schéma de branchement](schemas/branchement.svg)

> **Sans 74AHCT125 ?** Cette partie décrit le montage avec la puce. Pour la
> solution A (matrice en 4,4 V), suivez l'étape A ci-dessous en réglant
> l'alimentation sur **4,4 V**, puis le [schéma de la solution A](schemas/branchement_sans_puce.svg) :
> 3 fils seulement entre la fiche et le Pi, pas de plaque d'essai.

**Tout est débranché** : alimentation d'établi éteinte, Pi sans son bloc
secteur.

### Étape A : l'énergie de la matrice

Exactement comme avec l'Arduino ([README Arduino, parties 5 et 6 A](../matrice_8x32/README.md#5-régler-lalimentation-détabli)) :

1. Réglez l'alimentation d'établi sur **5,0 V**, limite de courant **3 A**,
   puis éteignez-la.
2. Cordon **rouge** : borne **+** → fil **rouge** du milieu de la matrice.
3. Cordon **noir** : borne **−** → fil **noir** du milieu.
4. **Condensateur 1000 µF** entre ces deux fils (bande « − » côté noir).

### Étape B : la puce sur la plaque d'essai

5. Enfoncez le **74AHCT125** à cheval sur la **rainure centrale** de la plaque
   d'essai, encoche à gauche. (Chaque patte doit avoir sa propre rangée de
   trous ; sans la rainure, les pattes d'en face seraient reliées entre elles.)
6. Branchez la **fiche** sur le connecteur **`DIN`** de la matrice.
7. Fil **rouge** de la fiche → rangée de la **patte 14** (VCC).
   *Avec l'Arduino, ce fil restait isolé. Ici, il apporte le 5 V de la matrice
   à la puce. Une puce consomme à peine quelques milliampères : aucun risque.*
8. Fil **blanc** de la fiche → une **ligne de masse** de la plaque d'essai
   (la bande bleue « − » sur le côté).
9. Patte **7** (GND) → ligne de masse (fil mâle-mâle).
10. Patte **1** (1OE) → ligne de masse (fil mâle-mâle).
11. **Résistance 330 Ω** : une patte dans la rangée de la **patte 3** (1Y),
    l'autre dans une rangée libre.
12. Fil **vert** de la fiche → la rangée libre de la résistance.

### Étape C : le Raspberry Pi

Le connecteur du Pi a **40 pattes** sur deux rangées. La **patte 1** est celle
qui a une **pastille carrée** au dos du circuit, dans le coin. Les pattes
**impaires** (1, 3, 5…) sont sur la rangée intérieure, les **paires** (2, 4,
6…) sur la rangée du bord.

```
           bord de la carte
    ┌──────────────────────────────────────
    │  2   4   6   8  10  12  14  …  40      ← rangée du bord (paires)
    │ 5V  5V GND          GPIO18
    │  1   3   5   7   9  11  13  …  39      ← rangée intérieure (impaires)
    │ 3V3
```

13. Fil femelle-mâle : patte **6** (GND) du Pi → ligne de masse de la plaque.
14. Fil femelle-mâle : patte **12** (GPIO 18) du Pi → rangée de la **patte 2**
    (1A) de la puce.

### Étape D : vérifier

- [ ] Alimentation d'établi réglée sur 5,0 V, limite de courant réglée
- [ ] + rouge → fil rouge du milieu ; − noir → fil noir du milieu ; condensateur dans le bon sens
- [ ] Fiche sur **`DIN`** (pas `DOUT`)
- [ ] Puce à cheval sur la rainure, **encoche à gauche**
- [ ] Rouge de la fiche → patte 14 ; blanc → masse
- [ ] Pattes 1 et 7 → masse
- [ ] Patte 3 → 330 Ω → vert de la fiche
- [ ] Pi : patte 12 → patte 2 de la puce ; patte 6 → masse
- [ ] **Rien** sur les pattes 1, 2, 4 (3,3 V et 5 V) du Pi
- [ ] Montage vérifié par l'encadrant

### Ordre d'allumage et d'extinction

| Allumer | Éteindre |
|---|---|
| 1. l'alimentation d'établi | 1. arrêter le Pi proprement (`sudo poweroff`), attendre que la LED verte s'éteigne |
| 2. puis le bloc secteur du Pi | 2. débrancher le bloc secteur du Pi |
| | 3. éteindre l'alimentation d'établi |

> **Bonus du montage** : la puce est alimentée **par la matrice** (fil rouge
> de la fiche). Si l'alimentation d'établi est éteinte, la puce l'est aussi et
> ne fait plus passer le signal : la première LED est protégée.

---

## 7. Préparer le Raspberry Pi

C'est l'objet d'un guide à part : **[INSTALLATION_PI.md](INSTALLATION_PI.md)**.
En résumé :

1. installer **Raspberry Pi OS Lite** sur la carte SD avec **Raspberry Pi Imager** ;
2. se connecter au Pi depuis son ordinateur (**SSH**) ;
3. copier ce dossier sur le Pi ;
4. lancer `bash installation/installer.sh`, qui installe tout le reste.

Comptez une heure la première fois.

---

## 8. Premier allumage : le test

Sur le Pi (connecté en SSH), dans le dossier du projet :

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

> **Pourquoi `sudo` ?** Pour envoyer un signal aussi rapide et précis
> (800 000 bits par seconde), la bibliothèque utilise directement des
> circuits internes du Pi. Linux réserve cet accès à l'**administrateur** :
> `sudo` veut dire « exécuter en tant qu'administrateur ».

Le test se déroule en trois temps (voir [`test_matrice.py`](test_matrice.py)) :

**1. Les coins** (5 secondes). La matrice est **posée debout**, comme dans
la vitrine, **face LED vers vous** (réglage `ROTATION = 90` dans
[`matrice.py`](matrice.py)). On doit voir :

```
   ROUGE ● · · · · · · ● VERT
         · · · · · · · ·
         · · · · · · · ·      (32 lignes)
         · · · · · · · ·
   BLEU  ● · · · · · · ● BLANC
```

| Ce que vous voyez | Ce qu'il faut faire, dans [`matrice.py`](matrice.py) |
|---|---|
| Rouge en haut à gauche, vert en haut à droite | rien, c'est parfait ✅ |
| Rouge et vert inversés (gauche ↔ droite) | `INVERSER_X = True` |
| Rouge et vert en bas | `INVERSER_Y = True` |
| Les deux à la fois (image à l'envers) | les deux à `True` |
| Les couleurs sont sur les **grands côtés** (la matrice affiche « couché ») | `ROTATION` n'est pas à 90 : corrigez-la |

> **Matrice couchée** (à l'horizontale, 32 de large × 8 de haut) : mettez
> `ROTATION = 0`. Tout le reste (Krita, lecteur, page web) suit
> automatiquement : les images se dessinent alors en 32 × 8.

Pour modifier le fichier sur le Pi : `nano matrice.py`, changez la ligne,
puis **Ctrl + O**, **Entrée** (enregistrer) et **Ctrl + X** (quitter).

**2. Le serpentin** : un point orange parcourt les 256 LED dans l'ordre de la
chaîne.

**3. Les couleurs pleines** : rouge, vert, bleu, puis blanc. Si le rouge
apparaît vert, l'ordre des couleurs est faux (voir partie 11).

---

## 9. Jouer les animations

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

Le lecteur joue en boucle, **par ordre alphabétique**, tout ce qu'il trouve
dans le dossier des animations :

| Format | Exemple | Remarque |
|---|---|---|
| GIF animé | `01_coeur_qui_bat.gif` | le plus simple ; la vitesse est dans le fichier |
| PNG animé (APNG) ou WebP animé | `04_balle.png` | plus de couleurs que le GIF |
| Séquence de PNG | `03_vague/` contenant `vague_0000.png`, `vague_0001.png`… | la vitesse est dans `images_par_seconde.txt` (sinon 12) |
| Image fixe | `logo.png` | affichée 10 secondes |

Le dossier lu est **`/boot/firmware/animations`** (ou **`/boot/animations`**
sur Raspbian 11, comme sur le Pi de l'école) s'il existe : il est créé par
l'installation, voir [MODE_VITRINE.md](MODE_VITRINE.md). Sinon, c'est le dossier
[`animations`](animations/) à côté du programme. Il est **relu à chaque tour** :
on peut ajouter un GIF pendant que ça tourne.

Pour arrêter : **Ctrl + C**.

Les réglages sont en haut de [`lecteur.py`](lecteur.py) (durée minimum par
animation, pause entre deux, horaires) et de [`matrice.py`](matrice.py) :

| Réglage | Fichier | Valeur | À quoi ça sert |
|---|---|---|---|
| `LUMINOSITE` | matrice.py | `40` | de 0 à 255 ; montez en plein jour, en vitrine |
| `COURANT_MAX_MA` | matrice.py | `2500` | un peu **sous** la limite de l'alimentation |
| `ROTATION` | matrice.py | `90` | `90` = matrice debout (image 8 × 32), `0` = couchée (32 × 8) |
| `INVERSER_X`, `INVERSER_Y` | matrice.py | `False` | sens de l'image (partie 8) |
| `GAMMA` | matrice.py | `2.2` | correction des couleurs (1.0 = aucune) |
| `DUREE_MINIMUM` | lecteur.py | `10` | une animation courte est rejouée pendant au moins 10 s |
| `HORAIRES` | lecteur.py | `None` | ex. `("09:00", "22:30")` |

### Sans matériel : le simulateur

Sur **n'importe quel ordinateur** avec Python et Pillow (voir
[GUIDE_KRITA.md, partie 7](GUIDE_KRITA.md#7-prévisualiser-sur-son-ordinateur)) :

```bash
python3 lecteur.py --simulateur
```

Une fenêtre s'ouvre avec 256 ronds de couleur qui imitent la matrice.

---

## 10. L'interface web : piloter la vitrine depuis un navigateur

Le Pi fait aussi tourner un **petit site web**. Depuis un ordinateur ou un
téléphone connecté au même réseau, on ouvre l'adresse du Pi dans un
navigateur, et on gère la vitrine sans terminal ni carte SD.

![L'interface web, sur le Pi de l'école](schemas/interface_web.png)

### Ce qu'on peut faire

| Action | Comment |
|---|---|
| **Déposer** des GIF, PNG animés, WebP, images fixes | cadre « Un ou plusieurs fichiers » |
| **Déposer une séquence de PNG** exportée de Krita | cadre « Une séquence de PNG » (+ nom et images/s) |
| **Voir un aperçu animé** de chaque animation | il est fabriqué comme le lecteur verra l'image (taille adaptée, rotation) |
| **Changer l'ordre** de lecture | ▲ ▼ (les fichiers sont renumérotés `01_`, `02_`…) |
| **Retirer** une animation de la boucle, sans la supprimer | ⏸ (elle passe dans « Pas jouées ») ; ＋ pour la remettre |
| **Jouer tout de suite** une animation, ou **passer** à la suivante | ▶ et **Suivante ⏭** |
| **Supprimer** | ✕ : elle va à la corbeille ; « Vider » efface pour de bon |
| **Savoir ce que joue la matrice** | en haut de la page, mis à jour toutes les 2 secondes |

Chaque fichier envoyé est **ouvert et vérifié** avant d'être accepté : un
fichier abîmé ou d'un format inconnu est refusé, une mauvaise taille est
signalée par ⚠. Les noms sont nettoyés (pas d'accents ni d'espaces).

### L'adresse de la page

Le Pi de l'école a **deux adresses**, une par réseau. Le réseau Wi-Fi et le
réseau filaire de l'école ne communiquent pas entre eux : prenez celle de
**votre** réseau.

| Vous êtes connecté… | Adresse |
|---|---|
| en **Wi-Fi** (téléphone, portable) | **http://172.16.50.27** |
| par **câble** | http://172.16.7.199 |

Ces adresses sont distribuées par le réseau et **peuvent changer** : les
adresses du moment sont toujours écrites **en bas de la page web**, et
`hostname -I` les affiche sur le Pi.

### Comment c'est construit

Deux programmes tournent **en même temps**, chacun dans son propre
**service** (un programme que Linux lance au démarrage et relance s'il
s'arrête) :

```
  téléphone / ordinateur
          │  (réseau, page web)
          ▼
  serveur_web.py ──── range les fichiers ───▶  /boot/animations/
  service vitrine-web                            01_…, 02_…, .desactivees/, .corbeille/
          │                                              │
          │ « post-it » dans /run/vitrine-pixels/        │ relu à chaque tour
          │ (jouer maintenant, suivante, en cours)       ▼
          └──────────────────────────────────▶  lecteur.py ──▶ matrice
                                                 service vitrine-pixels
```

- [`serveur_web.py`](serveur_web.py) est écrit avec **Flask**, une
  bibliothèque Python pour fabriquer des sites web. La page elle-même est dans
  [`web/page.html`](web/page.html), son style dans [`web/style.css`](web/style.css).
- Le serveur **ne parle jamais à la matrice** : il range les fichiers dans le
  dossier des animations, et laisse des « post-it » (de tout petits fichiers,
  en mémoire vive) que le lecteur consulte en permanence. Ainsi, une erreur
  dans la page web ne peut pas figer la vitrine.
- « Pas jouées » et la corbeille sont des sous-dossiers dont le nom commence
  par un point (`.desactivees`, `.corbeille`) : le lecteur les ignore.

### Démarrer, arrêter, surveiller

L'installation (`installation/installer.sh`) installe les deux services, et
**active l'interface web** tout de suite. Le lecteur, lui, s'active à la main
une fois la matrice testée (partie 8).

| Je veux… | Commande (sur le Pi) |
|---|---|
| activer le lecteur au démarrage | `sudo systemctl enable --now vitrine-pixels` |
| savoir si l'interface web tourne | `systemctl status vitrine-web` |
| la relancer (après une modification) | `sudo systemctl restart vitrine-web` |
| voir ses messages et erreurs en direct | `journalctl -u vitrine-web -f` |
| la lancer à la main, pour tester | `sudo systemctl stop vitrine-web` puis `sudo ~/vitrine-env/bin/python serveur_web.py` |

**Sur son ordinateur**, sans Pi : `python3 serveur_web.py --port 8080`, puis
ouvrir <http://localhost:8080>. Avec `python3 lecteur.py --simulateur` dans un
autre terminal, la fenêtre du simulateur réagit aux boutons de la page.
(Il faut Flask : `pip install flask`.)

### Réglages et sécurité

En haut de [`serveur_web.py`](serveur_web.py) :

| Réglage | Valeur | À quoi ça sert |
|---|---|---|
| `MOT_DE_PASSE` | `None` | ⚠️ sans mot de passe, **toute personne sur le réseau** peut ajouter ou supprimer des animations. Ex. `"pixels"` : le navigateur le demandera |
| `PORT` | `80` | le port web habituel ; un autre port s'ajoute à l'adresse (`http://172.16.50.27:8080`) |
| `TAILLE_MAX_MO` | `50` | taille maximum d'un envoi |

> **Avec la protection contre les coupures de courant** (overlay, voir
> [MODE_VITRINE.md](MODE_VITRINE.md#4-survivre-aux-coupures-de-courant)), si la
> partition de démarrage est protégée en écriture, la page ne peut plus rien
> modifier : elle affiche une erreur, mais « jouer » et « suivante » marchent
> toujours.

Le mode d'emploi détaillé, pour l'équipe design, est dans
**[INTERFACE_WEB.md](INTERFACE_WEB.md)**.

---

## 11. Ça ne marche pas ?

| Symptôme | Causes probables | Solution |
|---|---|---|
| **Rien ne s'allume** | Fiche sur `DOUT` au lieu de `DIN` | Changer de côté |
| | Alimentation d'établi éteinte | L'allumer, activer `OUTPUT` (la puce aussi est alimentée par là) |
| | Puce à l'envers | Encoche à gauche, patte 1 en bas à gauche |
| | Fil sur la mauvaise patte du Pi | Patte **12** = GPIO 18 ; recompter depuis la patte 1 |
| | Pas de GND commun | Patte 6 du Pi, patte 7 et patte 1 de la puce, fil blanc : tous sur la même ligne de masse |
| **`ws2811_init failed`** ou **`Permission denied`** | Programme lancé sans `sudo` | Ajouter `sudo` devant la commande |
| **`ModuleNotFoundError: rpi_ws281x`** | Mauvais Python | Utiliser `~/vitrine-env/bin/python`, pas `python3` |
| | Installation incomplète | Relancer `bash installation/installer.sh` |
| **Le simulateur s'ouvre au lieu de la matrice** | Même cause : `rpi_ws281x` introuvable | Idem |
| **La page web ne s'ouvre pas** | Mauvaise adresse pour votre réseau (Wi-Fi ou câble) | Voir partie 10 ; adresses du moment : `hostname -I` |
| **Un GIF s'affiche en morceaux ou avec un fond coloré** | Pillow trop ancienne dans `~/vitrine-env` | `~/vitrine-env/bin/pip install --upgrade pillow`, puis relancer les services |
| **Ça marche, puis tout se fige ou scintille quand on branche un casque / lance un son** | La sortie audio utilise le même circuit que GPIO 18 | Vérifier `dtparam=audio=off` dans `/boot/firmware/config.txt`, redémarrer |
| **Couleurs aléatoires, scintillement** | Puce absente ou de type HC (sans T) | Vérifier les lettres sur la puce |
| | Montage sans puce (solution A) | Baisser encore un peu l'alimentation (4,2 V), raccourcir le fil vert, ou passer à la solution B |
| **Rien ne s'allume avec le transistor** (solution B) | `INVERSER_SIGNAL` oublié, ou transistor à l'envers | `INVERSER_SIGNAL = True` dans `matrice.py` ; vérifier E-B-C |
| | Masse mal serrée | Revérifier toutes les masses |
| **Couleurs fausses** (rouge ↔ vert) | Ordre des couleurs | Dans `matrice.py`, remplacer `WS2811_STRIP_GRB` par `WS2811_STRIP_RGB` |
| **Les couleurs sombres de mon dessin n'apparaissent pas** | Normal : correction gamma + luminosité faible | Voir [GUIDE_KRITA.md, partie 5](GUIDE_KRITA.md#5-ce-qui-change-entre-lécran-et-les-led) |
| **Un fichier est sauté** (`✗ impossible de lire`) | Fichier abîmé ou format inconnu (MP4, KRA…) | Réexporter en GIF ou PNG |
| **La matrice devient orangée quand tout s'allume** | L'alimentation atteint sa limite (voyant `CC`) | Baisser `LUMINOSITE` ou `COURANT_MAX_MA` |
| **Le Pi redémarre tout seul, éclair jaune à l'écran** | Bloc secteur du Pi trop faible | Utiliser le bloc officiel |
| **Ça chauffe, ça sent le brûlé** | Court-circuit, condensateur ou puce à l'envers | **Tout couper immédiatement**, appeler l'encadrant |

Pour voir ce que fait le lecteur quand il tourne tout seul (mode vitrine) :
`journalctl -u vitrine-pixels -f` (voir [MODE_VITRINE.md](MODE_VITRINE.md)).

---

## 12. Petit lexique

| Mot | Signification |
|---|---|
| **Raspberry Pi** | Petit ordinateur complet sur une seule carte |
| **Raspberry Pi OS** | Le système d'exploitation du Pi (une version de Linux) |
| **Carte SD** | Le « disque dur » du Pi : système, programmes et animations |
| **GPIO** | *General Purpose Input/Output* : les pattes du Pi qu'on peut commander par programme |
| **3,3 V / 5 V** | Les deux niveaux électriques en jeu : celui du Pi et celui des LED |
| **Adaptateur de niveau** | Puce qui traduit un signal 3,3 V en 5 V (ici le 74AHCT125) |
| **DIP 14** | Boîtier de puce à 14 pattes, en deux rangées, qui s'enfiche dans une plaque d'essai |
| **SSH** | Moyen de « taper des commandes » sur le Pi depuis un autre ordinateur, par le réseau |
| **Terminal** | Fenêtre où l'on tape des commandes au lieu de cliquer |
| **sudo** | « Exécuter en tant qu'administrateur » |
| **Python** | Le langage de programmation utilisé ici |
| **Bibliothèque** | Code écrit par d'autres qu'on réutilise (Pillow pour les images, rpi_ws281x pour les LED) |
| **Environnement virtuel** | Une boîte qui contient les bibliothèques Python du projet (`~/vitrine-env`) |
| **Service** | Programme que Linux lance tout seul au démarrage, et relance s'il s'arrête |
| **Correction gamma** | Calcul qui adapte les couleurs d'un écran à la façon dont les LED émettent la lumière |
| **GIF, APNG, WebP** | Formats d'images animées |
| **Serpentin** | Câblage en zigzag des LED : une colonne descend, la suivante remonte |

---

## 13. Les fichiers du dossier

| Fichier | Pour qui | Contenu |
|---|---|---|
| [README.md](README.md) | électronique | ce document |
| [INSTALLATION_PI.md](INSTALLATION_PI.md) | électronique | préparer la carte SD et le Pi, pas à pas |
| [GUIDE_KRITA.md](GUIDE_KRITA.md) | design | dessiner, exporter, vérifier pour la matrice |
| [MODE_VITRINE.md](MODE_VITRINE.md) | tous | démarrage automatique, changer les animations, entretien |
| [INTERFACE_WEB.md](INTERFACE_WEB.md) | tous | la page web : déposer, ordonner, activer, jouer les animations |
| [CODER_EN_PYTHON.md](CODER_EN_PYTHON.md) | code | créer des animations en Python ; comparaison avec l'Arduino |
| [`matrice.py`](matrice.py) | | le moteur : réglages, `XY()`, gamma, vraie matrice et simulateur |
| [`lecteur.py`](lecteur.py) | | joue les animations du dossier en boucle |
| [`serveur_web.py`](serveur_web.py) | | l'interface web (Flask) : dépôt et choix des animations |
| [`web/`](web/) | | la page web : `page.html`, `infos.html`, `style.css` |
| [`test_matrice.py`](test_matrice.py) | | test de branchement et d'orientation |
| [`mes_animations.py`](mes_animations.py) | | les animations de l'Arduino, traduites en Python |
| [`animations/`](animations/) | | exemples : GIF, séquence de PNG, APNG |
| [`schemas/`](schemas/) | | schémas de branchement, brochage de la puce, chaîne Krita → matrice, capture de l'interface web |
| `apercus/` | design | créé par `verifier_animation.py` : aperçus « façon LED » à partager |
| [`krita/palette_vitrine_pixels.gpl`](krita/palette_vitrine_pixels.gpl) | design | palette de couleurs adaptée aux LED, à importer dans Krita |
| [`outils/verifier_animation.py`](outils/verifier_animation.py) | design | vérifie un export et crée un aperçu « façon LED » |
| [`outils/generer_exemples.py`](outils/generer_exemples.py) | | recrée les exemples et la palette |
| [`outils/schemas.py`](outils/schemas.py) | | redessine les schémas du dossier `schemas/` |
| [`installation/`](installation/) | électronique | script d'installation, services de démarrage automatique (lecteur et interface web) |

---

## Pour aller plus loin

- **La matrice finale 7 × 39** : changez `COLONNES_PANNEAU`,
  `LIGNES_PANNEAU` et, si besoin, `ROTATION` dans `matrice.py` ; il faudra une
  alimentation 5 V de 10 A environ.
- **Plusieurs matrices** : la bibliothèque sait piloter deux chaînes à la fois
  (GPIO 18 et GPIO 13).
- **Interactivité** : la page web sait déjà déclencher une animation. Sur le
  même principe (un « post-it » pour le lecteur), un bouton ou un capteur de
  présence branché sur le Pi pourrait en déclencher une quand quelqu'un passe.