eForth for cheap STM8S gadgets

The STM8FLASH installation instruction on GitHub are best described as "you know how to read a Makefile and learn from the error output, don't you?".

I now described the (simple) steps for installing and testing stm8flash with a bit more detail.

There are also updated instructions for resetting a read-protected STM8 µC (some manufacturers of STM8SF103F3P6 demo boards think it's wise to protect their "intellectual property" in "blinking LED algorithms" by setting the Flash protection option bits).

I asked Dr. H.C. Ting, the original author of eForth for the STM8S Discovery for permission to publish an improved eForth for the STM8S, which he kindly granted today!

I updated the copyright information in forth.asm, and README.md, I also added a LICENSE.md file to the repository.

If creating a self-contained Forth system for a tiny µC is akin to building a miniature clockwork, then writing the documentation is like machining the case: It has nothing to do with the intricate mechanics, but it's indispensable for using the clock. I just updated the Practical eForth Programming section in the Wiki on GitHub.

The W1209 is a very cheap control board with one analogue input, one relay output, and basic UI elements. It's sufficient for many SISO (single input single output) control, monitoring or timer applications.

The only problem is that the serial interface uses the same GPIO pin as the analog input. However, often it's sufficient to use the serial interface off-line (i.e. either the control application, or the diagnostics).

The following small program demonstrates such a use case:

( W1209 measures U with Q12.4 LPF U = adc + U - U/16 )

FILE NVM

: adc   ( -- n ) 6 ADC! ADC@ 7 ADC! ;
: U   ( -- a ) 0 ;
: lpf   ( n -- n ) U @ DUP 16 / - + DUP U ! ;      

: measure   ( -- ) adc lpf 16 / . ;

: start   ( -- )
   0 U !
   [ ' measure ] LITERAL BG !
   BEGIN
     ?KEY IF 13 = ELSE 0 THEN
   UNTIL
   0 BG ! ;
 
' start 'BOOT !

RAM HAND

The word adc reads ADC6 (and switches then to the non existent ADC7 to free up RxD), U, a symbol for address 0 in the scratch-pad RAM, is the state variable of the LPF (a Q12.4 fractional number, i.e. fixed point arithmetics), lpf is a 1st order low-pass-filter with k=1.0625. The word measure samples the ADC, applies the LPF, scales fixed point to integer, and displays the result (in background on the 7S-LED display).

The initialization part in start first resets the LPF state variable U, then sets measure as the background task. All the foreground task has to do now is checking if ASCII CR (13) appears on the serial port, which indicates that the sensor has been exchanged by a serial terminal. It exits the loop, stops the background task, and drops to the Forth prompt.

Finally, the phrase ' start 'BOOT ! sets the word start as the initialization routine, and RAM for stores the Flash dictionary pointers to Flash.

Instead of just displaying the low-pass-filtered ADC value on the 7S-LED display, by using this simple pattern other features can be implemented easily on the W1209.

In the GitHub Wiki I added a new page on Practical STM8S eForth Programming.

All you need is your favorite serial terminal program, and a text editor on your host (I now use picocom and ascii-xfr allong with gVim).

FILE
( lines 
  with code and instructions
  here )
HAND

Edit: there is a new word RESET for resetting the NVM contents to default (startup, dictionary etc). I also reduced the memory footprint of CORE to 4620 bytes. A full featured MINDEV binary uses 5360 bytes (incl. background task and compile to Flash), and a W1209 binary requires 5699 bytes incl. 7S-LED, keys, and half-duplex serial interface.

A bug in the handling of the HLD pointer into PAD in the context switch to the background task under certain circumstances caused RAM corruption. The bug also simplifies the code a bit.

I now assume that a numeric output is always complete at the end of a background task run.

GitHub and files here are up to date.

XON/XOFF is on ice. I decided to implement a FILE mode with a PACE character for performing a handshake with an uploader. Until I have a matching uploader, I'm using picocom with ascii-xfr (borrowed from minicom) with a long delay at the end of each line.

STM8EF is now very close to a self-contained development environment, and it's at the point of being an MVP (Minimal Viable Product).

The files on GitHub are up-to-date :-)

I've been adding XON/OFF (or rather vice versa) to STM8EF. In theory it should work like this:

After receiving CR the eForth sends XOFF (0x13), the interpreter starts processing, some text followed by a LF gets written to the serial interface, and then XON (0x11) is sent to indicate that the next line can be received and processed.

In practice all the Linux terminals I tested are based on the termios layer which apparently doesn't stop transmission after receiving XOFF.

Edit2: I traced the problem through picoterm, stty/termios, line-discipline, and all the driver levels down to the device driver (e.g. 8250, or CH341). The short version is that there is no such thing as "flow control" in any USB-serial adapter based on USB-serial. The long version is here in the 5th post.

I'm at it. Stay tuned :-)

Compile to Flash did work in the last release, but using CREATE or "," in NVM didn't. I had to fix the code in a number of places. 6 bytes longer now, but it works ;-)

Issue #6 on GitHub explains the details. The binaries here in the project are already up-to-date.

I just released the Compile to Flash feature. I tried to stick to the original design of eForth as much as possible, but maintaining two vocabularies, one in Flash, and one in RAM is a bit challenging. The way I implemented it it's now possible to change between the modes RAM and NVM (Non Volatile Memory) back and forth, while linking new words to the right space in the vocabulary, and preventing words from volatile RAM to be referenced by non-volatile words (words in RAM are always available in interactive mode, though).

Let me give you a walk-through:

after flashing the MINDEV binary to a $0.70 board you'll get a clean vocabulary. Then we change to NVM mode, define a new greeting word, set it as the boot word, and restart.

NVM ok
: mystart CR 3 FOR I . NEXT CR ." Hi!" CR ; ok
' mystart 'BOOT ! ok
RAM ok
COLD
 3 2 1 0
Hi!

NVM unlocks the Flash memory, and the core words CONTEXT, CP, and OVERT do some magic in the background to keep the vocabularies in good order. RAM locks the Flash memory and makes the pointers LAST and CP persistent. After defining the simple startup word mystart, ' (tick) retrieves its address, 'BOOT gets the address of the startup word pointer, and ! stores the address of our word to it.

Setting a startup word is also a good way for first initializing an application, and then starting the background control task. Here is a very simple example, that shows a running counter on the 3 digit 7S-LED display of a W1209:

NVM ok
: bg TIM . ; ok
: start [ ' bg ] LITERAL BG ! ; ok
' start 'BOOT ! ok
RAM ok

Here is how this looks like: