General

Q. I want to learn Forth! Where should I start?

The canonical source is Starting Forth by Leo Brodie, which taught at least one of PropellerForth's authors (and his dad). There's an online copy hosted on forth.com.

Starting Forth describes a slightly different dialect of Forth than what you'll find in PropellerForth, but most of the tutorials should work unchanged.

Q. There are a bunch of download options! Which should I choose?

The options available will vary with each release, as we make experimental features available to folks who want them. Currently, you have two choices to make: * Target board, and * Features available.

For information about each supported target board, see SupportedTargets. For information on the various feature releases, see the ReleaseNotes for the current version.

Q. I'm getting some cryptic exception code! What does it mean?

PropellerForth uses standard ANS Forth exception codes, but unfortunately doesn't translate them for you yet. For now, refer to the official list in the ANS Exception standard.

Remember that the list is in decimal, but your terminal is in whatever base you've set (using words like hex), so you might need to convert.

Q. I've typed in some loops or IF/THEN statements and they're not working. Why?

PropellerForth's flow control words (like BEGIN, DO, IF, and kin) only work in compiled words -- that is, between : and ; . This is because they have to scan over and modify the code being compiled -- and in the interactive interpreter, there's no code being compiled.

This may change in the future, but for now, define a simple word to play with flow control. You can always FORGET it later.

Working with Code

Q. Pasting text into my terminal seems to mangle it! What gives?

Short answer: PropellerForth is off compiling what you've entered, and misses some characters. * Try setting your terminal up to delay about 10ms between characters, and about 100ms between newlines. * On 8.01 and later, try typing USEBOOTASP to enable new, faster, experimental serial I/O.

Long answer:

PropellerForth's serial I/O is reasonably fast, but if the text you're pasting causes any computation to happen -- for example, if you're pasting source code to be compiled -- PropellerForth may miss some characters.

We agree that this is lame, and we're trying to fix it. As a short-term solution, if you're using 8.01, enter USEBOOTASP to switch the console driver to the experimental Boot Asynchronous Serial Port. This will cost you one Cog, but provides full-duplex buffered serial I/O. BootASP may be enabled by default on a future release.

If your terminal supports it, try adding a character delay of a 10ms and a newline delay of about 100ms. (HyperTerminal on Windows, ironically, has better support for this than minicom on Unix.) 100ms will cover most compilation pauses, but if you paste in something really expensive it might still glitch.

The real solution is to implement handshaking, which would give the Propeller a way of indicating that it's busy so your terminal will stop sending data. While the USB-to-Serial chip used by most Propeller board has hardware handshaking capability, the boards don't actually route these lines to the Prop! A future version of the ASP driver may provide in-band XON/XOFF handshaking (aka Software Flow Control), but we're still testing it.

Q. I've entered a bunch of source code. How do I save it?

If part of the source code you've entered includes the optional EEPROM word set, you can save it to EEPROM by typing savemem. (If you're on the HYDRA, you can carefully hot-swap the memory card before doing this if you want to keep a backup copy of your old EEPROM.)