# Fullmo MovingCap CODE - micropython example.
# original file name: refgo.pyi
"""refgo-Modul Stub/Schnittstelle für fullmo MovingCap Servoantriebe / CODE / Micropython

Das refgo Python-Modul/Bibliothek bietet Zugriff auf den ASCII-Protokoll-Interpreter auf TCP-Port 10001.

REFGO ist MovingCaps ASCII-Befehlsprotokoll für Antriebs-Steuerung und Status-Überwachung. Es bietet
eine einfache, textbasierte Schnittstelle für gängige Antriebsoperationen, ohne Kenntnisse des
CiA402-Objektverzeichnisses zu erfordern.

Dieses Modul unterstützt zwei Anwendungsbereiche: 

1. Direkte RefGo-Befehlsausführung über `cmd()`
   - REFGO-Befehle senden und Antworten direkt empfangen
   - Automatisches Parsing und Rückgabewert-Konvertierung
   
2. Zugriff auf die MovingCap TCP-Port 10001 Server-Daten, mittels `open()`, `read()`, `write()`, `close()`:
   - Lesen/Abgreifen von REFGO-Daten, die an den MovingCap-Server-Port 10001 gesendet werden
   - Schreiben eigener Antworten auf Client-Anfragen
   - Ermöglicht benutzerdefinierte Protokollimplementierungen, z.B. für Protokoll-Kompatibilitäts-
     schichten zu Master-Applikationen, die das JennyScience XENAX® ASCII-Protokoll verwenden

Hinweis: Die 'TS'- und 'TP'-Befehle geben zur Performance-Verbesserung Integer-Werte direkt zurück,
während andere Befehle String-Antworten zurückgeben.
"""
__author__ =  "Oliver Heggelbacher"
__email__ = "oliver.heggelbacher@fullmo.de"
__version__ = "50.00.10.xx"
__date__ = "2025-11-04"

def cmd(command: str):
    """RefGo-Befehl ausführen und Antwort zurückgeben.

    So können Sie auf den vollständigen REFGO-Befehlssatz aus Ihrem MovingCap CODE Python-Skript zugreifen.
    
    Spezielle Optimierung: Die Befehle 'TS' (tell status), 'TPSR' (tell process status register) und 'TP' (tell position)
    geben Integer-Werte anstelle von Strings zurück, für bessere Performance und zur
    Vermeidung unnötiger Konvertierung auf der Skript-Seite. 

    :param command: Die RefGo-Befehlszeichenfolge, ohne CR/LF-Zeilenende. 
        Beispiel: 'TS', 'TP', 'G5000'
    :type command: str
    :return: RefGo-Antwort-String oder int für TS/TP-Befehle. 
        Gibt None zurück, wenn keine Antwort oder Fehler.
    :rtype: str or int or None

    Beispiele:
        refgo.cmd("TS")  # Aktuelle Position abrufen (gibt int zurück)
        refgo.cmd("G5000")  # Zur Position 5000 fahren
    """
    pass

def open(redirect_mode: int) -> int:
    """RefGo-Kommunikationskanal öffnen.
    
    Öffnet Zugriff auf den RefGo-Protokoll-TCP-Port (10001), um den eingebauten
    REFGO-Befehlsinterpreter zu ergänzen oder zu ersetzen.

    :param redirect_mode: Der Umleitungsmodus:
        1 - Alle eingehenden REFGO-Daten an dieses Python-Skript weiterleiten.
        2 - Nur Daten weiterleiten, die nicht vom eingebauten REFGO-
            Befehlsinterpreter verarbeitet wurden
        3 - Den eingebauten REFGO-Befehlsinterpreter deaktivieren und alles
            an dieses Python-Skript weiterleiten.
    :return: 0 bei Erfolg, ungleich null bei Fehler.
    :rtype: int
    """
    returnCode = 0
    return returnCode

def read() -> str:
    """Eingehenden Befehl lesen
    
    Liest den nächsten Text-Befehl, der am REFGO-TCP-Server-Port 10001 empfangen wurde.

    :return: Der Befehl als String, ohne CR-Terminator. None, wenn kein Befehl verfügbar.
    :rtype: str or None
    """
    pass

def write(msg: str) -> int:
    """Daten zum angegebenen RefGo-Kanal schreiben.
    
    Sendet Ihre REFGO-Befehlsantwort an den verbundenen Client. 

    :param msg: Die zu sendende Antwort.
    :type msg: str   
    :return: 0 bei Erfolg, ungleich null bei Fehler.
    :rtype: int
    
    Beispiel:
        refgo.write('OK')  # 'OK'-Antwort senden
        refgo.write('100')  # Numerische Antwort senden
    """
    returnCode = 0
    return returnCode

def close(index: int):
    """RefGo-Kommunikationskanal schließen.
    
    Schließt den mit open() geöffneten Kanal und gibt zugehörige Ressourcen frei.

    :param index: Der Kanal-Index wie beim Aufruf von open() angegeben.
    :type index: int
    
    Beispiel:
        refgo.close(0)  # Kanal 0 schließen
    """
    pass