trgenlib¶

Una libreria MATLAB per il dispositivo TriggerBox di IIT 📚

Architettura¶

Come illustrato in questo diagramma Mermaid, è possibile “collegare” n (0-25) TrgenPort al TrgenClient.

        graph TD
    A[TrgenClient]
    A --> Impl[TrgenImplementation]
    A --> B0[TrgenPort 0]
    A --> B1[TrgenPort 1]
    A --> BN[TrgenPort n]
    B0 --> P0[TrgenPin]
    B1 --> P1[TrgenPin]
    BN --> PN[TrgenPin]
    B0 --> M0[Memory]
    B1 --> M1[Memory]
    BN --> MN[Memory]
    M0 --> I0[Instruction 0]
    M0 --> I1[Instruction 1]
    M0 --> I2[Instruction n]
    M1 --> J0[Instruction 0]
    M1 --> J1[Instruction 1]
    M1 --> J2[Instruction n]
    MN --> K0[Instruction 0]
    MN --> K1[Instruction 1]
    MN --> K2[Instruction n]

Ogni TrgenPort può essere programmato con una serie di istruzioni. Possiamo utilizzare la funzione set_instruction() in diversi slot di memoria. Infine, possiamo usare set_trgen_memory su uno specifico TrgenPort ed eseguire il TrgenClient con client.start()

NOTA¶

Ogni TrgenPort può supportare una lista di N istruzioni, dove N = 2^MTML (Max TrgenPort Memory Length)

Descrizione¶

trgenlib è una libreria MATLAB che fornisce un’interfaccia semplice e intuitiva per controllare il dispositivo TriggerBox dell’Istituto Italiano di Tecnologia (IIT). La libreria permette di programmare trigger temporizzati su diversi pin di uscita del dispositivo.

Caratteristiche principali¶

✅ Interfaccia TCP/IP per comunicazione con il dispositivo
✅ Supporto per programmazione di trigger su pin multipli (NS0-NS4, SPI_CS, SPI_CLK)
✅ Controllo temporale preciso (microsecondi)
✅ Verifica di integrità dei dati con CRC32
✅ Gestione automatica della memoria dei trigger
✅ API orientata agli oggetti

Prerequisiti¶

MATLAB R2019b o superiore
Instrument Control Toolbox (per la comunicazione TCP/IP)
Dispositivo TriggerBox IIT configurato sulla rete

Installazione rapida¶

Clona il repository

git clone https://gitlab.com/your-group/trgenlib.git
cd trgenlib

Avvia MATLAB e naviga nella cartella del progetto
Esegui lo script di startup
```
startup
```
Questo comando aggiunge automaticamente tutti i path necessari e importa la libreria.

Installazione manuale del path¶

Se preferisci aggiungere manualmente i path:

% Aggiungi la cartella src al path MATLAB
addpath(genpath('src'));
savepath;  % Salva permanentemente il path

Verifica dell’installazione¶

Per verificare che l’installazione sia andata a buon fine:

% Testa la creazione di un client
client = TrgenClient('192.168.123.1');
disp('✅ trgenlib installata correttamente!');

Esempio base¶

% Esempio di utilizzo del client TRGEN in MATLAB
addpath(genpath('src'));

% Inizializza il client
client = TrgenClient('192.168.123.1');

% Verifica se il dispositivo è disponibile
if client.isAvailable()

    fprintf('✔ TRGEN disponibile\n');

    % connect to device
    client.connect();

    client.setDefaultTriggerDuration(40)
    % Single trigger on default pin
    client.sendTrigger(0);  % 10µs su TMSO, valore di default
    client.sendTrigger(TrgenPin.NS5,80);     % Durata default su TMSO

    % Marker on default pin
    client.sendMarker('markerNS', 5);                     % Marker 5 su NS
    client.sendMarker('markerGPIO', 3, 'duration', 15);   % Marker 3 su GPIO per 15µs
    client.sendMarker('markerNS', 7, 'markerSA', 2);      % Su entrambi NS e SA

    % Multiple triggers
    client.sendCustomTrigger({TrgenPin.NS7}, 10);  % Multipli pin


    % custom approach
    % Request implementation details
    impl = client.getImplementation();
    fprintf('↪ Memoria per trigger: %d istruzioni\n', impl.memoryLength);

    % Create a trigger generator on pin NS5
    %trig = client.createTrgen(TrgenPin.NS5);

    % Add instructions to the trigger generator
    % Programm a trigger with 10µs pulse
    %client.programDefaultTrigger(trig, 10);

    % Avvia i trigger
    %client.start();
    %fprintf('✅ Trigger programmato e avviato\n');

else
    fprintf('✘ TriggerBox non raggiungibile\n');
end

Esempio avanzato con trigger multipli¶

% Crea trigger su pin diversi
triggerNS0 = TrgenPort(TriggerPin.NS0, impl.memoryLength);
triggerNS1 = TrgenPort(TriggerPin.NS1, impl.memoryLength);

% Programma sequenze diverse
% NS0: impulso lungo (100µs)
triggerNS0.setInstruction(0, Instruction.activeForUs(100));
triggerNS0.setInstruction(1, Instruction.endInst());

% NS1: impulsi multipli
triggerNS1.setInstruction(0, Instruction.activeForUs(10));
triggerNS1.setInstruction(1, Instruction.unactiveForUs(5));
triggerNS1.setInstruction(2, Instruction.activeForUs(10));
triggerNS1.setInstruction(3, Instruction.endInst());

% Invia entrambi i trigger
client.sendTrigger(triggerNS0);
client.sendTrigger(triggerNS1);

Per la documentazione completa dell’API, esempi dettagliati e guide avanzate, consulta la documentazione online generata automaticamente.

trgenlib/
├── README.md                 # Questo file
├── startup.m                 # Script di inizializzazione
├── src/                      # Codice sorgente
│   ├── TrgenClient.m         # Client principale
│   ├── TrgenPort.m             # Classe per i trigger
│   ├── Instruction.m         # Istruzioni del trigger
│   ├── TriggerPin.m          # Definizione dei pin
│   └── ...
├── demo/                     # Esempi di utilizzo
│   └── example_usage.m       # Esempio principale
├── docs/                     # Documentazione generata
└── tests/                    # Test automatici

La libreria supporta i seguenti pin di uscita:

Pin	Descrizione	Uso tipico
NS0-NS4	Pin di trigger numerici	Trigger generici
SPI_CS	Chip Select SPI	Controllo dispositivi SPI
SPI_CLK	Clock SPI	Segnale di clock

Problemi comuni¶

❌ Errore di connessione TCP/IP

Verifica che l’IP del dispositivo sia corretto
Controlla che il dispositivo sia acceso e raggiungibile
Verifica che il firewall non blocchi la porta 4242

❌ Timeout di comunicazione

Il dispositivo potrebbe essere occupato
Prova ad aumentare il timeout: client.timeout = 5.0;

❌ Path non trovato

Assicurati di aver eseguito startup o aggiunto manualmente i path
Verifica che tutti i file siano presenti nella cartella src/

Log di debug¶

Per abilitare i log di debug:

client.impl.debug = true;  % Abilita logging dettagliato

Contributi sono benvenuti! Per contribuire:

Fork del progetto
Crea un branch per la tua feature (git checkout -b feature/nuova-feature)
Commit delle modifiche (git commit -am 'Aggiungi nuova feature')
Push del branch (git push origin feature/nuova-feature)
Apri una Pull Request

Questo progetto è rilasciato sotto licenza MIT. Vedi il file LICENSE per i dettagli.

Sviluppato presso l’Istituto Italiano di Tecnologia (IIT)
Mantenuto dal team di [Nome Team]

v1.0.0¶

Prima release pubblica
Supporto completo per tutti i pin del TriggerBox
API stabile e documentata