Contents

This is a list of the words that have been added to the built-in vocabulary to support the RCX hardware. They generally follow the calling conventions as outlined in Kekoa Proudfoot's disassembly of the ROM - with exceptions noted in the description of each word.

One of the biggest changes to this documentation is that the numeric option codes for things like LCD and sensor control are listed in hex and decimal. Some programmers were confused by pbForth's dynamic base changing, and thought that everything had to be in hex. In fact, there is no difference between the internal representation of hex or decimal numbers.

Note that some of the words have changed or disappeared since the first incarnation of pbForth. The reason is mainly for compatibility with the RCX ROM routines. I wanted to do a minimum of stack juggling to interface with them.


LCD Control Words


LCD_SHOW"l-c-d-show"RCX EXT[Top]

( segment -- )

Turns on the selected LCD segment. You must use LCD_REFRESH to actually upate the display. The table below shows the correspondence between segments and the numerical codes.
HexDecimalDescription
0x300612294Standing Figure
0x300712295Walking Figure
0x300812296Sensor 0 View Selected
0x300912297Sensor 0 Active
0x300A12298Sensor 1 View Selected
0x300B12299Sensor 1 Active
0x300C12300Sensor 2 View Selected
0x300D12301Sensor 2 Active
0x300E12302Motor 0 View Selected
0x300F12303Motor 0 Backward Arrow
0x301012304Motor 0 Forward Arrow
0x301112305Motor 1 View Selected
0x301212306Motor 1 Backward Arrow
0x301312307Motor 1 Forward Arrow
0x301412308Motor 2 View Selected
0x301512309Motor 2 Backward Arrow
0x301612310Motor 2 Forward Arrow
0x301812312Datalog Indicator
0x301912313Progress Indicator A
0x301A12314Progress Indicator B
0x301B12315Battery Low Indicator
0x301C12316IR Activity A
0x301D12317IR Activity B


LCD_HIDE"l-c-d-hide"RCX EXT[Top]

( segment -- )

Turns off the selected LCD segment. You must use LCD_REFRESH to actually upate the display. See the table in the description of LCD_SHOW for the correspondence between segments and the numerical codes.


LCD_NUMBER"l-c-d-number"RCX EXT[Top]

( comma value number -- )

This is the routine used to format numbers in the LCD. The comma parameter has the following possibilities:
HexDecimalDescription
0x00000Single digit to right of display, use with number = 0x3017
0x300212290No decimal point
0x30031229110th's decimal point
0x300412292100th's decimal point
0x3005122931000th's decimal point

The number parameter is used to determine where and how the value parameter is displayed:
HexDecimalDescription
0x301712311Single digit on right of display, use with comma = 0x0000
0x300112289Signed with no leading zeros
0x301F12319Unsigned with leading zeros


LCD_4TH"l-c-d-forth"RCX EXT[Top]

( -- )

Puts "4th" on the LCD display. Remember to call LCD_REFRESH.


LCD_REFRESH"l-c-d-refresh"RCX EXT[Top]

( -- )

Updates the display. This MUST be called before you will see any changes due to LCD_NUMBER or LCD_SHOW or LCD_HIDE words being used. It is probably a good idea to call this only as often as necessary...


Motor and Servo Control Words


MOTOR_SETRCX EXT[Top]

( power mode idx -- )

Sets the motor specified by an index of 0-2 to a power between 0-7. The allowed modes are:
HexDecimalDescription
0x00011Forward
0x00022Backward
0x00033Stop
0x00044Float


SERVO_SETRCX EXT[Top]

( level mode idx -- )

Note that the range of the level parameter has changed to signed numbers as of pbForth Version 2.0.0 - previous versions used unsigned numbers and were confusing to many programmers!

This word allows the RCX to generate waveforms that can be interpreted by a standard servo with the help of a simple circuit. The servo driver circuit can be made to be polarity sensitive, which allows up to two seros to be controlled from one RCX output port! The output port is specified by an index of 0-2 which matches up with the motor ports.

The mode specifies the "direction" of the signal polarity. If you are using the unipolar version of the servo signal converter, you can control two servos at once from one output port. The allowed modes are:
HexDecimalDescription
0x00000Enable Motor Driver
0x00011ServoA
0x00022ServoB

The level may range from -127 to 127. Smaller levels correspond to shorter pulse widths. The pulse widths range from 0.50 msec to 2.50 msec. as a maximum. It should be noted that the servos I tested use this as a practical range for 180 degrees of travel on the servo arm. Test your servos with an initial level of 0, which gives a 1.50 msec pulse and will center the servo arm.


Sensor Control Words

The sensor control words have undergone significant changes as of pbForth V2.0.0, the most notable being that you no longer need to initialize the sensor subsystem or tell the RCX whether a sensor is active or passive. These words were confusing to many programmers because the sensor system had to be reinitialized after every power-down sequence.


SENSOR_TYPERCX EXT[Top]

( type idx -- )

Sets the sensor type to one of the following:
HexDecimalDescription
0x00000Raw sensor (useful for custom devices)
0x00011Touch sensor
0x00022Temperature sensor
0x00033Light sensor
0x00044Rotation sensor


SENSOR_MODERCX EXT[Top]

( mode idx -- )

Sets the specified sensor to one of the following modes. Use your common sense when combining different modes and types...
HexDecimalDescription
0x00000Raw mode
0x002032Boolean mode
0x004064Edge detection - every transition counts
0x006096Pulse detection - only negative transitions count
0x0080128Percent of scale
0x00A0160Degrees Celsius
0x00C0192Degrees Fahrenheit
0x00E0224Angle detection


SENSOR_CLEARRCX EXT[Top]

( idx -- )

Clears the sensor's current raw, value, and boolean fields. The type and mode are left unchanged.


SENSOR_READRCX EXT[Top]

( idx -- code )

Reads the specified sensor and returns a flag indicating success (0) or busy (other values). In practice, I've never seen a non-zero return code, but I have seen lots of programs crash becuse the programmer forgot to DROP the result!


SENSOR_RAWRCX EXT[Top]

( idx -- value )

Retrieves the sensor's current raw data field. Note that this item will not change unless you call the SENSOR_READ on the sensor first.


SENSOR_BOOLRCX EXT[Top]

( idx -- value )

Retrieves the sensor's current boolean data field. Note that this item will not change unless you call the SENSOR_READ on the sensor first.


SENSOR_VALUERCX EXT[Top]

( idx -- value )

Retrieves the sensor's current value data field. Note that this item will not change unless you actually call the SENSOR_READ on the sensor first.


Timer Control Words


TIMER_SETRCX EXT[Top]

( value idx -- )

Sets the specified internal low resolution firmware timer (0-3) to the desired value. Note that these timers handle 0.1 second increments up to 0x7FFF or 32767, and that they are count UP and WRAP timers. Also note that writing to timer numbers beyond 3 will likely corrupt memory and cause mysteriious craches.


TIMER_GETRCX EXT[Top]

( idx -- value )

Retrieves the current value of the low resolution timer specified by idx.


timer_SETRCX EXT[Top]

( value idx -- )

Sets the specified internal high resolution firmware timer (0-9) to the desired value. Note that these timers handle 0.01 second increments up to 0xFFFF or 65535, and that they are count DOWN and STOP timers. Also note that writing to timer numbers beyond 9 will likely corrupt memory and cause mysteriious craches.


timer_GETRCX EXT[Top]

( idx -- value )

Retrieves the current value of the high resolution timer specified by idx.


Button and Sound Control Words


RCX_SOUND"r-c-x-sound"RCX EXT[Top]

( -- a-addr )

Returns the address of the buffer to use when figuring out the state of the RCX sound system.


SOUND_PLAYRCX EXT[Top]

( sound code -- )

Plays one of the 7 pre-defined system sounds. The legal hex values for code are:



0x4003 Sound is queued


0x4004 Sound is unqueued


The legal values for sound are:
HexDecimalDescription
0x00000Blip
0x00011Beep Beep
0x00022Downward Tones
0x00033Upward Tones
0x00044Low Buzz
0x00055Fast Upward Tones
0x00066Low Buzz


SOUND_TONERCX EXT[Top]

( time freq -- )

Plays a tone at freq Hz for time hundredths of a second. For some reason this was one of the most requested features for the next release of pbForth, and after using it to do some debugging, I can see why. Plus you can now play really annoying music in pbForth. Thi sis new as of Version 2.0.0 of pbForth.

I have not determined the high and low limits of the tones yet.


SOUND_GETRCX EXT[Top]

( a-addr -- )

Grabs the current state of the sound system, and places the result in the buffer pointed to by a-addr. The result is 0 if the system is idle (no sound is playing), or a non-zero value if it is busy.


RCX_BUTTON"r-c-x-button"RCX EXT[Top]

( -- a-addr )

Returns the address of the buffer to use when figuring out the state of the RCX buttons.


BUTTON_GETRCX EXT[Top]

( a-addr -- )
HexDecimalDescription
0x00011Run
0x00022View
0x00044Prgm


Power Control Words


RCX_POWER"r-c-x-power"RCX EXT[Top]

( -- a-addr )

Returns the address of a buffer that you can use to store the result of power queries in. More importantly, after doing a POWER_GET, the results are saved in this variable.


POWER_GETRCX EXT[Top]

( a-addr code -- )

Here's the word you need when you want to figure out the raw battery voltage or if the ON/OFF key is pressed. The results are placed in the buffer pointed to by a-addr. The allowable hex values for code are:
HexDecimalDescription
0x400016384On/Off button state - 0 if pressed
0x400116385Raw battery voltage


POWER_OFFRCX EXT[Top]

( -- )

I finally firgured out how POWER_OFF is supposed to work - so now it does. Versions of pbForth before 2.0.0 did not actually power the RCX down properly and the power up sequence messed up the sensors. This version fixes all that.

When POWER_OFF is called now, the RCX uses its built-in routines to take the brick into a deep sleep. When you press the On-Off button again, the RCX wakes up right where it left off, except the display is blanked. You will need to take care of this yourself.


RANGE_SETRCX EXT[Top]

( flag -- )

CAUTION! Setting the range of the IR system to far can damage your RCX if you send out lots of data for a long time. The RCX has a flaw in the serial driver hardware that sends too much current through the IRED under some conditions!

Sets the range of the IR subsystem to near if flag is 0 or far if flag is non-zero. This is another long-awaited feature that is new in Version 2.0.0 of pbForth.


Words Removed as of Version 2.0.0


SENSOR_INITRCX EXT[Top]

( -- )

This word has been removed from pbForth as of Version 2.0.0.


SENSOR_ACTIVERCX EXT[Top]

( idx -- )

This word has been removed from pbForth as of Version 2.0.0.


SENSOR_PASSIVERCX EXT[Top]

( idx -- )

This word has been removed from pbForth as of Version 2.0.0.


BUTTON_INITRCX EXT[Top]

( -- )

This word has been removed from pbForth as of Version 2.0.0.


RCX_INIT"r-c-x-init"RCX EXT[Top]

( -- )

This word has been removed from pbForth as of Version 2.0.0.


RCX_ECHO"r-c-x-echo"RCX EXT[Top]

( -- a-addr )

This word has been removed from pbForth as of Version 2.0.0.


RCX_EMIT"r-c-x-emit"RCX EXT[Top]

( c -- )

This word has been removed from pbForth as of Version 2.0.0.


POWER_INITRCX EXT[Top]

( -- )

This word has been removed from pbForth as of Version 2.0.0.