SoftAgent Benutzerhandbuch

Bestätigen, dass die Umgebung die Anforderungen erfüllt, und die Installation vorbereiten.

1. Bestätigen Sie, dass der Ziel-PC Windows 10/11 x64 betreibt.
2. Bestätigen Sie, dass Sie über Administrator-Kontoberechtigungen verfügen (der Installer löst eine UAC-Erhöhungsaufforderung aus).
3. Bestätigen Sie, dass die Firewall eingehenden UDP-Verkehr auf Port 6500 (SoftAgents Lauschport) zulässt.
4. Das Installer-Paket ist in sich geschlossen — auf dem Zielrechner muss kein .NET-Runtime vorinstalliert sein.

• Programme als Administrator ausführen können (UAC-Erhöhung akzeptiert).
• UDP-Port 6500 wird nicht von einem anderen Programm belegt.

• Mehrere kontrollierte PCs können denselben Installer verwenden — Port und Reporting-Adresse auf jedem unabhängig konfigurieren.
• Für Ausstellungsprojekte wird empfohlen, alle kontrollierten PCs auf Auto-Login mit einem Administrator-Konto zu setzen, damit die Autostart-Aufgabe zuverlässig ausgelöst wird.

Installation abschließen und bestätigen, dass SoftAgent normal im Systemtray läuft.

1. Doppelklicken Sie auf SoftAgent-Setup-Version.exe und klicken Sie in der UAC-Aufforderung auf Ja, um Administratorrechte zu gewähren.
2. Folgen Sie dem Installer-Assistenten zur vollständigen Installation (Standard: C:\Programme\SoftAgent\).
3. Auf der Abschlussseite können Sie optional 'SoftAgent jetzt starten' auswählen oder danach manuell starten.
4. Nach dem Start erscheint SoftAgent im Systemtray (kein Hauptfenster öffnet sich).
5. Rechtsklicken Sie auf das Tray-Symbol und wählen Sie 'Konfiguration öffnen' — bestätigen Sie, dass das Hauptfenster mit 4 Tabs erscheint (Eigenschaften / Programme / Watchdog / Einstellungen).

• SoftAgent-Symbol erscheint im Systemtray.
• Task-Manager zeigt sowohl SoftAgent.App als auch SoftAgent.Watchdog-Prozesse laufend.
• Rechtsklick auf das Tray zeigt: Konfiguration öffnen / Status / Watchdog pausieren / Protokollverzeichnis öffnen / Info / Beenden.

SoftAgent verwendet eine Dual-Prozess-Architektur: Der App-Prozess übernimmt die Funktionalität, und der Watchdog überwacht und startet den App automatisch neu, wenn er abstürzt — sie sichern sich gegenseitig ab.

Grundkonfiguration abschließen und Agentfunktion per UDP-Ping bestätigen.

1. Doppelklicken Sie auf das Tray-Symbol, um das Hauptfenster zu öffnen, wechseln Sie zum Einstellungen-Tab.
2. Bestätigen Sie, dass der Lauschport 6500 ist (oder passen Sie ihn nach Bedarf an), und aktivieren Sie 'Autostart', um die geplante Aufgabe zu registrieren.
3. Für die SoftControl-Integration geben Sie die IP:Port des SoftControl-Rechners im Feld 'Reporting-Adresse' ein.
4. Klicken Sie auf 'Speichern und Anwenden', um die Konfiguration zu speichern.
5. Öffnen Sie PowerShell und senden Sie einen Ping zur Verifikation:
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. Der Empfang von ok:pong bestätigt, dass der Agent normal funktioniert.

• Das Senden von ping erhält ok:pong-Antwort.
• Autostart-Kontrollkästchen im Einstellungen-Tab ist gespeichert.
• schtasks /Query /TN SoftAgent ausführen zeigt die registrierte geplante Aufgabe.

• Port ändern, aber vergessen auf 'Speichern und Anwenden' zu klicken, sodass die Änderung nicht wirksam wird.
• Den HTTP-Verwaltungskonsolen-Port statt des UDP-Lauschports eingeben.

Befehlsformat und Risikoniveaus für die sichere Nutzung von SoftAgent beherrschen.

1. Befehlsformat: verb oder verb:arg (Argument folgt nach dem ersten Doppelpunkt), z. B. volume:80 oder ping.
2. Erfolgsantwort: ok:<code>, z. B. ok:pong oder ok:volume.
3. Fehlerantwort: err:<code>, z. B. err:wol.invalidMac.
4. Drei Risikoniveaus: Sicher (keine Unterbrechung, wiederholbar) / Störend (unterbricht Sitzung/Prozess, kein Datenverlust) / Destruktiv (Herunterfahren/Neustart/Abmelden usw.).
5. Destruktive Befehle zeigen einen Bestätigungsdialog in der Benutzeroberfläche. Bei Remote-Auslösung liegt die Bestätigungsverantwortung beim Aufrufer.

• Das Senden von ping erhält ok:pong und bestätigt, dass Verbindung und Befehlsformat korrekt sind.
• Das Senden von describe erhält eine JSON-Fähigkeitsliste mit allen unterstützten Befehlen und deren Risikoniveaus.

Der describe-Befehl gibt die vollständige Fähigkeitsliste dieser SoftAgent-Instanz zurück, einschließlich Name, Beschreibung, Risikoniveau und ob Bestätigung erforderlich ist — nützlich für die Fähigkeitserkennung bei der Integration mit SoftControl oder KI-Systemen.

Sichere Befehle für tägliche Lautstärkeregelung und Statusüberwachung beherrschen.

1. Verbindungssondierung: ping (antwortet ok:pong, bestätigt, dass Agent online ist).
2. Fähigkeitsliste abrufen: describe (gibt JSON zurück, das alle Befehle mit Beschreibungen und Risikoniveaus listet).
3. Geräteentdeckung: discover (gibt einen Heartbeat-Snapshot-JSON mit Hostname, IP, MAC, Lautstärke, Guard-Status zurück).
4. Lautstärke um einen Schritt erhöhen: volup (Standard +5% pro Aufruf).
5. Lautstärke um einen Schritt verringern: voldown (Standard -5% pro Aufruf).
6. Stummschaltung umschalten: mute (zwischen stummgeschaltet und nicht stummgeschaltet umschalten).
7. Primäre NIC-MAC-Adresse abrufen: getmac (gibt Format mit Großbuchstaben und Bindestrichen zurück, z. B. AA-BB-CC-DD-EE-FF).
8. Wake-on-LAN-Magic-Packet senden: wol:AA-BB-CC-DD-EE-FF (Rechner mit angegebener MAC aufwecken).
9. Tastatur-Simulation: key:^s (Strg+S), key:{F5} (F5-Taste), key:Hallo (Zeichen eingeben).

• ping-Befehl gibt ok:pong zurück.
• volup/voldown ändert die Lautstärke des kontrollierten Rechners.
• wol-Befehl weckt den Zielrechner auf (erfordert WoL auf dem Ziel aktiviert).

• Verwenden Sie discover, um schnell den aktuellen Zustand eines kontrollierten Rechners (IP, Lautstärke, Guard-Status) zu erhalten — nützlich für SoftControl-Batch-Integritätsprüfungen.
• key: verwendet Microsoft SendKeys-Syntax: ^ ist Strg, % ist Alt, + ist Umschalt, Sondertasten in geschweiften Klammern wie {ENTER}.

Bildschirmsperre, Prozessstart/-stopp und Abbruch-Herunterfahren-Befehle beherrschen.

1. Bildschirm sperren: lock (sperrt die aktuelle Arbeitsstation — erneute Anmeldung zum Wiederherstellen).
2. Ausstehend verzögertes Herunterfahren/Neustart abbrechen: cancelshutdown (während des Herunterfahren-Countdowns verwenden).
3. Watchdog-Element nach ID starten: run:id (z. B. run:db-player startet das Element mit dem Namen db-player).
4. Watchdog-Element nach ID stoppen: stop:id (stoppt und pausiert Watchdog — Prozess wird nicht automatisch neugestartet).
5. Verwaltetes Programm nach Index starten: startpro:0 (startet das Programm bei Index 0 in der verwalteten Programmliste).
6. Verwaltetes Programm nach Index stoppen: killpro:0.
7. Alle verwalteten Programme stoppen: killall.

• Nach lock zeigt der kontrollierte Rechner den Sperrbildschirm.
• Nach run:id startet das entsprechende Watchdog-Element — Status ändert sich von Gestoppt zu Laufend im Watchdog-Tab.
• cancelshutdown während eines Herunterfahren-Countdowns bricht das Herunterfahren ab.

• Verwenden Sie run/stop mit Watchdog-ID (stabiler Bezeichner) statt startpro/killpro mit Index (Index ändert sich beim Löschen oder Neuordnen von Elementen).
• Watchdog-IDs werden im SoftAgent-Watchdog-Tab konfiguriert. SoftControl-Befehle aktualisieren, wenn eine ID umbenannt wird.

Destruktive Operationen wie Herunterfahren, Neustart und Abmelden sicher ausführen.

1. Verzögertes Herunterfahren (empfohlen): shutdown:60 (nach 60 Sekunden herunterfahren, cancelshutdown kann während des Countdowns abbrechen).
2. Sofortiges Herunterfahren (mit Vorsicht verwenden): shutdown (ohne Verzögerung, kann nicht abgebrochen werden).
3. Verzögerter Neustart (empfohlen): reboot:60 (nach 60 Sekunden neu starten).
4. In BIOS/UEFI neu starten: reboot:firmware (erfordert UEFI-Firmware-Unterstützung).
5. Aktuellen Benutzer abmelden: logoff (vor der Ausführung bestätigen, dass keine ungespeicherten Daten vorhanden sind).
6. UAC aktivieren/deaktivieren: uac:off / uac:on (Registrierungsänderung, erfordert Neustart zum Wirksam-Werden, erfordert Admin).
7. Touchscreen-Randgesten aktivieren/deaktivieren: edgeswipe:off / edgeswipe:on.
8. Windows-Startup-Auto-Reparatur aktivieren/deaktivieren: autorepair:off / autorepair:on.

• Nach shutdown:60 zeigt das System eine Countdown-Benachrichtigung 'Herunterfahren in 60 Sekunden'.
• cancelshutdown während des Countdowns bricht das Herunterfahren ab.

• shutdown ohne Verzögerung senden, macht Abbruch unmöglich — der kontrollierte Rechner fährt sofort herunter.
• Nach uac:off nicht neu starten und davon ausgehen, dass UAC bereits deaktiviert ist (erfordert Neustart zum Wirksam-Werden).

Herunterfahren-Befehle erfordern Administratorrechte. Bei unzureichenden Berechtigungen wird ein klarer Fehlercode wie err:power.denied zurückgegeben — kein stilles Versagen.

Grundkonfiguration abschließen, damit SoftAgent von SoftControl korrekt entdeckt und gesteuert werden kann.

1. SoftAgent-Hauptfenster öffnen und zum Einstellungen-Tab wechseln.
2. Lauschport (Standard 6500): SoftControl und andere Controller senden UDP-Befehle an diesen Port.
3. Reporting-Adresse (Format IP:Port): SoftAgent sendet periodisches Heartbeat-JSON an diese Adresse; SoftControls IP und Lauschport eingeben.
4. Heartbeat-Intervall (Sekunden): Standard 10 Sekunden; Heartbeats enthalten Hostname, IP, MAC, Lautstärke, Guard-Status usw.
5. Autostart-Verzögerung (Sekunden): Verzögerung nach Anmeldung bevor SoftAgent startet (nützlich zum Warten auf Netzwerkbereitschaft).
6. Nach Änderungen auf 'Speichern und Anwenden' klicken — Port-Änderungen zeigen einen dauerhaften 'Neustart erforderlich'-Hinweis; andere Änderungen werden sofort wirksam.

• Konfiguration wird nach dem Speichern sofort wirksam (Port-Änderungen erfordern Neustart).
• Wenn eine Reporting-Adresse konfiguriert ist, sollte SoftControl beginnen, periodisches Heartbeat-JSON von diesem SoftAgent zu empfangen.

• Für mehrere kontrollierte PCs wird empfohlen, denselben Port (6500) auf allen zu verwenden, um die Batch-Befehlseingabe in SoftControl zu vereinfachen.
• Leer gelassene Reporting-Adresse bedeutet, dass SoftAgent proaktiv keine Heartbeats sendet, aber weiterhin auf UDP-Befehle antwortet.

Kontrollierte Rechner-IP-Konfiguration über SoftAgents Schnittstelle ohne RDP ändern.

1. Hauptfenster öffnen, zum Eigenschaften-Tab wechseln und die Ziel-Netzwerkkarte im Netzwerkfeld-Dropdown auswählen.
2. Nach Auswahl einer NIC werden aktuelle IP, Subnetzmaske, Gateway, DNS und MAC-Adresse automatisch ausgefüllt.
3. Zwischen 'Statische IP / DHCP'-Modus umschalten: Felder sind im statischen Modus bearbeitbar; im DHCP-Modus schreibgeschützt.
4. Ziel-IP, Subnetzmaske, Gateway und DNS ausfüllen (statischer Modus).
5. Auf 'IP-Einstellungen ändern' klicken und im Bestätigungsdialog bestätigen.
6. IP-Änderung ist eine destruktive Operation — die aktuelle Verbindung bricht nach der Änderung ab. Mit der neuen IP reconnecten.

• Nach der Änderung kann der kontrollierte Rechner erfolgreich an der neuen IP-Adresse angepingt werden.
• SoftAgent-Heartbeat-JSON zeigt die aktualisierte IP-Adresse.

IP-Änderung ist destruktiv. Vor dem Fortfahren bestätigen, dass die neue IP im LAN erreichbar ist, um den Fernzugriff auf den kontrollierten Rechner nicht zu verlieren.

Autostart konfigurieren, damit SoftAgent nach dem Neustart des kontrollierten PCs automatisch wieder läuft.

1. Im Hauptfenster-Einstellungen-Tab 'Autostart' aktivieren.
2. Auf 'Speichern und Anwenden' klicken.
3. Verifizieren mit: schtasks /Query /TN SoftAgent in PowerShell — bestätigen, dass die geplante Aufgabe registriert ist.
4. Aufgaben-Auslöser: ONLOGON (wird nach Benutzeranmeldung ausgelöst) mit HIGHEST-Berechtigungsstufe.
5. Zum Setzen einer Startverzögerung (auf Netzwerk oder abhängige Dienste warten) Sekunden im Feld 'Autostart-Verzögerung' eingeben.
6. Zum Deaktivieren des Autostarts 'Autostart' deaktivieren und speichern.

• schtasks /Query /TN SoftAgent zeigt, dass die Aufgabe existiert und aktiviert ist.
• Nach dem Neustart des kontrollierten PCs erscheint SoftAgent nach der Anmeldung automatisch im Systemtray.

SoftAgent-Befehlseinrichtung in SoftControl für schaltflächenbasierte Steuerung kontrollierter Rechner abschließen.

1. SoftControl-Admin-Panel aufrufen und Befehlsverwaltung öffnen.
2. Neuen Befehl erstellen, UDP-Protokoll auswählen.
3. Zieladresse auf die IP des kontrollierten PCs setzen (z. B. 192.168.1.101).
4. Port auf SoftAgents Lauschport setzen (Standard 6500).
5. Befehlstext auf den spezifischen Befehl setzen, z. B.: volup (Lautstärke erhöhen), mute (Stummschaltung umschalten), lock (Bildschirm sperren), shutdown:60 (in 60s herunterfahren).
6. Befehl speichern und einzeln testen — bestätigen, dass der kontrollierte Rechner korrekt reagiert.
7. Verifizierten Befehl an eine Schaltfläche auf SoftControls Frontend-Schnittstelle binden.

• Nachdem SoftControl den UDP-Befehl sendet, führt SoftAgent des kontrollierten Rechners die Aktion aus.
• SoftControl-Protokolle zeigen, dass der Befehl erfolgreich gesendet wurde (OK-Antwort).

• Einen Befehlssatz für jeden kontrollierten Rechner erstellen und den Gerätename als Präfix verwenden (z. B. 'Halle-PC-01_Herunterfahren') für einfache Wartung.
• Für Batch-Operationen wie das Schließen der Ausstellung SoftControls Befehlsgruppen verwenden — Herunterfahren-Befehle für mehrere Rechner zu einer Gruppe hinzufügen und einmal auslösen.

Heartbeat-Meldungen konfigurieren, um den Online-Status kontrollierter Rechner von SoftControl aus zu überwachen.

1. In SoftAgent-Einstellungen die Reporting-Adresse auf SoftControls IP:Port konfigurieren (SoftControls externe UDP-Schnittstelle, Standard 8818).
2. SoftAgent sendet beim Start sofort einen Heartbeat, dann weiterhin im konfigurierten Intervall (Standard 10 Sekunden).
3. Heartbeat-JSON enthält: agentId (eindeutiger Gerätebezeichner), hostname, ip/mac (Netzwerkinfo), volume/muted (Audiostatus), guards (Watchdog-Prozessstatus), uptimeSeconds.
4. Um den aktuellen Zustand eines kontrollierten Rechners aktiv abzufragen, discover von SoftControl senden — SoftAgent gibt einen Heartbeat-Snapshot zurück.
5. Das guards-Feld in Heartbeats zeigt an, ob Watchdog-Prozesse normal laufen, und enthüllt Abstürze oder Aufgabe-Zustände.

• SoftControl empfängt periodisches Heartbeat-JSON von SoftAgent.
• Das Senden von discover erhält eine JSON-Antwort mit Hostname, IP, Lautstärke und anderen Infos.

Absturz-Auto-Neustart-Watchdog für Ausstellungsanwendungen konfigurieren.

1. SoftAgent-Hauptfenster öffnen und zum Watchdog-Tab wechseln.
2. Auf 'Durchsuchen...' klicken, um die zu überwachende .exe auszuwählen, optional einen Namen und eine Watchdog-ID setzen (stabiler Bezeichner für run/stop-Befehle).
3. Auf 'Hinzufügen' klicken, um es in die Watchdog-Liste zu setzen. Einzelner Umschalter steuert, ob der Watchdog dieses Elements aktiviert ist.
4. Der Haupt-Watchdog-Umschalter befindet sich oben im Tab — Deaktivieren pausiert alle Watchdog (synchronisiert mit Tray-Menü 'Watchdog pausieren').
5. Status-Abzeichen zeigen den Zustand jedes Elements: Laufend / Gestoppt / Abgestürzt / AufgegebenGibt-Auf (Watchdog nach zu vielen Abstürzen im Zeitfenster aufgegeben).
6. Nach einem Absturz startet SoftAgent mit exponentiellem Backoff neu (anfänglich 5 Sekunden, verdoppelt sich jedes Mal; aufgegeben nach überschrittenem Limit im Zeitfenster).

• Das überwachte Programm zeigt 'Laufend'-Status in der Watchdog-Liste.
• Manuelles Beenden des überwachten Prozesses und SoftAgent startet es nach einer Verzögerung automatisch neu.
• Heartbeat-JSON guards-Feld spiegelt die neuesten Watchdog-Zustände wider.

Watchdog-ID nicht willkürlich ändern — SoftControl-run/stop-Befehle sind davon abhängig. Wenn eine ID umbenannt wird, die entsprechenden SoftControl-Befehle aktualisieren.

Den UDP-Befehlssteuerungskanal wiederherstellen.

1. Bestätigen Sie, dass SoftAgent im Systemtray sichtbar ist (Prozess läuft).
2. Bestätigen Sie, dass der Sendeport mit SoftAgents konfiguriertem Lauschport übereinstimmt (Standard 6500).
3. Prüfen Sie, ob Windows-Firewall eingehenden UDP-Verkehr auf Port 6500 zulässt.
4. Versuchen Sie ping von localhost (127.0.0.1) zuerst, um Netzwerkprobleme auszuschließen, dann remote versuchen.
5. Prüfen Sie Protokolldateien in %ProgramData%\SoftAgent\logs\ auf Befehlsempfangs-Einträge.

• ping an 127.0.0.1 senden erhält ok:pong und bestätigt, dass SoftAgent und UDP-Port funktionieren.
• ping von einem Remote-Rechner senden erhält auch eine Antwort und bestätigt, dass der Netzwerkpfad frei ist.

Sicherstellen, dass SoftAgent mit Administratorrechten läuft, um alle systemseitigen Befehle zu unterstützen.

1. Bestätigen Sie, dass SoftAgent mit Admin-Rechten läuft: Autostart verwendet geplante Aufgabe mit HIGHEST-Berechtigung; für manuellen Start .exe rechtsklicken und 'Als Administrator ausführen'.
2. Wenn Befehle über SoftControl ausgelöst werden, benötigt SoftControl selbst keine Admin-Rechte — Berechtigungen werden von SoftAgent auf der kontrollierten Seite bestimmt.
3. Im Task-Manager-Details-Tab die 'Erhöht'-Spalte für SoftAgent.App.exe prüfen — sollte 'Ja' anzeigen.
4. Wenn nicht als Admin laufend, SoftAgent beenden und als Administrator neu starten.

• Task-Manager-Details-Tab zeigt 'Ja' in der Erhöht-Spalte für SoftAgent.App.exe.
• volup/voldown-Befehle reagieren normal (kein Admin erforderlich — nützlich für grundlegende Verifikation).
• lock-Befehl sperrt den kontrollierten Rechner-Bildschirm (Störend-Stufe — bestätigt, dass Berechtigung korrekt ist).

Autostart-Fehler diagnostizieren und beheben.

1. schtasks /Query /TN SoftAgent in PowerShell ausführen, um zu bestätigen, dass die geplante Aufgabe existiert.
2. Wenn die Aufgabe nicht existiert, SoftAgent-Einstellungen-Tab öffnen, 'Autostart' erneut aktivieren und speichern.
3. Bestätigen Sie, dass der PC Auto-Login verwendet (üblich in Ausstellungen) statt auf manuelle Anmeldung zu warten — der Aufgaben-Auslöser ist ONLOGON, erfordert Benutzeranmeldung.
4. Wenn für Auto-Login eingerichtet, bestätigen Sie, dass das Auto-Login-Konto Berechtigungen hat, die Aufgabe auszuführen (erfordert Administrator-Konto).
5. Aktuelle Protokolle in %ProgramData%\SoftAgent\logs\ auf Startfehler-Gründe prüfen.

• schtasks /Query /TN SoftAgent-Ausgabe enthält ONLOGON-Auslöser und HIGHEST-Berechtigung.
• Nach dem Neustart des kontrollierten PCs und Anmeldung erscheint SoftAgent automatisch im Systemtray.

Verstehen, warum der Watchdog aufgegeben hat, und die Überwachung der Zielanwendung wiederherstellen.

1. Im SoftAgent-Hauptfenster-Watchdog-Tab das Status-Abzeichen prüfen — bestätigt 'GibtAuf'-Zustand.
2. Protokolldateien in %ProgramData%\SoftAgent\logs\ auf den spezifischen Absturzgrund prüfen (Fehler vor jedem Absturz).
3. Die Ursache der Abstürze der überwachten Anwendung beheben (Konfigurationsfehler, fehlende Abhängigkeit, Port-Konflikt usw.).
4. Nach der Behebung den einzelnen Umschalter des Watchdog-Elements im Watchdog-Tab aus- und wieder einschalten (oder run:id von SoftControl senden), um Watchdog neu auszulösen.
5. Bestätigen, dass sich der Watchdog-Element-Status zu 'Laufend' ändert und im Laufe der Zeit stabil bleibt.

• Nach Behebung der überwachten Anwendung ändert sich der Watchdog-Status von 'GibtAuf' zu 'Laufend'.
• Heartbeat-JSON zeigt den aktualisierten Watchdog-Element-Status als laufend.

GibtAuf ist absichtliches Verhalten, um endlose Neustart-Stürme zu verhindern, die Systemressourcen beeinträchtigen. Die eigentliche Lösung ist die Behebung der Absturzursache — nicht manuelles Watchdog-Neu-Auslösen wiederholen.