trgenlib ======== Una libreria MATLAB per il dispositivo TriggerBox di IIT πŸ“š .. image:: https://img.shields.io/badge/docs-latest-brightgreen.svg :target: https://your-gitlab-pages-url/docs :alt: Documentation .. image:: https://img.shields.io/badge/license-MIT-blue.svg :target: LICENSE :alt: License Architettura ^^^^^^^^^^^^ Come illustrato in questo diagramma `Mermaid `_\ , Γ¨ possibile "collegare" n (0-25) TrgenPort al ``TrgenClient``. .. mermaid:: 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 Installazione ------------- Prerequisiti ^^^^^^^^^^^^ * MATLAB R2019b o superiore * Instrument Control Toolbox (per la comunicazione TCP/IP) * Dispositivo TriggerBox IIT configurato sulla rete Installazione rapida ^^^^^^^^^^^^^^^^^^^^ #. **Clona il repository** .. code-block:: bash git clone https://gitlab.com/your-group/trgenlib.git cd trgenlib #. **Avvia MATLAB** e naviga nella cartella del progetto #. **Esegui lo script di startup** .. code-block:: matlab startup Questo comando aggiunge automaticamente tutti i path necessari e importa la libreria. Installazione manuale del path ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Se preferisci aggiungere manualmente i path: .. code-block:: matlab % 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: .. code-block:: matlab % Testa la creazione di un client client = TrgenClient('192.168.123.1'); disp('βœ… trgenlib installata correttamente!'); Utilizzo rapido --------------- Esempio base ^^^^^^^^^^^^ .. code-block:: matlab % 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: matlab % 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); Documentazione completa ----------------------- Per la documentazione completa dell'API, esempi dettagliati e guide avanzate, consulta la `documentazione online `_ generata automaticamente. Struttura del progetto ---------------------- .. code-block:: 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 Pin supportati -------------- La libreria supporta i seguenti pin di uscita: .. list-table:: :header-rows: 1 * - 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 Troubleshooting --------------- 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: .. code-block:: matlab client.impl.debug = true; % Abilita logging dettagliato Contribuire ----------- 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 Licenza ------- Questo progetto Γ¨ rilasciato sotto licenza MIT. Vedi il file `LICENSE `_ per i dettagli. Autori e riconoscimenti ----------------------- * Sviluppato presso l'Istituto Italiano di Tecnologia (IIT) * Mantenuto dal team di [Nome Team] Changelog --------- v1.0.0 ^^^^^^ * Prima release pubblica * Supporto completo per tutti i pin del TriggerBox * API stabile e documentata