Developing and deploying Punyforth applications (obsolete)

**This tutorial is only applicable to Punyforth version <=0.5. **

A simple blinker application

In this tutorial we're going to develop a simple Punyforth appication that will blink a led.

Open a text editor and enter the following program.

( This is a simple Punyforth application that blinks a LED )

\ This constant defines the GPIO pin that is attached to a LED
13 constant: LED \ D7 leg on a nodemcu devboard

\ Let's define a new word that will blink the LED 10 times
: start-blinking ( -- )
    println: 'Starting blinking LED'
    LED 10 times-blink
    println: 'Stopped blinking LED' ;

\ execute the previously defined word
start-blinking

Save the file as blinker.forth.

Generating uber.forth

$ cd arch/esp8266/bin
$ python modules.py --app blinker.forth core gpio

This will generate a file uber.forth that contains our blinker program with all of its dependencies (gpio, core). This file is terminated with a zero character that will help Punyforth to detect the end of the code.

The above command should give you a similar output.

Chosen modules ['core', 'gpio']. App: blinker.forth. Block format: False
Analyzing dependencies..
Modules with dependencies: ['core', 'gpio']
uber.forth ready. Use flash <COMPORT> to install

Flashing uber.forth and Punyforth to the esp8266

After the uber.forth is generated we can flash the esp8266.

./flash.sh /dev/ttyUSB4

This will store the uber.forth into the flash memory of the esp. After you restarted the esp Punyforth will read code from the flash and run it. The code is compiled into the memory of the esp.

You should see the led blinking 10 times. If you attach a serial terminal to the esp, you'll be able to invoke the start-blinking again, and see the printouts.

Terminal settings

Use these settings for CoolTerm (Cross-platform with GUI) or Termite (Windows with GUI):

Baud rate: 115200 bps. 
Local echo: on
Line mode: enabled

Picocom (command line terminal) should work too with these settings:

picocom /dev/ttyUSB4 -b 115200 --omap crlf --echo --imap delbs

Although I recommend using either Termite or CoolTerm because picocom sends characters over as you type them in so you cannot use backspace to correct typos.

Sending files without persistently storing in flash

If you just want to send some code without storing it in the flash memory of the esp, you can use the following command (or you can use your favorite serial terminal application with file upload support).

cat file.forth > /dev/ttyUSB4

This will send the content of file.forth to the given serial port. But first run the above picocom command to have the port configured in the appropriate way.

For example

Open picocom in a terminal window.

picocom /dev/ttyUSB4 -b 115200 --omap crlf --echo --imap delbs

Execute the following in a different terminal window.

echo ": hello ( -- ) println: 'Hello World' ;" > hello.forth
cat hello.forth > /dev/ttyUSB4

Now if you type hello in picocom, you should see the 'Hello World' message.

If you restart or crash the esp and try to call the hello world again, you'll get an undefined word error.

Using markers to forget words

Because of the Forth Hyper Static Global Environment a redefinition of a word won't remove the pervious version of the word.

: myword println: 'ver1' ;
freemem . cr \ prints out the available dictionary space

: myword println: 'ver2' ;
freemem . cr \ the available dictionary space is smaller than before

: myword println: 'ver3' ;
freemem . cr \ the available dictionary space is smaller than before

If you don't want to run out of memory during development, you'll need to learn about the marker: word. This word creates a restorable checkpoint.

To be more precise, the marker: word creates a new word whose execution semantics are to remove itself and everything defined after it.

\ print out available dictionary space
freemem . cr

\ create a marker whose name is -checkpoint
marker: -checkpoint

\ this definition will consume some of the dictionary space
: hello println: 'hello world' ; 
hello
freemem . cr \ dictionary space is less than before

\ Forget every definitions that were made after the marker (including the marker)
-checkpoint  

hello \ hello is no longer defined
freemem . cr \ available dictionary space is same as before

If you keep sending code during development put this 2 lines in the beginning of the file to avoid running out of memory.

-checkpoint
marker: -checkpoint