Common User Issues¶
Lockups¶
Problem: You’ve just flashed Mecrisp-Stellaris Forth onto a board or chip and your terminal shows the boot up Greetings message.
When you hit the “Enter” key a “OK” response is received and all looks good. However when you upload Forth source code the terminal locks up after the first few Words!
The terminal is then frozen and the MCU must be be reset to recover … what’s wrong ??
Answer¶
Forth has a compiler inside the software, which is inside your MCU and when you enter or upload any source ‘Definitions’ (Words) they are compiled, one after the other.
The MCU needs time to compile the Definitions and if new Definitions are uploaded while the chip is still compiling the previous Definition it will appear to ‘lock up’. This is a “Flow Control” issue.
Note
Mecrisp-Stellaris won’t generally ‘lock up’ without giving a error message, of course if you were to write code that disabled the USART, or turned of the CLOCK etc, it may appear that Mecrisp has locked up but this is entirely different to the “Flow Control” problem described above.
Solution 1¶
The simple way to get around this problem is to use a terminal with a ‘end of line delay’ usually about 200 milliseconds, to allow the MCU time to compile the longest Definitions.
Find how to configure a 200 millisecond “end of line” delay for the terminal you are using and if it doesn’t have one, find one that does.
The downside is that the serial upload speed will be slowed by 200 milliseconds for EVERY LINE, long or short.
If you use Linux/*bsd, or Apple Mac see this page serial terminals
Solution 2¶
A much better but more complex solution is called “Hardware Flow Control”, This solution does not need slow “end of line delays” and compiles as fast as the MCU is able. See hardware handshaking.
Solution 3¶
Some serial terminals designed especially for Forth will look for the ‘OK’ prompt and use this as flow control. It actually works rather well.
Examples¶
Zeptocom Web Terminal (Chrome Browser only)
E4thcom (Linux only)
How do I save programs permanently to the MCU?¶
So that I don’t have to always upload it from the terminal ?
You can upload your source into ‘flash’ or ‘ram’. Ram is great for testing but scarce and volatile.
The Word “compiletoflash” will put Mecrosp-Stellaris into “save any new words to flash mode”, but you’ll have to erase everything if you want to alter it later so I develop and test in ram first.
The word “compiletoram” puts Mecrosp-Stellaris into “save any new words to ram mode”. Don’t forget to switch back to this mode after compiling anything to flash.
How to view the disassembly of a word?¶
Use ‘see’ .’see’ is included in every tarball in the programs ‘dissasembler-m0’ or dissasembler-m3’ and need to be uploaded to your mcu depending on type.
These are found on the ‘common’ directory of the Mecrisp-Stellaris distribution.
GPIO Manipulation¶
For a beginner trying to enable then manipulate the GPIO Ports on the STM32F103 (Blue Pill) with Mecrisp Stellaris is a monumental task . I’ve just spent all day on this thing trying to get the portB pins flashing a couple of LEDs. The STM32F103 data sheet was written by Boffins for Boffins, the average electronics hobbyist, even some of the better ones would find this document really hard going. For a start it’s over 100 pages (the SMT32F family one is over 1,000 pages) so you are constantly scanning for what you need next.
Solution¶
See the Blue Pill Starter Kit page.
How To Turnkey¶
Q: I want to make my program run from cold boot or after a reset how do I do that ?
A: This called “Turnkey” because the user turns a key and it always runs.
If a word named INIT is found in the Dictionary at boot, the INIT Word contents will be executed after reboot ot power up.
Warning
If your program is a closed loop program with no method to break out of the loop such as “KEY?” then reflashing Mecrisp-Stellaris will be required to access the Terminal because you won’t have access to “ERASEFLASH”. Make sure you erase ALL the Flash before reflashing Mecrisp-Stellaris as well.
Example 1¶
Turnkey operation, no way to break out of the “closed.loop.program”
compiletoflash
: closed.loop.program \ runs forever
begin
." This MCU is running a TURNKEY application" cr
again
;
: INIT
closed.loop.program
;
compiletoram
Rebooting the MCU will print the above message “This MCU is running a TURNKEY application” again and again … forever.
Example 2¶
Turnkey with Terminal escape.
compiletoflash
: non.closed.loop.program \ loop until keyboard key pressed which will exit loop and return control to the terminal
begin
." This MCU is running a TURNKEY application" cr
key? until
;
: INIT
non.closed.loop.program
;
compiletoram
Rebooting the MCU will print the above message “This MCU is running a TURNKEY application” again and again until a keyboard key is hit.
Different Forths Have Different Words!¶
It seems there have been many variations of Forth over the years and Words get dropped or changed or modified ?
Actually there is no “Standard Forth” and the designer of Forth, Charles Moore was against any ‘standards’ because he felt they detracted from the ability of Forth to be a ‘problem solving language’. (I hope I have phrased that correctly). Sure there are “Standards Committees” for Forth, but he was not in favor of them.
C.Moore also said when asked “what is Forth?” , “I can’t say for sure what Forth is, but I know it when I see it”.
The Forth community has a saying that sums this up fairly well I think … “When you have learnt ONE Forth, then you have learnt ONE Forth”.
Then when you factor in different MCU’s there are always different designs, features, memory etc, so even within Mecrisp-Stellaris there are some features available on some MCU types, and not on others because of these differences.
The utter malleability of Forth is unique, you won’t find it anywhere else, try this in the safety of your own home!
: 1 0 ;
or this one
: + - ;
Note
One thing to be aware off is that people don’t program in Forth, they develop a “Domain Specific Language” to solve their problem with using Forth.
My Solution Isn’t Here!!¶
click on the “index” page link on this site, try a keyword in the “search” box.
Have a look thru the Mecrisp “Discussions Site” here https://sourceforge.net/p/mecrisp/discussion/ and if you can’t find anything hopeful post a message there describing your problem. This page is made from such posts and answers. Both the creator of Mecrisp and myself check these pages every few days.
