Manuel utilisateur SoftAgent

Confirmer que l'environnement répond aux exigences et préparer l'installation.

1. Confirmer que le PC cible fonctionne sur Windows 10/11 x64.
2. Confirmer que vous avez des droits de compte administrateur (le programme d'installation déclenchera une invite d'élévation UAC).
3. Confirmer que le pare-feu autorise le trafic UDP entrant sur le port 6500 (le port d'écoute de SoftAgent).
4. Le package d'installation est autonome — aucun runtime .NET ne doit être pré-installé sur la machine cible.

• Peut exécuter des programmes en tant qu'administrateur (élévation UAC acceptée).
• Le port UDP 6500 n'est pas occupé par un autre programme.

• Plusieurs PC contrôlés peuvent utiliser le même programme d'installation — configurer le port et l'adresse de rapport indépendamment sur chacun.
• Pour les projets d'exposition, il est recommandé de configurer tous les PC contrôlés pour la connexion automatique avec un compte administrateur afin que la tâche de démarrage automatique se déclenche de manière fiable.

Compléter l'installation et confirmer que SoftAgent fonctionne normalement dans la barre d'état système.

1. Double-cliquer sur SoftAgent-Setup-version.exe et cliquer sur Oui dans l'invite UAC pour autoriser les droits administrateur.
2. Suivre l'assistant d'installation pour terminer l'installation (par défaut : C:\Program Files\SoftAgent\).
3. Sur la page de fin, cocher optionnellement 'Lancer SoftAgent maintenant', ou démarrer manuellement après.
4. Après le démarrage, SoftAgent apparaît dans la barre d'état système (aucune fenêtre principale n'apparaît).
5. Faire un clic droit sur l'icône de la barre et sélectionner 'Ouvrir la configuration' — confirmer que la fenêtre principale apparaît avec 4 onglets (Propriétés / Programmes / Watchdog / Paramètres).

• L'icône SoftAgent apparaît dans la barre d'état système.
• Le Gestionnaire des tâches montre les processus SoftAgent.App et SoftAgent.Watchdog en cours d'exécution.
• Le clic droit sur la barre affiche : Ouvrir la configuration / État / Mettre en pause le watchdog / Ouvrir le répertoire des journaux / À propos / Quitter.

SoftAgent utilise une architecture à double processus : le processus App gère les fonctionnalités et le Watchdog surveille et redémarre automatiquement l'App en cas de crash — ils se protègent mutuellement.

Compléter la configuration de base et confirmer que l'agent fonctionne via UDP ping.

1. Double-cliquer sur l'icône de la barre pour ouvrir la fenêtre principale, passer à l'onglet Paramètres.
2. Confirmer que le port d'écoute est 6500 (ou changer selon les besoins), et cocher 'Démarrage automatique' pour enregistrer la tâche planifiée.
3. Pour l'intégration avec SoftControl, saisir l'IP:port de la machine SoftControl dans le champ 'Adresse de rapport'.
4. Cliquer sur 'Enregistrer et appliquer' pour sauvegarder la configuration.
5. Ouvrir PowerShell et envoyer un ping pour vérifier :
6. $u = New-Object System.Net.Sockets.UdpClient
7. $b = [Text.Encoding]::UTF8.GetBytes('ping')
8. $u.Send($b, $b.Length, '127.0.0.1', 6500)
9. $r = $u.Receive([ref](New-Object System.Net.IPEndPoint([Net.IPAddress]::Any, 0)))
10. [Text.Encoding]::UTF8.GetString($r)
11. Recevoir ok:pong confirme que l'agent fonctionne normalement.

• L'envoi de ping reçoit la réponse ok:pong.
• La case Démarrage automatique dans l'onglet Paramètres est enregistrée.
• L'exécution de schtasks /Query /TN SoftAgent affiche la tâche planifiée enregistrée.

• Changer le port mais oublier de cliquer sur 'Enregistrer et appliquer', de sorte que le changement ne prend pas effet.
• Saisir le port de la console de gestion HTTP au lieu du port d'écoute UDP.

Maîtriser le format de commande et les niveaux de risque pour une utilisation sûre de SoftAgent.

1. Format de commande : verbe ou verbe:arg (l'argument suit le premier deux-points), ex. volume:80 ou ping.
2. Réponse de succès : ok:<code>, ex. ok:pong ou ok:volume.
3. Réponse d'échec : err:<code>, ex. err:wol.invalidMac.
4. Trois niveaux de risque : Sûr (aucune perturbation, répétable) / Perturbateur (interrompt la session/le processus mais sans perte de données) / Destructeur (arrêt/redémarrage/déconnexion, etc.).
5. Les commandes destructrices affichent une boîte de dialogue de confirmation dans l'interface. Quand déclenchées à distance, l'appelant est responsable de confirmer l'intention.

• L'envoi de ping reçoit ok:pong, confirmant que la connexion et le format de commande sont corrects.
• L'envoi de describe reçoit une liste de capacités JSON avec toutes les commandes prises en charge et leurs niveaux de risque.

La commande describe retourne la liste complète des capacités de cette instance SoftAgent, incluant le nom, la description, le niveau de risque et si une confirmation est requise pour chaque commande — utile pour la découverte de capacités lors de l'intégration avec SoftControl ou des systèmes IA.

Maîtriser les commandes sûres pour le contrôle quotidien du volume et la surveillance de l'état.

1. Sonde de connectivité : ping (répond ok:pong, confirme que l'agent est en ligne).
2. Obtenir la liste des capacités : describe (retourne un JSON listant toutes les commandes avec descriptions et niveaux de risque).
3. Découverte d'appareils : discover (retourne un instantané JSON de battement de cœur avec nom d'hôte, IP, MAC, volume, état de garde).
4. Augmenter le volume d'un cran : volup (par défaut +5% par appel).
5. Diminuer le volume d'un cran : voldown (par défaut -5% par appel).
6. Basculer le muet : mute (basculer entre muet et non muet).
7. Obtenir l'adresse MAC de la NIC principale : getmac (retourne le format majuscules-tirets, ex. AA-BB-CC-DD-EE-FF).
8. Envoyer un paquet magique Wake-on-LAN : wol:AA-BB-CC-DD-EE-FF (réveiller la machine avec le MAC spécifié).
9. Simulation clavier : key:^s (Ctrl+S), key:{F5} (touche F5), key:Bonjour (taper des caractères).

• La commande ping retourne ok:pong.
• volup/voldown change le volume de la machine contrôlée.
• La commande wol réveille la machine cible (nécessite WoL activé sur la cible).

• Utiliser discover pour obtenir rapidement l'état actuel d'une machine contrôlée (IP, volume, état de garde) — utile pour les vérifications de santé en lots de SoftControl.
• key: utilise la syntaxe SendKeys Microsoft : ^ est Ctrl, % est Alt, + est Shift, les touches spéciales entre accolades comme {ENTER}.

Maîtriser le verrouillage écran, le démarrage/arrêt de processus et les commandes d'annulation d'arrêt.

1. Verrouiller l'écran : lock (verrouille le poste de travail actuel — reconnexion pour restaurer).
2. Annuler un arrêt/redémarrage différé en attente : cancelshutdown (utiliser pendant le compte à rebours d'arrêt).
3. Démarrer un élément watchdog par ID : run:id (ex. run:db-player démarre l'élément nommé db-player).
4. Arrêter un élément watchdog par ID : stop:id (arrête et met en pause le watchdog — le processus ne sera pas redémarré automatiquement).
5. Démarrer un programme géré par index : startpro:0 (démarre le programme à l'index 0 dans la liste des programmes gérés).
6. Arrêter un programme géré par index : killpro:0.
7. Arrêter tous les programmes gérés : killall.

• Après lock, la machine contrôlée affiche l'écran de verrouillage.
• Après run:id, l'élément watchdog correspondant démarre — l'état passe de Arrêté à En cours d'exécution dans l'onglet Watchdog.
• cancelshutdown envoyé pendant un compte à rebours d'arrêt annule l'arrêt.

• Utiliser run/stop avec l'ID watchdog (un identifiant stable) plutôt que startpro/killpro avec l'index (l'index change quand les éléments sont supprimés ou réorganisés).
• Les IDs watchdog sont configurés dans l'onglet Watchdog de SoftAgent. Mettre à jour les commandes SoftControl si vous renommez un ID.

Exécuter en toute sécurité des opérations destructrices comme l'arrêt, le redémarrage et la déconnexion.

1. Arrêt différé (recommandé) : shutdown:60 (arrêt après 60 secondes, cancelshutdown peut annuler pendant le compte à rebours).
2. Arrêt immédiat (à utiliser avec précaution) : shutdown (sans délai, impossible à annuler).
3. Redémarrage différé (recommandé) : reboot:60 (redémarrage après 60 secondes).
4. Redémarrer dans le BIOS/UEFI : reboot:firmware (nécessite la prise en charge du firmware UEFI).
5. Déconnecter l'utilisateur actuel : logoff (confirmer qu'il n'y a pas de données non sauvegardées avant d'exécuter).
6. Activer/Désactiver l'UAC : uac:off / uac:on (changement de registre, nécessite un redémarrage pour prendre effet, nécessite admin).
7. Activer/Désactiver les gestes de bord tactile : edgeswipe:off / edgeswipe:on.
8. Activer/Désactiver la réparation automatique au démarrage Windows : autorepair:off / autorepair:on.

• Après shutdown:60, le système affiche une notification de compte à rebours 'arrêt dans 60 secondes'.
• cancelshutdown envoyé pendant le compte à rebours annule l'arrêt.

• Envoyer shutdown sans délai, rendant impossible l'annulation — la machine contrôlée s'arrête immédiatement.
• Après uac:off, ne pas redémarrer et supposer que l'UAC est déjà désactivé (nécessite un redémarrage pour prendre effet).

Les commandes d'arrêt nécessitent des droits administrateur. Si les autorisations sont insuffisantes, un code d'erreur clair comme err:power.denied est retourné — aucun échec silencieux.

Compléter la configuration de base pour que SoftAgent puisse être correctement découvert et contrôlé par SoftControl.

1. Ouvrir la fenêtre principale SoftAgent et passer à l'onglet Paramètres.
2. Port d'écoute (par défaut 6500) : SoftControl et d'autres contrôleurs envoient des commandes UDP à ce port.
3. Adresse de rapport (format IP:port) : SoftAgent envoie périodiquement un JSON de battement de cœur à cette adresse ; saisir l'IP et le port d'écoute de SoftControl.
4. Intervalle de battement de cœur (secondes) : par défaut 10 secondes ; les battements de cœur contiennent le nom d'hôte, IP, MAC, volume, état de garde, etc.
5. Délai de démarrage automatique (secondes) : délai après la connexion avant que SoftAgent démarre (utile pour attendre la disponibilité du réseau).
6. Cliquer sur 'Enregistrer et appliquer' après les changements — les changements de port affichent un avis persistant 'Redémarrage requis' ; les autres changements prennent effet immédiatement.

• La configuration prend effet immédiatement après la sauvegarde (les changements de port nécessitent un redémarrage).
• Si une adresse de rapport est configurée, SoftControl devrait commencer à recevoir des JSON de battement de cœur périodiques de ce SoftAgent.

• Pour plusieurs PC contrôlés, il est recommandé d'utiliser le même port (6500) sur tous pour simplifier la saisie de commandes en lots dans SoftControl.
• Laisser l'adresse de rapport vide signifie que SoftAgent n'enverra pas proactivement de battements de cœur mais répondra toujours aux commandes UDP.

Modifier la configuration IP de la machine contrôlée via l'interface de SoftAgent sans RDP.

1. Ouvrir la fenêtre principale, passer à l'onglet Propriétés et sélectionner la carte réseau cible dans la liste déroulante du panneau réseau.
2. Après la sélection d'une NIC, l'IP actuelle, le masque de sous-réseau, la passerelle, le DNS et l'adresse MAC sont remplis automatiquement.
3. Basculer le mode 'IP statique / DHCP' : les champs sont modifiables en mode statique ; en lecture seule en mode DHCP.
4. Remplir l'IP cible, le masque de sous-réseau, la passerelle et le DNS (mode statique).
5. Cliquer sur 'Modifier les paramètres IP' et confirmer dans la boîte de dialogue de confirmation.
6. Le changement IP est une opération destructrice — la connexion actuelle tombe après le changement. Se reconnecter avec la nouvelle IP.

• Après le changement, la machine contrôlée peut être pinguée avec succès à la nouvelle adresse IP.
• Le JSON de battement de cœur SoftAgent affiche l'adresse IP mise à jour.

Changer l'IP est destructeur. Avant de procéder, confirmer que la nouvelle IP est accessible sur le LAN pour éviter de perdre l'accès à distance à la machine contrôlée.

Configurer le démarrage automatique pour que SoftAgent reprenne automatiquement après le redémarrage du PC contrôlé.

1. Dans l'onglet Paramètres de la fenêtre principale, cocher 'Démarrage automatique'.
2. Cliquer sur 'Enregistrer et appliquer'.
3. Vérifier avec : schtasks /Query /TN SoftAgent dans PowerShell — confirmer que la tâche planifiée est enregistrée.
4. Déclencheur de tâche : ONLOGON (se déclenche après la connexion utilisateur) avec niveau de privilège HIGHEST.
5. Pour définir un délai de démarrage (attendre le réseau ou les services dépendants), définir les secondes dans le champ 'Délai de démarrage automatique'.
6. Pour désactiver le démarrage automatique, décocher 'Démarrage automatique' et sauvegarder.

• schtasks /Query /TN SoftAgent montre que la tâche existe et est activée.
• Après le redémarrage du PC contrôlé, SoftAgent apparaît automatiquement dans la barre d'état système après la connexion.

Compléter la configuration des commandes SoftAgent dans SoftControl pour le contrôle des machines contrôlées par bouton.

1. Entrer dans le panneau d'administration SoftControl et ouvrir la gestion des commandes.
2. Créer une nouvelle commande, sélectionner le protocole UDP.
3. Définir l'adresse cible sur l'IP du PC contrôlé (ex. 192.168.1.101).
4. Définir le port sur le port d'écoute de SoftAgent (par défaut 6500).
5. Définir le texte de commande sur la commande spécifique, ex. : volup (augmenter le volume), mute (basculer le muet), lock (verrouiller l'écran), shutdown:60 (arrêt dans 60s).
6. Enregistrer et tester la commande individuellement — confirmer que la machine contrôlée répond correctement.
7. Lier la commande vérifiée à un bouton sur l'interface front-end de SoftControl.

• Après que SoftControl envoie la commande UDP, le SoftAgent de la machine contrôlée exécute l'action.
• Les journaux SoftControl indiquent que la commande a été envoyée avec succès (réponse OK).

• Créer un ensemble de commandes pour chaque machine contrôlée, en utilisant le nom de l'appareil comme préfixe (ex. 'Salle-PC-01_Arrêt') pour une maintenance facile.
• Pour les opérations en lot comme la fermeture de l'exposition, utiliser les groupes de commandes de SoftControl — ajouter des commandes d'arrêt pour plusieurs machines dans un groupe et déclencher une fois.

Configurer les rapports de battements de cœur pour surveiller l'état en ligne des machines contrôlées depuis SoftControl.

1. Dans les paramètres SoftAgent, configurer l'adresse de rapport sur l'IP:port de SoftControl (l'interface UDP externe de SoftControl, par défaut 8818).
2. SoftAgent envoie immédiatement un battement de cœur au démarrage, puis continue à l'intervalle configuré (par défaut 10 secondes).
3. Le JSON de battement de cœur inclut : agentId (identifiant unique de l'appareil), nom d'hôte, ip/mac (informations réseau), volume/muted (état audio), guards (états des processus watchdog), uptimeSeconds.
4. Pour interroger activement l'état actuel d'une machine contrôlée, envoyer discover depuis SoftControl — SoftAgent retourne un instantané de battement de cœur.
5. Le champ guards dans les battements de cœur indique si les processus watchdog fonctionnent normalement, révélant les crashs ou les états abandonnés.

• SoftControl reçoit des JSON de battement de cœur périodiques de SoftAgent.
• L'envoi de discover reçoit une réponse JSON avec le nom d'hôte, IP, volume et autres informations.

Configurer le watchdog de redémarrage automatique après crash pour les applications d'exposition.

1. Ouvrir la fenêtre principale SoftAgent et passer à l'onglet Watchdog.
2. Cliquer sur 'Parcourir...' pour sélectionner le .exe à surveiller, optionnellement définir un nom et un ID watchdog (identifiant stable utilisé pour les commandes run/stop).
3. Cliquer sur 'Ajouter' pour l'inclure dans la liste watchdog. Le contrôle de basculement individuel détermine si le watchdog de cet élément est activé.
4. Le basculement principal du watchdog est en haut de l'onglet — le désactiver met en pause tous les watchdogs (synchronisé avec le menu 'Mettre en pause le watchdog' de la barre).
5. Les badges d'état indiquent l'état de chaque élément : En cours d'exécution / Arrêté / Crashé / Abandonné (watchdog abandonné après trop de crashs dans la fenêtre temporelle).
6. Après un crash, SoftAgent redémarre avec un délai exponentiel (initial 5 secondes, doublant à chaque fois ; abandonné après dépassement de la limite dans la fenêtre temporelle).

• Le programme surveillé affiche l'état 'En cours d'exécution' dans la liste watchdog.
• Tuer manuellement le processus surveillé et SoftAgent le redémarre automatiquement après un délai.
• Le champ guards du JSON de battement de cœur reflète les derniers états watchdog.

Ne pas changer arbitrairement l'ID watchdog — les commandes run/stop de SoftControl en dépendent. Si vous renommez un ID, mettre à jour les commandes SoftControl correspondantes.

Restaurer le canal de contrôle des commandes UDP.

1. Confirmer que SoftAgent est visible dans la barre d'état système (le processus est en cours d'exécution).
2. Confirmer que le port d'envoi correspond au port d'écoute configuré de SoftAgent (par défaut 6500).
3. Vérifier si le pare-feu Windows autorise le trafic UDP entrant sur le port 6500.
4. Essayer ping depuis localhost (127.0.0.1) d'abord pour exclure les problèmes réseau, puis essayer à distance.
5. Vérifier les fichiers journaux dans %ProgramData%\SoftAgent\logs\ pour les enregistrements de réception de commandes.

• L'envoi de ping à 127.0.0.1 reçoit ok:pong, confirmant que SoftAgent et le port UDP fonctionnent.
• L'envoi de ping depuis une machine distante reçoit également une réponse, confirmant que le chemin réseau est clair.

S'assurer que SoftAgent s'exécute avec des droits administrateur pour prendre en charge toutes les commandes au niveau système.

1. Confirmer que SoftAgent s'exécute avec des droits admin : le démarrage automatique utilise le privilège HIGHEST de la tâche planifiée ; pour le démarrage manuel, faire un clic droit sur l'exe et 'Exécuter en tant qu'administrateur'.
2. Si les commandes sont déclenchées via SoftControl, SoftControl lui-même n'a pas besoin de droits admin — les privilèges sont déterminés par SoftAgent côté contrôlé.
3. Vérifier la colonne 'Élevé' pour SoftAgent.App.exe dans l'onglet Détails du Gestionnaire des tâches — devrait afficher 'Oui'.
4. Si SoftAgent ne s'exécute pas en tant qu'admin, quitter SoftAgent et le redémarrer en tant qu'administrateur.

• L'onglet Détails du Gestionnaire des tâches affiche 'Oui' dans la colonne Élevé pour SoftAgent.App.exe.
• Les commandes volup/voldown répondent normalement (aucun admin requis — utile pour la vérification de base).
• La commande lock verrouille l'écran de la machine contrôlée (niveau Perturbateur — confirme que le privilège est correct).

Diagnostiquer et résoudre les échecs de démarrage automatique.

1. Exécuter schtasks /Query /TN SoftAgent dans PowerShell pour confirmer que la tâche planifiée existe.
2. Si la tâche n'existe pas, ouvrir l'onglet Paramètres de SoftAgent, re-cocher 'Démarrage automatique' et enregistrer.
3. Confirmer que le PC utilise la connexion automatique (courant dans les expositions) plutôt que d'attendre une connexion manuelle — le déclencheur de tâche est ONLOGON, nécessitant qu'un utilisateur se connecte.
4. Si configuré pour la connexion automatique, confirmer que le compte de connexion automatique a les permissions pour exécuter la tâche (nécessite un compte administrateur).
5. Vérifier les journaux récents dans %ProgramData%\SoftAgent\logs\ pour les raisons d'échec de démarrage.

• La sortie de schtasks /Query /TN SoftAgent contient le déclencheur ONLOGON et le privilège HIGHEST.
• Après le redémarrage du PC contrôlé et la connexion, SoftAgent apparaît automatiquement dans la barre d'état système.

Comprendre pourquoi le watchdog a abandonné et restaurer la surveillance de l'application cible.

1. Dans l'onglet Watchdog de la fenêtre principale SoftAgent, vérifier le badge d'état — confirme l'état 'Abandonné'.
2. Vérifier les fichiers journaux dans %ProgramData%\SoftAgent\logs\ pour la raison spécifique du crash (erreurs avant chaque crash).
3. Corriger la cause racine des crashs de l'application surveillée (erreur de configuration, dépendance manquante, conflit de port, etc.).
4. Après la correction, basculer l'interrupteur individuel de l'élément watchdog off puis on dans l'onglet Watchdog (ou envoyer run:id depuis SoftControl) pour redéclencher le watchdog.
5. Confirmer que l'état de l'élément watchdog passe à 'En cours d'exécution' et reste stable dans le temps.

• Après la correction de l'application surveillée, l'état watchdog passe de 'Abandonné' à 'En cours d'exécution'.
• Le JSON de battement de cœur montre que l'état de l'élément watchdog correspondant est mis à jour en cours d'exécution.

Abandonné est un comportement intentionnel pour éviter que les tempêtes de redémarrage infinies n'impactent les ressources système. La vraie solution est de corriger la cause racine du crash — pas de redéclencher manuellement le watchdog de façon répétée.