io_decoder Project

USB HAL driver for LinuxCNC

View project on GitHub
🏠 Home 📖 Manuale 📥 Download v1.0-eval 💻 GitHub ✉️ Contatto UK Flag English

⚡ Guida io_decoder_eval

Benvenuto nella guida di io_decoder demo/eval mode. Segui questi passaggi per configurare la tua scheda in meno di 5 minuti.

1. Requisiti di Sistema

  • Sistema Operativo: Linux con kernel Real-Time.
  • LinuxCNC: Versione 2.8 o superiore.

  • Hardware: Una porta USB libera. Arduino UNO R3.
    Compatibilità Hardware
    Il file .hex fornito è compilato specificamente per il microcontrollore ATmega328P con clock a 16MHz.

    ✅ Confermati: Arduino Uno R3 (originale e cloni), Arduino Nano (versione 5V) e schede compatibili al 100% con il layout Uno.

❌ NON Compatibili: Arduino Mega, Leonardo, Micro o qualsiasi scheda a 32-bit (es. Due, Zero, ESP32, STM32).

    Da ora in poi in questa guida mi riferirò solo con arduino UNO.

2. Installazione del Driver

Scarica e poi decomprimi io_decoder_eval-v1.zip.

Sposta il file io_decoder.c del componente ed il file io_decoder_eval.hex dove ti resta più comodo;
sposta il file io_decoder-keymap.cfg nella cartella della configurazione della macchina cnc, se vuoi usare la funzionalità keyboard.

Comandi di installazione su macchina Linux

  • compilare il componente:
    Con il terminale aprire la cartella dove è salvato il file .c del componente e digitare: 
    sudo halcompile --install io_decoder.c
  • definire porta USB:
    1. Trova le informazioni sull’apparecchio USB
      Collega il dispositivo e dai questo comando per trovare le sue caratteristiche: 
        lsusb

      Nella risposta al comando, con la scheda collegata all’usb, dovrebbe apparire una riga come questa:
      Bus 001 Device 008: ID 2341:0043 Arduino SA Uno R3 (CDC ACM)

  1. Crea una regola udev
    Aprire un terminale ed aprire la cartella delle regole con: 
     cd /etc/udev/rules.d/

    Creare una regola per un device seriale USB:

     sudo nano /etc/udev/rules.d/99-io_decoder.rules

    Una volta eseguito, il terminale aprirà l’editor di testo nano. il numero 99 serve per dire al sistema di leggere la regola per ultima, fra tutte quelle che ha. Il nome del file 99-io_decoder.rules è quello che ho scelto io; ma questo può essere qualsiasi.
    Incolla la seguente regola all’interno del file:

     SUBSYSTEM=="tty", ATTRS{idVendor}=="2341", ATTRS{idProduct}=="0043", SYMLINK+="io_decoder", MODE="0666", ENV ID_MM_DEVICE_IGNORE}="1"

    Premi Ctrl + O per salvare (ti chiederà di confermare il nome del file e se non esiste questo verrà creato, premi Invio).
    Premi Ctrl + X per uscire dall’editor.
    Così il tuo device sarà accessibile come /dev/io_decoder indipendentemente dalla porta fisica.
    Se vuoi cambiare il nome del link simbolico dell’usb, modifica il valore scritto in SYMLINK+

    ATTENZIONE Con MODE=”0666” vengono aperti i permessi di lettura/scrittura della USB a chiunque usi il sistema. Se vuoi tenere il sistema con delle sicurezze maggiori devi creare, con i comandi di prompt, un gruppo che possa contenere la comunicazione con i permessi adeguati ed impostarlo nella stringa con GROUP=”nome_tuo_gruppo”.

  2. Ricarica le regole udev 
     sudo udevadm control --reload-rules    
 sudo udevadm trigger
  3. Verifica
    Scollega e ricollega il dispositivo, poi verifica con: 
     ls -l /dev/io_decoder

    Con queste impostazioni il valore di default dichiarato in fase di inizializzazione del componente è soddisfatto. Comunque il tutto è liberamente configurabile.

Comandi di installazione su arduino UNO R3

  • Come caricare il firmware (Flashing)
    Il file io_decoder_eval.hex deve essere trasferito sulla memoria dell’Arduino Uno. Scegli il metodo più adatto al tuo sistema operativo.

    • Opzione 1: Linux (Terminale) - Consigliato per utenti LinuxCNC Su Linux, lo strumento standard è avrdude. Apri il terminale nella cartella dove hai scaricato il file .hex ed esegui:

      # Identifica la porta (solitamente /dev/ttyACM0 o /dev/ttyUSB0)
ls /dev/tty*
  
# Carica il firmware
avrdude -v -patmega328p -carduino -P/dev/ttyACM0 -b115200 -D -Uflash:w:io_decoder_eval.hex:i

      Nota: Se ricevi un errore di “Permission denied”, assicurati che il tuo utente sia nel gruppo dialout: sudo usermod -a -G dialout $USER e riavvia la sessione.

    • Opzione 2: Windows (Grafico) Se preferisci un’interfaccia visuale, usa XLoader (un tool gratuito e leggero):

      Scarica ed esegui XLoader.

      In Hex file, seleziona io_decoder_eval.hex.

      In Device, seleziona Uno(ATmega328).

      Seleziona la COM Port corretta.

      Imposta Baud rate a 115200.

      Clicca su Upload.

    • Opzione 3: Arduino IDE (Avanzato) Se hai già l’IDE di Arduino installato, puoi usare l’utility avrdude inclusa, ma la riga di comando rimane il metodo più veloce.

  • ⚠️ Verifiche post-caricamento
    Una volta completato l’upload:

    Il LED “L” (collegato al pin 13) dell’Arduino dovrebbe fare un breve lampeggio di reset.

    Ora puoi collegare l’Arduino al PC dove gira LinuxCNC e lanciare il comando lsusb per verificare che venga riconosciuto (ID 2341:0043).

  • Un piccolo consiglio extra per te: Se usi un clone Arduino economico, la porta su Linux potrebbe chiamarsi /dev/ttyUSB0 invece di /dev/ttyACM0. Verifica con il comando dmesg | grep tty.

3. Configurazione HAL

Aggiungi queste righe al tuo file di configurazione .hal per integrare la scheda:

   loadrt io_decoder firmware=255
   addf io_decoder.update	servo-thread

Sinossi

  • loadrt io_decoder [input=num] [output=num] [usb_port_name=“string”] [firmware=num] [verbose=num] [keymap_file=“string”] [uinput_chmod_cmd=“string”]
    • input: questa versione ha il numero degli input fissato a 4. Se il parametro viene inserito il valore comunque viene settato a 4.
    • output: questa versione ha il numero degli output fissato a 4. Se il parametro viene inserito il valore comunque viene settato a 4.
    • usb_port_name: per poter nominare la porta a piacere e renderla fissa; vedere sezione definire porta USB . Valore di default “/dev/io_decoder”
    • firmware: In questa versione deve essere firmware=255
    • verbose: per abilitare il livello dei messaggi di errore sulla GUI. il numero attiva il tipo di messaggio indicato e quelli di valore inferiore. default 1.
      • 0=nessuno.
      • 1=componente. Invia messaggio in caso di disconnessione o di riavvio della comunicazione USB e segnala i messaggi della funzionalità keyboard se non è attivata per qualsiasi motivo.
      • 2=minimi. Messaggi di percentuale di errore parsing.
      • 3=tutti.
    • keymap_file: file di testo per impostare le corrispondenze input => simulazione tastiera. Valore di default “io_decoder-keymap.cfg”
    • uinput_chmod_cmd: parametro stringa per dare i permessi di scrittura su UINPUT per la funzionalità di tastiera simulata. Se si vuole essere sicuri di non dare i permessi il parametro deve essere “” (uinput_chmod_cmd=”” senza niente all’interno delle virgolette) . Valore di default “chmod 0666 /dev/uinput” .
  • Firmware 255
    • versione speciale di valutazione per arduino UNO R3
    • 4 input digitali
    • 4 output digitali
    • Encoder in quadratura: 1 @5Vdc
    • DAC (PWM): 1 @8bit 5Vdc
    • ADC: 1 @10bit 5Vdc

4. Test e Diagnostica

Verifica il funzionamento lanciando lo strumento di monitoraggio ‘halshow’ di linuxCNC:

Nella sezione Pins, cerca: io_decoder.in.00-0 -1 -2 -3 per vedere i segnali digitali in ingresso.
io_decoder.out.00-0 -1 -2 -3 per commutare lo stato delle uscite digitali.
io_decoder.enc.0 per vedere il conteggio dell’encoder.
io_decoder.dac.0 per settare il valore del DAC.
io_decoder.adc.0 per leggere il valore letto dall’ADC.

Lista completa dei pin di HAL disponibili.

5. Collegamenti elettrici per questa versione

io_decoder_eval

Arduino UNO Eval Pinout (Firmware 255)

Pin Funzione Direzione Pull-up Descrizione
D2 Encoder Phase A Input Interno Interrupt Hardware (Fase A)
D3 Encoder Phase B Input Interno ingresso digitale (Fase B)
D4 Input 0 Input Interno Ingresso Digitale 0 attivo basso
D5 Input 1 Input Interno Ingresso Digitale 1 attivo basso
D6 Input 2 Input Interno Ingresso Digitale 2 attivo basso
D7 Input 3 Input Interno Ingresso Digitale 3 attivo basso
D9 DAC (PWM) Output N/A Uscita Analogica (PWM da filtrare)
D10 Output 3 Output N/A Uscita Digitale 3 (LED) max 20mA
D11 Output 2 Output N/A Uscita Digitale 2 (LED) max 20mA
D12 Output 1 Output N/A Uscita Digitale 1 (LED) max 20mA
D13 Output 0 Output N/A Uscita Digitale 0 (LED “L” Integrato) max 20mA
A0 ADC 0 Input No Ingresso Analogico (0-5V)
5V VCC Power N/A Alimentazione Sensori/Encoder
GND Ground Power N/A Massa Comune

Nel manuale è spiegato a fondo tutte le configurazioni e possibilità di questo sistema hardware/software per linuxCNC.

🔗 Risorse Utili