STM8 eForth (stm8ef)
STM8 eForth is an interactive Forth system for the full range of STM8 8-bit MCUs, including low power and low cost variants. The Forth console, an interpreter-compiler that runs on the MCU, and multi-tasking features allow interactive control of peripherals, parameter tuning or even changing running code (which is rather unusual for a $0.20 "computer").
STM8 eForth originated in Dr. C.H. Ting's eForth for the STM8S Discovery. With the kind permission of the original author the exted code here is under MIT-like license. Much of the code was re-written and many features were added, e.g. compilation to Flash memory, autostart code, interrupt handling and more.
For a range of targets, the binary release provides ready-made Forth environments, including a library and STM8 register definitions. Through modular board support new targets can be added, and build automation, including running target code in the uCsim STM8 simulator in Travis-CI, makes building ready-to-run binaries in "downstream projects" possible.
The programming language Forth works by defining new words with phrases of existing words. "Hello World" in Forth is this:
: hello ." Hello World!" ;
Forth is very well suited for embedded control since data flows through the stack. In many cases there is no need for variables and memory allocation which greatly reduces complexity.
Find out more in the STM8 eForth Walk-Through.
STM8 eForth is configurable: a minimal interactive system fits in 3.5K and a full featured binary requires 4 to 5.5K Flash memory. Due to the extraordinary code density a small 8K device, e.g. STM8S003F3P6 or STM8L051F3P6, has sufficent space for applications. For larger applications low-cost 32K devices with many GPIOs and lots of features can be used, e.g. STM8S005C6 or STM8L052C6.
The Forth console uses the STM8 U(S)ART, or a simulated serial interface, either 3-wire (full-duplex) or 2-wire (half-duplex). For programming e4thcom is recommended but any serial terminal will work. The console can be configured, even at runtime, to use other types of character I/O, e.g. keyboard and display.
The Wiki on GitHub covers various topics, e.g. converting low-cost Chinese thermostats, voltmeters, or DC/DC-converters into Forth powered embedded control boards.
STM8 eForth provides configurations and binaries for typical STM8S and STM8L devices. The binaries for selected "Low", "Medium" or "High density" can be expected to work for all of the listed packaging and memory specs variants. For details please refer to the
README.md in the linked configuration folder.
Generic STMS targets
Support for STM8S devices in the RM0016 family is stable. Peripherals aren't as fancy as those of e.g. STM8L devices but that makes them easy to master. Automotive grade STM8AF devices belong to the same family and they can be expected to work. Various STM8 Discovery boards and breakout boards for "Low", "Medium", and "High density" devices can be used.
- STM8S "Low density" devices (up to 1K RAM, 8K Flash and 640 bytes EEPROM)
- STM8S "Medium density" devices (up to 2K RAM, 32K Flash and 1K EEPROM)
- STM8S105K4 for STM8S005C6/K6, STM8S105C4/K4/S4 and STM8S105C6/K6/S6
- STM8S "High density" devices (up to 6K RAM, 32K + 96K Flash and 2K EEPROM)
- STM8S207RB for STM8S007C8, STM8S207C6/K6/R6/S6, STM8S207C8/K8/M8/R8/S8, STM8S207CB/MB/RB/SB, STM8S208C6/R6/S6, STM8S208C8/R8/S8 and STM8S208CB/MB/RB/SB
Generic STML targets
Compared to STM8S most STM8L devices provide such a rich feature set that studying the reference manual may take some time. Although support for STM8L peripherals is still in an early phase the STM8 eForth core is mostly the same as for STM8S devices and well tested. The latest addition is support for STM8L101F3 and STM8L001J3, the only members of the RM0013 family.
For more details please refer to the
README.md in the board folders below.
- STM8L RM0013 family "Low density" devices (1.5K RAM, 8K Flash, basic peripherals)
- STM8L101F3 for STM8L101F1, STM8L101F2/G2, STM8L101F3/G3/K3 and STM8L001J3M3
- RM0031 family STM8L "Low density" devices (1K RAM, 8K Flash, 256 bytes EEPROM, advanced peripherals)
- STM8L051F3 for STM8L151C3/K3/G3/F3, STM8L151C2/K2/G2/F2, STM8L051F3 and STM8L050J3M3
- STM8L "Medium density" devices (2K RAM, 32K Flash, 1K EEPROM)
- STM8L151K4 for STM8L151C4/K4/G4, STM8L151C6/K6/G6, STM8L152C4/K4/G4, STM8L152C6/K6/G6 and STM8L052C6
- STM8L "High" and "Medium+ density" devices (4K RAM, 32K + 32K Flash, 2K EEPROM)
- STM8L152R8 for STM8L151C8/M8/R8, STM8L152C8/K8/M8/R8 and STM8L052R8
STM8 eForth provides board support, e.g. relay outputs or I/O with keys and LED displays, for several common boards and "Chinese gadgets" like thermostats, voltmeters or relay boards. There is more information in the Wiki.
- CORE "svelte" 4K configuration for STM8S "Low density" devices, some features are disabled (no background task,
DO .. LOOPor
CREATE .. DOES>). Also, the dictionary search is case-sensitive.
- SWIMCOM 2-wire communication through PD1/SWIM (i.e. the ICP pin) and a full feature set (the similar DOUBLECOM also provides UART I/O words for applications)
- MINDEV for the STM8S103F3P6 $0.80 "minimum development board" (just like the STM8S103F3 configuration but with a word
OUT!for controlling the LED)
- STM8L-DISCOVERY for the STM8L-Discovery Board (STM8L152C6 "Medium density" with LCD)
- C0135 the "Relay-4 Board" can be used as a Nano PLC (Forth MODBUS support is available)
- W1209 $1.50 thermostat board w/ 3 digit 7S-LED display, full- or half-duplex RS232 (some board variants, e.g. with CA LED displays, are supported)
- W1219 low cost thermostat with 2x3 digit 7S-LED display with half-duplex RS232 through PD1/SWIM
- W1401 (also XH-W1401) thermostat with 3x2 digit 7S-LED display with half-duplex RS232 through shared PD1/SWIM
- DCDC hacked DCDC converter with voltmeter
- XH-M194 Timer board with STM8S105K4T6C, 6 relays, RTC with clock display, 6 keys with half-duplex RS232 through PD1/SWIM
- 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
Targeting other boards
The binary release contains all files required for building a configured STM8 eForth, e.g. for a custom target board. The modular build repository provides instructions, a
Makefile and an example "board folder". Other examples are in the GitHub repositories W1209, STM8 eForth MODBUS, STM8L051LED or XY-LPWM.
STM8 eForth Feature Overview
Compared to the original "stm8ef" STM8 eForth offers many features:
- a versatile framework for development based on Manfred Mahlow's e4thcom
- compile Forth to Flash ROM with IAP (In Application Programming)
RAMswitch between volatile (RAM) and non volatile (NVM) modes (execute
NVMif you want your new words to be available after power-cycle or
- autostart feature for embedded applications
- RAM allocation for
ALLOTin NVM mode (basic RAM management)
- Subroutine Threaded Code (STC) with improved code density that rivals DTC
- relative CALL when possible (2 instead of 3 bytes)
- TRAP as a pseudo-opcode for literals (3 instead of 5 bytes)
- Forth - machine-code interface using STM8 registers
- preemptive background tasks
INPUT-PROCESS-OUTPUTtask indepent of the Forth console
- fixed cycle time (configurable, default: 5ms)
- on supported boards
?KEYreads board keys,
EMITuses board display
- robust context switch with "clean stack" approach
- cooperative multitasking with
- idle task execution while there is no console input with < 10µs cycle time
'IDLEtask code can run the interpreter with
- Low-level interrupts in Forth
- lightweight context switch with
- example code for HALT is in the Wiki
- lightweight context switch with
- configuration options for serial console or dual serial interface
TX!full-duplex w/ half-duplex option for STM8 "Low density" and STM8L RM0031 devices
- GPIO w/ Port edge & Timer4 interrupts:
?RXP .. TXP!
- half-duplex "bus style" communication using simulated COM port or UART
- any GPIO or pair of GPIOs from ports PA through PD can be used as a simulated COM port
- option for
TX! .. ?RXon simulated COM port, and
?RXP .. TXP!on UART
- configurable vocabulary subsets for binary size optimization
- board dependent configuration possible down to the level of single words
ALIASdefinitions for any unlinked words, also in the EEPROM
- Extended vocabulary:
CONSTANT(missing in the original code)
'EMITfor I/O redirection (originally hard-coded)
CREATE .. DOES>for defining words (few eForth variants have it)
DO .. LEAVE .. LOOP,
+LOOP(for better compatibility with generic Forth)
ADC@for STM8 ADC control
OUT!for board keys, outputs or LEDs
ULOCKFto lock and unlock EEPROM and Flash ROM
B!(b a u -- ),
[ .. ]B!(and more) bit access and native bit set/reset words
LEBF@bitfields for little- and big-endian
2C!for STM8 timer 16bit register access
FC@for far memory access
[ .. ]C!fast memory byte set with a
PERSISTfor compiling to Flash memory
'BOOTfor autostart applications
EVALUATEinterprets Forth code in text strings (even compilation is possible!)
BYEa simple debug console for foreground code
- many words from Forth systems that were popular in the 1980s are provided in the library
Other changes to the original STM8EF code:
The code has changed a lot compared to the original code but porting back some bug fixes or features should be possible.
- original code bugs fixed (e.g.
- "ASxxxx V2.0" syntax (the free SDCC tool chain allows mixing Forth, assembly, and C)
- hard STM8S105C6 dependencies were removed (e.g. initialization, clock, 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
- significant binary size reduction
This is a hobby project! Don't use the code if you need dependable support or if correctness is required.
The license is MIT. Please refer to LICENSE.md for details.