STM8 eForth: a user-friendly Forth for cheap µCs. Check out the Wiki!
TG9541 Merge pull request #230 from TG9541/update
Update targets and Wiki links
Latest commit 1a99489 Sep 15, 2018
Permalink
Failed to load latest commit information.
C0135 fixed #189 Enable UART simulation on Port E Apr 13, 2018
CORE fixed #189 Enable UART simulation on Port E Apr 13, 2018
DCDC fixes #194 Improve behavior of serial interface w/ shared LED-Display… Apr 15, 2018
DOUBLECOM fixed #189 Enable UART simulation on Port E Apr 13, 2018
MINDEV fixed #189 Enable UART simulation on Port E Apr 13, 2018
STM8L-DISCOVERY STM8L-Disco: LCD driver, short usage. May 17, 2018
STM8L051F3 fixes 16: STM8L051F3 USART TX:PA2/RX:PA3 as the default May 27, 2018
STM8S001J3 fixed #189 Enable UART simulation on Port E Apr 13, 2018
STM8S105K4 fixed #189 Enable UART simulation on Port E Apr 13, 2018
STM8S207RB fixed #189 Enable UART simulation on Port E Apr 13, 2018
SWIMCOM fixed #189 Enable UART simulation on Port E Apr 13, 2018
W1209-CA fixed #189 Enable UART simulation on Port E Apr 13, 2018
W1209-FD fixed #189 Enable UART simulation on Port E Apr 13, 2018
W1209 fixed #189 Enable UART simulation on Port E Apr 13, 2018
W1219 fixed #189 Enable UART simulation on Port E Apr 13, 2018
W1401 fixes #194 Improve behavior of serial interface w/ shared LED-Display… Apr 15, 2018
XH-M188 fixed #189 Enable UART simulation on Port E Apr 13, 2018
XH-M194 fixes #128 RTC burst-mode Apr 15, 2018
XY-LPWM Added makefile rules 'term' for run e4thcom terminal May 11, 2018
XY-PWM Basic support for XY-PWM/HW-0515 PWM generator board May 14, 2018
barebones Move barebones files into own directory Jun 15, 2017
docs fixes #192 Export arbitrary RAM locations as constants Apr 15, 2018
inc Update stm8_adc.inc Sep 11, 2018
lib Update rtc.fs Sep 12, 2018
mcu fixes #202 STM8L: wrong peripherals addresses Apr 28, 2018
test fixed #189 Enable UART simulation on Port E Apr 13, 2018
tools fixes #197 use POSIX awk, don't rely on linux script processor path Jul 22, 2018
.gitignore fixes #76 test automation facilities, console based smoke test Oct 1, 2017
.travis.yml fixes #120 deploy tgz files to mitigate zip file shortcommings Nov 24, 2017
CONTRIBUTING.md Update CONTRIBUTING.md Sep 30, 2017
LICENSE.md issue #32 Build framework feature #include Jul 2, 2017
Makefile Merge branch 'master' into fix-197 Jul 22, 2018
README.md Update targets and Wiki links Sep 15, 2018
forth.asm Merge remote-tracking branch 'mainline/master' Apr 18, 2018
forth.h Initial set of files based on STM8EF, Version 2.1, 13jul10cht from ht… Jul 2, 2016
main.c issue #128: initial commit for XH-M194 7S-LED, keys, outputs Apr 13, 2018

README.md

STM8 eForth (stm8ef)

Test

STM8 eForth is a lightweight interactive Forth for STM8 µCs with a good "feature-to-binary-size" ratio. It provides a binary release, easy configuration, a plug-in system for board support, a library infrastructure, and uCsim instruction level simulation for automated testing.

STM8 eForth is based on Dr. C.H. Ting's eForth for the STM8S Discovery. With the kind permission of the original author it has a permissive FOSS license.

STM8EF Wiki

Forth is a very simple but highly extensible programming language. "Hello World" is as simple as this:

: hello ."  Hello World!" ;

STM8 eForth runs on a microcontroller and interacts through a character interface with a console (e.g. a serial terminal program). With the help of e4thcom it can be used as a semi-tethered Forth (compilation runs on the µC but source dependencies are resolved by a PC).

The interactive Forth console can use any single GPIO, a pair of GPIOs, or the STM8 UART for 2-wire or 3-wire communication. Up to two serial interfaces can be used at the same time. The console can use any type of character I/O (e.g. keyboard and display), and can be configured even at runtime!

The Wiki on GitHub covers various topics, e.g. using Breakout Boards, or the conversion of low-cost Chinese thermostats, voltmeters, or DC/DC-converters into Forth powered embedded control boards.

STM8 eForth can be configured for a range of features and different STM8 devices: a full featured binary requires betwenn 4.7K and 5.3K, a basic interactive Forth fits in about 3.5K, and building even smaller interactive cores is possible. The unique ALIAS feature provides access to unlinked words.

Generic targets

Generic target binaries are provided for a quick start:

  • STM8S Low Density devices (e.g. STM8S103x3, STM8S003x3, or STM8S001J3)
    • CORE, a basic configuration for STM8S Low Density devices, some features are disabled (e.g. no background task)
    • SWIMCOM, a full feature set, and 2-wire communication through PD1/SWIM (i.e. ICP pin)
    • DOUBLECOM console through the SWIM interface, the UART can be used, e.g. for background tasks
    • STM8S001J3 like SWIMCOM but with console through PD5/UART_TX in half-duplex mode (not limited to STM8S devices in SO8N package)
  • STM8S105K4 for STM8S Medium Density devices (Value Line / Access Line)
  • STM8S207RB initial support for STM8S High Density devices (Performance Line)
  • STM8L051J3 support for STM8L Low Density devices (see issue)
  • STM8L-DISCOVERY support for STM8L Medium Density devices

Various STM8 Discovery boards and breakout boards for Low-, Medium-, and High-Density devices can be used. Initial support for STM8L Medium Density devices is available.

Board support:

TG9541/STM8EF provides board support for several common "Chinese gadgets" like the following:

  • MINDEV for the STM8S103F3P6 $0.65 "minimum development board"
  • W1209 $1.50 thermostat board w/ 3 digit 7S-LED display, full- or half-duplex RS232
  • W1219 low cost thermostat with 2x3 digit 7S-LED display, half-duplex RS232 through PD1/SWIM
  • W1401 (also XH-W1401) thermostat with 3x2 digit 7S-LED display, half-duplex RS232 through SWIM
  • C0135 "Relay-4 Board" - it can be used as a Nano PLC
  • DCDC hacked DCDC converter with voltmeter
  • XY-PWM PWM board w/ 3 digit 7S-LED display, 3 keys, dual PWM and full-duplex RS232
  • XY-LPWM PWM board w/ 2x4 digit 7S-LCD display, 4 keys, PWM and full-duplex RS232

The Wiki lists other supported "Value Line Gadgets", e.g. voltmeters & power supplies, breakout boards, and thermostats.

Feature Overview

Even though the binaries are very small, STM8 eForth offers many features:

  • Subroutine Threaded Code (STC) with improved code density
    • native BRANCH (JP), and EXIT (RET)
    • relative CALL with two bytes where possible
    • pseudo-opcode for DOLIT using TRAP: literals in 3 instead of 5 bytes
    • ALIAS words for indirect dictionary entries
  • compile Forth to NVM (Non Volatile Memory) with IAP
    • Words NVM and RAM switch between volatile (RAM) and non volatile (NVM) modes (REMEMBER execute RAM before a power recycle or executing COLD if you want the words added to NVM to be available in future terminal sessions)
    • RAM allocation for VARIABLE and ALLOT is transparent in NVM mode (basic RAM management)
    • autostart feature for embedded applications
  • Low-level interrupts in Forth
    • lightweight context switch with SAVEC and IRET
    • example code for HALT is in the Wiki
  • preemptive background tasks with fixed cycle time
    • configurable cycle (default: 5ms)
    • INPUT-PROCESS-OUTPUT task indepent of the Forth console
    • robust and fast context switch with a "clean stack" approach
    • concurrent interactive Forth console, e.g. for setting control process parameters
    • in background tasks ?KEY reads board keys, and boards with 7Seg-LED UI can simply EMIT to the LED display
  • cooperative multitasking with 'IDLE
    • code can be executed in an idle task while the console waits for user input
  • configuration options for serial console or dual serial interface
    • UART: ?RX and TX!
    • any GPIO or pair of GPIOs from ports PA through PD can be used as a simulated COM port
    • GPIO w/ Port edge & Timer4 interrupts: ?RXP .. TXP!
    • half-duplex "bus style" communication using simulated COM port or UART
    • option for TX! .. ?RX on simulated COM port, and ?RXP .. TXP! on UART
  • configurable vocabulary subsets for binary size optimization
    • configuration possible down to the level of single words
    • export of ALIAS definitions for unlinked words
  • Extended vocabulary:
    • CREATE ... DOES> for defining defining words
    • Vectored I/O: 'KEY? and 'EMIT
    • Loop structure words: DO .. LEAVE .. LOOP, +LOOP
    • STM8S ADC control: ADC!, ADC@
    • board keys, outputs, LEDs: BKEY, KEYB?, EMIT7S, OUT, OUT!
    • EEPROM, FLASH lock/unlock: LOCK, ULOCK, LOCKF, ULOCKF
    • native bit set/reset: B! (b a u -- ), [ .. ]B!
    • 16bit STM8 timer register access: 2C@, 2C!
    • compile to Flash memory: NVR, RAM, WIPE, RESET
    • autostart applications: 'BOOT
    • EVALUATE for interpreting text strings (even in the idle task!)
  • board support for STM8S based very-low-cost boards:
    • STM8S103F3P6 "$0.80" breakout board
    • Termostats, e.g. W1209, W1219, or W1401
    • Low cost power supply boards, e.g. XH-M188, DCDC w/ voltmeter
    • C0135 Relay Board
    • configuration folders for easy application to new boards

Other changes to the original STM8EF code:

  • "ASxxxx V2.0" syntax (the free SDCC tool chain allows mixing Forth, assembly, and C)
  • hard STM8S105C6 dependencies removed (e.g. RAM layout, UART2)
  • flexible RAM layout, basic RAM memory management, meaningful symbols for RAM locations
  • conditional code for different target boards with a subdirectory based configuration framework
  • bugs fixed (e.g. COMPILE, DEPTH, R!)
  • significant binary size reduction

Disclaimer, copyright

TL;DR: This is a hobby project! Don't use the code if support, correctness, or dependability are required. Additional licenses might apply to the code which may require derived work to be made public!

Please refer to LICENSE.md for details.