From 2cbbfa1466f53ed5d01064c7f224b4b36f1ac70b Mon Sep 17 00:00:00 2001 From: nicoboy Date: Sat, 1 Aug 2026 17:40:14 +0200 Subject: [PATCH] Documente le protocole UART ESP32 <-> TMS320 Cablage, parametres UART, format des trames telemetrie/commande et calcul du checksum, a l'usage de la programmation du firmware TMS320. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01StKu9rqrsdz8CAVt1XMxon --- doc/ESP32-UART.md | 136 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 doc/ESP32-UART.md diff --git a/doc/ESP32-UART.md b/doc/ESP32-UART.md new file mode 100644 index 0000000..3311d46 --- /dev/null +++ b/doc/ESP32-UART.md @@ -0,0 +1,136 @@ +# Liaison UART ESP32-C3 <-> TMS320 + +Ce document decrit le protocole que le firmware TMS320 doit implementer +pour dialoguer avec l'ESP32-C3 (cote ESP32 deja fonctionnel, voir +`src/tms_link.cpp` / `include/protocol.h`). Le TMS320 envoie sa telemetrie +periodiquement, et recoit periodiquement les commandes de l'operateur. + +## Cablage + +| Signal | ESP32-C3 (config.h) | TMS320 | +|---|---|---| +| ESP32 TX -> TMS320 RX | GPIO7 | RX | +| ESP32 RX <- TMS320 TX | GPIO6 | TX | +| GND commun | GND | GND | + +A verifier avant de cabler : le TMS320 doit etre en logique 3,3V (comme +l'ESP32-C3). Si sa liaison serie sort en 5V, prevoir un level shifter +avant de relier les deux cartes. + +## Parametres UART + +- Vitesse : **115200 bauds** +- Format : **8N1** (8 bits de donnees, pas de parite, 1 bit de stop) +- Cote ESP32 : `Serial1`, defini dans `TmsLink::begin()` + (`src/tms_link.cpp`) + +## Format des trames + +Protocole ASCII texte, inspire du format NMEA, terminé par `\n` (LF). +Chaque trame est encadree par `$` ... `*XX`, ou `XX` est un checksum XOR +en hexadecimal (2 chiffres, majuscules). + +### Telemetrie : TMS320 -> ESP32 (periodique) + +``` +$T,FREQ1=100000,FREQ2=100000,DUTY1=45.2,DUTY2=50.0,VIN=400.5,IIN=1.20,V1=200.3,I1=2.50,T1=45.2,VOUT=200.1,I2=2.48,T2=44.8,IOUT=1.05*7A +``` + +Champs (`TAG=valeur`, separes par des virgules, ordre libre) : + +| Tag | Unite | Description | +|---|---|---| +| `FREQ1` | Hz | Frequence de decoupage etage 1 | +| `FREQ2` | Hz | Frequence de decoupage etage 2 | +| `DUTY1` | % | Rapport cyclique etage 1 | +| `DUTY2` | % | Rapport cyclique etage 2 | +| `VIN` | V | Tension d'entree | +| `IIN` | A | Courant d'entree | +| `V1` | V | Tension etage 1 | +| `I1` | A | Courant shunt MOSFET etage 1 | +| `T1` | °C | Temperature NTC etage 1 | +| `VOUT` | V | Tension de sortie (sortie boost, etage 2) | +| `I2` | A | Courant shunt MOSFET etage 2 | +| `T2` | °C | Temperature NTC etage 2 | +| `IOUT` | A | Courant de sortie | + +**Frequence d'envoi recommandee : toutes les 200-500 ms.** L'ESP32 +considere la liaison perdue (`TMS:KO` affiche sur l'OLED/web) si aucune +trame `$T,...*XX` valide n'est recue depuis plus de **2 secondes** +(`TmsLink::linkOk()`). + +Tous les champs sont optionnels a l'envoi individuel (un champ absent +garde sa derniere valeur connue cote ESP32), mais en pratique il est plus +simple d'envoyer tous les champs a chaque trame. + +### Commande : ESP32 -> TMS320 (periodique + a chaque changement) + +``` +$C,HT=1,PWM1=1,PWM2=0*3E +``` + +| Tag | Valeurs | Description | +|---|---|---| +| `HT` | 0 ou 1 | Sortie HT activee/desactivee | +| `PWM1` | 0 ou 1 | PWM etage 1 activee/desactivee | +| `PWM2` | 0 ou 1 | PWM etage 2 activee/desactivee | + +L'ESP32 envoie cette trame toutes les **500 ms**, et immediatement a +chaque changement d'etat depuis l'IHM (OLED/web). Le TMS320 doit +simplement appliquer le dernier etat recu et valide (checksum correct). + +## Calcul du checksum + +XOR de tous les octets entre `$` et `*` (exclus), formate en hexadecimal +majuscule sur 2 chiffres (`%02X`). + +Exemple en C pour une trame a construire : + +```c +uint8_t checksum_of(const char *s, int len) { + uint8_t cs = 0; + for (int i = 0; i < len; i++) cs ^= (uint8_t)s[i]; + return cs; +} + +// Construction d'une trame telemetrie : +char body[128]; +int n = sprintf(body, "T,FREQ1=%.0f,FREQ2=%.0f,DUTY1=%.1f,DUTY2=%.1f," + "VIN=%.1f,IIN=%.2f,V1=%.1f,I1=%.2f,T1=%.1f," + "VOUT=%.1f,I2=%.2f,T2=%.1f,IOUT=%.2f", + freq1, freq2, duty1, duty2, vin, iin, v1, i1, t1, vout, i2, t2, iout); +uint8_t cs = checksum_of(body, n); +char frame[160]; +sprintf(frame, "$%s*%02X\n", body, cs); +// envoyer frame sur l'UART +``` + +Pour la reception des trames `$C,...*XX` : appliquer le meme calcul sur +la partie entre `$` et `*`, comparer au checksum recu, et ignorer la +trame si ca ne correspond pas (trame corrompue). + +## Cote ESP32 : ce qui existe deja + +- `include/protocol.h` : structures `Telemetry` et `CommandState`, + description du protocole (source de verite en cas de doute). +- `src/tms_link.cpp` : parsing des trames `$T,...`, envoi des trames + `$C,...`, gestion du timeout de liaison. Contient aussi + `updateSimulation()`, qui simule des valeurs realistes (utile comme + reference de plage de valeurs attendues : `Vin` ~400V, `Iin` ~1.2A, + `V1`/`Vout` ~200V, `I1`/`I2` ~2.5A, `T1`/`T2` ~40°C). +- `include/config.h` : `TMS_DUMMY_MODE` (actuellement `true`) fait + tourner l'ESP32 sur la simulation interne au lieu de lire l'UART reel. + **A passer a `false` une fois le firmware TMS320 pret et teste**, pour + activer la reception reelle des trames `$T,...*XX`. + +## Points de vigilance + +- Le format hexadecimal du checksum doit etre en **majuscules** sur 2 + chiffres (`%02X`), sinon la trame sera rejetee cote ESP32 (silencieux, + pas d'erreur visible — la telemetrie n'avancera simplement pas). +- Terminer chaque trame par `\n` uniquement (le `\r` est tolere/ignore + cote ESP32 mais pas necessaire). +- Ne pas depasser une longueur de ligne de 160 caracteres (buffer fixe + cote ESP32, `g_lineBuf[160]` dans `tms_link.cpp`). +- Verifier au multimetre/oscilloscope le niveau logique du TMS320 avant + de le relier a l'ESP32-C3 (3,3V attendu).