Pocket FORTH

Pocket FORTH is a compact FORTH environment for iPhone, iPad and Mac, with a remote terminal for compatible ESP8266 and ESP32 boards. Type commands directly, define and edit new words, inspect the stack, save programs as .4th files and move them between the app and embedded hardware over Wi-Fi.

Pocket FORTH è un ambiente FORTH compatto per iPhone, iPad e Mac, con un terminale remoto per schede ESP8266 ed ESP32 compatibili. Scrivi comandi direttamente, definisci e modifica nuove parole, controlla lo stack, salva programmi come file .4th e trasferiscili tra app e hardware embedded tramite Wi-Fi.

✓ iOS & macOS

✓ ESP8266 & ESP32

✓ Remote terminal

✓ .4th & QR sharing

Think in stacks

Values go on the stack, words consume and produce values. 5 DUP * . prints the square of 5.

I valori vanno sullo stack, le parole consumano e producono valori. 5 DUP * . stampa il quadrato di 5.

Build your language

Use colon definitions to create new words: : SQUARE DUP * ;. Small words combine into larger programs.

Usa le definizioni con i due punti per creare nuove parole: : SQUARE DUP * ;. Tante parole piccole diventano programmi più grandi.

Documentation

Reference for the Pocket FORTH 2.0 feature set.

Intro Stack Definitions Memory Control Flow Strings System Sharing

Introduction

FORTH is interactive and stack-based. You type words separated by spaces. Numbers are pushed on the stack; words operate on the stack.

2 3 + .        \ prints 5
5 DUP * .      \ prints 25
.S             \ inspect the stack

Truth values: Pocket FORTH follows the classic convention: TRUE is -1, FALSE is 0.

Stack and arithmetic

Word	Meaning	Stack effect
`+ - * /`	integer arithmetic	`a b -- result`
`MOD`	remainder	`a b -- rem`
`/MOD`	remainder and quotient	`a b -- rem quot`
`1+ 1- 2+ 2- 2* 2/`	small integer shortcuts	`n -- n'`
`ABS NEGATE MIN MAX`	numeric helpers	`...`

Stack manipulation

Word	Stack effect
`DUP`	`a -- a a`
`DROP`	`a --`
`SWAP`	`a b -- b a`
`OVER`	`a b -- a b a`
`ROT`	`a b c -- b c a`
`NIP`	`a b -- b`
`TUCK`	`a b -- b a b`
`2DROP 2DUP 2OVER 2SWAP`	double-cell stack helpers
`?DUP`	duplicate only if non-zero
`DEPTH PICK`	stack depth and deep stack access

Definitions and comments

Create new words with : and ;. Comments use backslash to the end of the line or parenthesized comments.

: SQUARE DUP * ;
9 SQUARE .

\ comment to end of line
( stack comment )

RECURSE can be used inside a definition to call the current word. EXIT exits the current word early.

Variables, constants and memory

Word	Meaning
`VARIABLE name`	creates a variable; executing it leaves its address
`value CONSTANT name`	creates a constant; executing it leaves its value
`@`	fetch value from address
`!`	store value to address
`?`	print value stored at address
`+!`	add to value stored at address
`HERE ALLOT , CREATE CELLS CELL+`	basic dictionary/memory words

VARIABLE A
10 A !
A @ .
5 A +!
A ?

Control flow

Implemented control words include IF ELSE THEN, BEGIN AGAIN UNTIL, DO ?DO LOOP +LOOP, I, J, LEAVE and UNLOOP.

: SIGN
  DUP 0< IF ." NEGATIVE" CR EXIT THEN
  DUP 0= IF ." ZERO" CR EXIT THEN
  ." POSITIVE" CR
;

: COUNT10
  10 0 DO I . LOOP
;

Comparison and logic

Available words: = < > 0= 0< 0> 0<> <> TRUE FALSE AND OR XOR INVERT <= >=

Output and strings

Word	Meaning
`.`	print top stack value
`.R`	right-aligned numeric output: `value width .R`
`." text"`	print literal text immediately
`S" text" TYPE`	compiled string/address+length, then output
`EMIT`	print character code
`CR SPACE SPACES BL`	formatting helpers

." HELLO" CR
65 EMIT CR
S" POCKET FORTH" TYPE CR

System commands

Command	Description
`WORDS`	list the dictionary
`.S` or `STACK`	show stack contents
`SEE word`	show a word definition
`EDIT word`	edit a colon definition
`HELP`	quick help in the console
`DIR`	list saved programs
`SAVE name`	save current source as `name.4th`
`INCLUDE name`	load a saved `.4th` program
`RUN`	execute the loaded program
`NEW`	reset the current session and clear source/output
`PAGE`	clear console output
`COPYWORD old new`	duplicate a user colon definition
`FORGET word`	remove a user word
`FORGET *`	remove all user-defined words

Limits

Resource	Limit
Data stack	128 cells
Return stack	128 cells
Dictionary	256 words
Input line	512 characters
Source lines per colon definition	64
Cell memory	1024 cells
String space	4096 bytes

Timing and compatibility

MS, MILLIS and MICROS are available in the local interpreter. The constants INPUT, OUTPUT, HIGH and LOW are also defined for compatibility with embedded programs.

Save and export plain-text .4th files containing user colon definitions, constants, variables and CREATE data.
Import/export QR codes; larger programs can be split across multiple QR parts.
Run saved programs from Apple Shortcuts using the Run FORTH Program action.
On Mac, saved programs can also be launched through the pocketforth://run?program=Name URL scheme.

Introduzione

FORTH è interattivo e basato sullo stack. Scrivi parole separate da spazi. I numeri vengono inseriti nello stack; le parole li consumano e producono nuovi valori.

2 3 + .        \ stampa 5
5 DUP * .      \ stampa 25
.S             \ mostra lo stack

Valori logici: Pocket FORTH segue la convenzione classica: TRUE è -1, FALSE è 0.

Stack e aritmetica

Parola	Significato	Effetto stack
`+ - * /`	aritmetica intera	`a b -- risultato`
`MOD`	resto	`a b -- resto`
`/MOD`	resto e quoziente	`a b -- resto quoziente`
`1+ 1- 2+ 2- 2* 2/`	scorciatoie intere	`n -- n'`
`ABS NEGATE MIN MAX`	aiuti numerici	`...`

Manipolazione stack

Parola	Effetto stack
`DUP`	`a -- a a`
`DROP`	`a --`
`SWAP`	`a b -- b a`
`OVER`	`a b -- a b a`
`ROT NIP TUCK`	riordino stack
`2DROP 2DUP 2OVER 2SWAP`	parole doppie
`?DUP DEPTH PICK`	duplicazione condizionale, profondità e accesso profondo

Definizioni e commenti

Crea nuove parole con : e ;. I commenti usano backslash fino a fine riga oppure parentesi.

: SQUARE DUP * ;
9 SQUARE .

\ commento fino a fine riga
( commento stack )

RECURSE richiama la parola corrente dall'interno della sua definizione. EXIT esce prima dalla parola corrente.

Variabili, costanti e memoria

Parola	Significato
`VARIABLE nome`	crea una variabile; eseguirla lascia il suo indirizzo
`valore CONSTANT nome`	crea una costante
`@`	legge da indirizzo
`!`	scrive a indirizzo
`?`	stampa il valore a indirizzo
`+!`	somma a una variabile
`HERE ALLOT , CREATE CELLS CELL+`	parole base di memoria/dizionario

VARIABLE A
10 A !
A @ .
5 A +!
A ?

Controllo del flusso

Sono implementate: IF ELSE THEN, BEGIN AGAIN UNTIL, DO ?DO LOOP +LOOP, I, J, LEAVE e UNLOOP.

: SIGN
  DUP 0< IF ." NEGATIVO" CR EXIT THEN
  DUP 0= IF ." ZERO" CR EXIT THEN
  ." POSITIVO" CR
;

: COUNT10
  10 0 DO I . LOOP
;

Confronti e logica

Parole disponibili: = < > 0= 0< 0> 0<> <> TRUE FALSE AND OR XOR INVERT <= >=

Output e stringhe

Parola	Significato
`.`	stampa il valore in cima allo stack
`.R`	stampa allineata a destra: `valore ampiezza .R`
`." testo"`	stampa testo letterale
`S" testo" TYPE`	stringa compilata + stampa
`EMIT`	stampa un carattere da codice
`CR SPACE SPACES BL`	formattazione

." CIAO" CR
65 EMIT CR
S" POCKET FORTH" TYPE CR

Comandi di sistema

Comando	Descrizione
`WORDS`	elenca il dizionario
`.S` o `STACK`	mostra lo stack
`SEE parola`	mostra una definizione
`EDIT parola`	modifica una definizione colon
`HELP`	aiuto rapido in console
`DIR`	elenca programmi salvati
`SAVE nome`	salva come `nome.4th`
`INCLUDE nome`	carica un programma `.4th`
`RUN`	esegue il programma caricato
`NEW`	resetta sessione e sorgente/output
`PAGE`	pulisce la console
`COPYWORD vecchia nuova`	duplica una definizione colon utente
`FORGET parola`	rimuove una parola utente
`FORGET *`	rimuove tutte le parole definite dall’utente

Limiti

Risorsa	Limite
Stack dati	128 celle
Return stack	128 celle
Dizionario	256 parole
Riga input	512 caratteri
Righe sorgente per definizione	64
Memoria celle	1024 celle
Spazio stringhe	4096 byte

Temporizzazione e compatibilità

MS, MILLIS e MICROS sono disponibili nell’interprete locale. Sono inoltre definite le costanti INPUT, OUTPUT, HIGH e LOW per facilitare la compatibilità con i programmi embedded.

Salva ed esporta file testuali .4th contenenti definizioni colon, costanti, variabili e dati creati con CREATE.
Import/export QR code; i programmi grandi possono essere divisi in più QR.
Esecuzione da Comandi Rapidi Apple con l'azione Run FORTH Program.
Su Mac si può usare anche lo schema URL pocketforth://run?program=Nome.

Remote Terminal

Use the Pocket FORTH app as a Wi-Fi console for a compatible ESP8266 or ESP32 board running the Pocket FORTH firmware.

Connection

Turn on the board, open Pocket FORTH and tap TERMINAL. The app joins the board access point and opens a TCP connection automatically.

Setting	Value
Wi-Fi network	`POCKETFORTH`
Address	`192.168.1.1`
TCP port	`2323`

Direct control: commands entered in remote mode are executed by the board, not by the local iOS interpreter.

Remote controls

Control	Action
`CONSOLE`	return to the local interpreter
`WORDS`	show the remote dictionary
`STACK`	show the remote data stack
`UPLOAD`	replace the board user program with the current local `.4th` program
`DOWNLOAD`	import the board user program into the app
`RESET`	restart the board
`HELP`	show the firmware quick help

After a reset or a temporary Wi-Fi interruption, the app attempts to restore the remote session. Hardware output and available words depend on the selected board.

Collegamento

Accendi la scheda, apri Pocket FORTH e tocca TERMINAL. L’app si collega al punto di accesso della scheda e apre automaticamente la connessione TCP.

Impostazione	Valore
Rete Wi-Fi	`POCKETFORTH`
Indirizzo	`192.168.1.1`
Porta TCP	`2323`

Controllo diretto: i comandi inseriti in modalità remota vengono eseguiti dalla scheda e non dall’interprete locale iOS.

Comandi remoti

Comando	Azione
`CONSOLE`	torna all’interprete locale
`WORDS`	mostra il dizionario remoto
`STACK`	mostra lo stack dati remoto
`UPLOAD`	sostituisce il programma utente della scheda con il programma `.4th` locale corrente
`DOWNLOAD`	importa nell’app il programma utente presente sulla scheda
`RESET`	riavvia la scheda
`HELP`	mostra l’aiuto rapido del firmware

Dopo un reset o una temporanea interruzione Wi-Fi, l’app prova a ripristinare la sessione remota. Le uscite hardware e le parole disponibili dipendono dalla scheda utilizzata.

Embedded Firmware

Run Pocket FORTH directly on supported ESP8266 and ESP32 boards, using serial or the built-in Wi-Fi terminal.

Read before downloading: installing firmware changes the contents of the board flash memory. Make sure the selected image matches your hardware and read the firmware disclaimer below.

ESP8266 firmware

Precompiled Pocket FORTH binary for compatible ESP8266 boards.

Download ESP8266 .bin

ESP32 firmware

Precompiled Pocket FORTH binary for compatible ESP32 boards.

Download ESP32 .bin

Hardware words

Word	Stack effect / meaning
`PINMODE`	`pin mode --`
`DIGITAL!`	`value pin --`, write a digital output
`DIGITAL@`	`pin -- value`, read a digital input
`PWM!`	`duty pin --`, set PWM output
`ANALOG@`	`pin -- value`, read an analog input where supported
`MS`	`milliseconds --`, delay execution
`MILLIS MICROS`	return elapsed time since startup

: BLINK
  2 OUTPUT PINMODE
  5 0 DO
    LOW 2 DIGITAL!
    500 MS
    HIGH 2 DIGITAL!
    500 MS
  LOOP
;

Pin numbering, active-high or active-low behavior, analog capabilities and safe voltage levels vary by board. Check the documentation for your exact hardware before connecting anything.

Read the complete firmware disclaimer

Leggere prima del download: l’installazione del firmware modifica il contenuto della memoria flash della scheda. Verifica che l’immagine scelta corrisponda al tuo hardware e leggi il disclaimer firmware riportato più avanti.

Firmware ESP8266

File binario Pocket FORTH precompilato per schede ESP8266 compatibili.

Scarica ESP8266 .bin

Firmware ESP32

File binario Pocket FORTH precompilato per schede ESP32 compatibili.

Scarica ESP32 .bin

Parole hardware

Parola	Effetto stack / significato
`PINMODE`	`pin modalità --`
`DIGITAL!`	`valore pin --`, scrive un’uscita digitale
`DIGITAL@`	`pin -- valore`, legge un ingresso digitale
`PWM!`	`duty pin --`, imposta un’uscita PWM
`ANALOG@`	`pin -- valore`, legge un ingresso analogico dove supportato
`MS`	`millisecondi --`, introduce un ritardo
`MILLIS MICROS`	restituiscono il tempo trascorso dall’avvio

: BLINK
  2 OUTPUT PINMODE
  5 0 DO
    LOW 2 DIGITAL!
    500 MS
    HIGH 2 DIGITAL!
    500 MS
  LOOP
;

La numerazione dei pin, il comportamento attivo alto o attivo basso, gli ingressi analogici e i livelli di tensione sicuri cambiano da una scheda all’altra. Consulta la documentazione del tuo modello prima di collegare qualunque circuito.

Leggi il disclaimer firmware completo

Examples

Small programs you can type, save as .4th, export or convert to QR code from the app.

Piccoli programmi da digitare, salvare come .4th, esportare o trasformare in QR code dall'app.

1

Square / Quadrato — first custom word

Defines SQUARE, duplicates the number and multiplies it.

FORTH Code

\ PROGRAMMA QUADRATO
: SQUARE DUP * ;
9 SQUARE .

2

Integer square root / Radice intera — Newton method

Pocket FORTH currently uses integers, so this version adapts the pseudocode to an integer Newton iteration and stops when the improvement is 1 or less.

FORTH Code

\ RADICE QUADRATA INTERA CON METODO DI NEWTON
\ funzione radice(N): m=N/2; ripeti m=(m+N/m)/2

VARIABLE N
VARIABLE M
VARIABLE D

: RADICE ( n -- m )
  DUP 2 < IF EXIT THEN
  N !
  N @ 2/ M !
  BEGIN
    N @ M @ / M @ - ABS D !
    M @ N @ M @ / + 2/ M !
    D @ 1 > 0=
  UNTIL
  M @
;

81 RADICE .

3

Fibonacci — variables, DO LOOP, stack operations

Small program for Fibonacci sequence, with ASSEGNA defined before MAIN for VARIABLEs settings.

FORTH Code

\ PROGRAMMA FIBONACCI
\ BLOCCO DEFINIZIONI
VARIABLE START ( INIZIO SEQUENZA )
VARIABLE END   ( FINE SEQUENZA )

: ASSEGNA
  10 END !
  0 START !
;

\ BLOCCO MAIN
: MAIN
  ASSEGNA
  0 1       \ PRIMI DUE NUMERI DELLA SEQUENZA
  END @ START @ DO
    OVER .
    TUCK +
  LOOP
  2DROP
;

MAIN

Disclaimer

Pocket FORTH is intended for learning, experimentation and hobby use. Software and firmware are provided “as is”, without warranties.

Firmware and hardware warning
Downloading, installing or using Pocket FORTH firmware is entirely at the user’s own risk.

The author makes no warranty, express or implied, regarding compatibility, fitness for a particular purpose, reliability or safety. The author shall not be held liable for any direct or indirect damage, including damage to microcontrollers, development boards, computers, connected electronics, peripherals, power supplies or other equipment; loss or corruption of data; interruption of service; financial loss; or personal injury arising from installation, connection, configuration or use of the firmware.

The user is solely responsible for selecting the correct binary, flashing method, board configuration, pin mapping, voltage level, power supply and any connected circuit. Incorrect firmware, wiring or electrical levels may permanently damage hardware or create unsafe conditions.

Pocket FORTH is not certified and must not be used in safety-critical, medical, automotive, industrial control, security, life-support or other mission-critical systems. By downloading or using a firmware image, the user acknowledges and accepts these conditions and assumes full responsibility for all consequences.

Privacy

Pocket FORTH programs are stored locally on your device unless you explicitly export or share them. QR and file sharing are user-initiated actions.

Email: support@pocketbasic.it

Pocket FORTH

Pocket FORTH

Think in stacks

Pensa a stack

Build your language

Costruisci il tuo linguaggio

Documentation

Documentazione

Introduction

Stack and arithmetic

Stack manipulation

Definitions and comments

Variables, constants and memory

Control flow

Comparison and logic

Output and strings

System commands

Limits

Timing and compatibility

Sharing and persistence

Introduzione

Stack e aritmetica

Manipolazione stack

Definizioni e commenti

Variabili, costanti e memoria

Controllo del flusso

Confronti e logica

Output e stringhe

Comandi di sistema

Limiti

Temporizzazione e compatibilità

Condivisione e persistenza

Remote Terminal

Terminale remoto

Connection

Remote controls

Collegamento

Comandi remoti

Embedded Firmware

Firmware embedded

ESP8266 firmware

ESP32 firmware

Hardware words

Firmware ESP8266

Firmware ESP32

Parole hardware

Examples

Esempi

Disclaimer

Privacy