Motore 3D in C++ – Raycasting parte I

Ecco una mia semplice implementazione C++ di un engine 3D basato sul metodo raycasting.

Il raycasting è una tecnica di rendering 3D particolarmente semplice e veloce in grado di creare viste tridimensionali a partire da mappe 2D.

Il motore grafico impone alcuni vincoli sul mondo da rappresentare ad esempio l’ortogonalità dei muri tra di loro e l’ortogonalità rispetto al pavimento, riuscendo quindi ad essere estremamente veloce: non è richiesta l’accelerazione GPU e nemmeno le librerie per il rendering 3D quali OpenGL o DirectX. Tutto il lavoro viene svolto in CPU disegnando la scena in un framebuffer in memoria.

Il raycasting è stato utilizzato per molto tempo come tecnica di rendering nei primi videogiochi 3D quali Wolfentein 3D, Rise Of The Triad, e con alcune modifiche minori anche DOOM, DOOM II e Duke Nukem 3D. Al tempo i computer non erano molto veloci (parliamo della fascia di processori che va dai primi Intel 286 fino ai 486-586) e quindi il raycasting ben si adattava alle limitate capacità di calcolo. Tuttavia ancora oggi troviamo esempi di motori 3D raycasting specialmente nelle architetture più limitate (ARM embedded, e anche calcolatrici).

Questo è il classico Wolfenstein 3D:

Wolfenstein_3D_Screenshot

Come si vede chiaramente il rendering finale è abbastanza spartano se comparato con i moderni motori 3D. Come dicevo il raycasting lavora su una rappresentazione estremamente semplificata dell’ambiente 3D: una semplice collezione di cubi di pari dimensioni disposti all’interno di una griglia 2D. I cubi hanno stesse dimensioni e quindi stessa altezza, sono tutti ortogonali tra di loro e non possono sovrapporsi. Tutti questi vincoli permettono la rappresentazione del mondo 3D tramite una semplice griglia quadrata bidimensionale: ogni cella della griglia può essere o vuota (spazio vuoto) o piena (blocco solido). Ad ogni blocco solido può essere associato un colore o una texture (ad esempio associando ad ogni cella della griglia un numero intero).

Ecco come si presenta l’editor delle mappe in Wolfentein 3D (primo livello):

nmap

L’intero ambiente 3D è rappresentabile da una mappa bidimensionale con vista dall’alto. I vincoli rendono impossibli elementi come piani obliqui, saltare, guardare in alto, in basso o accovacciarsi. Motori grafici tipo Build (utilizzato in Duke Nukem 3D), sebbene basati esclusivamente sul raycasting, hanno introdotto tutti questi elementi pur essendo trattati nel codice come casi speciali (qui un’ottima review del motore Build).

Come funziona il raycasting?

Definiti la posizione e la direzione del punto di vista all’interno della griglia-mondo il raycasting procede in questo modo: per ogni riga di pixel verticale dello schermo viene “lanciato” un raggio (da qui il termine ray-casting) che parte dalla posizione corrente del giocatore e prosegue in avanti ad esso. Ad esempio, con una risoluzione di 1024 pixel in orizzontale verranno lanciati 1024 raggi in avanti ma ognuno ad una angolazione leggermente differente. Il raggio prosegue all’interno della griglia-mondo (in avanti rispetto al giocatore) fino a che non incontrerà una cella piena (un blocco-muro). A quel punto viene calcolata la lunghezza del raggio che corrisponde alla distanza effettiva del giocatore da quel muro. Il valore distanza viene utilizzato per calcolare quanto lunga dovrà essere disegnata la linea di pixel sullo schermo a quella data riga; più il raggio è lungo più corta sarà la linea verticale disegnata (muro lontano), più il raggio è corto più la linea sarà disegnata lunga (muro vicino). In figura si mostra come procede l’algoritmo: la vista è dall’alto, il punto verde è il giocatore, la riga nera è il piano di camera (lo schermo). Alcuni raggi (in giallo) campionano la mappa (notare le differenti lunghezze rilevate):

raycasting - algoritmo

Ad ogni passo si prende la prossima riga verticale dello schermo e si lancia il raggio corrispondente con l’opportuna angolazione. L’algoritmo termina quando sono state disegnate tutte le linee sullo schermo: il rendering della scena è completato.

Qui sotto in figura viene mostrato come un singolo raggio si traduce in linea verticale sullo schermo. Notare che l’altezza della linea sul rendering finale (la linea gialla sullo schermo) dipende unicamente dalla lunghezza del raggio. Il colore della linea può essere dato dal “colore” del blocco (in questo caso o blu o rosso).

rayhit1

Notare che il rendering finale è sempre simmetrico rispetto all’asse verticale.

Per rilevare la collisione tra raggio e muro si può procedere in questo modo: facciamo partire il raggio dal punto in cui si trova il giocatore (punto verde in figura) e poi via via ne aumentiamo la lunghezza controllandone l’eventuale collisione con un muro. Aumentare la lunghezza del raggio di una costante fissa non è la soluzione corretta in quanto può accadere di “non vedere” il muro, come mostrato in figura:

raycasting - miss

Infittire i punti di check non risolve il problema perchè si può dimostrare che per qualsiasi costante di incremento esisterà sempre una certa probabilità di non rilevare la collisione (sebbene tale probabilità si possa ridurre a piacere). Un modo teorico per avere la certezza assoluta sarebbe quello di considerare infiniti punti di check (incremento infinitesimo) il che ovviamente non è implementabile.

Un metodo pratico ed anche estremamente veloce per risolvere il problema è quello di considerare solo i punti del raggio che cadono sulle righe della griglia. Sapendo che il raggio si muove sempre all’interno di una griglia di quadrati (pieni o vuoti) possiamo effettuare il test di collisione solo nei punti di intersezione tra il raggio e la griglia: questo metodo garantisce una accuratezza assoluta senza margine di errore. In figura l’algoritmo:

raycast - nomiss

Per una mappa di NxN blocchi l’algoritmo richiede al più 2N controlli di collisione per singolo raggio il che lo rende abbastanza efficiente. Da notare che stanze molto grandi richiedono più tempo per essere spazzate dai raggi (più controlli di collisione).

Gli engine raycasting non ammettono “spazi aperti” ossia configurazioni di blocchi che non separano completamente lo spazio esterno dall’interno. Mappe aperte non lasciano terminare l’algoritmo (il raggio potenzialmente può non intersecare mai alcun blocco pieno) e quindi non sono ammesse. Una soluzione è quella di creare blocchi “invisibili” che chiudono la mappa come richiesto ma che poi non vengono disegnati su schermo.

Posizione, direzione del giocatore e piano di camera

Prima di poter creare l’algoritmo vero e proprio occorre definire esattamente cosa è il giocatore. Il giocatore è definito da tre parametri:

  • posizione all’interno della mappa (posX, posY)
  • vettore di direzione (dirX, dirY)
  • piano di camera (camX, camY)

Il primo è banalmente la posizione del giocatore nella mappa, sono sufficienti due valori posX, posY. Il secondo è il vettore direzione ed indica appunto la direzione nella quale “sta guardando” il giocatore, un vettore nel piano è indentificato univocamente da due valori dirX, dirY. L’ultimo è il piano di camera, ossia il piano ortogonale al vettore direzione che rappresenta lo schermo del giocatore. Anche in questo caso due valori camX, camY sono sufficienti: il termine “piano” è improprio in quanto lavoriamo già su un piano (la mappa 2D), sarebbe più opportuno definirlo “segmento di camera” perchè rappresenta lo schermo del giocatore come visto dall’alto.

In figura la rappresentazione dall’alto delle tre componenti del giocatore:

player

Il modulo del vettore segmento di camera rappresenta l’estensione orizzontale dello schermo (la lunghezza del segmento nero) rispetto all’ambiente circostante (la mappa 2D). Per convenzione posizioniamo sempre il giocatore al centro del segmento nero (centro dello schermo).

Il modulo del vettore direzione (la sua lunghezza) viene interpretato come distanza del giocatore dal piano di camera. In geometria proiettiva tale distanza viene chiamata focale. Alterando la focale si altera automaticamente il FOV o campo visivo, ossia la massima area visibile in un dato instante.

Grandi valori del modulo del vettore direzione (vettore rosso) generano una FOV stretta (zoom-in):

lowFOV

Piccoli valori del modulo del vettore direzione generano una FOV ampia (zoom-out):

highFOV

Per un motore grafico una buon valore del modulo direzione è quello che genera una FOV di circa 66 gradi. Valori più grandi generano forti distorsioni all’immagine mentre valori troppo piccoli danno l’impressione di vedere tramite un forte zoom.

Generazione dei raggi

La generazione di un raggio uscente dal giocatore si traduce nella somma dei due vettori direzione e segmento di camera. Ad esempio, per uno schermo di 1024 pixel in orizzontale dobbiamo lanciare 1024 raggi aventi origine in posX, posY (posizione giocatore) ed intersecanti il segmento di camera ognuno in un punto differente. Il primo raggio (raggio 0) interseca il segmento di camera all’estrema sinistra: questo sarà il raggio lanciato per la riga 0 dello schermo (prima riga a sinistra, x=0). Il 1023 raggio (l’ultimo) interesecherà il segmento di camera all’estrema destra (ultima riga di pixel dello schermo, x=1023). Gli altri raggi saranno calcolati tramite uno scostamento progressivo e lineare lungo il segmento di camera.

In figura si mostrano i raggi relativi ad alcuni scostamenti di esempio (x=0, x=12, x=304 e x=1023):

castrays

In generale, per generare l’x-esimo raggio (vettore rayX, rayY)  basta suddividere la lunghezza del segmento di camera in 1024 parti, calcolare in funzione di x il vettore scostamento dal centro del segmento e sommare tra loro vettore direzione e vettore scostamento.

somma_vettori

Algoritmo di rendering

Definito il giocatore e i raggi possiamo finalmente chiarire l’algoritmo di rendering vero e proprio. Il rendering di un singolo frame prevede i seguenti passi:

passo 1) colorare lo schermo di nero (per eliminare il frame precedente)

passo 2) per ogni riga di pixel dello schermo:

  • calcolo dello scostamento sul segmento di camera
  • calcolo direzione del raggio rayX, rayY (somma vettore direzione e scostamento)
  • allungare il raggio avanzando di un blocco alla volta fino alla collisione con un muro
  • calcolo della lunghezza del raggio
  • tracciare una linea verticale alta h pixel. h è scelto in funzione della lunghezza del raggio (più il raggio è lungo, più h è basso e viceversa). Il colore della linea verticale può essere dato dal tipo di blocco incontrato (blocco blu, blocco rosso, blocco verde, etc… etc… possiamo definire quanti tipi di blocchi vogliamo)

Definizione della mappa

La mappa può essere definita da un semplice file di testo. Ad esempio, nel mio caso le prime due righe indicano rispettivamente la larghezza e la lunghezza (in blocchi) della mappa. In questo caso 64×64 blocchi. Le righe successive definiscono graficamente la mappa 2D. Ogni numero corrisponde ad un blocco solido di tipo (colore) diverso, blocco 1, 2, 3 e 4. Gli spazi bianchi definiscono i blocchi vuoti (spazi vuoti). world.txt

asciimap

definiamo ad esempio il blocco tipo ‘1’ verde, il blocco tipo ‘2’ bianco, il blocco tipo ‘3’ blu e il blocco tipo ‘4’ rosso.

Movimento

Il giocatore può muoversi in due modi distinti:

  • avanti/indetro
  • girare in senso orario/antiorario

Per il movimento avanti e indietro è sufficiente aggiornare in maniera opportuna la posizione corrente posX, posY rispetto al vettore direzione. Definito un passo di movimento P il cambio di posizione si traduce nel sommare tra loro vettore posizione e vettore direzione moltiplicato per il passo di movimento. Quindi, nel caso di movimento in avanti:

posX = posX + dirX * P;

posY = posY + dirY * P;

Nel caso di movimento all’indietro:

posX = posX – dirX * P;

posY = posY – dirY * P;

Per girare in senso orario o antiorario occorre ruotare il vettore direzione dirX, dirY. La posizione ovviamente rimane invariata. Detto il passo di rotazione (in radianti), la rotazione avviene moltiplicando il vettore direzione per  la classica matrice di rotazione 2×2:

rot

ossia:

dirX = dirX * cos(R) – dirY * sen(R)

dirY = dirX * sen(R) + dirY * cos(R)

cambiando segno ai coefficienti della matrice si inverte la rotazione (da oraria ad antioraria).

Codice sorgente – prima versione: raycasting senza texture mapping

Per disegnare a video ho utilizzato la libreria PixelToaster. Molto semplice da usare, basta aprire un display grafico di dimensione MxN pixel, in finestra o fullscreen, e settare individualmente i singoli pixel RGB. La libreria non fornisce alcuna primitiva grafica, ad esempio per disegnare rette, cerchi o rettangoli, se non quella per accendere o spengere singoli pixel sullo schermo (del colore RGB desiderato). Una comodo set di API aggiuntive permette di catturare gli eventi della tastiera (tasti premuti) e del mouse (coordinate x,y del cursore, stato dei bottoni).

In questa prima versione ho implementato l’engine raycasting nella sua versione più semplice, ossia senza texture mapping: ogni quadrato nella mappa (file world.txt) ha associato un numero intero e tale numero rappresenta un blocco solido di un dato colore.

source code (raycaster_ver01.cpp)

Per iniziare definiamo alcune costanti, risoluzione dello schermo, FOV, passo di movimento (P) e rotazione (R).

// risoluzione
#define SCREEN_W 640
#define SCREEN_H 480

// Field Of View
#define FOV 0.66

// Pi
#define PI 3.14159

// passo di movimento e rotazione
#define MOVSPEED 0.1
#define ROTSPEED 0.05

definiamo poi le strutture dati che ci serviranno, il framebuffer dove disegnare, i dati della mappa, stato del giocatore (telecamera) e il generico raggio:

// framebuffer
struct Frame
{
	uint32_t width;
	uint32_t height;
	TrueColorPixel *data;
};

// mappa
struct World
{
	uint32_t width;
	uint32_t height;
	uint8_t *data;
};

// stato della telecamera (posizione, direzione, piano di proiezione)
struct State
{
	double posx;
	double posy;
	double dirx;
	double diry;
	double camx;
	double camy;
};

// informazioni sul raggio
struct RayHit
{
	double distance;
	int mapX;
	int mapY;
	double rayDirX;
	double rayDirY;
	int side;
};

Il main() è abbastanza semplice, non facciamo altro che aprire una finestra delle dimensioni desiderate, inizializzare il framebuffer (delle stesse dimensioni della finestra), inzializzare la posizione del giocatore e caricare i dati della mappa dal file world.txt. Entriamo poi nel loop infinito while(1) nel quale facciamo ciclicamente il rendering della scena nel frambuffer (un semplice array di pixel RGB) e il disegno su video:

int main()
{
	// init schermo
	Display display("Raycaster", SCREEN_W, SCREEN_H, Output::Windowed);
	display.open();
	Listen l;
	display.listener(&l);

	// init framebuffer
	Frame frame;
	frame.data = new TrueColorPixel[SCREEN_W * SCREEN_H];
	frame.width = SCREEN_W;
	frame.height = SCREEN_H;

	// init stato
	State state;
	state.posx = 3;
	state.posy = 3;
	state.dirx = -1;
	state.diry = 0;
	state.camx = 0;
	state.camy = FOV;

	// caricamento mappa
	World world;
	if (!LoadWorld("world.txt", &world))
	{
		printf("\nError loading world file!");
		exit(0);
	}

	// init del listener
	l.state = &state;
	l.world = &world;
	l.moveSpeed = MOVSPEED;
	l.rotSpeed = ROTSPEED;

	while(1) // loop principale (rendering e disegno della scena)
	{
		RenderScene(state, world, frame);
		DrawScene(display, frame);
	}
}

La funzione RenderScene() prende lo stato attuale del giocatore (state), i dati della mappa (world)  e crea il rendering della scena nel framebuffer (frame). Drawscene() prende semplicemente il frame e lo mostra a video.

RenderScene() è il cuore dell’algoritmo. Per prima cosa lo schermo viene colorato completamente in nero al fine di cancellare il frame precedente:

	for(i = 0; i < (frame.width * frame.height); i++)
	{
		frame.data[i].r = 0; // R
		frame.data[i].g = 0; // G
		frame.data[i].b = 0; // B
	}

Fatto ciò inizia il ciclo for principale che per ogni riga verticale dello schermo lancia un raggio uscente dal giocatore:

	for (uint32_t column = 0; column < frame.width; column++) // per ogni riga

calcoliamo la posizione e direzione del raggio in funzione di column:

		// calcola la posizione e la direzione del raggio
		double cameraX = 2 * column / double(frame.width) - 1;
		double rayPosX = state.posx;
		double rayPosY = state.posy;
		double rayDirX = state.dirx + state.camx * cameraX;
		double rayDirY = state.diry + state.camy * cameraX;

Lanciamo ora il raggio dopo un breve setup dei valori iniziali. Il ciclo while() incrementa la lunghezza del raggio fino alla collisione con un muro:

		// il blocco attuale dove siamo
		int mapX = int(rayPosX);
		int mapY = int(rayPosY);

		// lunghezza del raggio dalla posizione attuale al blocco successivo
		double sideDistX;
		double sideDistY;

		// lunghezza del raggio da un blocco ad un altro
		double deltaDistX = sqrt(1 + (rayDirY * rayDirY) / (rayDirX * rayDirX));
		double deltaDistY = sqrt(1 + (rayDirX * rayDirX) / (rayDirY * rayDirY));
		double perpWallDist;

		// direzione nella quale andare (+1 o -1), sia per X che per Y
		int stepX;
		int stepY;
		int side; // faccia del cubo incontrata (faccia Nord-Sud o faccia Ovest-Est)

		if (rayDirX < 0)
		{
			stepX = -1;
			sideDistX = (rayPosX - mapX) * deltaDistX;
		}
		else
		{
			stepX = 1;
			sideDistX = (mapX + 1.0 - rayPosX) * deltaDistX;
		}

		if (rayDirY < 0)
		{
			stepY = -1;
			sideDistY = (rayPosY - mapY) * deltaDistY;
		}
		else
		{
			stepY = 1;
			sideDistY = (mapY + 1.0 - rayPosY) * deltaDistY;
		}

		// lanciamo il raggio
		while ((world.data[mapX + mapY * world.width] == 0)) // finche' non incontriamo un muro...
		{
			// andiamo al prossimo blocco nella mappa
			if (sideDistX < sideDistY)
			{
				sideDistX += deltaDistX;
				mapX += stepX;
				side = 0;
			}
			else
			{
				sideDistY += deltaDistY;
				mapY += stepY;
				side = 1;
			}
		}

mapX e mapY sono le coordinate intere del blocco dove si trova la punta del raggio ad ogni iterazione. Finchè la mappa restituisce zero (nella nostra convenzione 0 rappresenta un blocco vuoto) incrementiamo la lunghezza del raggio. Una volta incontrato un blocco solido usciamo dal ciclo while() e calcoliamo la lunghezza esatta del raggio:

		// calcolo lunghezza del raggio
		if(side == 0)
		{
			perpWallDist = fabs((mapX - rayPosX + (1 - stepX) / 2) / rayDirX);
		}
		else
		{
			perpWallDist = fabs((mapY - rayPosY + (1 - stepY) / 2) / rayDirY);
		}

Fatto ciò chiamiamo DrawColumn() che si occuperà di disegnare una linea larga 1 pixel e alta h. L’altezza h della colonna è funzione della lunghezza del raggio appena calcolato: più il raggio era lungo più la linea disegnata sarà corta, più il raggio era corto più la linea disegnata sarà alta. Il colore della linea di pixel è data dal tipo di blocco che il raggio ha incontrato. Tutte queste informazioni sono caricate nella struct RayHit e passate alla funzione DrawColumn() che la disegnerà nel framebuffer. Il ciclo for() riparte quindi con una nuova iterazione per il disegno della prossima linea di pixel e cosi’ via fino al margine destro dello schermo. Quando tutte le righe verticali dello schermo sono state disegnate il frame è finalmente completo e può essere passato alla funzione DrawScene() che lo mostrerà sul display (finestra o fullscreen che sia). La funzione DrawColumn() disegna una linea sullo schermo. Ma come viene disegnata questa colonna? E come viene calcolata esattamente l’altezza? Vediamo come.

Per prima cosa viene recuperato il tipo di blocco solido incontrato dal raggio:

	// tipo di blocco rilevato
	uint8_t type = world.data[what.mapX + what.mapY * world.width];

poi viene scelto un colore RGB in funzione del tipo blocco:

	// seleziona colore in base al tipo di blocco
	uint8_t r, g, b;
	switch (type)
	{
	case 1:
	{
		r = 0;
		g = 255;
		b = 0;
		break;
	}
	case 2:
	{
		r = 155;
		g = 155;
		b = 155;
		break;
	}
	case 3:
	{
		r = 0;
		g = 0;
		b = 255;
		break;
	}
	case 4:
	{
		r = 255;
		g = 0;
		b = 0;
		break;
	}
	}

Calcoliamo ora l’altezza h della linea di pixel da disegnare, in funzione della lunghezza del raggio.

	// calcola altezza colonna

	uint32_t colh = abs(int(frame.height / what.distance));

	uint32_t cropup = 0;
	uint32_t cropdown = 0;
	uint32_t index = 0;

	if (colh > frame.height) // se e' piu' alta dello schermo, taglia
	{
		index = column;
		cropup = (colh - frame.height) / 2;
		cropdown = cropup + 1;
	}
	else
	{
		index = column + ((frame.height - colh) / 2) * frame.width;
		cropup = 0;
		cropdown = 0;
	}

e finalmente viene disegnata la linea di pixel:

	// disegna colonna
	for (uint32_t c = cropup; c < (colh - cropdown); c++)
	{
		// disegna il pixel del colore selezionato
		frame.data[index].r = r;
		frame.data[index].g = g;
		frame.data[index].b = b;
		index += frame.width;
	}

Risultato finale

La nostra prima implementazione del raycaster. Qui trovate il codice sorgente completo.

Aggiungere terreno e cielo

Possiamo aggiungere una prima forma di terreno e soffitto al motore grafico. Esattamente come in Wolfenstein 3D, possiamo farlo semplicemente coorando le zone nere in alto (sopra la metà schermo) di blu e le zone nere in basso (sotto la metà schermo) di marrone. E’ molto più oneroso riempire le poche zone di schermo nere rimaste a rendering ultimato che non colorare a priori tutto lo schermo metà blu e metà marrone e poi applicare sopra il rendering stesso.

Quindi, prima del rendering della scena disegnamo lo schermo metà blu e metà marrone. Lo facciamo all’inizio della RenderScene().

Al posto del ciclo for che colora lo schermo completamente di nero:

	for(i = 0; i < (frame.width * frame.height); i++)
	{
		frame.data[i].r = 0;
		frame.data[i].g = 0;
		frame.data[i].b = 0;
	}

mettiamo un ciclo for modificato che colora la metà alta dello schermo di blu (cielo) e la metà bassa di marrone (terreno):

		// flat sky
		for(i = 0; i < (frame.width * frame.height / 2); i++)
		{
			frame.data[i].r = 135;
			frame.data[i].g = 206;
			frame.data[i].b = 250;
		}

		// floor
		for(i = (frame.width * frame.height / 2); i < (frame.width * frame.height); i++)
		{
			frame.data[i].r = 102;
			frame.data[i].g = 51;
			frame.data[i].b = 0;
		}

Questo nuovo ciclo for non fa altro che colorare lo schermo in questo modo:

raycast - flat landscape

A rendering ultimato il risultato finale è questo:

Questo il sorgente della versione con soffitto e terreno.

Nel prossimo articolo vedremo come implementare il texture mapping sia per i muri verticali che per il pavimento e soffitto (in gergo floor-casting e ceiling-casting). In più vedremo come aggiungere un primo abbozzo di skydome (cielo aperto).

Guida pratica al PIC 16F84

Il mio vecchio tutorial sul PIC 16F84. La guida risale all’ormai lontano 2004 ed è ancora oggi molto “navigata” da hobbisti e tutti quelli che si vogliono avvicinare al mondo dell’embedded.

Questo modello di PIC ha avuto grande successo in passato perchè molto utilizzato con le simcard pirata per il satellitare e per il suo bassissimo costo. Ricordo che la Microchip (il produttore del PIC) decise di metterlo online come free-sample aprendo la strada alla moltitudine di smanettoni (compreso me) che impararono ad usarlo.

 

Oggi esistono versioni di PIC molto più avanzate, ricche in funzionalità (vedi ad esempio la famiglia PIC 18Fx) e a minor prezzo: non ci sono proprio più scuse a voler contiuare ad usare il 16F84 se non per scopi didattici.

In ogni caso, la guida permette di entrare gradualmente nel mondo dell’embedded. Vengono coperti tutti gli aspetti del PIC, dall’architettura di massima al linguaggio assembler. In più viene mostrato come realizzare il primo programma in ambiente MPLAB, compilarlo ed inserirlo all’interno del micro. L’esempio riguarda il classico LED lampeggiante, l’equivalente embedded dell’intramontabile “Hello World”.

La guida si trova a questo indirizzo:

http://gianluca82.altervista.org/pic16f84/data/indice.html

Indice generale:

Introduzione alla guida

  • Il PIC 16F84
    • Introduzione
    • Caratteristiche
    • Piedinatura
    • Il piedino #MCLR
    • Oscillatore esterno
      • XT
      • RC
      • LP e HS
    • Struttura interna del PIC
  • Memoria RAM/FLASH/EEPROM
    • La memoria dati (memoria RAM)
      • I registri SFR
      • I registri GPR
    • La memoria istruzioni (memoria FLASH)
      • Il program counter
    • La EEPROM
  • Linguaggio assembly – parte I
    • Introduzione
    • Concetti generali
    • Operazioni di base
      • Set e clear dei bit (BSF e BCF)
      • Selezione del banco RAM
      • Spostare i dati (MOVF, MOVWF e MOVLW)
      • Azzerare i registri (CLRF e CLRW)
      • No operation (NOP)
      • Salto incondizionato (GOTO)
      • Salti condizionati (BTFSC, BTFSS, DECFSZ e INCFSZ)
      • Cicli di delay
  • Utilizzare le porte di I/O
    • Le porte di I/O
    • Caratteristiche elettriche
      • Linee porta A
      • Linee porta B
    • Lettura e scrittura
    • Esempi software
    • Esempi di collegamento
      • Utilizzare i piedini come ouput
      • Utilizzare i piedini come input
  • Linguaggio assembly – parte II
    • Operazioni logiche
      • AND logico (ANDWF e ANDLW)
      • OR logico (IORWF e IORLW)
      • XOR logico (XORWF e XORLW)
      • NOT logico (COMF)
    • Operazioni aritmetiche
      • Addizione (ADDWF e ADDLW)
      • Sottrazione (SUBWF e SUBLW)
      • Decremento (DECF)
      • Incremento (INCF)
    • Operazioni di modifica dei registri
      • Rotazione (RRF e RLF)
      • Nibble-swap (SWAPF)
    • Chiamata a funzione
      • Chiamata a funzione (CALL)
      • Ritorno semplice (RETURN)
      • Ritorno con parametro (RETLW)
  • Programmare il PIC
    • Fasi di sviluppo
    • Costruzione del programmatore
      • Funzionamento e schema elettrico
      • Configurazione di ICPROG
    • L’ambiente MPLAB
      • Creazione del progetto e del programma
      • Compilazione
    • Debug del codice
    • Programmazione del pic
  • Sistema di interrupt
    • Interrupt dal piedino RB0/INT
    • Interrupt da RB4..RB7
    • Interrupt per completamento della fase di scrittura della EEPROM
    • Interrupt dal timer TIMER0

LED Cube 3x3x3 PIC16F84 con microfono incorporato

Un LED cube 3x3x3 costruito completamente a mano!

I LED cube sono matrici LED a tre dimensioni in grado di illuminarsi nelle più complesse animazioni; ne esistono di numerosi tipi tra cui 3x3x3, 4x4x4 e addirittura 8x8x8. Alcuni sono comandati via PC, altri sono provvisti di microcontrollore e quindi completamente autonomi.

Nel mio caso ho dotato il cubo di microfono e amplificatore per lampeggiare a tempo di musica (una specie di VU meter tridimensionale). L’ho realizzato con un semplice PIC micro 16F84, un amplificatore MAX9812, microfono e pochi altri componenti.

DSCN4392

Multiplexing

La griglia LED è composta da 3 piani di 9 LED ciascuno per un totale di 27 LED (3x3x3). Il micro prevede solo 13 GPIO, ovviamente non sufficienti a pilotare tutti e 27 i LED singolarmente; ho quindi realizzato un indirizzamento del singolo LED secondo la coppia piano/colonna. In questo modo per accendere un LED e’ sufficiente specificare il piano (uno di tre, quindi 3 GPIO) e la colonna di afferenza (una di nove, quindi altri 9 GPIO) per un totale di 12 GPIO. Elettricamente cio’ si traduce nel collegare tra loro i catodi dei LED di ogni piano e tutti gli anodi secondo le colonne.

Questa particolare configurazione purtroppo ci costringe ad accendere un solo piano alla volta: abilitare piu’ di un piano contemporaneamente comporterebbe l’accensione di LED non desiderati. E’ comunque possibile risolvere il problema avvicendando i 3 piani molto velocemente tra loro (tecnica display multiplexing): in sostanza il micro seleziona il primo piano, ne accende opportunatamente i nove LED, spegne il primo piano, accende il secondo, accende i nove LED del secondo piano, spenge il secondo piano, accende il terzo e cosi’ via in loop il più velocemente possibile. L’occhio umano non e’ in grado di percepire questo veloce cambiamento e la percezione finale e’ quella di avere tutti i LED accesi contemporaneamente. Nel mio caso ho programmato il multiplexing ad una frequenza di circa 100Hz ottenendo cosi’ un frame rate dell’intero pattern LED di circa 33,3Hz. Nell’immagine qui sotto mostro i collegamenti tra i GPIO del micro con alla griglia LED 3x3x3.

multiplex

Luminosita’ variabile dei LED

In aggiunta al multiplex, il micro alimenta i LED tramite PWM cosi’ da poterne modificare la luminosità. Il pic 16F84 non prevede hardware dedicato per il PWM ma e’ comunque possibile realizzarlo via software togglando molto velocemente on/off i GPIO opportuni.

Animazioni

Il cubo e’ in grado di mostrare fino ad 8 animazioni differenti, ognuna composta da un certo numero di frame (un frame è semplicemente una configurazione ON/OFF dei 27 LED). Le animazioni sono codificate nella flash del micro come semplici tabelle retwl di lookup.

Sincronizzazione con musica esterna

Ho dotato il cubo di un microfono amplificatore integrati. In questo modo e’ in grado di mostrare le animazioni LED andando piu’ o meno a tempo di musica. Il segnale analogico captato dal microfono viene amplificato, filtrato da un filtro RC passa basso e poi squadrato in un segnale TTL 0-5V. Il segnale cosi’ ottenuto passa al piedino RB0/INT del micro. Il filtro RC è dimensionato per far in modo che passino solo le basse frequenze ad esempio la batteria di una musica o simili. Ogni volta che il microfono capta un segnale a bassa frequenza il piedino RB0 viene portato a livello logico alto il che scatena un interrupt nel microcontrollore. Il micro quindi seleziona casualmente una animazione (dalle 8 disponibili) e la sulla griglia LED, un frame dopo l’altro (e’ possibile impostare da software la velocita’ delle animazioni).

Schema elettrico

Questo lo schema elettrico completo:

ledcube - schematic

Il pic 16F84 è nella sua classica configurazione con oscillatore esterno da 4MHz e circuito di reset. I pin da RB1 a RB7 e RA2,RA3 indirizzano le 9 colonne LED tramite apposite resistenze limitatrici, i pin RA0,RA1 e RA4 attivano rispettivamente il piano alto, di mezzo e il basso tramite i 3 FET di potenza (2N7000). La sezione audio analogica è composta da microfono, integrato amplificatore MAX9812, filtro passa basso (R17,C7) e squadratore di segnale (i due BC547 a valle). Notare il pullup di 4.7K per il pin RA4: RA4 e’ l’unico pin del 16F84 ad essere open-collector, occorre quindi il pull-up.

DSCN4394 DSCN4399

DSCN4397 DSCN4396

Il MAX9812 non viene commercializzato nel classico package DIL ma solo su TSOP: essendo un package estremamente miniaturizzato ho dovuto realizzare una basetta adapter apposita (vedi foto in basso a destra) sulla quale saldare a parte l’integrato.

Codice sorgente

Il codice sorgente è scritto interamente in assembler in quanto sia per il multiplexing dei 3 layer che per il PWM occorre un timing particolarmente accurato, dell’ordine dei microsecondi. Il codice si compone di tre sezioni principali:

  • Inizializzazione
  • Idle routine
  • ISR (Interrupt Service Routine)

Al power on viene eseguita l’inizializzazione delle varie parti del micro (direzioni dei GPIO, timer interno, variabili di programma etc…). Immediatamente dopo il cubo entra nella idle routine nella quale parte la modalità glowing (tutti e 27 i LED rimangono accesi e si aumenta e diminuisce ciclicamente la luminosità. Il cubo permane in questa modalità fino a che non subentra un interrupt esterno (dal pin RB0) corrispondente ad un beat del segnale sonoro captato dal microfono (una musica, un battito di mani, etc…). L’interrupt viene immediatamente servito dalla routine ISR: viene impostata la luminosità massima e viene scelta una animazione casuale (fra 8 disponibili) che viene mostrata sulla griglia led. L’animazione è mostrata sulla griglia LED un frame dopo l’altro, cicliclamente. Ad ogni giro viene decrementata la luminosità di un fattore 1. Quando la luminosità raggiunge lo zero il micro esce dalla ISR e si riporta in modalità attesa (cubo glowing).

Ecco il flowchart completo del programma:

flowchart

Dettaglio codice sorgente

Il sorgente si compone di un singolo file .asm. Per la compilazione e programmazione del micro e’ sufficiente l’ambiente MPLab e apposito programmatore, ad esempio il pickit 3

ICSP40PICkit3PG

Download codice sorgente: ledcube

Nella prima parte del codice indichiamo il micro che andremo ad utilizzare (16F84) e la base per le costanti (base 16, hex):

;directives

PROCESSOR 16F84A
RADIX HEX

passiamo poi a creare i define dei registri principali del micro

;defs

PCL EQU 0x02
OPTREG EQU 0x01
TMR EQU 0x01
INTCON EQU 0x0B
TMR0 EQU 0x01
TRISB EQU 0x06
TRISA EQU 0x05
PORTA EQU 0x05
PORTB EQU 0x06
STATUS EQU 0x03
FSR EQU 0x04
INDF EQU 0x00
Z EQU 2        ; Z flags
GIE EQU 7      ; GIE bit
INTF EQU 1     ; INTF flag

infine definiamo le variabili (parliamo sempre di locazioni a 8bit) del nostro programma, in particolare i 3 layer (LOWL, MIDL e HIGL) e il layer “extra” EXTL che andrà a contenere tutti i noni LED dei layer (useremo quindi solo 3 bit in EXTL). TIME sarà la velocità delle animazioni e BRIG il livello di luminosità:


LOWL EQU 0x20   ; bottom layer (8 bit pattern)
MIDL EQU 0x21   ; middle layer (8 bit pattern)
HIGL EQU 0x22   ; upper layer (8 bit pattern)
EXTL EQU 0x23   ; extra layer (9th led for each layer)
TIME EQU 0x24   ; current frame speed
TCONT EQU 0x25  ; frame speed counter
LSEL EQU 0x26   ; layer selector
BCONT EQU 0x27  ; brightness counter
BRIG EQU 0x28   ; brightness
CURL EQU 0x29   ; current layer

La primissima istruzione (locazione 0x0000) è un semplice goto alla routine di inizializzazione. Occorre mettere il goto in quanto il micro richiede che all’indirizzo 0x0004 parta la routine di gestione interrupt.

ORG 0x0000              ; start from address 0x0000
goto Init

A questo punto osserviamo il codice di inizializzazione:

Init:                   ; initialization
bsf     STATUS,5        ; select RAM bank 1
movlw   b'00000001'
movwf   TRISB
movlw   b'00000000'
movwf   TRISA
bcf     OPTREG,5        ; start the TMR module in counter mode
bcf     STATUS,5        ; select RAM bank 0
movlw   0x00            ; all leds off
movwf   PORTA
movwf   PORTB
clrf    LSEL            ; no layer selected
call    IdleCube

molto semplicemente impostiamo tutti i GPIO come output (bit di TRISB e TRISA a zero) tranne il primo bit di PORTB (RB0) che ci servirà invece come ingresso per triggerare l’interrupt (RB0 è collegato all’amplificatore audio esterno). Avviamo il timer interno in modalità conteggio ciclico, resettiamo gli output ed infine saltiamo alla funzione IdleCube.

Passiamo ora ad analizzare la funzione IdleCube:

per prima cosa impostiamo il pattern “full 27 led” ossia tutti e 27 i led accesi. Da notare che i noni LED di ogni layer sono mappati rispettivamente nel primo, secondo e quinto bit di EXTL (RA0, RA1 e RA4): osservare lo schematico per vedere questa corrispondenza.

;******** IDLECUBE ***********************************
;
; The cube is glowing and ready to trigger...
;
;*****************************************************

IdleCube:

movlw   b'11111111'
movwf   LOWL
movlw   b'11111111'
movwf   MIDL
movlw   b'11111111'
movwf   HIGL
movlw   b'00010011'
movwf   EXTL

settiamo al minimo luminosità e velocità di animazione:

movlw   0x01
movwf   BRIG      ; smallest brightness
movlw   0x02
movwf   TIME      ; smallest pattern duration

Abilitiamo poi l’interrupt esterno dal pin RB0

bcf   INTCON,INTF
bsf   INTCON,4     ; enabling the interrupt from the RB0/INT pin
bsf   INTCON,GIE   ; enabling the interrupt service

passiamo poi ciclicamente a fare fadein e fadeout del ful-27-led pattern:

IdleCube_fadein:          ; fade in loop
callShowCube
incfsz	BRIG
goto	IdleCube_fadein
IdleCube_fadeout:         ; fade out loop
call	ShowCube
decfsz	BRIG
goto	IdleCube_fadeout
incf	BRIG,1
goto	IdleCube_fadein

Il micro rimane in questa condizione indefinitamente. Ecco il cubo durante la fase idle:

Non appena la sezione microfono/amplificatore emette un segnale sul pin RB0, viene triggerato un interrupt gestito immediatamente dal micro. Il micro inizia quindi ad eseguire il codice alla locazione 0x0004 (inizio della nostra routine ISR). La routine è abbastanza semplice e si compone di tre parti principali:

  • disabilitazione interrupt
  • selezione di un valore random da 0 a 7
  • jump table per lanciare uno di 8 animazioni led

Per il valore random viene campionato il valore corrente del timer (un valore compreso tra 0 e 255) e viene messo in AND con la maschera 0x07 per prelevarne solo i 3 bit meno significativi. Questi 3 bit sono il nostro valore casuale 0-7 e vengono sommati al program counter per chiamare la funzione animazione corrispondente.

Interrupt:              ; interrupt service routine
bcf    INTCON,INTF      ; disable the interrupt service
bsf    INTCON,GIE
movf   TMR,0            ; pick a pattern at random
andlw  0x07
addwf  PCL,1            ; jump into jump table
goto   Pattern_treble
goto   Pattern_updown
goto   Pattern_twobars
goto   Pattern_buildframe
goto   Pattern_rotplane
goto   Pattern_rlplane
goto   Pattern_snake
goto   Pattern_fourface

Analizziamo ora la funzione principale, ossia ShowCube. ShowCube mostra sulla griglia led un singolo frame dell’animazione prescelta. Il frame è codificato nei 24 bit di LOWL, MIDL, HIGL e nei 3 bit aggiuntivi di EXTL per un totale di 27 bit (i 3x3x3 led della griglia). Il pattern completo è mostrato sulla griglia accendendo un layer alla volta ad una frequenza di circa 100Hz. I bit RA0, RA1 e RA4 abilitano il layer corrispondente (controllare lo schematico per le corrispondenze). Il singolo layer è mostrato invocando la funzione ShowLayer.

;******** ShowCube ***********************************
;
; Shows the cube pattern for 0.01 * TIME sec using
; brightness level BRIG. The refresh rate is 100Hz.
;
;*****************************************************

ShowCube:

; setup counter
movf    TIME,0
movwf   TCONT           ; TCONT 0
decfsz  TCONT,1
goto    ShowCube_loop
return

Per finire ecco la funzione ShowLayer utilizzata per illuminare un singolo layer della griglia. La funzione implementa un classico PWM per settare la luminosità del singoli LED ad un valore prescelto (variabile BRIG): per un tempo pari a (BRIG/255)% il layer rimane acceso, per un tempo pari a ((255-BRIG)/255)% il layer rimane spento. In sostanza la variabile BRIG codifica il duty cycle del PWM.

;******** ShowLayer **********************************
;
; Shows the layer encoded in W and EXTL for x msec.
; (BRIG/255)% of the time the layer is ON, the
; remaining (255-BRIG)/255)% of the time the layer
; is OFF. (this is a PWM controlled brightness)
;
;*****************************************************

ShowLayer:
; layer on for (255/BRIG)*x msec
; layer off for (255/(255-BRIG))*x msec
; where x depends on the osc used

; set the first seven leds (bit0 of PORTB is used to receive interrupts!)
movwf   PORTB           ; PORTB
; set/clear the 8th led
btfsc   CURL,0
bsf     PORTA,2

; test the 9th bit of the current layer and set
; the 9th led accordingly (9th led = bit3 of PORTA)
movf    EXTL,0
andwf   LSEL,0          ; W btfss   STATUS,Z        ; is the 9th bit clear (9th led off)?
bsf     PORTA,3         ; no, set the 9th bit

; set the 9th bit of the current layer and turn on
; the entire layer
movf    LSEL,0
xorwf   PORTA,1         ; PORTA
; wait (BRIG/255)%
movf    BRIG,0
movwf   BCONT
ShowLayer_loop_layeron:
decfsz  BCONT
goto    ShowLayer_loop_layeron

; turn off the entire layer
clrf    PORTA

; wait ((255-BRIG)/255)%
movf    BRIG,0
movwf   BCONT
decf    BCONT,1
ShowLayer_loop_layeroff:
incfsz  BCONT
goto    ShowLayer_loop_layeroff

return

Ecco il cubo all’opera: