eForth for cheap STM8S gadgets

The new STM8L001J3 sample, and no luck with STM8FLASH

Yesterday I received a sample of the STM8L001J3, a package variant of the STM8L101F3 with STM8L core, 8KiB Flash, and 1.5KiB RAM. I quickly extended STM8 eForth to cover also that STM8 sub-family (the configuration is still largely based on STM8L051F3).

Unfortunately, when I tried to flash it with vdudouyt/stm8flash I had no success. Flashing that device turned out to be impossible. Accessing the option bytes worked. Then tried to use the latest version of stm8flash (which didn't compile - I used the binary in the repository) the result was the same (in fact, the device ID had already been added to the tool, and I didn't even have to recur to using the STM8L101x3 configuration).

I started to dig deeper: stm8flash doesn't cluster technical information about STM8 variants into family and density. It simply uses the marketing name, and leaves QA to the user. That's not the way I would do it. 

Gathering Information about the Silicon

ST provides a tool STM8CubeMX. It's essential features serve the use cases of interactively exploring configuration constraints of various STM8 devices based on packaging (including shared pins for a group of GPIOs, e.g. STM8S001J3, STM8L001J3, and STM8L050J3). Data about the variants is stored in xml files in the folder db/mcu. Each file contains an element <Die> which gives insight into the produced silicon for each marketed variant.

The following script was used to get initial insight:

gawk '/<Die>/ { split($1,a,/[<>]/); die=a[3]; split(FILENAME,b,"."); device=b[1]; variants[die]=variants[die] "," device } END {for (d in variants) {print d, variants[d]}}' *xml|sort|gawk 'BEGIN {print "Die|Devices"; print "-|-"} {p=$1 "|"; split($2,variants,","); for (v in variants) {p= p variants[v] ", "}; print p}'

This results in the output below, which aligns nicely with what I already know about STM8 variants into family and density. I'll now check whether it's feasible to improve STM8FLASH. I also ordered some STM8L101F3 chips, just in case success with programming the STM8L001J3 depends on using the NRST pin.

DIE758
STM8L151C2Tx, STM8L151C3Tx, STM8L151F2Px, STM8L151F2Ux, STM8L151F3Px, STM8L151F3Ux, STM8L151G2Ux, STM8L151G3Ux, STM8L151K2Ux, STM8L151K3Ux, , STM8L050J3Mx, STM8L051F3Px,

DIE761
STM8L101F2Px, STM8L101F2UxA, STM8L101F2Ux, STM8L101F3Px, STM8L101F3UxA, STM8L101F3Ux, STM8L101G2UxA, STM8L101G2Ux, STM8L101G3UxA, STM8L101G3Ux, STM8L101K3Tx, , STM8L101K3Ux, STM8L001J3Mx, STM8L101F1UxA,

DIE764
STM8L152C6Tx, STM8L151C4Ux, STM8L152C6Ux, STM8L151C6Tx, STM8L152K4Tx, STM8L151C6Ux, STM8L151G4Ux, STM8L151G4Yx, STM8L151G6Ux, STM8L151G6Yx, STM8L152K4Ux, STM8L151K4Tx, STM8L152K6Tx, STM8L151K4Ux, STM8L152K6Ux, STM8L151K6Tx, STM8L151K6Ux, , STM8L152C4Tx, STM8L052C6Tx, STM8L152C4Ux, STM8L151C4Tx,

DIE765
STM8S208C8Tx, STM8S207C8Tx, STM8S208CBTx, STM8S207CBTx, STM8S208MBTx, STM8S207K6Tx, STM8S207K8Tx, STM8S207M8Tx, STM8S207MBTx, STM8S207R6Tx, STM8S208R6Tx, STM8S207R8Tx, STM8S208R8Tx, STM8S207RBTx, STM8S208RBTx, STM8S207S6Tx, STM8S208S6Tx, STM8S207S8Tx, , STM8S208S8Tx, STM8S207SBTx, STM8S007C8Tx, STM8S208SBTx, STM8S208C6Tx, STM8S207C6Tx,

DIE766
STM8S105C4Tx, STM8S105C6Tx, STM8S105K4Bx, STM8S105K4Tx, STM8S105K4Ux, STM8S105K6Bx, STM8S105K6Tx, STM8S105K6Ux, STM8S105S4Tx, STM8S105S6Tx, , STM8S005C6Tx, STM8S005K6Tx,

DIE767
STM8S903F3Ux, STM8S003F3Ux, STM8S903K3Bx, STM8S003K3Tx, STM8S903K3Tx, STM8S103F2Mx, STM8S103F2Px, STM8S103F2Ux, STM8S103F3Mx, STM8S103F3Px, STM8S903K3Ux, STM8S103F3Ux, STM8S103K3Bx, STM8S103K3Tx, STM8S103K3Ux, , STM8S903F3Mx, STM8S001J3Mx, STM8S903F3Px, STM8S003F3Px,

DIE768
STM8L151C8Ux, STM8L151M8Tx, STM8L151R6Tx, STM8L151R8Tx, STM8L152C8Tx, STM8L152C8Ux, STM8L152K8Yx, STM8L152M8Tx, STM8L152R6Tx, STM8L152R8Tx, STM8L162M8Tx, , STM8L162R8Tx, STM8L052R8Tx, STM8L151C8Tx,

DIE79A
STM8AF62A8Tx, STM8AF5286Ux, STM8AF62A9Tx, STM8AF5288Tx, STM8AF62AATx, STM8AF5289Tx, STM8AF528ATx, STM8AF52A6Ux, STM8AF52A8Tx, STM8AF52A9Tx, STM8AF52AATx, STM8AF6286Tx, STM8AF6288Tx, STM8AF6289Tx, , STM8AF628ATx, STM8AF5268Tx, STM8AF62A6Ux, STM8AF5269Tx,

DIE79B
STM8AF6246Ux, STM8AF6248Tx, STM8AF6266ITx, STM8AF6266Tx, STM8AF6266Ux, STM8AF6268Tx, STM8AF6269Tx, , STM8AF6246ITx, STM8AF6246Tx,

DIE79H
STM8AL3146Tx, STM8AL3148Tx, STM8AL3166Tx, STM8AL3166Ux, STM8AL3168Tx, STM8AL3L46Tx, STM8AL3L48Tx, STM8AL3L66Tx, STM8AL3L68Tx, , STM8AL3136Tx, STM8AL3138Tx,

DIE79J
STM8AF6223PxAx, STM8AF6223Px, STM8AF6226Tx, STM8AF6226Ux, , STM8AF6213Px, STM8AF6223IPx,

DIE79K
STM8AL318ATx, STM8AL31E88Tx, STM8AL31E89Tx, STM8AL31E8ATx, STM8AL3L88Tx, STM8AL3L89Tx, STM8AL3L8ATx, STM8AL3LE88Tx, STM8AL3LE89Tx, STM8AL3LE8ATx, , STM8AL3188Tx, STM8AL3189Tx,

The release notes for the upcoming STM8 eForth 2.2.21 describes some goodies. Check it out!

I had ordered a couple of STM8L051F3P6 chips months ago, and soldered one of them to a breakout-board. I had thought that getting them to work with STM8 eForth would be a matter of minutes.

I was wrong.

What I didn't take into account is that the STM8L family is a complete remake of the STM8S. It comes with a new reference manual RM0031 (597 pages) and it's up to the user to compare it with the 462 pages of the STM8S manual to find the many breaking changes. Nice job, ST!

However, after creating new register symbol files and after understanding that GPIOs for peripherals have to be assigned in many cases, I had a STM8 eForth console running. Compiling Forth code to Flash also works. The background task requires some fixing (the interrupt vector of TIM2 has changed).

The STM8L family appears to have a much richer set of peripherals (DMA, 12bit ADC, RTC), much like an STM32 chip only with less memory, and a fraction of the CPU power. Of course, the STM32F030, which in small quantities costs about the same, is better in almost all parameters (except the minimum supply voltage).

EDIT: the interrupt vector issues are now fixed, and the STM8L051F3 configuration is ready to use.

Yesterday, after 3 pre-releases, I finally decided to released a STM8 eForth 2.2.20. The main reason was the release of the W1209 data logging thermostat, which required some minor fixes (especially one that was a workaround for a uCsim bug).

This said, the W1209 project showed that STM8 eForth is now very usable

With 482 SLOC (i.e. including library, without empty or comment lines) the thermostat code is a good deal more complex than my previous demo programs:

• sensor filtering and linearization
• a 2 level menu with editor, plausibility checks, and defaults
• a (simple) temperature controller, and
• a data logger for 4 controller signals with text output

The program fits in 2840 bytes which indicates that the code is rather dense (about 6 bytes/SLOC).

What's more, the Continuous Integration chain produces µC firmware binary files from the same Forth source code that can be written, and tested interactively. In my view, STM8 eForth is now ready for practical applications.

Mr. Mahlow, a senior Forth expert, already did a lot for turning the tiny STM8 eForth into a powerful programming tool by supporting it in his embedded Forth terminal e4thcom. Now he's porting the innovative "VOC context switch" (i.e. Forth a namespace extension) to STM8 eForth. An article on Forth namespaces in German is here.

The essence is that with namespaces working with libraries is much easier. For instance, he provided an I2C library that uses the VOC name I2C as a prefix (e.g. "I2C init", "I2C start"). It's also possible to list the words in that namespace with "I2C WORDS".

Some of the implementation details are still being worked on. Most likely it will be provided as a loadable extension to STM8 eForth.

Some time ago Manfred Mahlow, the author or e4thcom, and I discussed how to use the e4thcom #include and #require feature for building STM8 eForth applications with the help of a library. One of the challenges when writing an interactive Forth for a µC with relatively little memory is the space the dictionary occupies. Especially symbols for hardware registers consume a lot of memory even if they're only used once (e.g. for initializing a peripheral).

STM8 eForth solves this problem with temporary dictionary entries in RAM which can be removed after appropriate words for using the peripherals have been built.

Here is an example:

\ STM8 eForth interactive RC-servo demo

\ set compilation target for STARTTEMP /  ENDTEMP
: TARGET NVM ;

#require hw/pwm.fs
#require OPT!

#include STARTTEMP

\res MCU: STM8S103
\res export OPT2

TARGET

  \ set option bits to enable PC5 TIM1_CC1, and PC6 TIM1_CC2
  : OptInit ( -- )
    OPT2 DUP C@ $01 OR SWAP OPT!
  ;
  \ timer1 init to 1MHz clock and 20ms period
  : ServoInit ( -- )
    15 T1PwmInit
    20000 T1Reload
    \ init servos to 50%
    1500 PWM1  \ PC6 pin 16
    1500 PWM2  \ PC7 pin 17
    1500 PWM3  \ PC3 pin 13
  ;
ENDTEMP

 The STARTTEMP - TARGET - ENDTEMP structures Forth code into part that resolves dependencies or defines temporary words, and a TARGET part that contains the words that should remain in the dictionary. ENDTEMP finally removes temporary words from RAM. STARTTEMP uses the word MARKER which means that the dependencies can be nested.

Mr. Mahlow also published a new version of e4thcom 0.6.3 that has improved support for "resource files". These can now reside in a search path folder (e.g. the mcu folder). It's also possible to create an arbitrary search path with up to 3 directories.

Folder "target" used for board specific output

@RigTig came up with use cases for a tiny Forth that required some innovation. This led to the development of the ALIAS feature, which can be used as a secondary (or temporary) dictionary entry. Long story short: from STM8 eForth 2.2.19 on aliases for unlinked Forth words are automatically generated into the folder out/<BOARD>/target during the build process.

When writing applications, all that's needed is a symlink to the desired target folder.

There are more goodies:

Auto-generated file FORTH.efr for STM8 eForth core RAM locations

The RAM addresses of internal core variables like 'PROMPT are now exported automatically to the file out/<BOARD>/FORTH.efr.

FORTH.efr contains lines like the following:

0068 equ 'PROMPT \  "'PROMPT" point to prompt word (default .OK)

In e4thcom compatible code this data can be used with the `\res` meta-statement:

\res MCU: FORTH
\res export 'PROMPT

It is now a recommended for STM8 eForth projects that use a binary release to set a symlink in the base folder to out/<BOARD>/FORTH.efr.

Emulation of e4thcom \res improved

The emulation of \res in codeload.py now tests if a word already exists in the dictionary before defining a CONSTANT. The behavior is now as robust as that of #require.

By the way, using a Forth CONSTANT doesn't necessarily require any additional memory: STM8 eForth allows defining CONSTANT words in RAM, and using them for building words in the Flash memory. They create a normal LITERAL during compilation, and can be discarded afterwards.

Tools folder part of the binary release

The tools folder is now part of the binary release file. An STM8 eForth project that uses the binary release can simply use tools (e.g. codeload.py) from the upstream project.

And finally:

Eating my own Dogfood

TG9541/W1209 contains an example implementation with dependency resolution. I'll be concentrating on finishing that project, and learning about required features for STM8 eForth on the way.

There is a fresh release: STM8 eForth 2.2.18.

CONSTANT and \res

e4thcom has the \res MCU: - \res export feature which requires a CONSTANT with distinct compiler/interpreter behavior. Thanks to Mr. Manfred Mahlow for pointing this out, and for providing not only an implementation of CONSTANT, but also the initial version of the STM8S103.efr resource file (which has been extended since then).

MARKER instead of RAMMARK

Mr. Mahlow also contributed a very nice implementation of MARKER which brings the management of temporary vocabularies in RAM to a new level (according to Mr. Mahlow this is a unique STM8 eForth feature!). MARKER now replaces RAMMARK which had issues with the e4thcom #require feature. Thanks!

codeload.py for serial port and uCsim

codeload.py replaces loadserial.py and codeloadTCP.py. It emulates e4thcom!
Travis-CI was the first to use the new script.

It should work on Windows, too (but I don't know). If you test it I'd really like to hear from you!

Issue 98: Bug Fix Context Switch for Forth Interrupts

Issue #98 fixes a bad bug (so bad that I really don't understand why it worked initially).

Issue 68: Minor Version Number

Some guys will like this:

hi
STM8eForth 2.2.18
 ok

The use case for @RigTig 's script loadserial.py has been merged with an improved codeloadTCP.py. The new script codeload.py can be used for Forth code transfer and test automation (serial, telnet). It emulates most of the features of Manfred Mahlow's e4thcom (not the assembler, though), and it can also be used for making flat Forth files. (expansion of #include, #require, and \res with the tracefile feature).

Code transfer works with serial interface(2 or 3 wire), or telnet connection to uCsim. There is also a "dry run" mode which just dumps code to the console.

The script uses the Python argparse library, which results in a nice command line interface with a decent help function:

thomas@w500:~/source/stm8s/stm8ef$ tools/codeload.py -h
usage: codeload.py [-h] [-p port] [-t tracefile] [-q]
                   {serial,telnet,dryrun} [files [files ...]]
positional arguments:
  {serial,telnet,dryrun}
                        transfer method
  files                 name of one or more files to transfer
optional arguments:
  -h, --help            show this help message and exit
  -p port, --port port  PORT for transfer, default: /dev/ttyUSB0,
                        localhost:10000
  -t tracefile, --trace tracefile
                        write source code (with includes) to tracefile
  -q, --quiet           don't print status messages to stdout

The script assumes Python 2.7, and under Linux x86-64 it just works (desktop, and Travis-CI with Docker). I'm not a Python programmer, and sometimes I assume portability features similar to Java (which Python doesn't have).

It would be really nice if someone could review the script for portability, and test it under Windows. Please expect an issue, or two.

e4thcom not only supports include files but also Forth dictionary based requirements resolution. Consider the following code:

#require CONSTANT
#require MARKER
#require ]B!
MARKER RAM\
\res MCU: STM8S103
\res export PB_ODR
 NVM
  : LED.on ( -- )  [ 0 PB_ODR 5 ]B! ;
  : LED.off ( -- ) [ 1 PB_ODR 5 ]B! ;
 RAM
RAM\
\index  LED.off  LED.on

#require uses ' to test whether a word is in the dictionary. If it's not there (the error message remains hidden in the background) it looks in the e4thcom source search path for a file with the same name, loads, and compiles it. If the compilation was successful, it checks if the required word is there, and if not it even defines a dummy word to satisfy future tests. Cascaded includes are supported up to a nesting level of 16, and simply including a required word, or a "vocabulary" works well.

In the example above, the CONSTANT is already satisfied by the core (not loaded). MARKER, a feature for marking a part of the dictionary as temporary, and the static bit manipolation feature ( [ flag addr b# ]B! ), are loaded to RAM.

The named marker RAM\ allows for freeing up dictionary RAM (the STM8S003F3 has a total of 1024 bytes, and not much more than 500 bytes can be used as temporary dictionary). With the help of MARKER that's plenty!

The \res MCU: statement reads a resource definition file STM8S103.efr containing "<address> equ <symbol>" lines (and Forth comments). Definitions can then be exported one-by-one with the \res export statement to Forth CONSTANT definitions (CONSTANT compiles to LITERAL, so no additional runtime code is needed), and the words defined that way can be temporary.

e4thcom proviedes the \index statement for inserting strings into the command completion index. Typing LED<tab> finds LED.on, and then toggles between LED.on and LED.off.

The result of the above is two new words LED.on and LED.off with very compact machine code:

cold
stm8eForth v2.2
last @ 10 dump
92C6   7 4C 45 44 2E 6F 66 66 72 1A 50  5 81  0  0  0  _LED.offr_P_____ ok

The dump shows that the code above translates to a dictionary entry (e.g. LED.off) and the following assembly instructions:

LED.off:
        BSET    0x5005,#5
        RET

Most of the above was made possible by the work, and active help with integration into STM8 eForth, from Manfred Mahlow, Forther, and author of e4thcom! According to him, the flexible usage of RAM as a unique feature of this tiny Forth solution. The combination the ALIAS feature has the potential to get even more out of 20ct µCs without sacrificing interactive development ( @RigTig ).

However, all of the above now also works using the codeloadTCP.py, part of the uCsim based build automation framework of STM8 eForth!

The combination of a convenient interactive µC programming environment (e4thcom) with Continuous Integration (codeloadTCP.py, uCsim, Docker, Travis-CI) is a new approach.

One of the things I'm now is on how to bring lightweight dependency management to more STM8EF (I'm looking into NPM's package.json, supported by GitHub).