Contents
There are a number of times when you would like to save a copy
of the work you have done in pbForth. This is especially true when
you are building a very complex system. By taking advantage of the
incremental nature of programming in Forth, you can code and test
your application in pieces, and save each step as an image.
Working with saved images is faster because you don;t need to load the
basic pbForth firmware and then load the text scripts on top of
that. You just load the image of the code you have written and
debugged so far.
Another benefit of saving an image is that you can enter contests
like the WORKSHOP 3D Lego RCX
Challenge. Among other outstanding events, there is a contest
for a standard line-following robot that allows contestants to
send in their firmware via email. This note describes how to make
such an image for a pbForth application.
To get the most up to date version of pbForth firmware and the example scripts,
you can get the
pbForth Scripts as a ziparchive or the
pbForth Scripts as a tar.gzarchive. The
scripts you'll need are in the saveSystem directory.
I'm assuming that you know the basics of Forth and how the MARKER word
lets you specify a place in your dictionary that you can return the
state of the system to. The MARKER word lets us limit the ammount
of stuff that is saved with the image so we can actually cut out
all of the words that we need to save the image in the first place.
Finally, I'm indebted to Sergey Udovenko for taking the time to
develop the core routines required to accomplish this task. Sergey
took advantage of building small bits of the application in Forth
and assebling them into a neat application.
I'm assuming you have extracted the script archive
file to a place you can remember. You'll need to choose the scripts
for saving the system from the saveSystem subfolder of wherever
you extracted the original scripts to.
You can save your system in one of two ways. The default is to save
everything, including the words required to save the system. From the pbForth
GUI console, upload each of the following scripts from the saveSystem
directory using the "pbForth->Upload Script" menu:
- srec.txt
- xsend.txt
- savesys.txt
Once these scripts have been uploaded, you're ready to save your complete
system by typing...
SAVE-SYSTEM
...and then choosing "pbForth->XMODEM Download" to specify a filename for
your new image. Be careful to not choose your current original pbForth
firmware name in case there is a problem!
After a few minutes, the GUI will tell you that it has completed the
download process and your new image file is ready to use!
The advanced method of saving your system requires you to edit
the savesys.txt file and to add a MARKER word to your system.
The extra work pays off becuase you will "cut out" the words required
to save the system and make the image file more compact.
First, you need to load up all of the scripts required by system you wish
to save. Then you define a special marker for the end of the image by typing:
MARKER end-of-image
Next, you'll need to edit the contents of savesys.txt by uncommenting
the SAVE-SYSTEM-ONLY word. Just remove the leading \\ at the
beginning of each of the lines.
From this point on, it's almost the same as the defualt save. From the
pbForth GUI console, upload each of the following scripts from the
saveSystem directory using the "pbForth->Upload Script" menu:
- srec.txt
- xsend.txt
- savesys.txt
Once these scripts have been uploaded, you're ready to save your partial
system by typing...
SAVE-SYSTEM-ONLY
...and then choosing "pbForth->XMODEM Download" to specify a filename for
your new image. Be careful to not choose your current original pbForth
firmware name in case there is a problem!
After a few minutes, the GUI will tell you that it has completed the
download process and your new image file is ready to use!
The big difference is that SAVE-SYSTEM-ONLY executes the
end-of-image marker word which restores the dictionary
to the point it was at just before you loaded all of the
scripts for saving the system. Neat huh?
