To load the zeptoforth image (whether just the kernel or an image including precompiled Forth code) onto an STM32L476, STM32F407, or STM32F746 DISCOVERY board or STM32F411 "Black Pill", first install st-flash, then attach the DISCOVERY board to one's PC via USB and execute:

$ st-flash erase
$ st-flash write <location of the zeptoforth image> 0x08000000
$ st-flash reset

Note the address referred to above. This will also reboot the board.

To load the zeptoforth image (whether just the kernel or an image including precompiled Forth code) onto an RP2040-based board, hold down the BOOTSEL button while connecting the board to one's computer via USB. This will result in a USB Mass Storage device appearing in one's /dev directory, and if supported by one's system, automatically mounted. Then one can copy the appropriate UF2 file to the USB Mass Storage device, which will automatically cause it to be loaded into flash and then executed.

Prebuilt binaries are in bin/<version>/<platform>/.

<Location of the zeptoforth image> is either:

• a freshly built zeptoforth.<platform>.{bin, uf2} file in the root directory of zeptoforth
• zeptoforth_kernel-<version>.{bin, uf2} (without precompiled Forth code)
• zeptoforth_<type>-<version>.{bin, uf2} (with full precompiled Forth code)

where <type> is one of:

• full (full functionality compiled in except for USB or swdcom support with a cornerstone* to enable resetting functionality back to "factory" settings)
• full_usb (full functionaly compiled in including USB CDC console support with a cornerstone* to enable resetting functionality back to "factory" settings)
• full_swdcom (full functionality compiled in including swdcom support with a cornerstone* to enable resetting functionality back to "factory" settings)
• mini (i.e. without fixed number, allocator, scheduler, or disassembler support, without swdcom support)
• mini_swdcom (i.e. without fixed number, allocator, scheduler, or disassembler support, including swdcom support)

and where <platform> is one of

• stm32f407
• stm32f746
• stm32l476
• stm32f411
• rp2040 (allocates 1024 KB of flash to code and 1024 KB of flash to blocks)
• rp2040_big (allocates 1536 KB of flash to code an 512 KB of flash to blocks, highly recommend if one is to use zeptoIP)

Note that for the rp2040 and rp2040_big platforms, to load code with the bootloader onto a RP2040-based board one needs a .uf2 file rather than a .bin file, unlike the other platforms, which will be located in the same location. Note that these files contain a boot block with a CRC32 checksum. Note that the rp2040 and rp2040_big platforms do not have the full_swdcom or mini_swdcom builds as swdcom does not properly function on this platform.

* No cornerstone is present on the stm32f411 platform because if there were one, it would exhaust all the remaining flash available. Consequently, cornerstone cannot be used on stm32f411 full or full_swdcom builds.

To build the kernel for each of the supported platforms, one first needs to install the gas and binutils arm-none-eabi toolchain along with Python 3.9 or later, and then execute:

$ make

to use the default version or:

$ make VERSION=<version>

This build a zeptoforth.<platform>.bin, a zeptoforth.<platform>.ihex, and a zeptoforth.<platform>.elf file for each supported platform. Additionally a zeptoforth.rp2040.uf2 file will be built for the rp2040 platform. The zeptoforth.<platform>.elf file is of use if one wishes to do source debugging with gdb of the zeptoforth kernel, otherwise disregard it.

The most recommended approach of using zeptoforth is to use zeptocom.js, a web serial terminal designed for Forth and for zeptoforth in particular which uses the Web Serial API and may be used under Chrome or Chromium, which have been tested to work under Linux and Windows (but Chromium has been reported to have issues connecting via serial on FreeBSD). zeptocom.js provides a full-fledged environment to interact with zeptoforth with, with seamless support for mass code uploads, error detection, multiple edit tabs, multiple terminal tabs, source file includes, symbol replacement, REPL history, and history completion.

One may also use typical terminal emulators to interact with zeptoforth aside from using zeptocom.js. On Linux, on may download and install e4thcom, swdcom, GNU Screen, or picocom, To use the board on xBSD, the same applies, except that e4thcom does not work under xBSD. To use the board on Windows, one may download and install TeraTerm. Note that of all these, only e4thcom and swdcom provide flow control when doing mass code uploads.

When using zeptocom.js or some other serial terminal emulator with zeptoforth (note that swdcom is not a serial terminal emulator per se) with the STM32F407 DISCOVERY, STM32F411 "Black Pill", and Raspberry Pi Pico boards, the following applies: Attach a USB-to-serial converter to your machine and make sure you have the proper permissions to access its device file. For the STM32F407 DISCOVERY or the STM32F411 "Black Pill" board, connect the RXD pin on the converter to PA2 on the board and the TXD pin on the converter to PA3 on the board. For the Raspberry Pi Pico, connect the RXD pin on the converter to GPIO0 (pin 1) on the board and the TXD pin on the converter to GPIO1 (pin 2) on the board. When using the STM32F746 or STM32L476 DISCOVERY boards, a USB serial device is provided simply by connecting a serial cable between the board at one's computer.

If one is using e4thcom, after having installed it, from the zeptoforth base directory execute:

$ e4thcom -t noforth -b B115200 -d <device, typically one of ttyACM0 or ttyUSB0>

If one is using a bare kernel image, to install a complete system, after one has connected with one's board with zeptocom.js or e4thcom, execute (including the leading '#'), for the STM32L476 DISCOVERY:

#include src/stm32l476/forth/setup_<type>.fs

or, for the STM32F407 DISCOVERY:

#include src/stm32f407/forth/setup_<type>.fs

or, for the STM32F746 DISCOVERY:

#include src/stm32f746/forth/setup_<type>.fs

or, for the STM32F411 "Black Pill";

#include src/stm32f411/forth/setup_<type>.fs

or, for RP2040-based platforms:

#include src/rp2040/forth/setup_<type>.fs

or:

#include src/rp2040_big/forth/setup_<type>.fs

where <type> is one of the types given above, with the meanings given above.

This will load a complete zeptoforth installation onto the MCU. This code is that is included in the zeptoforth_<type>-<version>.bin images along with the kernel itself, and is unneeded (and indeed will not work) if one has installed a non-kernel build already. The last thing that is included for full builds is a "cornerstone" named restore-state which, when executed, as follows:

restore-state

erases everything compiled to Flash afterwards and then does a restart.

To do a restart by itself (which now does a full reset of the hardware), execute the following:

reboot

If one is using an ordinary serial terminal emulator, issuing Control-C, or if one is using zeptocom.js, clicking Reboot will result in a best-effort attempt to reboot zeptoforth even if the REPL is not active. Note that this is not guaranteed to work; if zeptoforth's state is sufficiently corrupted, this may not work. Also note that this will not work with a bare kernel install unless the console is polled. If one is using swdcom, Control-C will normally force zeptoforth to reboot unless the CPU is in a completely non-functional state.

Additionally, if one is using an ordinary serial terminal emulator or swdcom, issuing Control-T, or if one is using zeptocom.js, clicking Attention followed by typing z (if one is using zeptocom.js, one will have to follow this with Enter) will send an exception to the main task, which, if uncaught or re-raised, will return control to the REPL provided that the state is sufficiently functional. Likewise, this is not available with a bare kernel install.

If one has a full or full_swdcom installation, one may start the task monitor by issuing:

monitor::start-monitor

Once one has done this, if one is using an ordinary serial terminal emulator or swdcom, issuing Control-T, or if one is using zeptocom.js, clicking Attention followed by typing t (if one is using zeptocom.js, one will have to follow this with Enter) will dump information on each running task to the console.

One may use GNU Screen with zeptoforth. One must configure it to use 115200 baud, 8 data bits, 1 stop bit, and currently there is no support for flow control with GNU Screen. Note that zeptoforth uses ACK and NAK for flow control, with ACK indicating readiness to accept a new line of input, and NAK indicating an error; these are not supported by GNU Screen. As a result, one would have to use slowpaste 5 with screen to set a proper paste speed. (This is far slower than the ACK/NAK method used with e4thcom.) Additionally, as screen does not honor directives to load files automatically, one will need to use readbuf <path> and paste <path> to paste files into the terminal manually.

A better approach than using slowpaste, readbuf, and paste with screen is to use codeload3.py, which is in the utils directory and which honors the e4thcom directives, so it can be used with the included setup.fs files without modification. It is invoked as follows:

$ ./utils/codeload3.py [-p <device>] -B 115200 serial <Forth source file>

It has significantly better performance and functionality than screen with slowpaste and is the recommended method of code uploading if e4thcom is not available. Note that it requires Python 3 and pySerial, and it must be given executable permissions before it may be executed.

Another terminal emulator one may use is picocom, which has many of the same considerations here as GNU Screen. For this reason it is not recommended for mass code uploads, for which codeload3.py is a better choice, and rather is limited in practice to interactive usage.

If one is using swdcom (assuming one has already built it and installed swd2 in some suitable location such as /usr/local/bin and that one has already written the zeptoforth_swdcom-<version>.bin binary to the board), simply execute swd2. This will provide a terminal session with zeptoforth. To upload Forth code to execute to the board, execute in the directory from which swd2 was executed:

cat <path> > upload.fs && pkill -QUIT swd2

This will simply upload the given file to the board as-is without any support for #include or #require, unlike e4thcom.

Note that screen and e4thcom are not suitable for using the block editor on the STM32F746 DISCOVERY board or the Raspberry Pi Pico—attempting to use the block editor on them will lock up zeptoforth because it will wait forever for a response when querying the terminal for a cursor position—whereas picocom and swdcom enable it to be used. Also, to use the block editor one must have the backspace key set to $7F (DEL), as it is by default; remapping backspace to backspace will break deleting characters in the block editor

To build a complete image for zeptoforth, one uses utils/make_image.sh or, for the Raspberry Pi Pico, utils/make_uf2_image.sh after using make clean, make VERSION=<version>, and make install VERSION=<version> to install binaries for all platforms in the bin/<version>/<platform> directories (which it creates if they do not exist).

In the case of RP2040-based platforms one must then flash one's RP2040-based device with bin/<version>/<platform>/rp2040/zeptoforth_kernel-<version>.uf2 or bin/<version>/<platform>/rp2040_big/zeptoforth_kernel-<version>.uf2 using the USB Mass Storage device, for which one either presses the BOOTSEL button while power cycling the Raspberry Pi Pico, or, if one already had zeptoforth installed, one enters bootsel at the console, after which one mounts the USB Mass Storage device.

Afterwards, one executes:

utils/make_image.sh <version> <platform> <TTY device> <build>

which will build bin/<version>/<platform>/zeptoforth_<build>-<version>.bin and the associated .ihex file, or for RP2040-based devices, one executes:

utils/make_uf2_image.sh <version> <platform> <TTY device> <build>

which will build bin/<version>/<platform>/zeptoforth_<build>-<version>.uf2 and the associated .ihex and .bin files. Note that utils/make_uf2_image.sh erases the contents of flash after it executes except for the zeptoforth kernel, as it is meant to be used with multiple different builds in a row; if one wants a particular build to be installed, execute bootsel at the console, mount the USB Mass Storage device, and the copies the desired build to the USB Mass Storage device.