What is it?
STM8 eForth is among the smallest user friendly Forth systems for µCs: it brings the simplicity of a 1980s style Forth to today's low-cost controllers. The project provides code for STM8 variants, board support for selected low cost targets, and docs. STM8 eForth has a long feature list but it uses very little memory. Innovative solutions, steady support, and an active community makes using it for new projects easy!
The code and binaries on GitHub can be used in many ways:
- as an alternative firmware for Chinese commodity boards (e.g. thermostats, DCDC converters, and relay boards)
- build embedded systems with an interactive shell (scriptable and extensible)
- for creating smart sensors with SPI, I2C, or RS232 and a scripting shell, e.g. for RaspberryPi, Arduino, or ESP8266
- as an interactive environment for exploring the STM8 architecture
- for learning Forth - it's easy and fun (find out why in the text below!)
Why a Forth for Cheap Chinese boards?
Because it's fun: cheap mass-produced imperfection is a playground for creativity :-)
The W1209 has long been my favourite target: it's a rather complete embedded control board with a UI at a very good price. It's as cheap as it looks, and the challenge is in it's imperfections: the guy who designed the board clearly didn't have a connected application in mind, and I had a lot of fun making it do things it was never intended to do.
There are challenges, like the lack of communication ports. The "sensor connector" can either be used as a a 2-wire RS232 "bus" or for sensing. If you need sensing and communication at the same time the project also provides a full-duplex 3-wire RS232 interface through the key pins (while keeping the keys functional). A plug-in system makes it easy to test new ideas, like using the "update connector" as a home brew field bus interface!
Which target boards are supported?
Besides generic targets for STM8S001, STM8S103, STM8S105, STM8S207 and STM8L051, there is currently support for the following boards:
- MINDEV STM8S103F3P6 Breakout Board
- XH-W1219 (2x3 7S-LED, 3 keys, relay)
- W1209 Thermostat Board (3 7S-LED, 3 keys, relay)
- W1401 Thermostat Board (3x2 7S-LED, 4 keys, relay, buzzer)
- C0135 STM8S103 4 Relay Board for MODBUS
- XH-M194 STM8S105S4 Timer with 6 Relays
- CN2596 DC/DC converter with voltmeter hack
- XH-M188 Linear power supply
Some more boards can be supported on request, e.g.
Read more about possible future targets below.
Again, because it's fun!
Forth starts out as a stack machine with a tiny instruction set and minimal hardware requirements. It fits in a few KiB, and the target, even a lowly µC, can even be used as the development system. The Forth stack machine is a minimalistic VM on a standard CPU, but there are also hardware implementations (e.g. for FPGAs, or a 144 core Forth processor). The VM is ideal for fast context switching and Forth easily meets hard-real-time requirements. It's no surprise that Forth was used in many NASA projects.
- compared to other programming environments Forth is easy to understand fully
- like Lisp, Forth has a REPL (Read-Evaluate-Print-Loop) which enables software testing in a way impossible with "Edit-Compile-Run-Debug" (e.g. Arduino)
- it's easy to build Domain Specific Languages (one can literally program the compiler!)
- the stack-oriented "factoring" method results in implicit data flow and modular code
- Interpreter-compiler, basic OS functions fit in just 4K code :-)
A Forth programmer is in control of all levels of problem abstraction, a unique advantage in a world where layer on layer of 2nd hand solutions leads to ever growing complexity (compilers, libraries, operating systems, drivers, frameworks, IDEs... ). I'm convinced that "Thinking Forth" will make you a better programmer, not just in the domain of embedded control!
Why STM8S003F3 or STM8S103F3?
Low-end "STM8S Value Line" STM8 µCs are very cheap (less than $0.40 in hobby quantities, $0.20@100pcs). That's why they appear in many cheap gadgets:
- a simple STM8S103F3P6 breakout board costs about $0.80,
- a W1209 thermostat (STM8S003F3P6, relay, 3 digit display, 3 keys) costs less than $1.50
- a hackable DC/DC-converter costs about $1.60
Of course, you can use what you already know (e.g. PIC, AVR, MSP430, or MCS51) - but learning to work with new architectures is fun :-) Besides, the STM8 is reasonably fast, and peripherals are similar to STM32. Personally, I like the challenge of turning this low-end chip into a powerful interactive embedded control device. It's just software after all ;-)
What do I need for flashing STM8 µCs?
All that's needed is an ST-LINK V2 compatible programmer ($2), and a serial interface with TTL level for interactive development (e.g. a CH340 dongle for $0.60). Ready-made binaries are on the GitHub releases page, but for building your own STM8EF configuration you'll need the open source SDCC tool chain.
There is a page on STM8S programming in the project Wiki with notes from my first steps, hints for tool installation, details on SDCC for STM8, and links to sites on STM8 programming that I found helpful.
Which features are supported?
Currently there is support for the following features:
- serial Forth console (if necessary using a single GPIO)
- a background tasks for INPUT-PROCESS-OUTPUT code with a fixed cycle time (e.g. 5ms)
- interrupt handlers can be written in Forth (SAVEC, IRET)
- CREATE .. DOES> for writing defining words
- DO .. LEAVE .. +LOOP/LOOP for loop structures (also FOR .. NEXT)
- vectored I/O with '?KEY, 'EMIT provides operating-system like features
- configurable vocabulary subsets for binary size reduction
- Extended vocabulary:
- STM8 ADC control: ADC! ADC@
- board keys, outputs, LEDs: OUT OUT!
- EEPROM, FLASH lock/unlock: LOCK ULOCK LOCKF ULOCKF
- native bit access B!
- inverted byte order 16bit register access: 2C@ 2C!
- compile to Flash memory: NVR RAM RESET 'BOOT
- ASCII file transfer: FILE HAND
- Optimized Subroutine Threaded Code (STC) with relative addressing, CPU instructions for literals, BRANCH and EXIT
- support for boards with 7Seg-LED UI: in a background task, 123 . goes to the 7Seg-LED display, and ?KEY reads board keys
More features might be supported in the future (e.g. SPI, I2C). Just ask.
What's a Background Task?
Basic single-user Forth systems, like eForth, are interactive until you start your application. Then they run the application until you stop it.
This implementation provides multitasking with one (1) concurrent thread that can be started by setting the variable BG to an "application word". The word then runs periodically in the background while the Forth console allows changing parameters, e.g. for tuning controllers!
If you're familiar with Arduino, the background word is akin to the body of loop(). What's different is that the loop code gets executed in fixed time intervals, and that there is an interactive console in the foreground. Of course, you can also interactively test your background task, or the words it's composed of.
Read more on the background task in the GitHub Wiki.
How can I spot suitable boards?
Many XH-Mxxx or XH-Wxxxx labeled boards from the usual Chinese market sites are STM8S003F3P6 based. Some of them are extremely cheap, others in the $10-$20 range but have interesting features (e.g. XH-M114, XH-M117, XH-M128, XH-M129, XH-M158, XH-M194, XH-M196,XH-M203, XH-M205, XH-M207, XH-M241, XH-M602, XH-M603, XH-M604 ...)
SmartClima boards like the (XH-)W1209 are likely to work. I guess that the exceptionally low price is due to copied products. Judging from product pictures at least the following boards are STM8 based: XH-W1210, XH-W1219, XH-W1301, XH-W1302, XH-W1304, XH-W1308, XH-W1313, XH-W1403, XH-W1403, XH-W1411, XH-W1501, XH-W1503, XH-W1504, XH-W1505, XH-W1601, XH-W1701, XH-W1702, XH-W1711, XH-W2100, XH-W2101, XH-W3001, and XH-W3002.
It's best if the serial port pins are easily accessible on headers, but this only applies to a small fraction of boards. STM8EF now provides support for all boards that have at least one free GPIO (e.g. PD1/SWIM on the ICP header). Even sharing the communication port with another function is possible.
Some boards, like a cheap 4 digit voltmeter aren't good targets as they lack a "brand" or generic "module name" which makes them difficult to identify: when you order something based on the description alone, there's no way to know what you'll get.
A target I considered is the B3603 power supply unit (read in the Wiki why I didn't do it, but I might change my mind). There is a Hackaday project by @Baruch Even who did a great job at developing a new open source firmware.
Of course, you can apply the code to any target. I would be happy to hear from you!
What about Windows as a development platform?
I don't use a Windows machine at home except for filing taxes, and that isn't fun.
However, the tool chain as a Docker image: it runs in Travis-CI, so that checking-in the code in to a GitHub repository will build your binary.
There is a Python 2.7 uploader that emulates the e4thcom terminal's dependency resolution and include file features. Working with an STM8 eForth binary the Windows HyperTerminal is also possible.
According to the docs, running the build tool chain on Windows should be possible, too:
- SDCC is available for Windows
- GNU make is available for Windows, but it isn't really required, as it can be replaced with a simple CMD script
- STM8FLASH can be compiled with mingw-w64-i686, but you can also use some other tool for flashing the target µC
Of course, you're welcome to share your experience, and contribute to the docs.
When will project goal be reached?
Now you caught me red-handed. As the real project goal is "Spass am Gerät" I'll close the project when I'm satisfied with what's been achieved, or if STM8 µCs fall out of favor in China ;-)