Pilotes NEEO avec meta

Que fait Pilotes NEEO avec meta ?

meta (jac459/meta) est un moteur Node.js qui lit des fichiers de périphérique JSON depuis son dossier active/ et transforme chacun d’eux en pilote SDK NEEO enregistré auprès du Brain NEEO local. Vous décrivez le périphérique en JSON ; vous n’écrivez pas de JavaScript (à l’exception de petites expressions DYNAMIK).

Langue : écrivez à l’utilisateur dans sa langue. Les clés JSON, mots-clés du moteur, noms de boutons et chaînes de logs restent exactement comme documentés ici (anglais).

Périmètre : seul le SDK NEEO pré-acquisition, le Brain local et meta comptent. Ignorez le matériel Control4 et le cloud NEEO (fermé).

Règles de base (ne jamais sauter)

1. N’inventez jamais une clé JSON ou un type de commande. Si une fonctionnalité n’est pas dans les références, dites-le et proposez une alternative : un service compagnon (Node‑RED + MQTT, ou une petite passerelle REST locale, voir references/companion-services.md), une commande cli, ou une chaîne de boutons cachés.
2. JSON pur : pas de commentaires, pas de virgules finales, guillemets doubles. Validez avec python3 -m json.tool fichier.json puis python3 scripts/check_driver.py fichier.json.
3. Les types de commande sont sensibles à la casse : http-get, http-rest, http-post, http-get-soap, static, cli, repl, webSocket, socketIO, jsontcp, mqtt, wol, mDNS, android.
4. Augmentez version à chaque ajout de composant visible. Le Brain ne fait qu’ajouter les composants ; renommer ou supprimer un composant oblige à supprimer puis ré‑ajouter le périphérique dans l’appli NEEO (les recettes et raccourcis doivent être refaits). Même une augmentation de version ne suffit parfois pas sur un périphérique déjà installé : consultez le Brain (references/debugging.md).
5. Noms (clés) des labels, interrupteurs, curseurs, images et capteurs : lettres et chiffres uniquement. Un espace ou un symbole casse le lien de capteur ("sensor": null dans le Brain) et la télécommande plante lors de la synchronisation dès que le composant est utilisé comme raccourci. Le texte label affiché est libre. Les noms de boutons peuvent contenir des espaces, mais évitez + et les accents (DISNEY PLUS, label Disney+).
6. N’écrivez jamais "" dans une variable liée à un label : sur meta v1.2.0, un label passant d’un texte à "" arrête meta. Écrivez " " (ou un texte de repli lisible). Initialisez aussi les variables de label avec " " en habitude.
7. Nettoyez tout texte externe avant qu’il n’atteigne un label : " -> ', \ -> /, caractères de contrôle -> espace, $ -> ＄ (pleine largeur). Faites‑le dans le pilote et à la source.
8. Les écouteurs démarrent une fois par session, via la garde ListenerOn + un bouton caché __LISTEN câblé dans chaque contrôle visible. Ne comptez jamais uniquement sur POWER ON, et n’appelez jamais __CLEANUP sur un écouteur mqtt (references/listeners-and-state.md).
9. Événements plutôt qu’interrogation (webSocket, socketIO, mqtt). Si interrogation, pooltime >= 3000.
10. $Result est toujours une chaîne, "undefined" en cas d’échec : protégez chaque JSON.parse. Un bouton reçoit un scalaire (ok) ; un chargeur d’action de répertoire reçoit ["ok"].
11. Noms de variables : n’utilisez jamais un nom qui soit un préfixe d’un autre ; $Var collé à des lettres est lu comme une variable différente.
12. Sécurité : DYNAMIK et cli exécutent du code sur l’hôte meta. Pas de secrets en dur dans un pilote destiné à être partagé ; meta ne doit pas tourner en root/admin.
13. Les changements irréversibles nécessitent un consentement : ajouter des composants visibles (ex. DIGIT 0‑9) ne peut pas être annulé sans réinstaller le périphérique. Demandez d’abord.
14. Livrables distincts : un pilote meta est un objet JSON (commence par {, jamais -flow dans son nom, va dans active/) ; un flux Node‑RED est une liste JSON (commence par [, toujours nommé *-flow.json, importé dans Node‑RED).
15. Dans template, dynamicname et dynamicid sont obligatoires ; dynamicid doit être stable (adresse MAC ou identifiant matériel plutôt qu’une IP DHCP).

Flux de travail

1. Collectez ce dont vous avez besoin (posez au maximum 3 questions ciblées à la fois) : modèle exact du périphérique ; son protocole ou API de contrôle (HTTP/REST, WebSocket, TCP brut, MQTT, IR uniquement, Android TV…) ; IP fixe ou non et un identifiant stable (MAC) ; ce qui doit être contrôlé et quel état doit être affiché ; version de meta et où meta s’exécute (Pi avec pm2, Docker…) ; si un courtier MQTT et Node‑RED sont disponibles. Cherchez la documentation officielle de l’API du périphérique quand elle existe.
2. Choisissez le type NEEO (references/driver-anatomy.md, section types et boutons reconnus) et le mode de découverte (references/discovery.md) : périphérique unique statique, IP saisie par l’utilisateur, mDNS, ou concentrateur.
3. Démarrez à partir d’un squelette dans assets/ : skeleton-static.json (un périphérique, adresse fixe) ou skeleton-register-ip.json (l’utilisateur tape l’IP). Réutilisez les patrons éprouvés de references/patterns.md.
4. Décidez où la logique réside. Périphérique HTTP ou WebSocket simple : tout dans le pilote. Protocole binaire ou avec état (TCP brut, sessions persistantes, appairage, état bursty) : mettez un service compagnon entre les deux, avec des commandes HTTP rapides et l’état poussé via un message MQTT retenu (references/companion-services.md).
5. Vérifiez avant de livrer :
   • python3 -m json.tool pilote.json puis python3 scripts/check_driver.py pilote.json (noms, valeurs vides de label, types, version, garde, interrogation…) ;
   • node scripts/simulate_guard.js pilote.json quand le pilote a des écouteurs (compte les __INITIALISE / __CLEANUP sur les sessions) ;
   • évaluez les expressions DYNAMIK délicates dans Node avec les vraies règles de substitution (references/logic-and-commands.md) ;
   • relisez references/pitfalls.md.
6. Livrez dans cet ordre : résumé (périphérique, protocole, type NEEO, mode de découverte, couvert / non couvert) ; le fichier JSON complet validé avec un nom de fichier explicite ; les étapes de déploiement (copier dans active/, redémarrer meta, ajouter le périphérique dans l’appli NEEO, visibilité des recettes et raccourcis à créer) ; le plan de test (boutons à essayer, résultat attendu, lignes de log à chercher) ; les hypothèses non vérifiées sur le vrai périphérique ; la prochaine itération. Pour les projets multi‑fichiers (pilote + flux + service) : ordre des opérations, un marqueur de version dans chaque livrable et comment vérifier quelle version est installée. Dites toujours ce qui n’a pas été testé sur le vrai périphérique.

Carte des références (lire seulement ce dont la tâche a besoin)

Fichier	À lire quand
references/meta-engine.md	Architecture, installation, dossiers, redémarrage, niveaux de log, sujets MQTT exposés par meta, hébergement Docker/NAS, bugs connus de meta v1.2.0
references/driver-anatomy.md	Clés de premier niveau, types de périphériques NEEO et noms de boutons reconnus, variables, substitution $, DYNAMIK, composants UI
references/logic-and-commands.md	evalwrite, evaldo, evalnext, boutons spéciaux, chaque type de commande, queryresult / JSONPath
references/listeners-and-state.md	Écouteurs, la garde ListenerOn, comportement des écouteurs MQTT, sources d’état bursty, reconstructions d’instance
references/discovery.md	discover, register, template, initcommandset, mDNS, saisie IP, concentrateurs, appairage
references/directories.md	Listes, chargeurs, champs item*, actions, navigation multi‑niveaux
references/patterns.md	Recettes éprouvées : volume, alimentation, barre d’état, persistance, chaînes, boucles, chemin de repli, lanceur d’applications, image d’illustration
references/pitfalls.md	Relecture obligatoire avant livraison
references/debugging.md	Lecture des données de meta, Mosquitto et Brain, signatures de log, isolation d’un lien, tests en bac à sable
references/companion-services.md	Passerelles Node‑RED et MQTT, passerelles REST locales, leçons Apple TV / pyatv
references/community-drivers.md	Pilotes de référence à imiter, mapping SDK <-> meta, sources

Étiquettes de preuve utilisées dans les références

[code v1.2.0] lu dans le code source de meta (branche Release) ; [observed] observé dans des pilotes réels ou des installations réelles ; [to verify] déduction non encore testée. Quand un comportement est important et n’est pas étiqueté, consultez le code de meta (git clone --depth 1 --branch Release https://github.com/jac459/meta) plutôt que de deviner, et dites ce que vous avez fait.