eForth for cheap STM8S gadgets

I didn't forget the "cheap Value Line" part of this project, but reverse engineering a gadget takes some time, writing and testing board support code even more (especially if there are many constraints, like in the case of the W1401 or the DC/DC converter).

The following boards are in the queue:

• 3 thermostats: W1209WK, XH-W1219, and W1701
• 2 cheap hackable voltmeters, both clearly designed by Chinese hacker-engineers (RX/TX available, unused ports broken out, etc)
• 1 wireless serial link module: HC12 (SI4463 based)
• 1 linear power supply: M188
• 1 hackable PWM module with LED display

The W1219, and the M188 might be the next boards to get a board folder, and a binary release. I'm open to requests, though :-).

Edit: the is an interesting W1209 related report about serial interface problems. Maybe I'll have to change the default serial interface of that board. Issue contains a test binary using a board key instead of the analog sensor header.

For the STM8 mainstream family *STM8S), ST marketing defined different "classes" of devices:

• STM8S00X: Value Line
• STM8S10X: Access Line
• STM8S20X: Performance Line

The code in this project initially targeted the STM8S105C6, but it's now optimized for low-grade Valdue Line devices (the STM8S103F3 is essentially a Value Line device with better specs).

I now have this STM8S105K4T6 devices on my desk:At about $1.90 it offers 16KiB Flash, 2KiB RAM, and 1KiB EEPROM, that's nothing to write home about. However, since the day when I started this project, I had the goal that the code isn't limited to a single STM8 variant. Now I have a target device for testing device configuration.

EDIT1: the code in the develop branch contains the necessary changes for applying STM8EF to Access Line devices. The new include file target.inc also provides board specific configuration options for the memory layout.

EDIT2: I just released v2.2.9 which adds support for Access Line devices. I haven't seen many cheap Access Line gadgets out there, but it's a nice addition to the home-brew toolbox anyway.

STM8S003F3P6 µCs are cheap (OK, this isn't the first time you read that). Some time ago @K.C. Lee used off-the-shelf TSSOP adapter PCBs as a simple µC board. A great idea! Like that one can make a Li coin battery powered board for about $0.60:

Like K.C. I added the essential components (2x 1µF capacitors) to the unused SOP20 pads on the other side, and did a test with the SWIMCOM image, and it worked nicely!

In "active halt" state it can run quite some time as an environmental data logger. I have some ideas for low-bandwidth environmental sensors that can be deployed, and recovered later on. I'll call this a "sensor throwie", since it's not a bit loss if some of them can't be recovered (missing in action. so to say).

... and, of course, same binary size. Here is the text from the release page on GitHub:

This release contains an important feature: VARIABLE and ALLOT allocate RAM in NVM mode, and support for a new board, or rather a nice little hack: a $1.60 programmable power supply.

VARIABLE and ALLOT allocate RAM in NVM mode

This feature adds transparent handling of Forth variables in for dictionaries in Flash, which means that also RAM allocation is handled automatically in the background. Please refer to the documentation in the Wiki section Forth VARIABLE in NVM mode, and to Issue #16 for technical details.

New board DCDC

Some cheap Chinese boards have surprising properties: the CN2596-2 "DCDC converter with voltmeter" can be turned into a programmable power supply (in the sense of the word). Please refer to the Hackaday project, and to Board CN2596 in the Wiki for details.

From time to time it's necessary to revise docs, especially as a project evolves and features get more mature. It's also a good opportunity to check whether casual readers find with they expect (e.g. simple examples and some nice illustrations). Some of the pages were likely to frighten the horses, so to say.

There is also a new sidebar, which makes finding some of the information easier.

Please have a look at the STM8EF Wiki. If you find mistakes, or stylistic cruelties, please drop me a note.

Issue 16 introduces "normal" operation of VARIABLE and ALLOT when compiled to non-volatitle memory. The feature also provides transparent RAM allocation.

This may not sound not like much, but it's an essential implementation of the memory allocation by a "linker" in a C programming environment. To give you an idea of the problem, consider the following code:

VARIABLE abc ok
' abc . 168 ok
' abc 5 dump
  A8  CD 83 54  0  0  0  0  4 64 75 6D 70  0  0  0  0  M_T_____dump____ ok
abc . 171 ok
12345 abc ! ok
abc ? 12345 ok

VARIABLE defines a word (abc) in the dictionary, which consists of code CALL DOVAR (CD 83 54) at address 168, and a RAM "CELL" (2 bytes) of storage at address 171. When the word abc is called, DOVAR places the address of the next memory location on the data stack and returns to the caller.

From the programmer's perspective, a variable in Forth is much like an array definition in C. The word VARIABLE, as a "defining word" is akin to a C declaration, we'll come back to this later on :-). Just like in C, access to array elements works with address arithmetics (in C, square brackets are used as "syntactical sugar"). In Forth variables are accessed with words like !, @, C!, C@, and ?.

An array with two bytes might not serve everybody. If more memory is needed (e.g. an array) it can be allocated with ALLOT.

VARIABLE def 8 ALLOT ok
VARIABLE ghj ok
ghj def - . 19 ok
def abc - . 11 ok

The variables abc, def, and ghj use consecutive RAM cells follow in the dictionary. Because of 8 ALLOT the variable def gets 10 byte RAM instead of the 2 bytes of abc. The overhead of 9 bytes is due to 2 link, 1 string length, 3 string, and 3 CALL DOVAR.

So far so good. But what happens when we're in NVM mode and create a variable?

COLD ok
NVM ok
VARIABLE abc ok
HEX abc . 9BD9 ok
' abc . 9BD6 ok

The variable abc is now in Flash (which starts at 0x8000). Unfortunately, the memory location it refers to is also in Flash, which is no good place for a variable, to say the least.

@RigTig provided a prototype implementation for VARIABLE with CREATE-DOES> that works in NVM:

: VARIABLE CREATE HERE , 2 $6E +! DOES> @ ;

This code is a bit tricky: variable is a replacement for the defining word VARIABLE, which works just like the normal one, except that it reserves memory in the RAM dictionary area when defining a new variable, and returns the address of that memory when using the variable, and $6E is the address where the next free location in the RAM dictionary is stored while STM8EF is in NVM mode.

Forth features like CREATE-DOES> are akin to high level language concepts like inheritance, reflection, and prototypes. Extending a 5K programming system that's embedded in a 8K µC on the fly really is something else! RigTig demonstrated the power of CREATE-DOES> by implementing a useful approach to the "Flash/RAM problem".

VARIABLE has been on my ToDo-list for months, and now had no excuse for not to sorting it out.. After some hacking, all the examples above work as expected, no matter whether you're in RAM or in NVM mode. Check out the preliminary docs and the preview code in Issue 16 on GitHub.

EDIT: the code size is now to below 5000 bytes for the MINDEV target (80 bytes down!). The CORE binary size target is still 21 bytes above the self-imposed limit of 4096 bytes (VARIABLE formerly wasn't part of CORE due to its limited usefulness). I pushed new code to the branch variable on GiHub.

EDIT2: the size of the CORE binary is now below 4096 bytes, and a minimal interactive system without NVM, interrupts in Forth code, and the new VARIABLE feature |is below 3700 bytes. The code has been merged from the feature branch variable to the develop branch, and there is a pre-release STM8EF v2.2.8.1.snapshot.

EDIT3: @RigTig did some testing with the new code, and he told me that the results are encouraging (e.g. improved code size in a quite complex application). I'll release the code soon, maybe together with initial support for the W1219 board.

The W1401 thermostat board has now initial STM8EF board support, and it's also better documented. There are maybe still some rough edges, but the things I tested work "as expected". It's now part of the "official" release v2.2.7.

• serial interface through PD1/SWIM
• 7S-LED through vectored I/O (auto-off w/ time delay while serial interface active)
• board keys through vectored I/O
• relay/red LED, and green LED through `OUT!`
• buzzer with programmable pitch (`BEEP_CSR` HW-register)
• read sensor input with `5 ADC! ADC@`

The analog input is surprisingly stable: there is just enough noise to get some extra resolution, but one still gets a stable readout down to the LSB without filtering!

The programmable pitch of the BEEP output isn't good enough for playing music (unless you spend extra effort to tuning the RC-oscillator, or if you don't mind annoying people).

The price for a W1401 starts from $2.60/piece (including shipping). It offers a lot of value for the money, especially if you're looking for a hackable board for SISO (Single Input Single Output) control (e.g. thermostat, solar heating, level control, charge control), or for monitoring/safeguarding applications!

While I was on a business trip something left a spike on the visitors graph on GitHub: @Elliot Williams wrote about his ESP-14 with MQTT-and-STM8EF project on Hackaday!

ESP-14 is an ESP8266 with an attached STM8003F3P6 in a package very similar to an ESP-12 module. Elliot used the ESP-14 for two reasons:

1. the ESP-14 has more ADC inputs than the ESP-12
2. a powerful ESP8266 bundled with a minimal STM8S running Forth is a crazy thing waiting to be done!

The schematics around the ESP-14 looks like this:

The ESP8266 connects the tiny STM8S003F3P6 to a Linux machine using JeeLab’s esp-link.

The ASCIIcinema recording of a remote log-in via WiFi to an 8bit Forth, with a demo of interactive testing on the Forth console is well worth watching!

Check out Elliot's article, it's great!

PS: Elliot and me discussed other use cases for the ESP-14, like battery powered IoT devices. All the tools to make this happen are now available!

The core code in this project has reached some degree of maturity, and I guess it's the right time to shift the attention to board support code, and to docs.

The following needs to be done:

• publish contents from notebooks, and also from this log, to the Wiki on GitHub
• restructure the Wiki without breaking links on external pages
• use custom GitHub sidebars and overview pages to make the contents accessible
• Enrich Wiki pages with diagrams, schematics, and photos
• Create a simple HowTo with a shopping list, and instructions that require "zero-problem-solving".

There is a page at GitHub that presents "Best Practice" for GitHub Wikis, but "Best" seems to stand for "use it for more than leaving an outdated boring Markdown wasteland", and "Practice" appears to mean "Improvise".

Documentation in a uniform and manageable way calls for a CMS, but a good folder structure and templates will do the job. I like the method used in this Wiki: it's based on sub-folders with local sidebars and locally stored images. It also shows that it takes quite some discipline to make it effective.

EDIT: I'm on a business trip, so no hacking :-{ Some of the docs on GitHub received an update.
There are some more boards in the pipeline. XH-W1401 is half-ready, and I can start with XH-W1219 or XH-1701. In order to improve accessibility to information it's maybe better to create some more HaD sub-projects.

My idea is:

• simple control boards (e.g. thermostats),
• voltmeters
• power supplies
• other boards here (unless they require more work)

After a day filled with business meetings | didn't want to risk killing the DC/DC converter for good, and I decided to look a little closer at one of the new arrivals from China, small and cheap voltmeter ($1.12 including shipping).

Repetitio non placet they say, but this voltmeter turned out to be really nice:

The LED display 3361BS is "0.36", red, common anode". The internal supply voltage is a bit unusual (3.0V), but otherwise the module is very hackable.

The 6 pads with 1.27mm pitch to the left are connected to the following signals:

1 SWIM (7S-LED segment D)
2 TxD
3 RxD
4 NRST
5 +Ub
6 GND

I guess that the designer was bored by making yet another cheap Chinese voltmeter, and he decided to make a hackable voltmeter instead. If not, why would one expose not only SWIM/NRST but also RxD and TxD? Why route a spare GPIO to the (unpopulated) NC pad of the LED display?

Hat-tip to China!