eForth for cheap STM8S gadgets

nRF24L01+ modules are ubiquitous, and cheap (very cheap: from $0.32/module!).

@richard started a distributed sensor project, and provided STM8 eForth code for the nRF24L01+. I joined the effort. My development target is a "tiered approach" to STM8 eForth applications, and of course I always wanted to have a cheap "sensor mesh network".

The tiered approach takes advantage of the STM8 eForth binary distribution (with Travis-CI), and it adds a middle layer for creating a "platform" image (e.g. STM8 eForth with nRF24L01+ library code) which is the basis for applications (e.g. a sensor node, or a base station). The approach takes full advantage of e4thcom, but writing application code a simple terminal program (e.g. under Windows) can be used.

Another thing we want to test, is distributing "operational code" through the mesh network. That's a use case for the EVALUATE feature introduced in the last STM8 eForth release.

So the tiers can be:

1. STM8S eForth image
2. Platform image
3. Application image
4. Operation code

The operation code can, in fact, modify the application code in operation by transferring bits of source code, and it's always possible to fall back to the next lower tier.

I ordered an XH-M194 board  about half a year ago, and it remained shelfed for about 5 months. A GitHub user finally nudged me into writing board support code.

The the guy who designed the board missed many opportunities, and it took me a while to decide how to implement the serial interface for the Forth console. The board offers a lot of outputs, more keys than most boards, and an RTC, but unfortunately no inputs.

The controller, an STM8S105S4T6, is an STM8S medium density device with 2K RAM, 1K EEPROM and 16K Flash. The medium density device I tested all had 32K Flash, and it's quite possible that you won't find a chip with no more than the advertised amount of memory.

The HaD effect: people come with use-cases ans ideas, a creative exchange starts, and innovation takes place. In this project, this happened a lot.

Recently @Richard needed a feature that I thought not to be possible with a µC as limited as a Low Density STM8S: the Forth interpreter should be running concurrent to the console!

It turned to be that complicated: now an idle task, similar to the background task (but only running while the console is idle) provides some kind of non-preemptive multitasking with a limited context switch (i.e. the interpreter state is preserved).

Consider the following example:

#require EVALUATE

: test $" 2 7 +" COUNT ;
test EVALUATE . 9 ok

EVALUATE relies on minuscule change in the STM8 eForth core: the address of the Terminal Input Buffer (TIB) is now a pointer, 12 bytes more code. The rest of the feature is optional Forth code.

IDLE was even more simple: only 5 bytes more assembly were needed in KEY to make it work.

Consider the following code running on STM8eForth 2.2.22:

#require 'IDLE
VARIABLE TALLY
: t TALLY @ 1+ DUP TALLY ! $F000 AND 0= OUT! ;
' t 'IDLE !

This flashes about 34 times per minute (unless the console has something better to do). One IDLE loop thus takes about 34s/(60*65536) = 8.65µs.

I think that the 17 bytes in the core were well spent.

The low-cost STM8S Low Densitity devices don't have a lot of Flash (8K) and RAM (1K), but they have a surprisingly generous amount of EEPROM (640 Bytes). Ok, officially, the Value Line devices only have 128 Bytes EEPROM, but in practice the Value Line STM8S003F3 devices I tested all behaved like an Acces Line STM8S103F3.

It's tempting to use the Flash Memory for storing code, but it turns out that jumping to an EEPROM address causes a reset!

I now found a way to use EEPROM as a substitute for Flash memory: the ALIAS feature of STM8 eForth allows for splitting the Forth Dictionary from the code, and since an ALIAS is not executed but merrily interpreted it doen't matter where it's stored.

For testing I stripped many dictionary entries from the CORE image for STM8S Low Density devices, and replaced them with ALIAS.

Here is the result:

WORDS
  RAM NVM WORDS .S DUMP IMMEDIATE VARIABLE CONSTANT CREATE ] : ; OVERT ." REPEAT WHILE BEGIN LITERAL C, , ' CR [ \ ( .( ? . U. KEY HEX HERE +! 0= ABS NOT 1+ 1- 2+ 2- 2* 2/ */ M* * / /MOD M/MOD UM/MOD < U< = ROT - 0< OR AND XOR + UM+ I OVER SWAP DUP DROP NIP >R R@ R> C! C@ ! @ 2@ 2! COLD 'BOOT U.R UNTIL UM* TYPE TX! THEN SPACE SIGN SAVEC #S ?RX RESET QUIT QUERY PICK PARSE PAD NEXT NEGATE NAME? NAME> MIN MAX ?KEY IRET IF HOLD FOR FILL EXTRACT EXIT EXECUTE EVAL EMIT ?DUP DOXCODE DNEGATE DIGIT DEPTH DECIMAL COUNT COMPILE? [COMPILE] COMPILE CMOVE CALL, BL ALLOT AHEAD AGAIN AFT ACCEPT ABORT 2DUP 2DROP #> # $" <#  ok
NVM $A000 HERE - . 4461 ok

Since more than half of the dictionary is stored in EEPROM (in bold text), a binary size of just 3731 Bytes offers a rich vocabulary!

It's simple to use, too:

\ EEPROM MODE:
\ * define ALIAS words in the EEPROM, 
\ * abort if a normal compilation (non-ALIAS words) is attempted
\   note: the STM8 resets when executing plain compiled words from EEPROM!
\ * return to RAM MODE with EECLOSE when done
\ * remove ALIAS words in EEPROM from dictionary with EERESET

#include EEALIAS

\ load ALIAS words
#require SPACES
#require DIGIT
#require DNEGATE

\ done: return to normal, and WIPE RAM
EECLOSE

 Check out the code of EEALIAS here - comments are, as always, appreciated!

@RigTig : I guess that with this method a Forth not much larger than 3K is now possible. As I think about it, an interactive Forth for the STM8S103F2 (4K Flash) is now also possible - not very useful, but possible :-)

The German Forth Conference is one of the better known venues in the international Forth scene. It will take place from 5 to 8 April 2018 in the Linuxhotel in Essen-Horst. The list of talks is here.

Manfred Mahlow will talk about WORDLIST, a name-space-like approach in Forth, and demonstrate it with two µC Forth implementations, one of which, I've heard, might be STM8 eForth (at least, it's part of the STM8 eForth release 2.2.21).

In a second talk, Manfred Mahlow will introduce STM8 eForth as a "semi-tethered" Forth, one that combines an embedded console with PC-side code. If you've followed this project on HaD, the idea should be familiar.

Edit: video recordings of the talks are here.

The new release STM8 eForth 2.2.21 brings so many new features, improvements, and also bug-fixes, that it would be exceedingly boring to name them all. Some stuff is actually quite interesting :-)

By the way, yesterday I started working on 2.2.22,pre, and the first preview already contains experimental support for STM8S High Density devices. STM8 eForth now runs on a chip with 6K RAM and 128K flash memory (remember that STM8 eForth works quite well on chips with 1K RAM and 8K flash). Only the lower 32K portion is directly usable for compiled Forth code but, given the density of Forth code, that's a lot.

... and a bug fix: in one of the former STM8 eForth 2.2.21-pre-releases WORDS got broken. It didn't show the RAM dictionary when in NVM mode! This is now fixed.

A major improvement is the implementation of WIPE, something similar to COLD, but only targeting the dictionary in RAM. WIPE gets called during start-up, and besides resetting the dictionary, it creates a dummy word, that makes using MARKER much easier.

#require WIPE creates an ALIAS word, which, if loaded into RAM, will reinitialize the dictionary (and remove itself if it was loaded into RAM).

Compiling a word in RAM memory into a target in Flash memory will now abort compilation, throwing a "target?" error.

Due to some refactoring and optimization, the size of the STM8  eForth binaries stays the same!

Several people received more or less compatible W1209 clones from vendors:

• different PCB, fully compatible
• compatible but 5k and 10k instead of 20k Rsense
• common anode instead of common cathode 7S-LED-Display
• same PCB but Nuvoton N76E003AT20 (8051) instead of STM8S003F3P6

@richard helped raise the issue, and provided a Wiki entry that helps you telling clones apart. Unfortunately vendors don't always show the variant you receive.

If you get one of the compatible clones you're lucky, and also the resistor variants are easy to deal with. Fortunately Zoltan documented the common anode variants, and provided the board configuration W1209-CA.

If you get a W1209 with a Nuvoton chip the only thing you can do is replace the µC, and call the vendor names, of course.

M. Mahlow reported what appears to be an old STM8 eForth bug:

    1 PICK equals DUP

The correct behavior is:

    0 PICK equals DUP
    1 PICK equals OVER

Note: the correction is a braking change!

Fact is that in STM8 eForth PICK never worked as it should. The core uses PICK only once (in .S), and there 1+ was applied just before calling PICK (with a different indentation). Of course, PICK could have been fixed instead of "fixing" a routine using it.

In STM8 eForth 3 library functions had to be fixed ( @inter, 2OVER, and DSQRT). Hopefully not too much user code depends on the buggy PICK behavior.

I gave up on STM8L101 devices for the time being. According to [RM0013 Reference manual STM8L001xx and STM8L101xx microcontroller families, table 6, footnote 3](http://www.st.com/content/ccc/resource/technical/document/reference_manual/73/41/6f/b1/fd/45/4e/18/CD00184503.pdf/files/CD00184503.pdf/jcr:content/translations/en.CD00184503.pdf) STM8L10x devices must be reset after a Flash unlock/lock activity:

```
The Flash program memory is write protected (locked) until the correct MASS key is written in the FLASH_PUKR. It is possible to lock the memory again by resetting the PUL bit in the FLASH_IAPSR register. Unlocking can only be done once between two resets.
```

Fact is that STM8FLASH doesn't work with STM8L101 devices (e.g. STM8L001). I did quite some research, and traced the interactions between the ST-LINK V2 dongle and STM8FLASH. I also filed an STM8FLASH issue on GitHub, but I didn't get any response from the author or the community. I even checked the flash IAP routines in ST's STM8L library (there aren't any). The STM8L05x family enjoys much better support!