From 4c50201a2048b7ffcc1b7086c9617112cb540501 Mon Sep 17 00:00:00 2001
From: Thomas Vanbesien <tvanbesi@proton.me>
Date: Mon, 16 Mar 2026 17:00:55 +0100
Subject: README.md, docs/guide.md (FR) — full API documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/guide.md | 480 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 480 insertions(+)
 create mode 100644 docs/guide.md

(limited to 'docs')

diff --git a/docs/guide.md b/docs/guide.md
new file mode 100644
index 0000000..32ed2eb
--- /dev/null
+++ b/docs/guide.md
@@ -0,0 +1,480 @@
+# Guide d'utilisation QtXpl2
+
+Ce guide explique comment utiliser le module QML `Xpl2` pour piloter un Jetting Controller Alchemie depuis une interface Qt Quick.
+
+## Import et connexion
+
+```qml
+import Xpl2
+
+// Xpl2Client est un singleton — pas besoin de l'instancier.
+// Configurer l'adresse du contrôleur :
+Xpl2Client.host = "192.168.1.100"
+
+// Se connecter / se déconnecter :
+Xpl2Client.connectToServer()
+Xpl2Client.disconnectFromServer()
+```
+
+### Propriétés de connexion
+
+| Propriété | Type | Description |
+|---|---|---|
+| `host` | string | Adresse IP du Jetting Controller (défaut : `"127.0.0.1"`) |
+| `connected` | bool | `true` quand les 3 ports TCP sont connectés |
+| `controllerId` | int | ID du contrôleur (renseigné après `getJcVersion()`) |
+| `firmwareVersion` | string | Version firmware du contrôleur |
+| `hardwareVersion` | string | Version hardware du contrôleur |
+| `printheadCount` | int | Nombre de têtes connectées |
+
+### Signaux généraux
+
+| Signal | Description |
+|---|---|
+| `errorOccurred(string error)` | Erreur de connexion ou de commande |
+| `statusMessage(string message)` | Message de log pour chaque réponse reçue |
+| `shuttingDown()` | Le serveur est en train de s'éteindre |
+
+---
+
+## Informations version
+
+### Obtenir la version du contrôleur
+
+```qml
+Xpl2Client.getJcVersion()
+```
+
+La réponse met à jour les propriétés `controllerId`, `firmwareVersion`, `hardwareVersion` et `printheadCount`. Le signal `jcVersionReceived()` est émis.
+
+### Obtenir la version d'une tête
+
+```qml
+Xpl2Client.getPhVersion(3)  // tête n°3
+```
+
+**Signal :** `phVersionReceived(controllerId, printheadId, mcuFirmwareVersion, mcuHardwareVersion, mcuFirmwareVariant, fpgaFirmwareVersion, fpgaHardwareVersion, bootloaderVersion)`
+
+```qml
+Connections {
+    target: Xpl2Client
+    function onPhVersionReceived(cid, phId, mcuFw, mcuHw, mcuVar, fpgaFw, fpgaHw, boot) {
+        console.log("Tête", phId, "— MCU:", mcuFw, "FPGA:", fpgaFw)
+    }
+}
+```
+
+---
+
+## Contrôle du jetting
+
+### Activer / désactiver le jetting
+
+```qml
+// Toutes les têtes
+Xpl2Client.jettingAllOn()       // → signal jettingAllOnResult(cid, success)
+Xpl2Client.jettingOff()         // → signal jettingOffResult(cid, success)
+
+// Avec un masque de buses (180 caractères, 12 par tête × 15 têtes)
+// Chaque caractère : 'F' = jet actif, '0' = jet inactif
+Xpl2Client.jettingOn("FFFF..." )  // → signal jettingOnResult(cid, success)
+
+// Une seule tête avec masque (12 caractères)
+Xpl2Client.phJettingOn(3, "FFFFFFFFFFFF")  // → signal phJettingOnResult(cid, phId, success)
+Xpl2Client.phJettingOff(3)                 // → signal phJettingOffResult(cid, phId, success)
+```
+
+### LEDs d'identification
+
+```qml
+// LED du contrôleur
+Xpl2Client.jcIdLedOn()    // → signal jcIdLedOnResult(cid, success)
+Xpl2Client.jcIdLedOff()   // → signal jcIdLedOffResult(cid, success)
+
+// LED d'une tête
+Xpl2Client.phIdLedOn(3)   // → signal phIdLedOnResult(cid, phId, success)
+Xpl2Client.phIdLedOff(3)  // → signal phIdLedOffResult(cid, phId, success)
+```
+
+### Calibration
+
+```qml
+// Calibrer toutes les têtes
+Xpl2Client.jcCalibration()   // → signal jcCalibrationResult(cid, success)
+
+// Calibrer une tête
+Xpl2Client.phCalibration(3)  // → signal phCalibrationResult(cid, phId, success)
+
+// Récupérer les données de calibration (48 fréquences par tête, -1 = non calibré)
+Xpl2Client.phCalibrationData(3)     // → signal phCalibrationDataReceived(cid, phId, frequencies)
+Xpl2Client.phCalibrationRawData(3)  // → signal phCalibrationRawDataReceived(cid, phId, frequencies)
+
+// Fréquence de base calibrée
+Xpl2Client.phCalibratedBaseFrequency(3)  // → signal phCalibratedBaseFrequencyReceived(cid, phId, baseFreq, activeBaseFreq)
+```
+
+### Codes de défaut
+
+```qml
+// Réinitialiser les codes de défaut
+Xpl2Client.jcResetFaultCodes()       // → signal jcResetFaultCodesResult(cid, success)
+Xpl2Client.phResetFaultCodes(3)      // → signal phResetFaultCodesResult(cid, phId, success)
+```
+
+### Désactivation de buses
+
+```qml
+// Masque de 12 caractères : '0' = buse active, autre = buse désactivée
+// "000000000000" réactive toutes les buses
+Xpl2Client.phNozzlesDisabled(3, "000000000000")  // → signal phNozzlesDisabledResult(cid, phId, success)
+```
+
+---
+
+## Messages de statut
+
+Le contrôleur peut envoyer périodiquement des messages de statut détaillés.
+
+### Démarrer / arrêter les messages
+
+```qml
+// Niveau 1 = basique, niveau 2 = étendu
+// Intervalle en millisecondes
+Xpl2Client.jcStatusMessagingStart(1, 1000)  // JC, niveau 1, toutes les secondes
+Xpl2Client.jcStatusMessagingStop()
+
+Xpl2Client.phStatusMessagingStart(2, 500)   // Têtes, niveau 2, toutes les 500ms
+Xpl2Client.phStatusMessagingStop()
+```
+
+**Signaux de confirmation :**
+- `jcStatusMessagingStartResult(cid, statusLevel, sendIntervalMs, success)`
+- `jcStatusMessagingStopResult(cid, success)`
+- `phStatusMessagingStartResult(cid, statusLevel, sendIntervalMs, success)`
+- `phStatusMessagingStopResult(cid, success)`
+
+### Recevoir les statuts
+
+Les messages de statut arrivent sous forme d'objets structurés avec des propriétés nommées.
+
+```qml
+Connections {
+    target: Xpl2Client
+
+    function onJcStatusReceived(status) {
+        // status est un objet Xpl2JcStatus
+        tempLabel.text = status.temperature.toFixed(1) + "°C"
+        cpuLabel.text = status.cpuPercentageBusy.toFixed(1) + "%"
+    }
+
+    function onPhStatusReceived(status) {
+        // status est un objet Xpl2PhStatus
+        console.log("Tête", status.printheadId, "temp:", status.temperature)
+    }
+}
+```
+
+### Champs du statut JC (`Xpl2JcStatus`)
+
+#### Niveau 1
+
+| Propriété | Type | Description |
+|---|---|---|
+| `controllerId` | int | ID du contrôleur |
+| `statusLevel` | int | Niveau de statut (1 ou 2) |
+| `cpuPercentageBusy` | float | Charge CPU (%) |
+| `rail5V` | float | Tension rail 5V |
+| `railCanBus8V` | float | Tension bus CAN 8V |
+| `temperature` | float | Température (°C) |
+| `humidity` | float | Humidité (%) |
+| `busCurrent` | float | Courant bus (A) |
+| `onTimeSeconds` | int | Temps de fonctionnement (s) |
+
+#### Niveau 2 (inclut le niveau 1 +)
+
+| Propriété | Type | Description |
+|---|---|---|
+| `ipAddress` | string | Adresse IP |
+| `eFuseVoltage` | float | Tension eFuse (V) |
+| `eFuseBusEnabled` | bool | Bus eFuse activé |
+| `busPowerEnabled` | bool | Alimentation bus activée |
+| `busPowerOk` | bool | Alimentation bus OK |
+| `switchValue` | int | Valeur du commutateur |
+| `firmwareVersion` | string | Version firmware |
+| `hardwareVersion` | string | Version hardware |
+| `indicator0` .. `indicator5` | bool | Indicateurs 0 à 5 |
+
+### Champs du statut PH (`Xpl2PhStatus`)
+
+#### Niveau 1
+
+| Propriété | Type | Description |
+|---|---|---|
+| `controllerId` | int | ID du contrôleur |
+| `statusLevel` | int | Niveau de statut |
+| `printheadId` | int | ID de la tête |
+| `temperature` | float | Température (°C) |
+| `humidity` | float | Humidité (%) |
+| `mcuTemperature` | float | Température MCU (°C) |
+| `pdsVoltage` | float | Tension PDS (V) |
+| `mdsVoltage` | float | Tension MDS (V) |
+| `systemVoltage` | float | Tension système (V) |
+| `eFuseCurrent` | float | Courant eFuse (A) |
+| `nozzleCurrent` | float | Courant buses (A) |
+| `vdd` | float | Tension VDD (V) |
+| `temperatureTrip` | bool | Seuil température dépassé |
+| `pdsOverVoltageTrip` | bool | Surtension PDS |
+| `pdsUnderVoltageTrip` | bool | Sous-tension PDS |
+| `pdsSupplyErrorTrip` | bool | Erreur alimentation PDS |
+| `mdsOverVoltageTrip` | bool | Surtension MDS |
+| `mdsUnderVoltageTrip` | bool | Sous-tension MDS |
+| `supplyOverVoltageTrip` | bool | Surtension alimentation |
+| `supplyUnderVoltageTrip` | bool | Sous-tension alimentation |
+| `eFuseOverCurrentTrip` | bool | Surintensité eFuse |
+| `eFuseInputVoltageErrorTrip` | bool | Erreur tension entrée eFuse |
+| `eFuseFaultTrip` | bool | Défaut eFuse |
+| `flashFaultyTrip` | bool | Défaut flash |
+| `flashChecksumErrorTrip` | bool | Erreur checksum flash |
+| `dutyCycle` | float | Rapport cyclique (%) |
+| `pwmFrequency` | float | Fréquence PWM (Hz) |
+| `drive` | int | Drive |
+| `nozzleDriveFrequency` | float | Fréquence drive buses (Hz) |
+| `nozzleDriveDutyCycle` | float | Rapport cyclique drive buses (%) |
+| `onTimeSeconds` | int | Temps de fonctionnement (s) |
+
+#### Niveau 2 (inclut le niveau 1 +)
+
+| Propriété | Type | Description |
+|---|---|---|
+| `accelerometerId` | int | ID accéléromètre |
+| `mcuId` | string | ID MCU |
+| `flashMemoryId` | string | ID mémoire flash |
+| `temperatureSensorSerialNumber` | int | N° série capteur température |
+| `mcuHardwareVersion` | string | Version hardware MCU |
+| `mcuFirmwareVersion` | string | Version firmware MCU |
+| `mcuFirmwareVariant` | string | Variante firmware MCU |
+| `fpgaHardwareVersion` | string | Version hardware FPGA |
+| `fpgaFirmwareVersion` | string | Version firmware FPGA |
+| `bootloaderVersion` | string | Version bootloader |
+| `maxAllowedTemperature` | float | Température max autorisée (°C) |
+| `pdsVoltageMax` | float | Tension PDS max (V) |
+| `pdsVoltageMin` | float | Tension PDS min (V) |
+| `pdsVoltageSetting` | float | Réglage tension PDS (V) |
+| `mdsVoltageMax` | float | Tension MDS max (V) |
+| `mdsVoltageMin` | float | Tension MDS min (V) |
+| `eFuseCurrentMax` | float | Courant eFuse max (A) |
+| `measuredHardwareVersion` | string | Version hardware mesurée |
+| `gyroX`, `gyroY`, `gyroZ` | int | Gyroscope X/Y/Z |
+| `accelerationX`, `accelerationY`, `accelerationZ` | int | Accélération X/Y/Z |
+| `purge`, `purgeState`, `purgeDelay`, `purgeCounter` | int | Paramètres de purge |
+| `cleaningStartPeriod`, `cleaningEndPeriod`, `cleaningStepPeriod`, `cleaningPeriod` | int | Paramètres de nettoyage |
+
+---
+
+## Configuration
+
+### ID des têtes
+
+```qml
+Xpl2Client.phSetId(3)       // → signal phSetIdResult(cid, phId, success)
+Xpl2Client.phDeassignId()   // → signal phDeassignIdResult(cid, success)
+```
+
+### Paramètres de jetting
+
+```qml
+// Pour tout le contrôleur
+Xpl2Client.jcSetJettingParams(dutyCycle, pwmFreq, drive, nozzleDriveFreq, nozzleDriveDutyCycle)
+// → signal jcSetJettingParamsResult(cid, dutyCycle, pwmFreq, drive, nozzleDriveFreq, nozzleDriveDutyCycle, result)
+
+// Pour une tête
+Xpl2Client.phSetJettingParams(phId, dutyCycle, pwmFreq, drive, nozzleDriveFreq, nozzleDriveDutyCycle)
+// → signal phSetJettingParamsResult(cid, phId, dutyCycle, pwmFreq, drive, nozzleDriveFreq, nozzleDriveDutyCycle, result)
+
+// Lire les paramètres d'une tête
+Xpl2Client.phGetJettingParams(3)
+// → signal phGetJettingParamsResult(cid, phId, dutyCycle, pwmFreq, drive, nozzleDriveFreq, nozzleDriveDutyCycle, result)
+```
+
+Le paramètre `result` est un `JettingParamsResult` :
+
+| Valeur | Signification |
+|---|---|
+| `1` (Ok) | Succès |
+| `0` (Failed) | Échec |
+| `-1` (DutyCycle) | Rapport cyclique invalide |
+| `-2` (PwmFrequency) | Fréquence PWM invalide |
+| `-3` (Drive) | Drive invalide |
+| `-4` (NozzleDriveFrequency) | Fréquence drive buses invalide |
+| `-5` (NozzleDriveDutyCycle) | Rapport cyclique drive buses invalide |
+
+### Calibration
+
+```qml
+Xpl2Client.jcSaveCalibration()       // → jcSaveCalibrationResult(cid, success)
+Xpl2Client.phSaveCalibration(3)      // → phSaveCalibrationResult(cid, phId, success)
+Xpl2Client.jcResetCalibration()      // → jcResetCalibrationResult(cid, success)
+Xpl2Client.phResetCalibration(3)     // → phResetCalibrationResult(cid, phId, success)
+```
+
+### Purge
+
+```qml
+// Configurer : intervalle (ms) et durée de jet (ms)
+// La durée doit être inférieure à l'intervalle
+Xpl2Client.jcSetPurgeSettings(5000, 200)  // → jcSetPurgeSettingsResult(cid, interval, time, success)
+Xpl2Client.jcSwitchOffPurge()             // → jcSwitchOffPurgeResult(cid, success)
+```
+
+### Setter / Getter générique
+
+Permet de lire ou écrire n'importe quel paramètre par son ID (voir Appendice D du protocole).
+
+```qml
+// Écrire un paramètre du contrôleur
+// saveNewValue : true pour sauvegarder en mémoire permanente
+Xpl2Client.jcSetter(true, 4, "35.0")   // setter ID 4 = température
+// → signal jcSetterResult(cid, saveNewValue, setterId, newValue, result)
+
+// Écrire un paramètre d'une tête
+Xpl2Client.phSetter(3, false, 23, "50.0")  // tête 3, setter ID 23 = duty cycle
+// → signal phSetterResult(cid, phId, saveNewValue, setterId, newValue, result)
+
+// Lire un paramètre du contrôleur
+// getSavedValue : true pour la valeur sauvegardée, false pour la valeur courante
+Xpl2Client.jcGetter(false, 4)
+// → signal jcGetterResult(cid, savedValue, getterId, currentValue, success)
+
+// Lire un paramètre d'une tête
+Xpl2Client.phGetter(3, false, 1)
+// → signal phGetterResult(cid, phId, savedValue, getterId, currentValue, success)
+```
+
+Le `result` des setters est un `SetterResult` :
+
+| Valeur | Signification |
+|---|---|
+| `1` (Ok) | Succès |
+| `0` (Failed) | Échec |
+| `-1` (IncorrectNewValue) | Valeur incorrecte |
+
+### Sauvegarde et réinitialisation
+
+```qml
+// Sauvegarder tous les réglages
+Xpl2Client.jcSaveAllPrintheadSettings()  // → jcSaveAllPrintheadSettingsResult(cid, success)
+Xpl2Client.phSaveSettings(3)             // → phSaveSettingsResult(cid, phId, success)
+
+// Réinitialiser les réglages
+Xpl2Client.jcResetSettingsAllPrintheads()  // → jcResetSettingsAllPrintheadsResult(cid, success)
+Xpl2Client.phResetAllSettings(3)           // → phResetAllSettingsResult(cid, phId, success)
+```
+
+### Redémarrage et arrêt
+
+```qml
+Xpl2Client.jcRebootAllPrintheads()      // → jcRebootAllPrintheadsResult(cid, success)
+Xpl2Client.phReboot(3)                  // → phRebootResult(cid, phId, success)
+Xpl2Client.jcResetControllerSoftware()  // → jcResetControllerSoftwareResult(cid, success)
+Xpl2Client.jcRestart()                  // → jcRestartResult(cid, success)
+Xpl2Client.jcShutdown()                 // → jcShutdownResult(cid, success)
+```
+
+---
+
+## Imaging
+
+Les commandes d'imaging sont envoyées sur le port 2 (9111).
+
+### Démarrer / arrêter l'impression
+
+```qml
+Xpl2Client.imagingStart(1.0)  // vitesse d'impression
+// → signal imagingReply(imageLines)  — nombre de lignes d'image à envoyer
+
+Xpl2Client.imagingStop()
+// → signal imagingStopResult(success)
+```
+
+### Masques d'image
+
+Les masques définissent quelles buses sont actives pour chaque ligne d'image. Le masque fait 12 caractères par tête (180 caractères pour 15 têtes).
+
+```qml
+// Envoyer un masque : m0 démarre, m1 termine et déclenche l'envoi
+Xpl2Client.imageMaskStart("FFFFFFFFFFFF...")   // 180 caractères
+Xpl2Client.imageMaskEnd("fin_du_message")
+// → signal imagingReply(imageLines)
+```
+
+### Masques de rapport cyclique
+
+Même principe avec 2 caractères hexadécimaux par tête.
+
+```qml
+Xpl2Client.dutyCycleMaskStart("FF...")
+Xpl2Client.dutyCycleMaskEnd("fin")
+// → signal imagingReply(imageLines)
+```
+
+### Compteur d'images
+
+Vérifie le nombre de lignes d'image restantes. Utilisé avant d'arrêter l'impression pour s'assurer que toutes les lignes ont été envoyées.
+
+```qml
+Xpl2Client.imageCount()
+// → signal imagingReply(imageLines)  — 0 signifie que tout est envoyé
+```
+
+---
+
+## Événements serveur
+
+Ces signaux sont émis automatiquement quand le serveur envoie des événements.
+
+### Erreurs
+
+```qml
+Connections {
+    target: Xpl2Client
+
+    // Erreur du contrôleur (codes 3000+)
+    function onJcErrorCode(controllerId, errorCode, params) {
+        console.log("Erreur JC:", errorCode, params)
+    }
+
+    // Erreur d'une tête (codes 4000+)
+    function onPhErrorCode(controllerId, printheadId, errorCode, params) {
+        console.log("Erreur tête", printheadId, ":", errorCode)
+    }
+
+    // Erreur d'imaging (codes 5000+)
+    function onImgErrorCode(controllerId, errorCode, params) { }
+
+    // Erreur de statut (codes 6000+)
+    function onStatusErrorCode(controllerId, errorCode, params) { }
+}
+```
+
+### Connexion des têtes
+
+```qml
+Connections {
+    target: Xpl2Client
+
+    function onPhConnectionChanged(controllerId, printheadId, connected) {
+        console.log("Tête", printheadId, connected ? "connectée" : "déconnectée")
+    }
+}
+```
+
+### Arrêt du serveur
+
+```qml
+Connections {
+    target: Xpl2Client
+    function onShuttingDown() {
+        console.log("Le serveur s'éteint")
+    }
+}
+```
-- 
cgit v1.2.3