Home page / LegoŽ / Robotics / emupbForth

Disclaimer
This page is not connected with or endorsed by The LEGO Company. LEGO, LEGOLAND, LEGO SYSTEM, LEGO TECHNIC, DUPLO, LEGO PRIMO and LEGO MINDSTORMS are trademarks of The LEGO Company.

emupbForth

Table of Contents

• What emupbForth is
• What emupbForth is not
• Technical description
• Requirements
• License
• Installing emupbForth
• Using emupbForth
• Porting emupbForth
• Downloads

What emupbForth is

emupbForth is a pbForth emulator. I assume that you know:

1. what the RCX is (if you don't, follow this link to the Lego® Mindstorm page to know more);
2. what pbForth is (if you don't, look at the Ralph Hempel's pbForth home page)
3. what the Forth programming language is (if you don't, I suggest you have a look at the Forth Interest Group home page)

I started this project because I like pbForth, but having no previous experience about coding in Forth I felt the need of a comfortable environment where to test and debug my programs.

I know that a good factored Forth code needs little if any debugging, but this tool might help some other Forth newbies in feeling more at ease during the steep learning curve of the language.

I believe that even the most experienced Forth programmer will find some value in emupbForth, at least for it allows writing and testing pbForth code even when he/she doesn't have the RCX and the IR Tower handy.

The main features include:

• A simple visual interface that allows the user to interact with the sensors and the pushbuttons while the program is running (to simulate external events). The interface shows the current state of three motors (virtually) attached to the A, B, and C ports, and emulates the display.
• An API layer to emulate the pbForth RCX specific words. Most of pbForth is actually implemented.
• A debug feature to check the actual parameters passed to any API call and see whether they are in the proper range, warning the user if they're not.
• All the debugging facilities of a complete Forth development environment.

What emupbForth is not

A full-featured bullet-proof commercial-like program. I made my best to make it bug free, but I wrote it for my own use so please be tolerant. I decided to share it with other pbForth users in the hope somebody else finds it useful and contributes to improve it.

Feel free to send me any comment, suggestion or bug report. Any feedback is welcome and important for me to understand whether to invest more time in further enhancements.

Technical description

The current version of the emulator is designed to run under Windows, and it's been tested on 2000 and XP machines.

emupbForth is made of two parts: a DLL which replicates the RCX, and some Forth code which defines the standard pbForth API words, mapping them to the proper DLL calls.

To run emupbForth you need a Windows based Forth interpreter. I use Win32forth, a popular public domain ANSI Forth environment written by Tom Zimmer and Andrew McKewan. However, there's nothing specific to Win32forth in my code, so I presume that my definitions are easy to export to any other Forth systems, provided that it allows for calls to a Windows DLL.

Requirements

You don't need to have pbForth installed neither the RCX itself to use emupbForth. That being said, it's obvious that the main reason for the existence of emupbForth is about developing programs to use on an actual RCX. pbForth is a Forth interpeter written and maintained by Ralph Hempel. The official pbForth web site is the best source of information about pbForth and you won't find here any documentation that's already provided there.

What you currently need is:

• A PC running Windows (until ports to other platform will be available)
• The Win32forth public domain Forth interpreter (until ports to other interpreters will be available, see the Porting emupbForth section below)
• The emupbForth emulator itself (see the Downloads section below)

License

emupbForth is “public domain”. Feel free to use, modify and spread its code as you prefer.

I would like very much to receive a copy of any correction, improvement or porting to new platforms. They will be published in this page crediting the contributors.

Installing emupbForth

1. If you don't have Win32Forth, download and install it. Win32Forth is public domain and available for download at many sites. A good starting point is the Win32Forth Items page at the Forth Interest Group web site.
   
   
2. Download the emupbForth.zip file from this site ( Downloads )
   
   
3. Unzip the emupbForth.zip file into the same directory that contains the Win32Forth interpreter. This will copy the following files:

emurcx.dll - The RCX emulator
emurcx.ini - The RCX emulator configuration file
emupbf.f - RCX API words
emu_test - A directory that contains some Forth script to test the emulator


Using emupbForth

If you got used to pbForth, emupbForth is quite easy to use.

1. Start Win32Forth
   
   
2. Load the emulator typing:
   FLOAD EMUPBF
   
   
3. Load your pbForth source and invoke the proper word to start your program.

All of the API calls defined by pbForth 2.1 are implemented, with the following exceptions:

• The word SERVO_SET is not yet implemented.
• The words timer_SET and timer_GET , which refer to fast timers, have been renamed FTIMER_SET and FTIMER_GET because Win32forth is not case sensitive and they were overlapped to the corresponding low resolution timer words.

Please refer to the pbForth RCX Words List for a detailed descriptions of the pbForth API for the RCX.

The following words are specific to the emulator and have no corresponding words in pbForth::

• RCX_EMU_VERSION ( -- version ) returns on the stack the version code of the emurcx DLL.
• RCX_DEBUG_MODE ( f -- ) sets the debug mode of the emurcx DLL. When f is true, every call to the API routines checks whether the passed parameters are in the valid range of values; if not, it shows a message dialog with the name of the API word, the wrong parameter and its value.

The emu_test directory contains two example programs:

• ARAGOSTA.F - A slightly modified version of an actual pbForth program I wrote for a Sumo robot.
• EMU_TEST.F - A sequence of calls to API words (badly) written just to test the emulator.

Both the files contain an explanation about how to use them.

Porting emupbForth

On the Forth side, the EMUPBF.F file is quite simple, being just a sequence of very short word definitions. Each word calls a corresponding function implemented in the emurcx DLL. Win32Forth allows for calling Windows DLLs using two words: WINLIBRARY dll_name to link the library, and CALL function_name to actually call one of functions in the DLL. Parameters are passed to the functions from the stack, in reversed order.

On the DLL side, I wrote the emurcx.dll using Delphi (6.0). I made almost no use of Windows-specific calls and components, thus I expect that the code can be easily ported to Kylix/Linux (but I might be wrong).

I'd like to be informed of any port of the emupbForth to other Forth interpreters or other platforms, and will publish any contribution in this page giving full credit to its authors.

Downloads

Here you can download the current version (1.0.0) of emupbForth:

emupbForth.zip (278 KB) - All you need to install, run and use emupbForth.

emupbForth_source.zip (31 KB) - The Delphi 6 source code of emurcx.dll.

Send me an e-mail if you like. I understand Italian, English, Spanish.