Schede e sensori

Una scheda a microcontrollore su un cavo USB trasforma qualsiasi sensore in una manopola e qualsiasi controllo di Humus in un interruttore, un dimmer o un colore. Ci sono due modi per comunicare con la scheda, e questa pagina li percorre entrambi con un Arduino Uno:

Board, un organism che non richiede codice sulla scheda. Carica una volta lo sketch standard Firmata e i suoi pin sono tuoi.
SerialIn e SerialOut, per uno sketch tuo. Lo sketch stampa e legge semplice testo o byte, e i due box parlano la lingua che ha deciso lo sketch: il protocollo è lo sketch.

Cosa ti serve

Una scheda con una connessione seriale USB. Gli esempi usano un Arduino Uno: sei ingressi analogici (da A0 ad A5) e il LED integrato sul pin 13. Un Nano, un Leonardo, un Mega, una scheda di sviluppo ESP32 o un Raspberry Pi Pico funzionano allo stesso modo, e l'organism Board ha un preset per ciascuno.
L'Arduino IDE, o l'editor che usa la tua scheda, per caricarci lo sketch.
Un sensore con uscita analogica per la prima storia: un potenziometro è il più semplice, un termistore o un sensore di temperatura analogico è quello della storia. Un LED e una resistenza da 220 ohm per la seconda storia, o semplicemente il LED integrato sul pin 13. Un anello di 24 LED indirizzabili per gli ultimi tre esempi.

Ogni patch e ogni sketch di questa pagina si trova in Humus sotto File > Esempi > Organisms, una cartella per ogni scenario: Board contiene le due storie con Firmata, SerialIn e SerialOut gli sketch tuoi, la cartella NeoPixel l'anello. Lo stesso albero è la cartella examples/ del sorgente, quindi lo sketch da caricare sta accanto alla patch che lo pilota, in una cartella con il suo stesso nome, come vuole l'editor della scheda.

Su Linux la porta appartiene al gruppo dialout; aggiungiti con sudo usermod -aG dialout $USER e rientra nella sessione. Su macOS e Windows la porta è pronta appena colleghi la scheda. Qualunque strada scegli, chiudi il Monitor seriale dell'IDE dopo aver caricato lo sketch: solo un programma alla volta può tenere la porta.

Nessun codice sulla scheda: Firmata

L'organism Board parla Firmata, un protocollo aperto per cui l'Arduino IDE include già uno sketch. Lo carichi una volta e non riapri più l'IDE:

Apri l'Arduino IDE, collega la scheda, scegli la scheda e la sua porta sotto Strumenti.
File ▸ Esempi ▸ Firmata ▸ StandardFirmata, poi Carica.

Storia uno: un sensore di temperatura suona un filtro

Collega l'uscita del sensore ad A0, l'alimentazione a 5V (o a 3.3V, quella che vuole il sensore) e la massa a GND. Un potenziometro va tra 5V e GND, con il cursore su A0.

In Humus apri Esempi > Organisms > Board > Sensor, oppure costruiscila da te:

Aggiungi un Board dalla categoria Primitive e scegli Arduino Uno / Nano tra i suoi preset. Il suo menu Port dice Auto, che va bene quando è collegata una sola scheda. Il misuratore del box comincia a lampeggiare un paio di secondi dopo l'apertura della patch: la scheda si riavvia quando la porta si apre e poi comincia a mandare letture.
Aggiungi un Number e trascina un cavo dall'uscita out1 (A0) di Board alla presa del Number. Ora il Number mostra il sensore dal vivo: scalda il sensore, o gira il potenziometro, e guarda il valore che si muove. È il box numerico della tradizione del patching, il posto dove leggi un controllo.
Aggiungi un TestGen, un Filter e un SoundOut. Collega le due uscite di TestGen ai due ingressi del Filter, e il Filter a SoundOut.
Fai clic destro sulla manopola Frequency del Filter, scegli Controlla con ▸ Number ▸ value e imposta l'intervallo a 200..8000. Stavolta niente cavo: la lettura che stai guardando ora apre il filtro mentre sale, e lo stesso Number può pilotare allo stesso modo qualsiasi altra manopola.

In Humus ogni parametro accetta un controllo in questo modo, e ogni presa accetta un cavo di controllo. Un sensore che legge 0..1 sull'uscita è la cosa più semplice da instradare; scalalo nell'intervallo del collegamento, oppure con uno Slider o un Math in mezzo quando gli serve una curva.

Ogni uscita legge il canale analogico impostato al suo fianco, quindi l'A8 di un Mega è a un numero di distanza, e Outlets stabilisce quante uscite mostra il box. Di default le letture arrivano ogni 19 ms (Read every).

Storia due: la musica accende un LED

Lascia il LED integrato sul pin 13, oppure, per la parte in cui la luce si attenua, collega un LED con una resistenza da 220 ohm tra il pin 11 e GND.

Apri Esempi > Organisms > Board > LED, oppure costruiscila da te:

Aggiungi un SoundIn e un Follower; collega l'uscita di SoundIn al Follower. Regola il Threshold del Follower in modo che il suo gate si apra a ogni colpo di qualunque cosa suoni nel microfono.
Aggiungi un Board con il preset Uno. Trascina un cavo dall'uscita gate del Follower alla presa 1 di Board. La presa 1 pilota Pin 1, che è il 13 in modalità Digital: il LED si accende a ogni colpo.
Trascina un cavo dall'uscita env del Follower alla presa 2. La presa 2 pilota il pin 11 in modalità PWM, e il secondo LED respira con il livello.

Tutto ciò che porta un controllo può pilotare un pin: un Button per un relè, un LFO per una dissolvenza lenta, uno Slider per una mano su un dimmer. La modalità Digital commuta a 0.5; PWM mappa 0..1 sul duty cycle del pin, e solo i pin PWM possono regolare l'intensità (3, 5, 6, 9, 10 e 11 sull'Uno).

Uno sketch tuo: SerialIn e SerialOut

Quando la scheda deve fare qualcosa che StandardFirmata non sa fare (leggere un sensore digitale via I2C, pilotare un anello di LED indirizzabili, fare il debounce di un tastierino), scrivi lo sketch da te e parla con Humus in semplice testo o in byte. Nessuna libreria nostra, nessun protocollo da imparare: il protocollo è lo sketch, e il box SerialOut mostra esattamente i byte che escono sul filo.

HumusBoard.ino è lo sketch di partenza, nella cartella HumusBoard sotto SerialIn e anche sotto SerialOut, e lavora in tutte e due le direzioni: ogni 30 ms stampa A0 e A1 su una riga, 0.512 0.087, e ogni volta che arriva una riga accende o spegne il pin 13 con il primo numero e regola l'intensità del pin 11 con il secondo. Caricalo come sopra.

Prima di tutto, l'autotest

Prima di qualsiasi cablaggio, verifica che il collegamento funzioni. Carica SerialTest.ino da Organisms > SerialIn > SerialTest e apri la patch che gli sta accanto. Lo sketch stampa tre numeri venti volte al secondo: una rampa che sale da 0 a 1 una volta al secondo, l'ultima cosa che ha sentito da Humus, e A0. Un SerialIn li porta su tre Number. Se la rampa si muove, la scheda parla con la porta e il baud è giusto; se l'eco segue l'LFO sulla prima presa di SerialOut, Humus viene sentito e il Format corrisponde; il Button sulla seconda presa accende il LED integrato della scheda, l'unica cosa da guardare sulla scheda stessa. Se la rampa resta ferma, controlla la porta e il baud; se è ferma solo l'eco, controlla il Format.

Le stesse due storie, passando per lo sketch

serial-sensor.hum è la storia uno passando per lo sketch: un SerialIn legge la riga che lo sketch stampa, la sua uscita a arriva su un Number, e il valore del Number apre il Filter con un collegamento Controlla con. Il menu Port dice Auto e il baud è 115200, quello che apre lo sketch. Il display nel box si muove un attimo dopo l'apertura della patch.

serial-led.hum è la storia due: l'uscita gate del Follower sulla presa 1 di SerialOut e la sua uscita env sulla presa 2, inviate come la riga di default %1 %2\n trenta volte al secondo; lo sketch accende e spegne il pin 13 e regola l'intensità del pin 11.

Storia tre: un anello di pixel, in tre modi

L'anello mostra un protocollo tutto tuo. NeoPixel.ino, sotto Organisms > SerialOut > NeoPixel, pilota un anello di 24 LED indirizzabili sul pin 6 e legge un comando per riga, con tutti i numeri in 0..1 tranne il numero di pixel: P i r g b colora un pixel, F n r g b accende i primi n e spegne gli altri, A r g b li colora tutti, H h s v li colora tutti per tinta, B v imposta la luminosità. Collega il pin dati dell'anello al 6, l'alimentazione a 5V e la massa a GND, carica lo sketch e apri una qualsiasi delle tre patch che gli stanno accanto.

paint.hum è quella semplice: quattro Slider su quattro prese di SerialOut, il Format P %1 %2 %3 %4\n, Send su On change. La prima presa ha Scale 23 e Int attivo, così uno slider 0..1 sceglie un pixel per numero; le altre dicono quanto rosso, verde e blu. Muovi uno slider e quel pixel lo segue.

vu-meter.hum calcola tutto il messaggio da un solo valore. L'env del Follower sta sulla presa 1 e il Format dice F %(floor(v1*24+0.5)) %(v1) %(1-v1) 0\n: il livello sceglie quanti pixel si accendono, e il colore va dal verde a riposo al rosso al massimo, trenta righe al secondo. È il box dei messaggi che fa i conti, così lo sketch può restare stupido.

spectrum.hum è la patch Pd che mappa la frequenza sul colore, ricostruita: un Crossover a tre bande divide il microfono, un Follower per banda ne legge il livello, e le tre uscite env arrivano su tre prese inviate come A %1 %2 %3\n, i bassi in rosso, i medi in verde, gli alti in blu, su tutto l'anello. Sposta le due frequenze del Crossover per decidere cosa conta come bassi e cosa come aria. Sostituisci le sorgenti dei Follower con degli LFO e l'anello cambia lentamente da solo; metti uno Slider tra un Follower e la sua presa per domare una banda. Ognuna delle tre potrebbe anche inviare H %1 1 %2\n con una tinta sulla presa 1 e un livello sulla presa 2, e la ruota dei colori la farebbe lo sketch.

I due box

Da Humus alla scheda. Un SerialOut mostra tante prese di valore quante ne indica il suo campo Values, due per cominciare e fino a otto, più una presa di trigger in modalità On trigger, e ha un campo Format. Da %1 a %8 stampano i valori, \n chiude una riga, \t è una tabulazione, \xNN è un byte grezzo. Ogni valore ha un campo Scale e un interruttore Int, così un controllo 0..1 esce come 0..255 con due clic, e una presa senza niente collegato manda il numero scritto nel suo campo. Send sceglie quando: Continuous alla frequenza che imposti, On change perché un comando parta una volta sola, oppure On trigger quando sale la presa di trigger, e così un Button diventa un box di comando.

Più comandi in un box. Scrivi un messaggio per riga nel campo Format e compare una presa Message: il numero che riceve sceglie la riga, così un Number o uno Slider sceglie tra home, M %1 e stop, e un Button sulla presa di trigger manda quello scelto.

Dalla scheda a Humus. Un SerialIn ha fino a otto uscite, dalla a alla h: il primo numero di ogni riga arriva su a, il secondo su b, e così via. Per uno sketch che stampa in una forma tutta sua c'è un modello Parse, lo specchio di Format: T=%1;L=%2 legge T=23.5;L=0.4, e una riga che non corrisponde viene ignorata. Con un modello impostato, un'uscita match scatta ogni volta che una riga corrisponde, così uno sketch che stampa pressed diventa la pressione di un Button. Il display nel box mostra cosa è arrivato. Porta i valori a 0..1 sulla scheda; Humus usa i numeri così come arrivano.

Messaggi calcolati. %(v1*180) stampa il risultato di un'espressione, nel linguaggio del box Math, e %?(v1>0.5){LED 1} stampa il contenuto delle graffe solo quando il test è vero, così un messaggio può cambiare forma con un valore. %b(expr) e %w(expr) mandano il risultato come byte.

Cosa mostra il box. Ogni box seriale dice in basso su quale porta si trova e cosa ha inviato o ricevuto per ultimo, byte per byte, e SerialIn segna come saltata una riga che non corrispondeva al suo Parse. Quando un protocollo non funziona, è quella riga da guardare. Il menu dei preset di SerialOut e SerialIn contiene le forme di messaggio più comuni da cui partire.

Nomi sul filo. Un Var è un valore con un nome. Collega un Var chiamato temp alla presa 1 di SerialOut e scrivi %n1 %1\n, e la scheda riceve temp 0.5. Nell'altro senso, un SerialIn che legge temp 23.5 light 0.4 consegna ogni numero al Var con quel nome, ovunque si trovi nella patch, senza nessun cavo: il send e receive di Pd, con il nome che viaggia insieme al valore.

Byte, non testo. Uno sketch che parla in byte grezzi usa %b1 per un byte e %w1 per una word di due byte, in entrambi i campi. In Format, Scale 255 trasforma un controllo 0..1 in un byte pieno; in Parse, \xAA%b1%w2 aspetta il byte di intestazione e prende i tre successivi, risincronizzandosi oltre qualsiasi cosa ci sia in mezzo.

Checksum, parole ed elenchi. %x o %s in un Format aggiunge lo XOR o la somma dei byte fin lì, %X e %S lo stesso come due cifre esadecimali, e %[ e %] delimitano la parte che coprono, così $%[HUM,%1,%2%]*%X\r\n è una frase in stile GPS. %{slow,fast,turbo}1 stampa una parola presa da un elenco in base al valore 1, e in lettura torna come posizione da 0 a 1. %c è un byte di conteggio e %b* i byte contati, per un pacchetto di lunghezza variabile; %* prende o stampa tutti i numeri di una riga. Un Parse verifica il checksum e scarta una riga che non lo supera. L'elenco completo è nell'aiuto di ciascun box.

La porta. Frame, su ogni box, imposta parità e bit di stop per i rari dispositivi che non sono 8N1; la lista dei baud arriva fino a 1000000 e Custom accetta qualsiasi altra velocità. Reset decide se aprire la porta riavvia la scheda come fa il suo editor; disattivalo per una scheda che deve continuare a girare mentre Humus si riconnette.

OSC su seriale. Una scheda che parla OSC incapsulato in SLIP, come fanno le librerie per Teensy ed ESP, non ha affatto bisogno di SerialIn: attiva OSC su seriale in Impostazioni ▸ MIDI e OSC e i suoi messaggi entrano nel bus di controllo OSC, così OSC learn su qualsiasi manopola li mappa. Vedi MIDI e OSC.

Su una porta possono stare quanti box Board, SerialIn e SerialOut vuoi: un cavo, tre formati, tre box, e ogni box dice cosa invia.

Quando non funziona

Non lampeggia niente. Un altro programma tiene la porta: il Monitor seriale dell'Arduino IDE, un Humus precedente che si sta ancora chiudendo. Premi Reconnect sul box, oppure scollega e ricollega la scheda; i box si riconnettono da soli.
Il misuratore lampeggia ma le uscite restano a zero. Sulla scheda non gira StandardFirmata. Caricalo di nuovo, oppure usa SerialIn per uno sketch tuo.
Il misuratore lampeggia ma il display resta fermo. Il baud non corrisponde a quello che apre lo sketch, oppure lo sketch stampa in una forma che il campo Parse non si aspetta. Svuota Parse per prendere tutti i numeri della riga.
Le letture coprono solo una parte dell'intervallo. Un sensore usa raramente tutti gli 0..5V. Imposta l'intervallo di Controlla con sulla parte che usa davvero, oppure metti uno Slider tra l'uscita e la destinazione e regola i suoi Min e Max.
Il pin non si attenua. Non tutti i pin hanno il PWM; passa a uno che ce l'ha.
Linux nega il permesso. Il gruppo dialout, vedi sopra.