Manuale NIKIBASIC

Manuale della versione corrente di NIKIBASIC shell/PC, con indicazione anche delle istruzioni previste per firmware PIC32 e dei token presenti nel vocabolario.

Uso Generale

NIKIBASIC accetta comandi diretti e righe numerate. Le righe numerate vengono memorizzate come programma; RUN compila ed esegue il programma ordinato per numero di riga.


10 PRINT "CIAO"
20 PRINT 2+3
RUN

Le frasi sulla stessa riga possono essere separate con :.


10 A=1:PRINT A

Per uscire dalla versione shell PC usare:


exit

Limiti Attuali

Limite	Valore
Lunghezza comando shell	80 caratteri
Lunghezza linea BASIC	80 caratteri
Numero massimo righe programma	50
Numero massimo variabili utente	32
Lunghezza nome variabile utente	8 caratteri massimi, incluso l'eventuale `$`
Lunghezza stringa variabile	64 caratteri
Profondita stack `GOSUB`	32 valori, quindi 16 chiamate linea/frase
Profondita stack `IF`	32
Profondita stack `FOR`	16

Variabili

Sono disponibili registri numerici a una lettera:


A=5
PRINT A

Le variabili utente numeriche e stringa devono essere dichiarate prima con
LET. INPUT non dichiara automaticamente una variabile inesistente.
La dichiarazione nasce soltanto quando il flusso esegue LET: compilazione,
LIST e istruzioni saltate non dichiarano e non attivano variabili. Anche i
controlli di READ e INPUT avvengono nella rispettiva istruzione eseguita.


LET VALORE=10
PRINT VALORE

Le variabili stringa finiscono con $.


LET NOME$="NIKI"
PRINT NOME$

Operatori

Operatore	Significato
`+`	Somma e segno positivo unario
`-`	Sottrazione e segno negativo unario
`*`	Moltiplicazione
`/`	Divisione
`<<`	Shift bit a sinistra
`>>`	Shift bit a destra
`=`	Assegnamento o confronto in condizioni
`<`	Minore
`>`	Maggiore
`<=`	Minore o uguale
`>=`	Maggiore o uguale
`<>`	Diverso
`AND`	Logico/bitwise AND
`OR`	Logico/bitwise OR
`XOR`	Logico/bitwise XOR
`~`	NOT previsto come token operatore

Funzioni Numeriche

Funzione	Descrizione
`SIN(x)`	Seno.
`COS(x)`	Coseno.
`TAN(x)`	Tangente protetta.
`ATAN(x)`	Arcotangente approssimata/protetta.
`ABS(x)`	Valore assoluto.
`SQR(x)`	Radice quadrata; se `x < 0` restituisce `0`.
`INT(x)`	Parte intera inferiore, equivalente a `floor`.
`RND(x)`	Numero pseudo-casuale tra `0` e `1`; con `x < 0` reimposta il seed.
`LOG(x)`	Logaritmo naturale; se `x <= 0` restituisce `0`.
`EXP(x)`	Esponenziale.
`SGN(x)`	Segno: `-1`, `0`, `1`.
`VAL(s$)`	Converte una stringa in numero.
`ASC(s$)`	Codice ASCII del primo carattere.
`LEN(s$)`	Lunghezza della stringa.
`PEEK(addr)`	Legge un byte dalla memoria generale interna.
`READAN(ch)`	Lettura analogica quando supportata dal firmware; su PC restituisce `0`.

Funzioni Stringa

Funzione	Descrizione
`CHR(n)`	Restituisce il carattere con codice ASCII `n`.
`STR(n)`	Converte un numero in stringa.
`LEFT(s$,n)`	Restituisce i primi `n` caratteri.
`RIGHT(s$,n)`	Restituisce gli ultimi `n` caratteri.
`MID(s$,start,n)`	Restituisce una sottostringa.
`INSTR(s$,sub$)`	Posizione 1-based di `sub$` dentro `s$`; `0` se non trovata.

Istruzioni BASIC Attive

Istruzione	Descrizione
`NEW`	Cancella programma e stato BASIC corrente.
`LIST`	Visualizza il programma memorizzato.
`RUN`	Compila ed esegue il programma memorizzato.
`HELP`	Lists all NIKIBASIC commands with a short English description.
`WIFI "ssid", "password"`	Imposta SSID e password WiFi nel runtime.
`HWNAME "nome"`	Imposta il nome hardware usato dal NIKIBASIC PC per identificarsi verso un server.
`MQTT x, "broker", "utente", "password"`	Imposta broker MQTT e credenziali nello slot `x`, da 1 a 5.
`INTERVAL n`	Imposta ogni quanti minuti l'ESP32 invia automaticamente i campioni MQTT. Valore minimo: 1 minuto.

I JSON di telemetria prodotti dal firmware ESP32 dalla versione
1.0.2-telemetry-metadata usano il protocollo DomAvioNak 1.1 e contengono
sempre firmware_version e protocol_version. Il primo identifica esattamente
il firmware che ha generato il file; il secondo identifica il formato del
payload. Il VPS conserva entrambi i campi ed accetta ancora i pacchetti legacy
del protocollo 1.0 che ne sono privi.

`END`	Termina il programma.
`REM testo`	Commento fino a fine frase/riga.
`PRINT expr,...`	Stampa numeri, stringhe, registri e variabili.
`LET var=expr`	Crea/usa una variabile utente e assegna un valore.
`INPUT var`	Ferma il programma, attende Invio e assegna il valore a una variabile o registro.
`INPUT A,B`	Legge piu valori dalla stessa riga, separati da virgola.
`INPUT "prompt";var`	Mostra `prompt?` e attende il valore, come il BASIC del Commodore 64.
`VARS`	Mostra registri e variabili utente.
`FREE`	Shows BASIC memory usage and free space.
`DATA val,...`	Definisce dati costanti nel programma.
`READ var,...`	Legge valori da `DATA`.
`RESTORE`	Riporta il puntatore `READ/DATA` al primo dato.

Esempio:


10 LET NOME$
20 LET ETA
30 INPUT "NOME";NOME$
40 INPUT "ETA";ETA
50 PRINT NOME$,ETA

Quando RUN incontra INPUT, l'esecuzione resta sospesa fino a quando
l'utente scrive una riga e preme Invio. Senza testo personalizzato compare il
prompt standard ? . Con un testo personalizzato, per esempio
INPUT "NOME";NOME$, compare NOME? .

Le variabili usate da INPUT devono essere gia state dichiarate con LET in
una riga precedente. Un nome inesistente produce `Variable Name Not Allowed
Error` quando l'esecuzione raggiunge quella specifica istruzione, prima di
chiedere dati. Un INPUT non raggiunto, per esempio per effetto di un GOTO,
non genera errori. Solo i registri incorporati A-Z possono essere usati
direttamente senza dichiarazione.

Il nome di ogni variabile utente puo avere al massimo 8 caratteri; il simbolo
$ delle variabili stringa conta come carattere. Un nome piu lungo produce
Variable Name Not Allowed Error.

Le destinazioni che terminano con $ ricevono testo: INPUT NOME$.
Registri e variabili numeriche ricevono interi o decimali: INPUT ETA.
Piu destinazioni possono essere compilate sulla stessa riga:

INPUT NOME$,ETA, seguito per esempio da Massimo,51.

Una stringa contenente virgole puo essere racchiusa tra virgolette:

"Roma, Italia",51.

INPUT funziona nella console PC, sulla seriale ESP32 e sulla console UART

PIC32. Su ESP32 e PIC32 il programma attende senza un limite di tempo.

Esempio completo:


10 LET NOME$
20 LET ETA
30 LET ALTEZZA
40 INPUT "COME TI CHIAMI";NOME$
50 INPUT "ETA E ALTEZZA";ETA,ALTEZZA
60 PRINT "CIAO ",NOME$
70 PRINT "ETA ",ETA," ALTEZZA ",ALTEZZA
80 END

Salti E Sottoprogrammi

Istruzione	Descrizione
`GOTO n`	Salta alla linea `n`.
`GOSUB n`	Salta alla linea `n` salvando linea/frase di ritorno.
`RETURN`	Ritorna da `GOSUB`.

Condizioni

Istruzione	Descrizione
`IF cond THEN ...`	Esegue il ramo vero.
`ELSE`	Ramo alternativo.
`ENDIF`	Fine blocco `IF`.

Esempio:


10 A=1
20 IF A=1 THEN PRINT "OK" ELSE PRINT "NO"

Cicli

Istruzione	Descrizione
`FOR var=start TO fine`	Ciclo numerico con passo `1`.
`FOR var=start TO fine STEP passo`	Ciclo numerico con passo personalizzato, anche negativo.
`NEXT`	Incrementa e ripete il ciclo corrente.
`NEXT var`	Incrementa e ripete verificando la variabile del ciclo.
`WHILE cond`	Ciclo condizionale.
`WEND`	Torna al `WHILE`.
`BREAK`	Esce dal ciclo `WHILE`.
`CNTN`	Continua il ciclo `WHILE`; token previsto per `CONTINUE`.

Esempio:


10 FOR I=1 TO 3
20 PRINT I
30 NEXT I

Memoria E I/O Basso Livello

Istruzione	Descrizione
`POKE addr,val`	Scrive un byte nella memoria generale interna.
`PEEK(addr)`	Legge un byte dalla memoria generale interna.
`OUT val`	Su PIC32 scrive sulle uscite; su PC stampa il valore binario.
`PUSH val`	Token attivo ma funzione non implementata.
`POP val`	Token attivo ma funzione non implementata.

Grafica E Video

Queste istruzioni sono previste per hardware/grafica Lyuda/PIC32; nella versione PC molte non producono effetto visibile perche' il corpo e' protetto da #ifdef PIC_32.

Istruzione	Descrizione
`CLS`	Cancella lo schermo/video quando supportato.
`LOC x,y`	Posiziona il cursore. Token interno: `TKN_LOCATE`.
`COL c`	Colore testo/primo piano.
`BCOL c`	Colore sfondo.
`DIMXY x,y`	Imposta dimensioni/coordinate per primitive.
`FILL x,y`	Riempimento grafico.
`SETMODE m`	Imposta modo grafico/copia.
`STSCAN x,y`	Start scan.
`STRETCH n`	Stretch grafico.
`MASKX n`	Maschera orizzontale.
`MASKY n`	Maschera verticale.
`PSET x,y,c`	Disegna punto.
`LINE x1,y1,x2,y2,c1,c2`	Disegna linea secondo routine firmware.
`WSYNC`	Attesa sincronismo video.

File System E SD/FAT32

Queste istruzioni sono previste per il filesystem SD/FAT32 del progetto. Nella versione PC dipendono dalle routine simulate/collegate.

Istruzione	Descrizione
`DIR`	Elenca la directory corrente.
`LOAD "nome"`	Carica programma/testo da file.
`SAVE "nome"`	Salva programma/testo su file.
`DEL "nome"`	Cancella file.
`MKDIR "nome"`	Crea directory.
`DELDIR "nome"`	Cancella directory.
`CD "nome"`	Entra in directory.
`CD..`	Sale alla directory padre.
`CD/`	Torna alla root.
`FORMAT`	Formatta/prepara struttura FAT32 secondo routine progetto.
`INFODSK`	Mostra informazioni disco. Token attivo nel dispatcher anche se il token non e' marcato keyword.
`CHKSD`	Controlla SD.
`CHKBOOT`	Controlla boot/struttura disco.
`CHECK`	Controllo filesystem/directory previsto da `NikiCHECK`.
`SENDDIR`	Invia directory in blocchi secondo protocollo progetto.

Tempo, Sensori E Alimentazioni

Istruzione	Descrizione
`PAUSE n`	Pausa/ritardo su firmware; su PC non effettua ritardo.
`RESET`	Reset software quando supportato.
`SETTIME h,m,s`	Imposta ora RTC.
`SETDATE d,m,y`	Imposta data RTC.
`TIME?`	Mostra ora/data.
`SON`	Accende alimentazione/sensori. Su ESP32 porta GPIO27 a livello alto (3,3 V logici).
`SOFF`	Spegne alimentazione/sensori. Su ESP32 porta GPIO27 a livello basso (0 V).
`GET n`	Legge un sensore/canale secondo firmware.
`GETSENS`	Lettura gruppo sensori.
`TEMP?`	Lettura temperatura.
`VTEST`	Test tensioni.
`VMON`	Monitor tensioni.

Audio, PWM E Comunicazioni

Istruzione	Descrizione
`BEEP`	Beep quando supportato.
`PWM ch,val`	Imposta PWM.
`PRESC2 n`	Imposta prescaler Timer 2/PWM.
`PR2 n`	Imposta periodo Timer 2.
`TX485`	Test/invio RS485.
`TXLORA`	Invio pacchetto LoRa.
`FLORA n`	Imposta frequenza LoRa.
`RXLORA n`	Avvia/ferma ricezione LoRa.
`DEFSENS x, "nome"`	Imposta il nome visualizzato/stoccato del sensore `analogx`, con `x` da 1 a 32. Il nome viene inviato nel JSON MQTT come campo `name` e il VPS lo usa nei grafici e in `geotech_readings.sensor_name`. Usare nomi corti, circa 12-16 caratteri al massimo.

Token Previsti Ma Non Agganciati Al Dispatcher

Questi token sono nel vocabolario, ma non hanno un case attivo nel dispatcher principale corrente, oppure sono commentati.

Token	Note
`DFNSNS`	Definizione numero sensori prevista.
`REPORT`	Report previsto.
`CRTFILE`	Creazione file prevista.
`DEFNAME`	Definizione nome prevista.
`DEFAPN`	Definizione APN prevista.
`DFROUTE`	Definizione route prevista.
`DEFWADR`	Definizione indirizzo previsto.
`DEFLOC`	Definizione localita/posizione prevista.
`SPREN`	Sprite enable previsto, dispatcher commentato.
`XC`	Coordinate X sprite previste, dispatcher commentato.
`YC`	Coordinate Y sprite previste, dispatcher commentato.
`CLKSPI`	Clock SPI previsto.
`PULSE`	Impulsi previsti, dispatcher commentato.
`RESSPI`	Reset SPI previsto.
`DOSPI`	Operazione SPI prevista.
`FPWM`	PWM/frequenza prevista.
`SENDSPI`	Invio SPI previsto, dispatcher commentato.
`READSPI`	Lettura SPI prevista.
`PLSESPI`	Pulse SPI previsto.
`DLYSPI`	Delay SPI previsto.
`SSECTOR`	Settore SD previsto.
`PRNGSNS`	Range sensori previsto.

Token Di Servizio Interni

Questi non sono istruzioni utente normali: <EXT>, <NEWLN>, <REMSTR>, <NUMB>, <TNUMB>, <ENDLN>, <ENDPHR>, <ENDPRG>, <TRUE>, <FALSE>, <VRUSR>, <USRSTR>, <STR>.

Errori Principali

Errore	Significato
`Syntax Error`	Sintassi non valida o token non gestibile nel contesto.
`Out Of DATA Error`	`READ` ha richiesto piu' valori di quelli presenti nei `DATA`.
`Type Mismatch Error`	Tipo non compatibile, per esempio testo in variabile numerica con `INPUT`.
`Inexistent Line Error`	Linea di destinazione non trovata.
`Underflow Call Stack Error`	`RETURN` senza `GOSUB`, oppure `NEXT` senza `FOR`.
`Overflow Call Stack Error`	Troppi `GOSUB` o `FOR` annidati.
`Division By Zero Error`	Divisione per zero.
`Variable Name is Too Long Error`	Nome variabile troppo lungo.
`Variable Name Already Defined Error`	Nome variabile gia' definito in contesto non ammesso.
`Illegal Assignment Error`	Assegnamento non valido.
`Invalid Operands Error`	Operandi non validi.
`IF Whitout ENDIF Error`	`IF` senza `ENDIF`.
`ENDIF Whitout IF Error`	`ENDIF` senza `IF`.
`ELSE Whitout IF Error`	`ELSE` senza `IF`.

Programmi Di Test Inclusi

Nel progetto sono presenti:

File	Scopo
`TESTPC.BAS`	Esempio BASIC PC con `DATA`, `READ`, `PRINT`.
`test_read_data.bas`	Test `READ`, `DATA`, `RESTORE` e `Out Of DATA`.
`test_generale_nikibasic.bas`	Test generale shell per aritmetica, funzioni matematiche, stringhe, `DATA`, `READ` e `RESTORE`.

La versione shell PC carica automaticamente il test generale all'avvio quando NIKIBASIC_LOAD_EXAMPLES e' attivo in main.c. Dopo l'avvio usare LIST per vederlo oppure RUN per eseguirlo.