# Fullmo MovingCap CODE - micropython example.
# original file name: refgo.pyi
"""Modulo refgo stub/interfaccia per i servoazionamenti fullmo MovingCap / CODE / Micropython

Il modulo/libreria Python refgo fornisce accesso all'interprete del protocollo ASCII sulla porta TCP 10001.

REFGO è il protocollo di comando ASCII di MovingCap per il controllo dell'azionamento e il monitoraggio dello stato. Fornisce
un'interfaccia semplice, basata su testo per operazioni comuni dell'azionamento senza richiedere la conoscenza del
dizionario oggetti CiA402.

Questo modulo supporta due aree di applicazioni:

1. Esecuzione diretta dei comandi RefGo tramite `cmd()`
   - Invia comandi REFGO e ricevi risposte direttamente
   - Analisi automatica e conversione del valore di ritorno
   
2. Accesso ai dati del server della porta TCP 10001 di MovingCap, usando `open()`, `read()`, `write()`, `close()`:
   - lettura/intercettazione dei dati REFGO inviati alla porta server 10001 di MovingCap
   - scrittura di proprie risposte alle richieste del client
   - Consente implementazioni di protocolli personalizzati, ad es. per livelli di compatibilità del protocollo con applicazioni
     master che utilizzano il protocollo ASCII XENAX® di JennyScience

Nota: I comandi 'TS' e 'TP' restituiscono valori interi direttamente per prestazioni migliori,
mentre altri comandi restituiscono risposte stringa.
"""
__author__ =  "Oliver Heggelbacher"
__email__ = "oliver.heggelbacher@fullmo.de"
__version__ = "50.00.10.xx"
__date__ = "2025-11-04"

def cmd(command: str):
    """Esegue comando RefGo e restituisce la risposta.

    Questo è il modo in cui puoi accedere al set completo di comandi REFGO dal tuo script Python MovingCap CODE.
    
    Ottimizzazione speciale: I comandi 'TS' (tell status), 'TPSR' (tell process status register) e 'TP' (tell position)
    restituiscono valori interi invece di stringhe per prestazioni migliori e per
    evitare conversioni non necessarie sul lato script.

    :param command: La stringa di comando RefGo, senza fine riga CR/LF.
        Esempio: 'TS', 'TP', 'G5000'
    :type command: str
    :return: Stringa di risposta RefGo, o int per comandi TS/TP.
        Restituisce None se nessuna risposta o errore.
    :rtype: str or int or None

    Esempi:
        refgo.cmd("TS")  # Ottieni posizione corrente (restituisce int)
        refgo.cmd("G5000")  # Vai alla posizione 5000
    """
    pass

def open(redirect_mode: int) -> int:
    """Apre il canale di comunicazione RefGo.
    
    Apre l'accesso alla porta TCP del protocollo RefGo (10001) per aumentare o sostituire
    l'interprete di comandi REFGO integrato.

    :param redirect_mode: La modalità di reindirizzamento:
        1 - Inoltra tutti i dati REFGO in arrivo a questo script Python.
        2 - Inoltra solo i dati che non sono stati elaborati dall'interprete di comandi REFGO
            integrato
        3 - Disabilita l'interprete di comandi REFGO integrato e inoltra tutto
            a questo script Python.
    :return: 0 se riuscito, diverso da zero in caso di errore.
    :rtype: int
    """
    returnCode = 0
    return returnCode

def read() -> str:
    """Legge il comando in arrivo
    
    Legge il prossimo comando di testo che è stato ricevuto sulla porta server TCP REFGO 10001.

    :return: Il comando come stringa, senza il terminatore CR. None se nessun comando disponibile.
    :rtype: str or None
    """
    pass

def write(msg: str) -> int:
    """Scrive dati al canale RefGo specificato.
    
    Invia la tua risposta al comando REFGO al client connesso.

    :param msg: La risposta da inviare.
    :type msg: str   
    :return: 0 se riuscito, diverso da zero in caso di errore.
    :rtype: int
    
    Esempio:
        refgo.write('OK')  # Invia risposta 'OK'
        refgo.write('100')  # Invia risposta numerica
    """
    returnCode = 0
    return returnCode

def close(index: int):
    """Chiude un canale di comunicazione RefGo.
    
    Chiude il canale aperto con open() e rilascia le risorse associate.

    :param index: L'indice del canale come specificato quando si chiama open().
    :type index: int
    
    Esempio:
        refgo.close(0)  # Chiudi canale 0
    """
    pass