Manuale NIKIBASIC

NikiBasic e' dedicato a mio figlio Nikita.

Versione del linguaggio: NikiBasic Core 1.0.0. Stato: stabile, congelato e
verificato il 20 agosto 2026 su PC, ESP32 e tramite build PIC32. Le correzioni
compatibili mantengono la versione del linguaggio; il firmware di prodotto puo'
avere una propria versione distinta.

Questo manuale descrive il linguaggio comune e segnala i comandi forniti dalle
estensioni. Un comando legato a filesystem, rete, orologio o hardware puo' non
essere disponibile su tutte le piattaforme. HELP elenca sempre i comandi
effettivamente presenti nella build in uso.

Primi comandi

Per mostrare un testo:

PRINT "CIAO"

Risultato:

CIAO

Per eseguire calcoli:

PRINT 2+3
PRINT 10/2

Il comando HELP mostra l'elenco dei comandi disponibili.

Sull'ESP32 del computer di stazione, DEVINFO identifica chiaramente il sistema.
La release corrente mostra:

Software: NikiBasic
Platform: ESP32
NikiBasic version: 1.0.0
Firmware version: 1.0.9-nikibasic-identity

Mostra inoltre Device ID, stato Wi-Fi/MQTT e supporto attivo: SD oppure
FAT FLASH.

Comandi immediati e programmi

Un comando senza numero viene eseguito subito:

PRINT "PROVA"

Una riga che comincia con un numero viene invece conservata come parte di un
programma:

10 PRINT "CIAO"
20 PRINT "QUESTO E' IL MIO PRIMO PROGRAMMA"
30 END

I numeri stabiliscono l'ordine delle righe. E' utile lasciare uno spazio tra i
numeri, per esempio 10, 20, 30, cosi' sara' possibile aggiungere in seguito una
riga 15 senza riscrivere tutto.

I comandi principali per lavorare con un programma sono:

Esempio di commento:

10 REM QUESTO PROGRAMMA SALUTA L'UTENTE
20 PRINT "BUONGIORNO"
30 END

E' possibile mettere piu' istruzioni sulla stessa riga separandole con ::

10 A=5:PRINT A

Per rendere i programmi facili da leggere, e' comunque preferibile usare una
riga per ogni operazione.

Correggere e cancellare una riga

Per sostituire una riga, riscrivere lo stesso numero con il nuovo contenuto:

10 PRINT "PRIMA VERSIONE"
10 PRINT "VERSIONE CORRETTA"

LIST mostrera' soltanto la seconda versione. Per eliminare una riga, inviare
soltanto il suo numero:

10

Questa operazione modifica il programma in memoria, ma non aggiorna
automaticamente il file dal quale era stato caricato. Per rendere permanente la
modifica occorre eseguire nuovamente SAVE.

Una sessione di lavoro consigliata

Un metodo semplice riduce il rischio di perdere modifiche o eseguire un
programma diverso da quello atteso:

1. usare NEW prima di iniziare un programma nuovo;
2. inserire o caricare le righe;
3. controllare con LIST;
4. provare con RUN;
5. correggere gli eventuali errori;
6. salvare con SAVE soltanto quando il risultato e' quello desiderato.

RUN controlla e compila l'intero programma prima di eseguirlo. Se trova una
riga non valida, non lascia una compilazione parziale: la console rimane
utilizzabile e la riga puo' essere corretta.

Numeri, testo e variabili

Una variabile e' un contenitore con un nome. Serve a conservare un valore per
usarlo in seguito.

Le lettere da A a Z possono contenere direttamente numeri:

A=12
PRINT A

Per nomi piu' descrittivi si usa LET:

LET PREZZO=25
PRINT PREZZO

Il testo va racchiuso tra virgolette. I nomi delle variabili che contengono
testo terminano con $:

LET NOME$="MASSIMO"
PRINT "CIAO ",NOME$

Regole pratiche:

• dichiarare una variabile con LET prima di usarla;
• usare nomi di non piu' di 8 caratteri, contando anche il simbolo $;
• usare $ soltanto per le variabili di testo;
• non racchiudere tra virgolette i nomi delle variabili.

Il comando VARS mostra le variabili e i valori presenti. Il comando FREE
mostra quanta memoria BASIC e' ancora disponibile.

Registri e variabili con nome

I registri A-Z sono comodi per calcoli brevi e contatori. Le variabili con
nome rendono invece piu' chiaro un programma lungo:

A=18
LET TEMPER=18

Entrambe conservano un numero, ma TEMPER spiega meglio lo scopo del valore.
NikiBasic distingue le variabili numeriche da quelle stringa mediante $:

LET STATO=1
LET STATO$="ATTIVO"

Sono due variabili diverse. Per evitare errori, scegliere nomi brevi ma
significativi e non riutilizzare lo stesso nome per scopi non collegati.

Controllare memoria e valori

Durante lo sviluppo usare:

VARS
FREE

VARS aiuta a trovare valori inattesi dopo un ciclo o un INPUT. FREE
riporta l'uso delle aree BASIC, comprese righe, programma compilato e variabili.
Se lo spazio si riduce troppo, accorciare il programma o eliminare dati e
variabili non necessari; non ignorare gli errori di memoria.

Chiedere dati all'utente

INPUT ferma il programma e aspetta che l'utente scriva una risposta e prema
Invio. La variabile deve essere stata preparata prima con LET.

10 LET NOME$
20 INPUT "COME TI CHIAMI";NOME$
30 PRINT "CIAO ",NOME$
40 END

Per chiedere un numero:

10 LET ETA=0
20 INPUT "QUANTI ANNI HAI";ETA
30 PRINT "HAI ",ETA," ANNI"
40 END

Si possono leggere piu' risposte insieme:

10 LET BASE=0
20 LET ALTEZZA=0
30 INPUT "BASE E ALTEZZA";BASE,ALTEZZA
40 PRINT "AREA = ",BASE*ALTEZZA
50 END

In questo caso l'utente separa i due numeri con una virgola, per esempio
5,8.

La richiesta puo' leggere registri o variabili gia' dichiarate. Se viene
richiesto un numero, inserire un valore numerico; se la destinazione termina con
$, il testo viene conservato come stringa. Un dato del tipo sbagliato produce
un errore esplicito invece di modificare una variabile in modo ambiguo.

Quando un programma resta in attesa su INPUT, BREAK deve poterlo riportare
alla console. Questo e' utile soprattutto durante le prove remote.

Calcoli e confronti

Priorita' degli operatori

NikiBasic rispetta le normali priorita' matematiche. Le espressioni tra
parentesi vengono calcolate per prime; seguono moltiplicazioni e divisioni;
infine vengono eseguite addizioni e sottrazioni.

PRINT 2+3*4

Il risultato e' 14, perche' viene calcolato prima 3*4 e poi viene aggiunto
2. Non si ottiene 20, che sarebbe invece il risultato eseguendo le
operazioni semplicemente da sinistra verso destra, come avviene in alcuni
interpreti BASIC tradizionali piu' semplici.

Le parentesi permettono di cambiare esplicitamente l'ordine:

PRINT (2+3)*4

In questo caso il risultato e' 20, perche' viene calcolato prima 2+3.

Le parentesi possono essere nidificate, cioe' inserite una dentro l'altra:

PRINT 2*(3+(4*5))

NikiBasic calcola prima la parentesi piu' interna e procede verso l'esterno:

1. 4*5 restituisce 20;
2. 3+20 restituisce 23;
3. 2*23 restituisce 46.

Il risultato finale e' quindi 46. Quando un'espressione e' complessa, usare
le parentesi rende il calcolo piu' chiaro e facile da controllare.

Lasciare uno spazio prima e dopo AND, OR e XOR.

Risultati logici e condizioni

I confronti vengono usati soprattutto dentro IF e WHILE. E' buona pratica
scrivere condizioni esplicite:

IF TEMPER>=20 AND TEMPER<=30 THEN PRINT "INTERVALLO NORMALE"

Non unire gli operatori alfabetici ai nomi: A OR B e' valido, mentre AORB
e' una parola diversa e viene rifiutata. Questa regola evita che un nome venga
interpretato accidentalmente come piu' token.

Divisione per zero, radice di un numero negativo, logaritmo fuori dominio e
overflow numerico generano un errore. Dopo l'errore la console deve restare
disponibile: correggere valori o formula e ripetere il comando.

Prendere decisioni con IF

IF permette al programma di scegliere cosa fare.

10 LET ETA=0
20 INPUT "ETA";ETA
30 IF ETA>=18 THEN PRINT "MAGGIORENNE" ELSE PRINT "MINORENNE"
40 END

Per decisioni composte da piu' righe si usano ELSE e ENDIF:

10 A=7
20 IF A>5 THEN
30 PRINT "A E' MAGGIORE DI 5"
40 ELSE
50 PRINT "A NON E' MAGGIORE DI 5"
60 ENDIF
70 END

La forma monoriga e' adatta a un'azione breve. La forma multilinea e'
preferibile quando ciascun ramo contiene piu' istruzioni. Ogni IF multilinea
deve avere il proprio ENDIF; l'indentazione non cambia l'esecuzione ma rende
visibili gli abbinamenti:

10 A=7
20 IF A>0 THEN
30   IF A<10 THEN
40     PRINT "A HA UNA CIFRA"
50   ENDIF
60 ELSE
70   PRINT "A NON E' POSITIVO"
80 ENDIF
90 END

Nelle righe inviate alla console gli spazi iniziali sono facoltativi. Sono
mostrati nell'esempio soltanto per rendere leggibile la struttura.

Ripetere operazioni

Ciclo FOR

FOR ripete un gruppo di righe per un numero stabilito di volte. NEXT chiude
il ciclo.

10 FOR I=1 TO 5
20 PRINT I
30 NEXT I
40 END

Con STEP si sceglie l'incremento:

10 FOR I=10 TO 0 STEP -2
20 PRINT I
30 NEXT I
40 END

Il passo deve essere coerente con la direzione del ciclo. Usare un passo
positivo per salire e negativo per scendere. La variabile indicata da NEXT
deve corrispondere a quella del relativo FOR.

Ciclo WHILE

WHILE continua finche' una condizione e' vera. WEND chiude il ciclo.

10 A=1
20 WHILE A<=5
30 PRINT A
40 A=A+1
50 WEND
60 END

BREAK interrompe il ciclo. CNTN passa direttamente al giro successivo.

Durante un programma e' possibile interrompere l'esecuzione dalla console con
BREAK. Sulla console seriale ESP32 la sequenza prevista e' composta da tre
ritorni carrello consecutivi; app Android e Terminale Universale espongono un
pulsante BREAK.

CNTN salta il resto dell'iterazione corrente e torna a valutare la condizione
del WHILE. BREAK esce dal ciclo piu' vicino. Un esempio che stampa soltanto
i valori dispari e si ferma prima di 8:

10 A=0
20 WHILE A<10
30 A=A+1
40 IF A=8 THEN BREAK
50 IF A=2 OR A=4 OR A=6 THEN CNTN
60 PRINT A
70 WEND
80 END

Assicurarsi che almeno una riga del ciclo possa rendere falsa la condizione;
altrimenti il ciclo continua finche' non arriva BREAK.

Salti e sottoprogrammi

GOTO continua l'esecuzione da un'altra riga:

10 PRINT "INIZIO"
20 GOTO 40
30 PRINT "QUESTA RIGA VIENE SALTATA"
40 PRINT "FINE"

GOSUB richiama una parte riutilizzabile del programma. RETURN torna alla
riga successiva alla chiamata:

10 PRINT "PRIMA"
20 GOSUB 100
30 PRINT "DOPO"
40 END
100 PRINT "SONO NEL SOTTOPROGRAMMA"
110 RETURN

Un sottoprogramma deve terminare con RETURN, non con un salto casuale nel
programma principale. END impedisce che l'esecuzione normale cada dentro le
righe del sottoprogramma poste in fondo:

10 GOSUB 100
20 PRINT "FINE PROGRAMMA"
30 END
100 PRINT "OPERAZIONE COMUNE"
110 RETURN

Usare GOTO per cambiare realmente fase del programma; per operazioni
riutilizzabili preferire GOSUB, perche' conserva automaticamente il punto di
ritorno.

Elenchi di dati

DATA conserva una serie di valori. READ li legge uno dopo l'altro e
RESTORE ricomincia dal primo valore.

10 DATA 12,25,8
20 READ A
30 READ B
40 READ C
50 PRINT A,B,C
60 RESTORE
70 READ A
80 PRINT A
90 END

Non chiedere con READ piu' valori di quelli inseriti con DATA.

DATA e' utile per tabelle fisse, messaggi o sequenze di calibrazione che fanno
parte del programma. RESTORE riporta il puntatore al primo elemento, quindi la
stessa tabella puo' essere riletta:

10 DATA 3,6,9
20 FOR I=1 TO 3
30 READ A
40 PRINT A
50 NEXT I
60 RESTORE
70 READ A
80 PRINT "PRIMO=",A
90 END

Il tipo della destinazione deve essere compatibile con il valore letto.

Funzioni utili

Una funzione esegue un'operazione e restituisce un risultato.

Funzioni numeriche

Funzioni per il testo

Comporre funzioni ed espressioni

Le funzioni possono comparire dentro espressioni piu' grandi:

PRINT ABS(-4)+SQR(25)
PRINT LEFT("NIKIBASIC",4),RIGHT("NIKIBASIC",5)

Con funzioni annidate usare parentesi chiare e provare prima le singole parti.
Gli indici e le lunghezze delle funzioni di testo devono riferirsi a posizioni
valide; un errore viene segnalato senza scrivere oltre i buffer disponibili.

Memoria virtuale con POKE e PEEK

POKE scrive un byte nella memoria virtuale NikiBasic e PEEK lo legge:

POKE 0,65
PRINT PEEK(0)

Il risultato e' 65. Indirizzo e valore devono essere numeri finiti e interi;
il byte deve essere compreso tra 0 e 255 e l'indirizzo deve appartenere alla
memoria disponibile sulla piattaforma. Valori negativi, frazionari o fuori
intervallo vengono rifiutati.

Questi comandi sono strumenti a basso livello. Non usarli come sostituti delle
variabili normali e non assumere che lo stesso indirizzo abbia un significato
hardware identico su PC, ESP32 e PIC32.

Salvare e aprire programmi

I comandi di questa sezione appartengono all'estensione filesystem. Sono
disponibili nella build PC e nelle composizioni embedded che includono un
filesystem.

I comandi per lavorare con file e cartelle sono:

Esempio:

SAVE "saluto.bas"
NEW
LOAD "saluto.bas"
LIST
RUN

Attenzione: DEL e DELDIR eliminano dati. Controllare sempre il nome prima
di confermare il comando.

Sugli ESP32 verificati il supporto viene scelto automaticamente:

• il modello con lettore usa la scheda SD FAT32;
• il modello costruito senza lettore SD usa la partizione interna FAT FLASH;
• AUTOEXEC.BAS viene caricato dal supporto attivo all'avvio;
• un normale aggiornamento firmware USB o OTA non cancella la FAT FLASH, mentre

una cancellazione completa della memoria fisica la elimina.

La scritta FILESYSTEM: FAT FLASH sul modello senza lettore SD indica il
funzionamento previsto, non un guasto.

Percorsi e cartella corrente

I nomi relativi partono dalla cartella corrente. Dopo:

CD "audio"

CAT "note.txt" cerca il file dentro audio. CD.. sale di un livello e
CD/ torna alla radice. Se un file sembra assente, eseguire DIR e controllare
prima la cartella corrente.

Aggiornare AUTOEXEC.BAS in sicurezza

AUTOEXEC.BAS viene eseguito automaticamente all'avvio sulle composizioni che
lo prevedono. Prima di sostituirlo:

1. caricare o inserire il nuovo programma;
2. provarlo manualmente con RUN;
3. verificare che BREAK riesca a interromperlo;
4. salvarlo come AUTOEXEC.BAS;
5. riavviare e controllare i messaggi di boot.

Un programma automatico non dovrebbe contenere cicli infiniti privi di attese o
punti di interruzione. Inserire PAUSE quando il lavoro non richiede esecuzione
continua alla massima velocita'.

Data e ora

TIME? e' un comando di estensione: e' disponibile soltanto nelle build che
includono il servizio RTC o l'orario di piattaforma.

Il comando TIME? mostra la data e l'ora correnti:

TIME?

Se l'orologio non e' ancora disponibile o sincronizzato, NikiBasic mostra un
messaggio esplicativo invece di fornire una data non valida.

NikiBasic sul computer di stazione ESP32

Il computer di stazione combina il Core con estensioni di piattaforma. Fra i
comandi disponibili possono comparire:

La disponibilita' esatta dipende dalla composizione caricata: controllare
HELP, non presumere che ogni build ESP32 includa tutti i gruppi.

I comandi MQTT, INTERVAL, SEND, SON, SOFF, HWNAME, DEFLOC,
DEFGPS, DEFSENS, DEFNSENS, DEFCLI e DEFMON appartengono alla
composizione datalogger separata e non al computer di stazione.

Wi-Fi e MQTT ritentano automaticamente la connessione dopo una perdita di rete.
La configurazione persistente non deve essere reinserita a ogni disconnessione.
DEVINFO e' il primo comando da usare per diagnosticare un dispositivo locale
o remoto.

La console seriale usa 9600 baud, 8N1, nessun controllo di flusso, DTR e RTS
disattivati. Il Device ID evita di comandare per errore un'altra centralina
quando si utilizza la console MQTT o l'app Android.

Messaggi di errore piu' comuni

Quando compare un errore, usare LIST, leggere la riga indicata e confrontarla
con gli esempi di questo manuale.

Metodo di diagnosi

Quando un programma non si comporta come previsto:

1. usare BREAK per tornare alla console;
2. eseguire LIST e controllare la riga indicata;
3. usare VARS per osservare i valori correnti;
4. provare separatamente l'espressione con PRINT;
5. correggere una sola regola generale alla volta;
6. rieseguire RUN dall'inizio;
7. salvare soltanto dopo il collaudo.

Su ESP32 aggiungere DEVINFO e DIR per distinguere un problema del programma
da rete, MQTT o cartella corrente. Non cancellare o riformattare il supporto per
risolvere un semplice errore di sintassi.

Esempio completo

Il programma seguente chiede un nome e tre misure, calcola la media e mostra un
messaggio diverso secondo il risultato.

10 LET NOME$
20 LET SOMMA=0
30 INPUT "NOME";NOME$
40 FOR I=1 TO 3
50 INPUT "MISURA";A
60 SOMMA=SOMMA+A
70 NEXT I
80 LET MEDIA=SOMMA/3
90 PRINT "UTENTE: ",NOME$
100 PRINT "MEDIA: ",MEDIA
110 IF MEDIA>=10 THEN PRINT "VALORE ALTO" ELSE PRINT "VALORE BASSO"
120 END

Per provarlo:

1. scrivere le righe una alla volta;
2. usare LIST per controllarle;
3. scrivere RUN;
4. rispondere alle richieste e premere ogni volta Invio;
5. usare SAVE "media.bas" se si desidera conservarlo.

Scrivere programmi affidabili

• Lasciare spazio fra i numeri di riga per poter inserire correzioni.
• Usare una riga per operazione quando il programma non e' banale.
• Dichiarare le variabili con LET prima di usarle con INPUT.
• Scegliere nomi coerenti e riservare i registri A-Z ai calcoli brevi.
• Separare sempre AND, OR e XOR con spazi.
• Chiudere ogni struttura: IF/ENDIF, FOR/NEXT, WHILE/WEND.
• Assicurarsi che i cicli possano terminare o essere interrotti.
• Controllare i percorsi con DIR prima di usare DEL o DELDIR.
• Provare AUTOEXEC.BAS manualmente prima di renderlo automatico.
• Usare DEVINFO, VARS e FREE come strumenti ordinari, non soltanto dopo un

guasto.

• Conservare una copia leggibile dei programmi importanti fuori dal dispositivo.

Promemoria rapido