API per Thymio II
Questa pagina descrive le funzionalità di programmazione di Thymio.
Elenca le differenti variabili e funzioni esistenti e indica a quali elementi fisici del robot si riferiscono. Questa pagina si riferisce alla versione 7 e successive del firmware del robot.
E' possibile accedere alle API delle versioni precedenti del firmware per le versioni da 3 a 6 e versione 2.
Funzionalità e variabili hanno convenzionalmente un nome in Inglese, per garantire la portabilità del software sviluppato.
Libreria standard
Thymio è dotato della libreria standard Aseba di funzioni documentate nella propria pagina wiki.
Bottoni
Thymio ha 5 bottoni capacitivi (sensibili al tocco) corrispondenti alle frecce e al bottone circolare centrale presenti sulla faccia superiore del robot. Cinque variabili predefinite contengono lo stato di questi bottoni (1 = premuto, 0 = rilasciato):
- button.backward : freccia indietro
- button.left : freccia a sinistra
- button.center : bottone centrale
- button.forward : freccia in avanti
- button.right : freccia a destra
Thymio aggiorna queste variabili campionando ad una frequenza di 20 Hz lo stato reale dei bottoni e genera l'evento buttons dopo ogni effettivo cambiamento di almeno una delle variabili. In oltre per la variazione di stato di ognuno di questi bottoni viene generato un evento con lo stesso nome della variabile corrispondente.
Sensori di distanza
Orizzontali
Thymio ha 7 sensori di prossimità al suo contorno. Un array di 7 variabili prox.horizontal, contiene il valore di prossimità rilevato da questi sensori:
- prox.horizontal[0] : anteriore sinistro
- prox.horizontal[1] : anteriore centrale sinistro
- prox.horizontal[2] : anteriore centrale
- prox.horizontal[3] : anteriore centrale destro
- prox.horizontal[4] : anteriore destro
- prox.horizontal[5] : posteriore sinistro
- prox.horizontal[6] : posteriore destro
I valori contenuti in questo array possono variare da 0 (il sensore del robot non rilleva alcun ostacolo) a diverse migliaia (il robot è molto vicino ad un ostacolo). Thymio aggiorna questo array alla frequenza di 10 Hz, e genera lo stesso evento prox dopo ciascuna modifica.
Inferiori
Thymio ha due sensori di prossimità inferiori. Questi sensori sono collocati anteriormente sulla faccia inferiore del robot e possono essere usati per seguire una traccia ad alto contrasto presente sul terreno. Tre arrays consentono di leggere i valori misurati da questi sensori :
- prox.ground.ambiant : intensità della luce ambientale sul terreno, varia tra 0 (assenza di luce) e 1023 (massima luce)
- prox.ground.reflected : intensità della luce infrarossi riflessa quando il sensore la emette, varia tra 0 (nessuna luce riflessa) e 1023 (massima luce riflessa)
- prox.ground.delta : difference tra la la luce riflessa e la luce ambientale, legata alla distanza e al colore del terreno.
Per ciascun array, l'indice 0 corrisponde al sensore di sinistra e l'indice 1 al sensore di destra. Come per i sensori di prossimità orizzontali Thymio aggiorna questo array alla frequenza di 10 Hz.
Comunicazione locale
Thymio può utilizzare i sensori orizzontali di prossimità per comunicare un codice numerico ad altri robot Thymio in un raggio massimo di circa 15 cm. Questo codice numerico è inviato 10 volte al secondo mentre viene processata la distanza rilevata dal sensore. Thymio invia un valore a 11 bit (ma un bit va considerato riservato al firmware per usi futuri quindi vanno considerati solo 10 bit). Per usare la comunicazione chiamare la funzione prox.comm.enable(state), con 1 in state per abilitare la comunicazione e con zero per per disabilittarla. Se la comunicazione è abilitata il valore numerico contenuto nella variabile prox.comm.tx viene trasmesso ogni 100 ms. Quando Thymio riceve un valore, l'evento prox.comm viene attivato e il valore ricevuto viene memorizzato nella variabile prox.comm.rx.
Accelerometri
Thymio contiene un accellerometro a 3 assi. Un array di tre variabili, acc contiene i valori proporzionali all'accellerazione lungo questi tre assi:
- acc[0] : asse x (da destra a sinistra, positivo verso sinistra)
- acc[1] : asse y (da davanti a dietro, positivo verso dietro)
- acc[2] : asse z (da sopra a sotto, positivo verso il terreno)
I valori in questo array variano da -32 a 32, con 1 g (accellerazione pari a quella di gravità terrestre: 9.822 m/s2 o 9.822 N/kg) corrispondente al valore 23, e quindi una unità corrisponde a 0.45 N/Kg. Thymio aggiorna questo array alla frequenza di 16 Hz e genera l'evento acc dopo ogni aggiornamento, se in presenza di variazioni. In oltre quando viene rilevato un urto, viene emsso un evento tap.
Sensore di temperatura
La variabile temperature contiene la temperatura corrente misurata in decimi di grado Celsius. Thymio campiona questo valore con la frequenza di 1 Hz, e genera l'evento temperature quando rileva una modifica del valore.
LED
Thymio ha parecchi LED sparsi nel proprio corpo. Molti di questi sono associati a sensori e possono mostrare la loro attivazione: in questo caso la luminosità del LED è legata al valore rilevato dal sensore. Tuttavia quando il LED viene pilotato dal codice, il programma prende il controllo e il LED non rispecchia più il valore del sensore.
Le funzioni native consentono ai vari LED di essere controllati. Per tutti i LED i valori di intensità variano da 0 (spento) a 32 (massima luminosità).
Il cerchio di LED sulla sommità del robot
8 LED gialli creano un cerchio sulla faccia superiore del robot attorno ai bottoni.
Attivazione predefinita: riflettere i valori dell'accellerometro. Tutti i LED sono spenti quando il robot è orizzontale. Quando il robot si inclina un singolo LED mostra la direzione di inclinazione, con una luminosità proporzionale all'angolo di inclinazione.
- la funzione a 8 argomenti leds.circle(led 0, led 1, led 2, led 3, led 4, led 5, led 6, led 7) imposta la luminosità dei vari LED, dove led 0 imposta l'intensità luminosa del LED posto sul davanti del robot e gli altri seguendo una numerazione oraria.
I LED RGB
Ci sono due LED RGB sulla parte superiore del robot comandati insieme. Questi LED sono normalmente utilizzati dal firmware del robot per mostrare tramite un colore il comportamento preselezionato del robot. Ci sono altri due LED RGB sulla parte inferiore del robot che possono essere comandati separatamente.
Attivazione predefinita: spenti quando in modalità Aseba.
- la funzione leds.top(rosso, verde, blu) imposta l'intensità luminosa dei vari colori dei due LED RGB superiori.
- la funzione leds.bottom.left(rosso, verde, blu) imposta l'intensità luminosa dei vari colori del LED inferiore sinistro.
- la funzione leds.bottom.right(rosso, verde, blu) imposta l'intensità luminosa dei vari colori del LED inferiore destro.
I LED dei sensori di prossimità.
Ogni sensore di prossimità ha almeno un LED rosso a lato (i sensori frontali hanno due LED, uno per ciascun lato).
Attivazione predefinita: i LED si accendono quando un oggetto è vicino al sensore associato, con una intensità inversamente proporzionale alla distanza.
- la funzione leds.prox.h(led 1, led 2, led 3, led 4, led 5, led 6, led 7, led 8) attiva i LED dei sensori orizzontali anteriori e posteriori . Da led 1 a led 6 corrispondono i LED frontali, da sinistra a destra, mentre led 7 e led 8 corrispondono al LED posteriore sinistro e destro.
- la funzione leds.prox.v(led 1, led 2) attiva i LED associati con i sensori inferiori, rispettivamente sinistro e destro.
I LED dei bottoni
Quattro LED rossi si trovano vicino ai bottoni capacitivi.
Attivazione predefinita: Per ciascuno dei bottoni a freccia si accende un LED quando il bottone viene premuto. Quando il bottone centrale viene premuto si accendono tutti e quattro i LED.
- la funzione leds.buttons(led 1, led 2, led 3, led 4) controlla questi LED, con led 1 corrispondente al LED frontale, con numerazione oraria degli altri LED.
Il LED del ricevitore Infrarossi
Questo LED è collocato vicino al ricevitore del telecomando a infrarossi.
Attivazione predefinita: lampeggia quando il robot riceve un codice RC5.
- la funzione leds.rc(led) controlla questo LED.
I LED del sensore di temperatura
Questi due LEDs (uno rosso e uno blu) sono collocati vicino al sensore di temperatura.
Attivazione predefinita: rosso se la temperatura è superiore a 28°C, rosso e blu tra 28° e 15°, blu se la temperatura è sotto 15°.
- la funzione leds.temperature(red, blue) controlla questi LED.
Il LED del microfono
Questo led blu è collocato vicino al microfono.
Attivazione predefinita: spento.
- leds.sound(led) controlla questo LED.
Ci sono anche altri LED che l'utente non può controllarel:
- 3 LED verdi al centro della faccia superiore del robot che mostrano il livello di carica della batteria.
- un LED blu e uno rosso sulla faccia posteriore del robot che mostrano lo stato di ricarica della batteria (rosso= in carica, blu= carica completata)
- un LED rosso sul retro del robot vicino alla sede della memoria SD che si accende quando la scheda viene letta.
Motori
Potete modificare la velocità delle ruote scrivendo in queste variabili:
- motor.left.target: velocità richiesta per la ruota sinistra
- motor.right.target: velocità richiesta per la ruota destra
Potete leggere la velocità reale delle ruote da queste variabili:
- motor.left.speed : velocità reale della ruota sinistra
- motor.left.speed : velocità reale ruota destra
I valori vanno da -500 a 500. Un valore di 500 approssimativamente coorrisponde a una velocità lineare di 20 cm/s. Potete leggere i valori dei comandi ai motori dalle variabili motor.left.pwm e motor.right.pwm.
Rilevazione dell'intensità dei suoni
Il Thymio può riconoscere quando un suono ambientale è superiore ad una data intensità ed emettere un evento.
La variabile mic.intensity mostra il valore corrente di intensità del suono rilevata dal microfono (valori da 0 a 255), mentre la variabile mic.threshold contiene il valore di intensità limite per generare l'evento. Se mic.intensity è superiore a mic.threshold allora viene generato l'evento mic.
Eseguire e registrare suoni
Thymio può eseguire suoni sintetici o suoni di sistema. In aggiunta, se avete installato una micro-SD card formattata come FAT, potete registrare ed eseguire i vostri propri suoni. I file sono memorizzati nella micro-SD card, in formato wave (.wav), 8-bit senza segno, a 8 kHz. Quando Thymio completa una richiesta di esecuzione di un suono effettuata tramite Aseba, viene attivato l'evento sound.finished. Non viene generato un evento se il suono viene interrotto e un nuovo suono viene eseguito.
Suoni sintetici
La funzione nativa sound.freq esegue un tono ad una certa frequenza, specificata in Hz, per una certa durata, specificata in sessantesimi di secondo. Specificando una durata 0 il suono viene esguito senza interruzione e specificando una durata -1 il suono si interrompe.
Modificare la forma d'onda primaria
Il sintetizzatore di suoni lavora utilizzando una forma d'onda primaria campionata. Normalmente la orma d'onda è triangolare, ma si può definire una propria forma d'onda usando la funzionalità nativa sound.wave. Questa funzione prende in input un array di 142 campioni, con valori da -128 a 127. Questo buffer rappresenta la forma d'onda della frequenza tonica specificata in sound.freq. Poichè Thymio esegue i campioni a 7812.5 Hz, questo array è eseguito completamente alla frequenza di 7812.5/142 = ~55 Hz. Eseguire suoni a frequenza maggiore provocherà il salto di campioni durante l'esecuzione.
Registrare
Potete registrare suoni usando la funzione nativa sound.record. Questa funzione prende come parametro un numero da 0 a 32767 che viene associato alla registrazione. I file risultanti vengono memorizzati nella scheda di memoria micro-SD con il nome rX.wav dove X è il parametro passato alla funzione sound.record. Per smettere di registrare chiamare la funzione sound.record con il valore -1.
Riprodurre
Potete rieseguire un suono registrato utilizzando la funzione nativa sound.replay. Questa funzione prende come parametro un numero di registrazione da 0 a 32767 ed eseguirà il file rX.wav dalla scheda SD, dove X è il parametro passato alla funzione sound.replay. Per interrompere una riesecuzione chiamare la funzione sound.replay con il valore -1.
Durata (dalla versione del firmware 11)
È possibile recuperare la durata di un suono registrato utilizzando la funzione nativa sound.duration(x,duration). Il suo primo parametro, x, è un numero compreso tra 0 e 32767, che è l'indice del file Rx.wav dalla scheda SD. Il risultato in 1/10 di secondi viene inserito nella variabile duration come secondo parametro.
Creare suoni sul proprio computer
Potete creare suoni per Thymio utilizzando il vostro computer. Un modo efficiente di fare questo è utilizzare il software Audacity, versione 1.3, che esiste per vari sistemi operativi. Qui ci sono i passi per creare un suono compatibile con Thymio:
- Una volta che Audacity è partito, modificare il project rate da 44100 Hz (default) a 8000 Hz. Questo parametro è collocato in basso a sinistra nella finestra di Audacity.
- Registrate il vostro suono con il tasto di registrazione rosso in alto a sinistra della finestra. Dovreste vedere il cursore avanzare e il grafico dell'onda sonora cambiare. Arrestare con il tasto di stop.
- Il suono deve essere Mono (mettere Tracks->Stereo a Mono)
- Andare al menu File sotto Export…
- Dare un nome di file, per esempio p0.wav come primo file da eseguire utilizzando la funzione nativa sound.play.
- Scegliere other uncompressed files come format.
- Sotto options, scegliere come header l'opzione WAV (Microsoft) e come Encoding, scegliere Unsigned 8 bit PCM.
- Assicurarsi che i metadati del file non siano valorizzati.
- Salvare una copia del file sulla micro-SD card.
Per fare un rapido test potete salvare questo file con il nome s0.wav. Thymio riprodurrà il suono contenuto nel file all'avvio.
Qui potete trovare un video illustrativo che mostra come fare la procedura di cui sopra.
Qui potete trovare un foglio A4 riassuntivo per la procedura. (per ora in francese)
Esecuzione
Potete rieseguire un suono da voi prodotto utilizzando la funzione nativa sound.play, che prende un numero di registrazione da 0 a 32767 come parametro. Il file deve essere disponibile nella scheda micro-SD con il nome pX.wav dove X è il parametro passato alla funzione sound.play. Per interrompere l'esecuzione di un suono chiamare la funzione sound.play con il valore -1. Gli utenti possono condividere i loro suoni prodotti per Thymio nella libreria dei suoni.
Suoni disistema
Potete eseguire un suono di sistema utilizzando la funzione nativa sound.system, che prende un numero di registrazione da 0 a 32767 come parametro. Alcuni suoni sono già disponibili nel firmware (vedere tabella sotto), ma potete sovrascrivere questi suoni e aggiungerne dei nuovi utilizzando la memoria SD-card. In questo caso il file si deve chiamare sX.wav dove X è il parametro passato alla funzione sound.system. Per interrompere l'esecuzione di un suono, chiamare la funzione sound.system con il valore -1.
Libreria dei suoni di sistema
Nel firmware di Thymio sono disponibili i seguenti suoni di sistema:
parametro | descrizione |
---|---|
-1 | interrompe l'esecuzione di un suono |
0 | suono di avvio |
1 | suono di arresto (questo suono non è configurabile) |
2 | suono dei bottoni a freccia |
3 | suono del bottone centrale |
4 | suono di caduta libera (spaventoso) |
5 | suono di collisione |
6 | Obiettivo ok per il comportamento amichevole |
7 | riconoscimento obiettivo per comportamento amichevole |
Se volete rendere silenzioso il vostro Thymo potete scompattare nella memoria micro-SD questo archivio contenente file di suono vuoti.
Controllo remoto
Thymio contiene un ricevitore per telecomandi ad infrarossi compatibile con il protocollo RC5. Quando Thymio riceve un codice RC5, genera l'evento rc5. In questo caso, le variabili rc5.address e rc5.command vengono aggiornate.
Timer
Thymio fornisce due timer definiti dall'utente. Un array di due valori, timer.period, consente di specificare la durata del timer in ms:
- timer.period[0] : durata del timer 0 in millisecondi
- timer.period[1] : durata del timer 1 in millisecondi
Quando l'intervallo di tempo impostato scade, i timer generano rispettivamente gli eventi timer0 e timer1. Questi eventi sono gestiti alla stessa maniera di tutti gli altri e non possono interrompere un gestore di evento già in esecuzione.
Leggere e scrivere dati dalla SD card
Se è presente una SD card, la variabile sd.present è impostata su 1 (altrimenti 0) e Thymio può leggere e scrivere dati su file. Può essere aperto un solo file alla volta. L'unità di lettura e scrittura è un numero binario a 16 bit con segno. Le funzioni fornite sono:
- sd.open(x,status): apre il file Ux.DAT. Il valore x può essere un valore nell0intervallo [0:32767], using -1 si chiude il file aperto in questo momento. Un valore 0 viene scritto nella variabile status se l'operazione ha successo, -1 se l'operazione fallisce.
- sd.write(data,written): tenta di scrivere un array data completo nel file correntemente aperto. Il numero di di valori scritti viene restituito nel parametro written. Deve essere uguale alla dimensione di data, eccetto quando la scheda di memoria è piena, il file è più grane di 4 Gb, o nessun file è stato aperto.
- sd.read(data,read): legge e riempie l'array data dal file correntemente aperto. Il numero di valori letti è restituito nel parametro read. Deve essere uguale alla dimensione di data, eccetto quando la fine del file viene incontrata o nessun file è aperto.
- sd.seek(position,status): sposta il puntatore di lettura e scrittura nel file aperto correntemente. Il puntatore viene spostato nella posizione assoluta position nel file aperto. L'intervallo valido è [0:65535]. non è correntemente possibile raggiungere una posizione oltre 65535. Il valore 0 viene scritto nella variabile status se l'operazione ha avuto successo, -1 se l'operazione è fallita.
E' possibile decodificare i dati scritti in un file .DAT utilizzando un foglio excel con una macro. Il formato consiste in una semplice concatenazione di valori binari a 16 bit.
Nota: non rimuovere la scheda SD con il robot acceso. Spegnere sempre il robot prima di rimuove la scheda SD.
Caricare un programma dalla scheda SD
Thymio può caricare un programma dalla SD card. Quando parte, Thymio carica il file vmcode.abo dalla scheda SD se presente. Il file deve essere compatibile con le specifiche AS 001.
Per ottenere il file vmcode.abo dal file .aesl, apri Aseba Studio, apri il tuo programma (lad esempio mio_programma.aesl). QUindi fai click su "Strumenti", quindi "Salva codice binario…", quindi "…per thymio". Si aprirà una finestra di dialogo. Scegli un posto dove salvare il tuo file ed è tutto, hai salvato mio_programma.aesl con il formato .abo. (Devi chiamare il filevmcode.abo se vuoi che il tuo Thymio lo legga all'avvio)
Tabella degli eventi locali
eventi | descrizione | frequenza (Hz) | risultato |
---|---|---|---|
button.backward | il bottone freccia indietro è stato premuto o rilasciato | su azione | button.backward |
button.left | il bottone freccia a sinistra è stato premuto o rilasciato | su azione | button.left |
button.center | il bottone centrale è stato premuto o rilasciato | su azione | button.center |
button.forward | il bottone freccia indietro è stato premuto o rilasciato | su azione | button.forward |
button.right | il bottone freccia a destra è stato premuto o rilasciato | su azione | button.right |
buttons | I valori dei bottoni sono stati verificati | 50 | buttons.backward, buttons.left, buttons.center, buttons.forward, buttons.right |
prox | i sensori di prossimità sono stati letti | 10 | prox.horizontal[0-7], prox.ground.ambiant[0-1], prox.ground.reflected[0-1] and prox.ground.delta[0-1] |
tap | un urto è stato riconosciuto | su urto | acc[0-2] |
acc | l'accelerometro è stato letto | 16 | acc[0-2] |
mic | l'intensità del suono ambientale è superiore alla soglia | quando la condizione è vera | mic.intensity |
sound.finished | un suono eseguito da Aseba ha terminato l'esecuzione da solo (senza essere interrotto) | quando il suono finisce | |
temperature | la temperatura viene letta | 1 | temperature |
rc5 | il ricevitore infrarossi ha ricevuto un comando RC5 | su ricevimento di un segnale | rc5.address e rc5.command |
motor | viene eseguito un PID | 100 | motor.left/right.speed, motor.left/right.pwm |
timer0 | Quando l'intervallo di durata del timer 0 termina | definito dall'utente | |
timer1 | Quando l'intervallo di durata del timer 1 termina | definito dall'utente |