cctweaked_drone/README.md

# Drone V2 : quadricoptere Create Aeronautics / CC:Tweaked

Reecriture complete, concue contre les oscillations permanentes de
la V1. Installation: copier drone.lua puis `drone maj <url_base>`
(Forgejo raw, domaine autorise dans la config http de CC:Tweaked).

## Pourquoi la V1 oscillait, et les parades de la V2

1. QUANTIFICATION: les RSC acceptent des rpm ENTIERS. A ~20 rpm de
   sustentation, 1 rpm = 5% de poussee par coin: aucun regulateur ne
   peut converger, il ne peut qu'osciller autour (cycle limite).
   PARADE MATERIELLE FORTEMENT RECOMMANDEE: engrener les helices
   pour que la sustentation tombe vers 60-100 rpm (meme poussee,
   3 a 5 fois plus de resolution de commande).
2. RETARD DE BOUCLE (ticks, transitions de rotation): la calibration
   par RELAIS mesure la periode ultime REELLE retard compris, et
   TYREUS-LUYBEN laisse ~3x de marge de gain: stabilite garantie
   pour la dynamique identifiee.
3. BRUIT DE MESURE: derivee FILTREE dans le PID; vitesse verticale
   par velocity sensor AUTO-DETECTE a la calib altitude (repli:
   derivee filtree de l'altitude).
3b. ANTI-CLAQUAGE: la boucle de vitesse est bornee a +-DELTA_MAX
   (60%) du rpm de sustentation, son integrale a 30%, et la base
   est limitee en PENTE (2x la sustentation par seconde: les
   helices ont un temps de transition reel, mesure et journalise
   par la calib altitude). Le passage brutal de 0 a pleine
   puissance est structurellement impossible; l'autorite d'assiette
   n'est jamais detruite par un ecretage a zero.
4. FILET DE SECURITE: un SUPERVISEUR detecte l'oscillation de
   chaque boucle en vol (passages a zero repetes au-dela d'un seuil
   d'amplitude) et reduit ses gains de 20% automatiquement, avec
   journalisation et persistance: meme mal regle, le systeme
   converge vers la stabilite.

## Modes

- `off` : moteur coupe, RSC a 0
- `sol` : moteur allume, RSC a 0
- `stationnement` : helices a pleine puissance INVERSEE (plaquage),
  propulseurs a 0. Entree: au sol (optical <= DIST_SOL) ET
  horizontal (<= ANGLE_MAX). Sortie AUTO vers vol si perdu.
- `vol` : assiette horizontale, altitude vers la consigne (+-1/+-10
  au moniteur), deplacements au joystick (propulseurs
  differentiels avance/virage)
- `atterrissage` : descente a VITESSE_ATTERRISSAGE puis
  stationnement. La verification d'un sol posable est au pilote.

## Regulation

- ALTITUDE en cascade: erreur -> vitesse verticale cible (P bornee
  V_MONTEE_MAX / V_DESCENTE_MAX) -> PID vitesse -> delta rpm autour
  du rpm de sustentation MESURE (corrige par la pression).
  Adaptation lente a la charge en quasi-stationnaire.
- ASSIETTE: PID par axe, derivee filtree, autorite bornee a
  ASSIETTE_PLAFOND * rpm de sustentation.
- MOTEUR: bouton on/off ou adaptatif au moniteur. En adaptatif, le
  besoin est PREVU (coefficients su/rpm mesures pendant la calib
  rsc) et le niveau est regle AVANT l'ecriture des RSC en montee de
  regime, apres en descente; garde: besoin borne a capacite max *
  SECURITE.

## Calibrations (onglet CALIB), dans l'ordre

1. `gimbal` (mode sol): a plat, nez bas, a plat, penche a gauche.
2. `joystick` (mode sol): pousser a fond dans chaque direction.
3. `rsc` (mode sol): chaque RSC tourne a RPM_MANUEL, toucher sur
   l'art la position qui tourne; mesure AUSSI les coefficients
   su/rpm, la capacite moteur par niveau (mode adaptatif) et
   l'association helice <-> speedometer.
3b. `boite` (mode sol, optionnelle, rsc requis): association de
   CHAQUE face du second relay a SON helice (chaque helice tourne a
   son tour; la face dont le signal 13 = rapport 2/16 reduit la
   vitesse lue par le speedometer de cette helice est la sienne).
   En vol, le meme signal est ecrit sur les 4 faces: rapport
   identique sur les 4 helices, indispensable a la symetrie.
4. `altitude` (mode sol, AUTO-AMORCANTE): rampe lente jusqu'au
   decollage -> rpm de sustentation MESURE. Si les boites sont
   calibrees: retour au sol, CHOIX DU RAPPORT (k = plus petit k/16
   tel que la sustentation RSC <= BOITE.RSC_CIBLE, soit ~70% de la
   plage avec x1.4 de marge de montee), re-decollage au rapport
   definitif, verification par speedometer. Puis gains d'assiette
   par defaut dimensionnes, detection du velocity sensor vertical,
   relais d'Astrom-Hagglund sur la boucle de vitesse -> gains
   Tyreus-Luyben, retour au sol automatique.
5. `inclinaison` (mode vol, stationnaire): relais par axe ->
   gains Tyreus-Luyben.

Toutes re-executables; gains persistes en surcharges, visibles et
retouchables page PARAM (parametrage manuel guide). Le superviseur
peut ensuite les affiner a la baisse en vol si necessaire.

## Affichages

- Moniteur: onglets MODE / CALIB / PARAM / JOURNAL, echelle de
  texte auto, art du quadricoptere (blanc 0, rouge max, jaune en
  changement, vert stable, violet en calibration), autonomie en
  minutes, choix du regime moteur.
- Conduite (2x22): ALT reelle > consigne, VIT globale
  (sqrt(v1^2+v2^2+v3^2)); messages longs en segments de mots.
- Carburant (2x4): pourcentage de reserve.

## Boites de vitesse (analog transmission, optionnelles)

Une par helice, CHACUNE sur SA face du second redstone relay
(association apprise par la calib boite), plus un speedometer par
helice. Le meme signal est ecrit sur les 4 faces: rapport identique
pour les 4, indispensable a la symetrie. Rapport = (15-signal)/16
(signal 0 = 1/1; signal 15 INTERDIT = rapport 0). Interet: a ~20 rpm
de sustentation, 1 rpm RSC entier = 5%% de poussee (oscillation
inevitable); au rapport 2/16 la sustentation RSC passe a ~160 rpm et
la resolution est multipliee par 8.

BOITE AUTOMATIQUE: le regulateur travaille en RPM HELICE (unites
physiques); la conversion RSC = helice / rapport n'a lieu qu'a la
frontiere de l'actionneur. Le gain de boucle est donc INVARIANT au
rapport: les gains calibres une fois valent a tous les rapports. En
vol, si la commande RSC des helices sort de la bande [RSC_BAS,
RSC_HAUT] (charge accrochee en vol, perte de poussee en altitude),
le rapport change d'UN cran, uniquement en quasi-stationnaire et a
plat, avec ATTENTE de temps mort, et dans un ORDRE SUR: le
transitoire d'un tick est toujours un CREUX de poussee symetrique
(jamais un pic): montee de k = RSC reecrits puis redstone; descente
= redstone puis RSC. k=15 est saute (signal 15 = rapport 0,
interdit). Les speedometers surveillent en continu que vitesse
reelle = commande * rapport (ecart > 25%% persistant 2 s -> alerte
BOITES INCOHERENTES + reassertion du signal).

## Renumerotation des relays

Les NOMS des peripheriques peuvent changer a la reconnexion du
reseau; les FACES des relays sont stables. Si les noms stockes ne
correspondent plus au reseau, les modes de vol sont verrouilles et
la REIDENTIFICATION AUTOMATIQUE se lance en mode sol (~3 s:
l'helice lf tourne a bas regime, le signal 13 sur sa face designe
le relay des boites via le speedometer; le joystick est l'autre
relay). Aucune action manuelle.

Non utilises: GPS, typewriter.