| Tills Palm Pages | http://www.harbaum.org/till/palm |
| Control your Lego RCX via your Palms IrDA interface |
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_CMD Do nothing. REMOTE_MSG1_CMD Send message code 1. REMOTE_MSG2_CMD Send message code 2. REMOTE_MSG3_CMD Send message code 3. REMOTE_AFWD_CMD Turn motor A on in forward direction. REMOTE_BFWD_CMD Turn motor B on in forward direction. REMOTE_CFWD_CMD Turn motor C on in forward direction. REMOTE_AREV_CMD Turn motor A on in reverse direction. REMOTE_BREV_CMD Turn motor B on in reverse direction. REMOTE_CREV_CMD Turn motor C on in reverse direction. REMOTE_PRG1_CMD Select and run program 1. REMOTE_PRG2_CMD Select and run program 2. REMOTE_PRG3_CMD Select and run program 3. REMOTE_PRG4_CMD Select and run program 4. REMOTE_PRG5_CMD Select and run program 5. REMOTE_STOP_CMD Stop all motors. REMOTE_BEEP_CMD Play 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! |