eForth for cheap STM8S gadgets

The free services for Open Source projects by Travis-CI.org were terminated last summer. Since I had a lot of things to do in other projects I didn't "immediately" realize it. Instead of migrating to Travis-CI.com it made much more sense to move on to GitHub Actions, which, of course, required a bit of space in my brain for different concepts yet to be learned. Plenty of reasons to wait a bit longer...

OK, finally I did that step. It turned out that using a Docker container (with tool chain and µC emulator based test environment) for building and testing an embedded Forth was a very good choice. It "survived" hundreds of deployments, several major host OS and tool chain upgrades and when changing the CI provider (from Travis-CI to GitHub Actions) it was the least of my concerns.

All it takes (really!) is to add an Action file to .github/workflows.  Building and testing STM8 eForth in a Docker container soon worked. The build steps for publishing binaries to GitHub Releases was a bit harder. Here is the result:

name: build-test
on: [push]
jobs:
  Build-Test-Release:
    runs-on: ubuntu-latest
    container: tg9541/docker-sdcc:V3.9.0
    steps:
      - run: |
          echo "triggered by: ${{ github.event_name }}"
          echo "repository:   ${{ github.repository }}"
          echo "branch name:  ${{ github.ref }}"
      - name: Check out repository code
        uses: actions/checkout@v2
      - name: Build and test
        run: |
          echo "; ##########################################" >> forth.asm
          echo "; # Release info added by GitHub action:"     >> forth.asm
          echo "; #   repository:   ${{ github.repository }}" >> forth.asm
          echo "; #   branch name:  ${{ github.ref }}"        >> forth.asm
          echo "; #   sha:   ${{ github.sha }}"               >> forth.asm
          echo "; ##########################################" >> forth.asm
          make BOARD=test forth
          make clean
          make all
          echo "Job status: ${{ job.status }}."
      - name: GH Release
        uses: softprops/action-gh-release@v0.1.14
        if: startsWith(github.ref, 'refs/tags/')
        with:
          files: |
            out/stm8ef-bin.zip
            out/stm8ef-bin.tgz
            out/stm8ef-rst.tgz
      - name: Keep non-release binaries
        uses: softprops/action-gh-release@v0.1.14
        if: (! startsWith(github.ref, 'refs/tags/'))
        with:
          tag_name: volatile
          files: |
            out/stm8ef-bin.zip
            out/stm8ef-bin.tgz
            out/stm8ef-rst.tgz

I decided to use the plugin "GH Release" from the "Actions Marketplace" for publishing binaries to GitHub Releases. It's well maintained and has a good set of features. After I realized that I can use the publish step from inside a Docker container, publishing the STM8 eForth 2.2.29-pre1 worked like charm. Nice.

The step "Build and test" does the obvious but it also appends version information to the file forth.asm in the workspace. The reason for this is simply that I decided to upload binaries from any non-tag push to the default Git tag "volatile" - and after downloading a binary from the Volatile Release you might want to know what exactly you're looking at, e.g.:

; ##########################################
; # Release info added by GitHub action:
; #   repository:   TG9541/stm8ef
; #   branch name:  refs/heads/master
; #   sha:   8ee3453ce577181ef5e9bddda94f56d448dbf962
; ##########################################

You can use the "sha" field to construct a GitHub URL to the precise version like this:
https://github.com/TG9541/stm8ef/commit/8ee3453ce577181ef5e9bddda94f56d448dbf962

Next Saturday, 9/Oct/2021, Chuck Moore, the father of Forth, will be the guest star of the Forth2020 user group Zoom meeting!

Peter Forth, the organizer of the meeting, told me that all Forthers are welcome!

With release STM8 eForth 2.2.28 this "Small Forth" is more "Forth-Standard" leaning. One notable change is the usage of the POSTPONE method instead of COMPILE and [COMPILE]. In fact, the new method for extending the Forth compiler is not only more elegant, it's also more code efficient. The words DEFER ... IS were added - these words facilitate an interactive stile of top-down programming. 

Since this is an embedded Forth for small µCs full standard compliance will be out of reach unless there is a standard for implementations that keep their dictionary in an executable ROM. Where code size or speed is concerned compatibility will always be an option to facilitate porting code. A good example is using 1-Wire code for DS18B20 that Brad Rodriguez wrote for CamelForth.

There is an open issue that collects small Forth-Standard compatibility additions.

So far we're here:

One notable difference will be "pictured number output": Forth Standard compliance requires # ( ud -- ud) instead of # ( u -- u) (double instead of single math). Although this increases the code size only marginally it makes printing numbers in a background process slower. Instead there will be a change in the upcoming release 2.2.29 that speeds up printing numbers (by a factor of 2.5 to 7). Words for dealing with double numbers will be added as an option.

Another notable change is a re-write of CREATE ... DOES> that makes using this key feature both code efficient and fast.

Last week I released the 27th release of the this Small Forth for simple µCs (by today's standards - what's "simple" today would have been the stuff of dreams in the 1990s).

STM8 eForth 2.2.27 contains nifty features, e.g. an easy to use "compiler overlay" for structure words (e.g. IF ... ELSE ... THEN) with relative branches. This is useful for e.g. for the ISR programming or for relocatable code. Mixing Forth code with assembler instructions is now an really easy thing to do.

That 40 years old bug in UM/MOD I wrote about the other day: it's been fixed now, but it almost deserves a place in a museum of computer history!

I was asked whether STM8 eForth can support Brad Rodriguez 1-Wire code which was written for the MSP430 and I had a look into it. After familiarizing myself with the time-honored 1-Wire protocol (which I read for the first time at least 20 years ago) I quickly hacked some low-level routines:

That's indeed all that's needed for basic operations.

Brad Rodriguez, a well known name in the Forth scene, did some more than that: he also implemented the ROMSEARCH algorithm, needed for getting all devices on a bus. The code is part of his CamelForth repository.

CamelForth code looks very similar to eForth code (indeed I just had to provide INVERT as an "alias" of NOT, and implement a few words like LSHIFT. 

A write-up is here: https://gist.github.com/TG9541/348abfae54c79f1c1c5a4f4ed0dcfdf5

What happens when a user tells you about a bug in a completely inconspicuous part of a software, one that you never touched and that you'd thought of as reliable since you'd been working with the software? It happened to me last week, and disbelieve was naturally my first reaction but the problem in UM/MOD, the "32/16bit-division-with-remainder" was real!

The same user quickly found a bug and provided a fix. I then informed the owner of another project, that started off of Dr. Ting's "STM8EF for the STM8S Discovery", also had never noticed any problem although he had identified and fixed another unrelated bug in UM/MOD!

What started then was a thorough analysis of the code, which unearthed yet another bug related to an edge case. Automated testing with a Python script makes more bugs in that code very unlikely.

The moral is this: bugs happen, and they can be very well hidden under other layers of code that "rescues" the expected behavior but open source software not only leads to much better testing for unexpected things but it can also make skilled teams appear out of thin air!

Manfred Mahlow published version 0.8.5 of the embedded Forth terminal and programming tool e4thcom which introduces the source file level keywords #ifdef <name> and #ifndef <name>: they make e4thcom check if <name> is defined in the target dictionary and transfer the rest of the line on that condition

The following example shows the source level keywords supported by e4thcom and codeload.py :

#include hw/pd8544.fs \ unconditional uploading
#require ALIAS \ conditional uploading if the word ALIAS isn't in the dictionary

\res MCU: STM8S103  \ use the STM8S103.efr symbol/address file

\ get GPIO registers addresses, insert definitions like `hex 5000 CONSTANT PA_ODR`
\res export PA_ODR PA_IDR PA_DDR PA_CR1 PA_CR2

#ifndef OUT! \res export PB_ODR
#ifndef OUT! : OUT! ( f -- ) PB_ODR 4 B! ;

\\ ignore the rest
 of the file

This feature is useful for testing target properties while sending code to the target. Writing device independent low-level code is among possible use cases.

The codeload.py in the STM8 eForth tools folder, very useful for transferring code to the target from the command line, now also supports this feature. There are some more improvements, e.g. better newline handling, better error messages and support of Python3 by default.

After the recent introduction of >REL for control structures with relative addressing the docs for the STM8 eForth Assembler Interface were in need of an update.

I used the opportunity to restructure the paragraphs a bit. Feedback is welcome!

I just published STM8 eForth 2.2.27.pre1:

the GitHub release notes list the most important features, e.g. optional relative addressing for IF .. ELSE .. THEN, support for defining the "Background Task" event in user code (e.g. the RTC alarm).

Today, IR remote control is by far the cheapest option for consumer electronics. I've long had the idea that Forth is ideal for interactive scripting of IR remote-controlled devices, and I used the light bulb at my desk to learn how to do it with STM8 eForth.

PulseView and an IR receiver (a rather dated SHARP GP1UD272XK) revealed that the protocol is a "NEC" variant:After some learning, thinking and coding, entering "7 ir<enter>" is all it takes for switching this $2 miracle on. The solution is quite generic and controlling other devices shouldn't be difficult.

I made a write-up of what I learned, including surprisingly simple working code in this GitHub Gist.