RCXSimulator

RCXSimulator is an emulator of the Lego Mindstorms RCX. The RCX is a Lego brick that encloses a fully programmable Hitachi H8 microcontroller. This simulator emulates this microcontroller at instruction level. Furthermore some peripheral devices of the microcontroller are simulated such as the 16-bit timer. Beside the emulation of the microcontroller the surrounding Lego parts are simulated. A GUI displays the LC display and the buttons. These components are connected to the simulated microcontroller and, therefore, are accessible as in the real brick. Thus it is possible to use this simulator to develop firmware or ROM images for the Lego Mindstorms RCX. The simulator can display the currently executed instruction, occurring interrupts and accesses to the microcontroller's periphery. Beside the debugging support of the simulator an interface for the GNU debugger allows GDB to connect to the simulator and provide a comfortable step-by-step execution and memory inspection.

Download

Getting started

Run the Simulator with the ROM image "ROM.srec":
java -jar RCXSimulator.jar -r ROM.srec

Run the simulator with the modified ROM image and a "Hello World"-program:
java -jar RCXSimulator.jar -r util/srec/LEGO/modROM.srec -f util/srec/helloworld.srec

Command Line Parameters

valid parameters: -r romfilename [ -f firmwarefile ] [-irfeedback] [-ir=module[:parameter] ] [-p priority] [-gdb [-gdbport port] ] [-d] [-nowin] [-T] [-V] [-S] [-I] [-C] [-P]

-r <romfile>

Specify the filename of a ROM image file in SREC format.

-f <firmwarefile>

Specify the filename of a firmware image file (in SREC format) that is loaded at startup of the simulator. This is only useful if a modified ROM image is used.

-irfeedback

Simulate the IR feedback of the RCX. Every character sent is immediately received.

-ir=<module>:<parameter>

Specify the infrared emulation i.e. how to communicate with the RCX. In the real RCX an IR transmitter is connected to the serial interface of the microcontroller that sends and receives serial data via infrared. In the simulator you have the possibility to use UDP packets to simulate the connectionless IR communication or a pseudo terminal to simulate the serial connection to a host. If you use the serial interface to output debugging data you may just be interested to display your output. For this purpose you can use stdout or GDB's virtual console to output the serial data. The default is equivalent to: -ir=UDP:8000.

-ir=UDP[:<port>]

Use UDP packets to represent IR communication. This is the default. A UDP port may be specified that is used to listen for incoming packets. Data that is send to this port is accepted by the simulator and transformed into incoming serial data. Outgoing serial data is send to the last UDP port a packet was received from. (If no data was received yet, the data is send to UDP port 8001.)

-ir=PTY:<filename>

Use a device e.g. a pseudo terminal to emulate IR communication. The name of the device file must be specified e.g. -ir=PTY:/dev/ptyp1. The simulator transforms data read from this device into incoming serial data. Outgoing serial data is written to this device.

-ir=GDB

Interpret outgoing serial data as ASCII characters and send them to GDB's console. If GDB support is not activated print the characters to stdout. Receiving of data is not possible.

-t

Trace mode: display each instruction as it is executed.

-V

Verbose mode: display the register contents after each instruction.

-S

Step mode: stop after each instruction and wait until a key is pressed.

-I

Debug Interrupt mode: display occurring interrupts.

-C

Debug Communication mode: display the data transferred via the simulated serial communication interface.

-P

Debug Periphery mode: display all accesses to the microprocessors periphery.

-d

Display the debug window during simulation. The debug window shows some information of the simulator state:

the contents of the control registers of the periphery
the communication with a connected GDB
the data transfer to the simulated display driver via the simulated I²C bus
the current CPU state (= a message when the simulated CPU switches into a power-saving mode)

Furthermore six buttons are controlling the debug options and output on stdout.

"Step" switches to step mode (waits for input after each instruction) (see -S)
"Trace" displays each instruction as it is executed (see -t)
"Verbose" displays the register contents after each instruction (see -V)
"Port" displays all accesses to the microprocessors periphery (see -P)
"IRQ" displays occurring interrupts (see -I)
"SCI" displays the data transferred via the simulated serial communication interface (SCI) (see -C)

All these options can be turned on either by command-line parameters, via the debug window or, during simulation, with key commands to stdin. The following key commands are accepted: t, v, s, i, c, p toggling the respective debug mode (trace, verbose, step, dbgIRQ, dbgSCI, and dbgPort). Furthermore G activates a GDB trap if the GDB stub is active and Q can be used to quit the simulation.

-gdb

Activate the GDB remote debugging stub.

-gdbport <port>

Set the TCP port for the GDB stub (default: 9000).

-nowin

Hide the main window. Useful if you are not interested in the LCD output. Speeds up the simulation.

-p <priority>

Set the priority of the simulation thread between 1 and 10. Without this option the simulation threads runs at the lowest priority giving enough CPU cycles to the Java SWING framework to compute the GUI. Increasing the priority may result in a very slow (and therefore wrong) GUI update (especially on slow machines).

Using GDB with the RCXSimulator

Firmware Download

The easiest way to use the simulator with a firmware is to use the command line option -f and a modified ROM image.

Another way is to use the unmodified Lego ROM image and load a firmware file with the emulated serial interface. The serial interface is ether simulated by a network connection or by a Linux device. If you specify the command line parameter -u a UDP port is opened and incoming packets are handled as if they are coming from the serial interface of the microcontroller. A little Java program (FWdown) is available that can be used to download a firmware file to the simulator.

Alternative: A Linux device driver is available that simulates the Lego infrared tower. It provides two entries in the device filesystem. One entry should be used by the simulator. Command line parameter -c is used to provide the name of this Linux device file to the simulator. The other entry can be used like any other serial device file by any existing download program (like firmdl3).
(The Linux device driver copies all data written into one device file to the other device file where it can be read. A similar effect can be achieved by using a pseudo terminal (e.g. /dev/ptyp1 and /dev/ttyp1 if available). However some firmware-download software (e.g. an unmodified version of firmdl) does not accept the pseudo terminal as device).

Getting a ROM Image

To simulate a complete RCX brick a ROM image is necessary. The original Lego ROM is copyrighted by Lego and is, therefore, not included. But you can extract one out of your RCX brick. Kekoa Proudfoot wrote a good documentation how to get a ROM image of a RCX brick.
The modifications to the original Lego firmware, described on that web page, are combined in this patch. The patch can be applied on the firmware v3.09 (/firm/firm0309.lgo on the Mindstorms CD included with the RCX 1.0).

A Modified ROM-Image

When the simulator is started the execution starts with code in the ROM. If you are using the ROM image that you have extracted from your RCX, the ROM program is able to receive a firmware from the serial interface. Multiple possibilities to transfer the firmware via the simulated serial interface are described above.
All these possibilities have the drawback that they are rather slow and error-prone due to incorrect timing of the simulation.

A very convenient way to install a firmware is to load it when the simulator starts. With the command line option -f you have the possibility to specify the filename of a firmware file (in SREC-format). The data in the file is installed in the simulated memory before the simulation is started. However, the original Lego ROM code does not know about the firmware we have loaded into memory. Thus we have to modify the ROM image in a way that it jumps directly to the entry point of the loaded firmware after the system is initialized. This patch contains the necessary modifications for the ROM image of the RCX 1.0. To apply the path you have to do something similar to the following:
patch ROM.srec ROMPatch.diff
The patched ROM program jumps to the address 0x8000 after the peripherals are initialized. If you use this patch make sure that your firmware starts at 0x8000, the typical entry point for RCX firmwares.