Tills Palm Pages http://www.harbaum.org/till/palm 
Control your Lego RCX via your Palms IrDA interface
 Tills Home
 Palm stuff
 
  Get in touch
 
  Argon V
BlueBlocks
Elite
IR Pong 1/2
Mulg
Phoinix Tools
 
  axxPac FTP
Battery Hack
Bluetooth
IR Ping
NoStreak Hack
OS Flash
 
  Tilt-Sensor
Cradle
Palm III-4MB
 
  FlashLib
Mensa
Mobile25
PBrickLib
SpaceLib
Step Counter
 
  Phoinix
palmOne
Open Source
FSF
GPL
 

 

Visit the project home at sourceforge.

The PBrick library provides a API for bidirectional IR communication between the palm computing platform and the lego mindstorms RCX controller. Possible applications for this library range from simple emulation of the lego remote control to lego robots extended with an on-board palm device using the RCX as an intelligent IO controller and the palm As the central processor of the robot.

Important: The pbrick library is not compatible with PalmOS 5 based devices. This is due to the fact, that the pbrick library does some very nasty things to the irda hardware of the palm and hence directly accesses the irda hardware. PalmOS 5 based device use a completely different hardware and thus require a complete rewrite of pbricks.

1. Overview over the PBrick Library

The PBrick Library provides:
IR communication:
No additional hardware required, no mindstorms IR tower needed, just place your palm in front of your RCX and you are done. You can even make the palm being part of you mindstorms creation. If you think your palm does not fit into the lego world take a look at the lego palm.
Bidirectional communication between palm and RCX:
Commands can be sent to the RCX and e.g. sensor values can be read back into the palm.
Extensibility:
The PBrickLib is open source. Feel free to add all the cool features you need and extend it however you want.
Free of charge:
The PBrickLib is free, just download and use it.

2. Installing and using PBrickLib

In order to install PBrickLib on your palm, simply hotsync the library itself (PBrickLib.prc) to your palm and install at least one program that makes use of the library. The current distribution of the PBrick library contains two PBrickLib enabled programs:
PBRemote.prc
This is a emulation of the lego remote control using one-way communication only. This program provides a functionality similar to RMover or OmniRemote.
PBDemo.prc
This demo shows the real advantage of the PBrick library. This simple demo shows PBrick capability to read back values from the RCX. Just tap the FW or BT buttons to request the Firmware version on the RCX or the remaining juice in the RCXs batteries. Use this program as a basis for your own software.

3. Using the library functions in your own projects

You can use the PBrick library to write your own PBrick enabled palm software. For examples see the sources of PBRemote and PBDemo in the archive. These source have been developed with the prc-tools, but should be portable to Codewarrior without major changes.

The PBrick library provides a simple and easy to use interface to these functions allowing the library itself to be updated and maintained whenever necessary without the need to recompile your PBrick enabled software. Since the PBrick library needs to perform direct hardware accesses in order to provide the communication functionality, it is very likely, that future palm hardware will required a updated PBrick library.

3.1. Error return codes

All functions in the PBrick library provide the same type of return value. A 0 or positive value indicates no error, while a negative return value indicates a error:
/* error codes */
#define errNoMgr    -1   /* no new serial manager installed */
#define errOpenSer  -2   /* unable to open serial lib */
#define errSetPort  -3   /* error setting port controls */
#define errNoIR     -4   /* setting IR failed */
#define errLevel0   -5   /* low level receive error */
#define errLevel1   -6   /* high level receive error */
#define errReplyLen -7   /* unexpected reply length */
#define errReply    -8   /* unexpected reply message */
#define errSpeed    -9   /* unsupported communication speed */

3.2. Internal configuration

These functions are used to get and set library internal settings. They do not cause data exchange with the RCX and do not require a RCX to be seated in front of the palm.

These functions use a data structure of type PBrickConfigType:

typedef struct {
  /* entries to be read an set, -1 = don't set */
  Int16 check_alive;   /* 0/1 = enable alive check for high level functions */
  Int16 retries;       /* maximum number of retries (default = 5) */
  Int16 com_speed;     /* interface speed (currently only 2400 bit/s) */

  /* read only entries */
  UInt16  version;     /* library version */
  Boolean cpu_is_ez;   /* a ez/vz cpu was detected */
  UInt16  timer_val;   /* internal timer value */
  Int16   error;       /* frequency generation error */
} PBrickConfigType;
Err PBrickGetConfig(UInt16 refnum, PBrickConfigType *config)
This function can be used to retreive the current library settings.

Input values:

UInt16 refnum
PBrick library reference.
PBrickConfigType *config
Pointer to configuration space to be filled with the current library settings.

Return value: 0 on success, negative values indicate an error (see Error return codes).

Err PBrickSetConfig(UInt16 refnum, PBrickConfigType *config)
This function can be used to change the current library settings. Not all settings can be changed.

Input values:

UInt16 refnum
PBrick library reference.
PBrickConfigType *config
Pointer to configuration space to be used to change the current library settings. Values set to -1 are not changed.

Return value: 0 on success, negative values indicate an error (see Error return codes).

3.3. Low level functions

The low level functions provide access to the basic palm to RCX communication routines of the PBrick library. These mechanisms provide a flexible interface to the RCX. For a detailed command listing have e.g. a look at Kekoa Proudfoots great RCX Opcode Reference.

Err PBrickCmd(UInt16 refnum, Int8 *cmd, UInt16 clen)
Sends the contents of a command buffer to the RCX, ignores any reply sent by the RCX.

Input values:

UInt16 refnum
PBrick library reference.
Int8 *cmd
Pointer to a buffer containing the command to be send to the RCX.
UInt16 clen
Number of bytes stored in command buffer.

Return value: 0 on success, negative values indicate an error (see Error return codes).

Err PBrickCmdReply(UInt16 refnum, Int8 *cmd, UInt16 clen, Int8 *reply, UInt16 *replylen)
Sends the contents of a command buffer to the RCX and expects a reply from the RCX. The reply is stored in a separate buffer.

Input values:

UInt16 refnum
PBrick library reference.
Int8 *cmd
Pointer to a buffer containing the command to be send to the RCX.
UInt16 clen
Number of bytes stored in command buffer.
Int8 *reply
Buffer to be used to store reply message sent by RCX.
UInt16 *replylen
To be set to the buffer size. Changed by the function call to the number of bytes actually received.

Return value: 0 on success, negative values indicate an error (see Error return codes).

3.4. High level functions

These functions allow for easy to use access to dedicated RCX functions. Currently there are only a few functions implemented. More functions will follow. RCX functions not supported by PBrick high level functions can always be used via the low level functions.
Err PBrickAlive(UInt16 refnum)
Sends a alive request to the RCX. Returns a failure, if the communication with the RCX fails.

Input values:

UInt16 refnum
PBrick library reference.

Return value: 0 on success, negative values indicate an error (see Error return codes).

Err PBrickSound(UInt16 refnum, UInt16 sound_id)
Instruct the RCX to play a predefined sound.

Input values:

UInt16 refnum
PBrick library reference.
UInt16 sound_id
PBrick library reference. Possible sound values:
0 Blip
1 Beep beep
2 Downward tones
3 Upward tones
4 Low buzz
5 Fast upward tones

Return value: 0 on success, negative values indicate an error (see Error return codes).

Err PBrickGetVersions(UInt16 refnum, UInt16 *rom_ver, UInt16 *fw_ver)
Request firmware and ROM version numbers from the RCX.

Input values:

UInt16 refnum
PBrick library reference.
UInt16 *rom_ver
Pointer to a 16 bit integer used to store the ROM version number.
UInt16 *fw_ver
Pointer to a 16 bit integer used to store the firmware version number.

Return value: 0 on success, negative values indicate an error (see Error return codes).

Err PBrickGetBattery(UInt16 refnum, UInt16 *millivolts)
Request battery voltage from the RCX.

Input values:

UInt16 refnum
PBrick library reference.
UInt16 *millivolts
Pointer to a 16 bit integer used to store the battery voltage in millivolts number.

Return value: 0 on success, negative values indicate an error (see Error return codes).

Err PBrickRemote(UInt16 refnum, UInt16 command)
Send a remote control command to the RCX.

Input values:

UInt16 refnum
PBrick library reference.
UInt16 command
PBrick library reference. The command may consists of the following parts. Multiple parts can be or'd into one command:
REMOTE_NULL_CMDDo nothing.
REMOTE_MSG1_CMDSend message code 1.
REMOTE_MSG2_CMDSend message code 2.
REMOTE_MSG3_CMDSend message code 3.
REMOTE_AFWD_CMDTurn motor A on in forward direction.
REMOTE_BFWD_CMDTurn motor B on in forward direction.
REMOTE_CFWD_CMDTurn motor C on in forward direction.
REMOTE_AREV_CMDTurn motor A on in reverse direction.
REMOTE_BREV_CMDTurn motor B on in reverse direction.
REMOTE_CREV_CMDTurn motor C on in reverse direction.
REMOTE_PRG1_CMDSelect and run program 1.
REMOTE_PRG2_CMDSelect and run program 2.
REMOTE_PRG3_CMDSelect and run program 3.
REMOTE_PRG4_CMDSelect and run program 4.
REMOTE_PRG5_CMDSelect and run program 5.
REMOTE_STOP_CMDStop all motors.
REMOTE_BEEP_CMDPlay sound.

Return value: 0 on success, negative values indicate an error (see Error return codes).

5. Downloads

Version 1.0 of the pbrick library, incl. the full source code
6. Related projects

Several other projects and programs have been developed in order to provide an interface between the palm and the RCX controller, but they all have their limitations:
Pacific Neoteks OmniRemote development kit
This kit uses a commercial OmniRemote remote control emulation software to emulate the remote control like signals of the lego RCX controller.
Advantages: Uses palm IR hardware
Disadvantages: Palm to RCX transfers only, limited extensibility, commercial project
RCXLib 0.1 for Palm
A open source project for communication between palm and RCX. Requires a serial mindstorms IR tower (not available anymore) to be connected to the palm.
Advantages: Bidirectional communication, open source project
Disadvantages: Unable to use palm IR hardware directly
Robotic Mover 1.0
A freeware program providing a similar functionality to the Omniremote software.
Advantages: Uses palm IR hardware, freeware project
Disadvantages: Palm to RCX transfers only, no extensibility
Other related links

LEGO MINDSTORMS(tm) Internals
A nice overview over projects related to the lego RCX controller
 Tills Palm Pages Get in touch!