JeeLabs: A new serial tool: vive la Folie!

Working with embdded µC boards involves quite a few steps: apart from the hardware itself, you need to connect to it and figure out how to upload code, of course. But you also think about the development cycle and revision control. The list of tools needed to get going can grow quickly…

Not so with Forth. It’s all self-contained and self-hosted. The embedded µC does it all, it just needs to be sent the source code. The same applies to uploading the initial firmware image: all you need, is a way to send the proper bytes to the µC while it is in a special boot loader mode.

In the Arduino world, this is handled by anIDE, which combines an editing environment, a cross-compiler for the µC you’re using, the“avrdude” or “stlink” utilities to handle firmware uploads, and a built-in serial terminal for actually interacting with the code, once it’s running. The success of the Arduino is probably largely due to the fact that this all-in-one approach has been properly packaged as a single “app” which runs on Windows, Mac OSX, and Linux.

Could something similar be done in a Forth-based environment?

Yes, it sure can, but quite differently: meet the Forth LineEvaluator -Folie, in short!

Folie combines a number of functions into an installation-free (!), single-file (!) executable, and is available for Windows, Mac OSX, and Linux (both Intel and ARM):

• it’s a serial terminal to let you talk to the attached µC board
• there’s command history to re-use easily previous entries via up-arrow
• there’s a file include mechanism to send sources as if you had typed them in
• all lines sent are throttled to avoid over-running the Forth word parser

Here is a brief interactive session as example:

$ folie -p /dev/cu.usbserial-A8009L2N
Connected to: /dev/cu.usbserial-A8009L2N
  ok.
7 8 * . 56  ok.
\       >>> include a
1 2 + . 3  ok.
3 a 0 1 2  ok.
\       <<<<<<<<<<< a (3 lines)
\ done.
8 9 * . 72  ok.
^D
$

To clarify this further, here is what was typed in, literally:

<CR>
7 8 * .<CR>
include a<CR>
8 9 * .<CR><CTRL-D>

The contents of the “a” file is:

1 2 + .
: a 0 do i . loop ;
3 a

As you can see, it’s more or less just a line-by-line serial terminal, whereby each line is sent when you hit return (it can be edited locally until then). That and (nestable) include file expansion.

The line starting with “include” was not sent - the file’s contents was sent instead. Lines which generate no output will not echo back, only lines which cause some other effect will be shown. Which is why the “: a ...;” text does not show on the screen, but everything else does.

Folie is clearly not an IDE - it’s not even trying to be one. It only handles the communication with an attached µC running Mecrisp Forth. Folie is in fact intended to be usedalongside your own preferred editor. Once done editing, switch to Folie and enter “include somefile.fs” to apply the changes (or hit up-arrow plus return). With proper definitions at the beginning, this’ll replace or extend what was already loaded - you can even include commands to start things up.

That’s the whole Forth development cycle: edit, send changes, explore interactively, repeat…

One more thing: to get started, Mecrisp Forth needs to be uploaded and “flashed” onto the µC. Since Folie has support for the STM32F103 ROM boot loader, it can also be used for this step:

• set up the µC board to have the BOOT0 pin tied high, with the jumper in position “1”
• insert the USB interface and board to power it up
• launch Folie as follows: folie -p <comport> -u <firmware-file>

If all is well, you should see something like this:

$ folie -p /dev/cu.usbserial-A8009L2N -u mf224.hex
Connected to: /dev/cu.usbserial-A8009L2N
        File: mf224.hex
       Count: 15684 bytes (converted from Intel HEX)
    Checksum: 4e555979 hex
 Synchronise: .+ OK
 Boot loader: 22 hex
   Chip type: 0410 hex - STM32F1, performance, medium-density
   Unprotect: OK
      Resume: .+ OK
  Mass erase: OK
   Uploading: ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ OK
$

Now restore the BOOT0 jumper to its normal “0” setting, and press reset.

Note: as of this writing (end March 2016), uploading works on Mac OSX and Linux, but not on Windows (grrr!) - you will need to use another mechanism, see this article for some options.

The latest Folie binary releases can be foundhere. If you haveGo installed and properly set up, you can also build from source (onGitHub) using this magic incantation:

go install github.com/jeelabs/embello/tools/folie

Folie is a fairly small open source application, written in Go - it is still evolving quite rapidly at the moment, but everything should work as expected w.r.t. what has been described so far. A lot of its magic comes from the excellent chzyer/readline andtarm/serial packages it is based on.

The one remaining issue is: what firmware do we upload to the STM32F103?

If you’re really impatient, you can extract the latest“mecrisp-stellaris-stm32f103.hex” image from the Mecrisp release and get your feet wet in the world of Forth on ARM chips - or … check out the next article for a more complete image with RFM69 wireless radio support!