Ichtyomètre - Documentation Technique

Copy of sumaris-app/.agents/rules/ichthyometer.md (rule written for AI coding agents, always applied). Do not edit here: run npm run site:sync-rules to update it.

Cette documentation détaille le fonctionnement des ichtyomètres dans l'application SUMARIS, en particulier le modèle à code-barres (Ichthyometer Ruler).

Types d'ichtyomètres

L'application supporte plusieurs types d'ichtyomètres via l'interface Ichthyometer :

1. Ichthyometer Ruler (Code-barres) : Communique via Bluetooth LE, envoie des codes-barres correspondant à des mesures ou des fonctions.
2. Ichthyometer Gwaleen : Modèle spécifique intégré (voir ichthyometer.gwaleen.ts).

---

Ichtyomètre à Code-barres (Ruler)

L'ichtyomètre à code-barres fonctionne en envoyant des chaînes de caractères (codes-barres) via Bluetooth.

1. Format Physique Historique (ITF)

Historiquement, les codes-barres gravés sur les ichtyomètres utilisent le format ITF (Interleaved 2 of 5).

• Format d'encodage : ITF (numérique haute densité).
• Checksum : Utilise un caractère de contrôle basé sur l'algorithme Modulo 10 (pondération 3-1, identique à l'EAN).
• Transmission Bluetooth : Bien que le code physique soit numérique (ITF), le lecteur est configuré pour ajouter un préfixe D lors de l'envoi de la donnée à l'application.

2. Mapping Historique (legacy-mapping.json)

Le fichier src/assets/data/ichthyometer/legacy-mapping.json définit la correspondance entre les codes-barres reçus (avec préfixe D) et leur signification.

Structure d'une entrée :

{
  "decimal": 244,
  "hex": "F4",
  "barcode": "D9454",
  "type": "function",
  "value": "species",
  "label": "ICHTHYOMETER.RULER.FUNCTIONS.SPECIES"
}

• decimal : Identifiant numérique unique (0-255).
• hex : Conversion hexadécimale du champ decimal (2 caractères).
• barcode : Le code-barres reçu par l'application (ex: D9454).
• type : Type de donnée (cm, string, function, alphanumerique).
• value : La valeur traitée par l'application (nombre pour les cm, identifiant pour les fonctions).

---

3. Logique des Codes-barres (D<NNN><C>)

Les codes-barres reçus commencent par D. Le corps numérique NNN et le checksum C suivent les règles suivantes :

• Structure : D + NNN + C
• Algorithme de Checksum : Modulo 10 avec pondération 3-1 depuis la droite (Standard EAN/ITF).
• Logique pour les Fonctions :
  • Formule : NNN = decimal + 701
  • Exemple : ESPECE (décimal 244) -> NNN = 945. Checksum(945) = 4. Code reçu : D9454.
• Logique pour les Mesures (cm) :
  • Formule : NNN = decimal + 1 (correspond à la valeur en cm).
  • Exemple : 15 cm (decimal=14, NNN=015) -> Checksum(015) = 4. Code reçu : D0154.
  • Note historique : Les codes-barres entre 14 et 36 cm ont été corrigés dans le mapping logiciel pour respecter strictement cette règle decimal + 1.

---

4. Système d'Alias (Combinaison de codes)

Pour permettre d'envoyer plusieurs informations en un seul scan (ex: une fonction + un code espèce), l'application supporte un format d'Alias hexadécimal.

Format : D<HEX_FONCTION><HEX_DATA...>

Si un code reçu n'est pas trouvé directement dans le mapping, l'application tente de le décomposer par paires hexadécimales.

• Format d'impression recommandé : CODE 128 (obligatoire car l'ITF ne supporte pas les lettres A-F de l'hexadécimal).
• Préfixe : D
• Données : Suite de paires hexadécimales.

Exemple : ESPECE (F4) + "MNZ" (D4, D5, E1)

• Code reçu : DF4D4D5E1.
• Décodage :
  1. F4 -> Déclenche la fonction ESPECE.
  2. D4, D5, E1 -> Groupés en une seule chaîne "MNZ".