search

TG9541 / stm8ef

STM8 eForth - a user friendly Forth for simple µCs with docs
https://github.com/TG9541/stm8ef/wiki
Other
315 stars 66 forks source link
c0135 eforth forth stm8 stm8l stm8s w1209 w1219

readme

STM8 eForth (stm8ef)

Build

STM8 eForth is a ready to use interactive Forth system for STM8 MCUs. The STM8 family of highly reliable 8bit microcontrollers has 16bit extensions and modern peripherals. STM8 devices are widely available and easy to master. The embedded Forth turns STM8 devices into a "computer" with a serial console. STM8 eForth has been used for learning, creating one-off appliances, and for small-scale commercial projects.

The Forth console provides a command interpreter, a native code compiler, and features like background execution of application code. This enables use cases like interactive testing of peripherals, control parameter tuning, and adding or changing code in the Flash ROM while application code is running. Code examples for STM8 peripherals, e.g., timers, RTC, ADC, I2C, can be used as a starting point for creating reliable embedded systems.

STM8EF Wiki

The binary release provides ready-to-run Forth binaries with STM8 register definitions and a library for a range of STM8 chips and target boards. Build- and test-automation uses the uCsim STM8 simulator in a GitHub Action. Releases are presented as "release" (stable), "pre-release" (unstable) and "volatile" (latest).

The binary release contains all necessary sources, tools and libraries needed by downstream projects for building a custom STM8 eForth core. The SDCC tool chain is used, and the modular build concept simplifies use cases like "adding board support", "custom memory layout", "tailored vocabulary" or a "mixed C/Forth project".

About Forth

Forth works by defining new words with "phrases" consisting of existing words, numbers or strings. A simple "Hello World" in Forth looks like this:

: hello ." Hello World!" ;

The Forth language is so simple that you can learn the basics in a snap, e.g., with the STM8 eForth Walk-Through. Forth has no real syntax but good design results in readable phrases (e.g. 15 deg left servo turn-by or center right servo turn-to).

Forth is a stack based language: data flows on the data stack from one word to the next and in most cases there is no need for temporary variables.

The Forth programming style encourages "factoring" functionality. This leads to very good code density but it also simplifies testing. Forth is a "low level" language that offers a high level of abstraction: even words for control structures like IF ... THEN are just Forth words that compile code.

The best feature of Forth is that it allows interactive testing of words and phrases. An embedded system can be used as its own application oriented test environment!

About STM8 eForth

The STM8 eForth core is written in STM8 assembly using the SDCC tool chain. Combining Forth with C is supported.

The original STM8 eForth was written by Dr. C.H. Ting's eForth for the STM8S Discovery. With the kind permission of Dr. Ting the code presented here is under MIT license. Bugs were fixed, the code size reduced, standards compatibility improved and many features were added (e.g. compilation to Flash memory, autostart code, interrupt handling - see overview and words list in the docs folder.

STM8 eForth is highly configurable: a Forth binary that allows compiling new words to Flash ROM or RAM fits in less than 4K, amd a binary with extended vocabulary requires about 5.5K. Due to the high code density a low cost devices with 8K Flash ROM, like the STM8S003F3P6, is sufficient for non-trivial applications. If more space is needed a low-cost 32K device can be used, e.g. STM8S005C6 or STM8L052C6.

The Forth console uses the STM8 UART or a simulated serial interface for communication with a serial terminal (3-wire full-duplex and 2-wire half-duplex are supported). For console access and programming e4thcom is recommended but any serial terminal will work. The console can be configured, even at runtime, to use other character I/O channels, e.g., a keyboard and a character 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.

Board support:

STM8 eForth provides board support for selected mass-produced Chinese low-cost control boards, e.g. words for relay outputs, or I/O with keys and LED displays. Since the appearance of MCUs with the same pin-out as the popular STM8S003F3P6 common "Chinese gadgets" like thermostats, voltmeters or relay boards can no longer be expected to use an STM8 chip, and soldering skills are required to replace it. There is more information in the Wiki.

Note that break-out boards and the C0135 control board can be expected to work without any change.

C0135

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

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.

Generic targets

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" (i.e., a device with 32K Flash specified as 16K). For details please refer to the README.md in the configuration folders referenced below. The automotive grade and the special purpose families should also work. Please open an Issue or use Discussions if you have questions about support for a device!

STM8S targets

Support for STM8S devices in the RM0016 family is stable. Peripherals aren't as advanced as those of e.g. STM8L devices but that makes them easy to master. Automotive grade STM8AF devices in the same family can be expected to work. Various STM8 Discovery boards and breakout boards for "Low", "Medium", and "High density" devices can be used.

STM8L targets

STM8L support for RM0031 family devices in STM8 eForth is stable. Compared to STM8S most STM8L devices provide a much richer feature set, and studying the reference manual may take more time. The STM8 eForth core is mostly the same as for STM8S devices. The latest addition was support for STM8L101F3 and STM8L001J3, the only members of the frugal RM0013 family.

For more details please refer to the README.md in the board folders below.

Other configuration examples

The STM8 eForth core is highly configurable. The following configuration examples showcase minimal configurations or communication settings.

Release and development cycle

The Github Releases section contains binary releases. As STM8 eForth is based on eForth V2 (embedded STC Forth) and, since it improves on STM8EF V2.1, releases follow the naming scheme "STM8 eForth 2.2.x".

Using a target binary requires setting a symlink target to the desired board target folder, e.g. ln -s out/STM8S105K4/target target (use make BOARD=<target> or BOARD=<target> make).

The git master branch contains the current development version (releases are tagged). After cloning the repository make will build all targets.

Running make BOARD=STM8S105K4 will set a symlink. The Forth console prompt will show the release version (e.g. STM8eForth 2.2.27) or the next pre-release (e.g. STM8EF2.2.28.pre1).

Disclaimer, copyright

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.