TinyVM: User's Guide

The information in this guide may only apply to the latest version of TinyVM Unix/CygWin Edition. For the Cross-Platform Edition, please read the Readme.doc file included with that distribution. If you plan to use TinyVM under CygWin, don't forget to read the Windows Notes.

TinyVM Requirements

These are the current requirements for TinyVM, as far as I can tell. (Please let Jose know if you have been successful with other setups).

Linux (See also: Windows/CygWin, Solaris).
JDK 1.1.x or JDK 1.2.x (available at java.sun.com). Other JVMs should also work.
Familiarity with Java or other languages that can run on a JVM.

Installation and Setup

Installation consists of unzipping the file you downloaded. A top-level directory is provided, so there's no need to create one. To complete TinyVM's setup:

Make sure the JDK's bin directory is in your PATH.
Go to TinyVM's directory and run make.
Set RCXTTY to the IR serial port (e.g. /dev/ttyS0 or COM1).
Add TinyVM's bin directory to your PATH setting. Remove previous versions of TinyVM from your PATH.

Example: View

Once installation and setup is completed, type the following commands to test TinyVM:

cd examples/view tvmfirmdl (Wait for double beep) export CLASSPATH=. tvmc View.java tvmld View -d

This particular example yields a linked binary file of about 3 Kb. It takes approximately 30 seconds to download. As soon as the LCD shows a standing man figure, you can press Run to start the View program.

This example allows you to test sensors and motors. Press View to select a sensor or motor. Press Run to activate or passivate a device. Press Prgm to change sensor mode or motor power. To exit this program, press On/Off. The program can be rerun as many times as you like (starting with 0.2.0).

Downloading the Firmware

To download the firmware, run:


tvmfirmdl

Fast firmware downloading was added in TinyVM 0.2.1:


tvmfirmdl --fast

(Note that fast firmware downloading may not work under CygWin 1.1.x).

Alternatively, you can use any of the firmware downloaders available in the public domain, such as Dave Baum's firmware downloader included with NQC :


nqc -firmfast $TINYVM_HOME/bin/tinyvm.srec

Donwloading the firmware will take a couple of minutes at most. The counter will reach 970 or so. Then you'll hear 2 beeps, and the LCD will show a number in the 200s or 300s. This means TinyVM's firmware is in program-download mode.

The number shown in the LCD is the battery power level. For fresh batteries, it should be around 340. I've had TinyVM work with a battery power level of 212, but I do not recommend using it if the power level is below 250.

TinyVM allows other firmware to get downloaded when it is in program-download mode. (You can always get to program-download mode by switching the RCX off and on).

RCX Java Programs

Writing Java programs for TinyVM is not unlike writing programs for other Java environments. However, you should keep in mind that only a small subset of the standard Java APIs is supported by TinyVM. When in doubt, consult TinyVM's API Documentation.

Compiling

To compile Java programs for TinyVM you should use tvmc instead of javac. Note that tvmc is simply a script provided for convenience which calls javac with a special -classpath option value.

NOTE: Do not add lib/classes.jar to your CLASSPATH setting. This will affect other JVMs.

If you try to compile a TinyVM program using only javac, the compiler will not be able to find TinyVM APIs, which are located under lib/classes.jar. If you try to place classes.jar in the CLASSPATH before calling javac, some of the core Java classes from classes.jar might be confused with core Java classes from the JDK's classes.zip file.

Some classes from the JDK's classes.zip (or rt.jar) file might work with TinyVM, as long as no native methods are involved. However, this hasn't been tested and it is not recommended.

Linking

The linking step is one that departs from what you normally would do in other Java environments. The linker in TinyVM produces a binary file containing resolved bytecode, and compact data structures which are somewhat different from those of class files. Component names and other information is not kept. In order to link your program, use


tvmld -o <class>.tvm <class>

This will produce a .tvm file which you can download into the RCX.

Downloading Java Programs

TinyVM's firmware must be in program-download mode (battery power level shown) before you can download any programs into it. If you have another program running in TinyVM, switch off the RCX and then switch it on.

To download a previously linked program, run:


tvm <class>.tvm

The linker (tvmld) can also download programs directly to the RCX. Simply pass a -d option to it, instead of -o, as follows:


tvmld <class> -d

You should see the number of bytes downloaded divided by 100 in the LCD. If nothing happens, make sure the RCX is in range, and try again. If you hear beeps, kill tvm, switch off the RCX, wait until the IR tower's light is off, and try again.

Exceptions

TinyVM will show simple exception/error "traces" for all uncaught exceptions/errors. They will be displayed in the LCD using two numbers: (1) signature of the method where the throwable object was thrown, and (2) index of the object's class mod 10. The linker (tvmld) will dump a list of classes and signatures if you pass a -verbose option to it.

To take an example,

[0000 7]

could mean that a NullPointerException exception (class index 7) was thrown in a main method (method signature 0). To facilitate identification of stack traces, you will also hear a low buzz (like system sound 4) and the LCD will show a wedge right below sensor 2.

NOTE: Uncaught exception traces will suspend your program. To continue, press On/Off.

Performance Tips

Declare your methods to be either private, final or static whenever possible.
The location of non-private virtual methods matters: place your virtual methods close to the top of the class declaration. The same goes for static initializers and main methods.
Local variable access is considerably faster than field access. This even applies to constants.
Accessing array elements of arrays assigned to local variables is faster than field access, but slightly slower than local variable access.
Synchronized methods are slightly more efficient than synchronized blocks.

[ TinyVM ]