nxtOSEK/lejos_nxj/README.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">\r
   2 <html>\r
   3 <head>\r
   4   <title>leJOS NXJ, a Java system for the Lego Mindstorms NXT</title>\r
   5 </head>\r
   6 <body style="background-color: rgb(255, 255, 255);">\r
   7 <ul>\r
   8   <li><a href="#what_is_lejos">What is leJOS NXJ?</a></li>\r
   9   <li><a href="#preliminiaries">Preliminiaries</a></li>\r
  10   <li><a href="#installation_and_set_up">Installation and Set Up</a></li>
  11   <li><a href="#using-lejos">Using leJOS NXJ</a></li>
  12   <li><a href="#compiling">Compiling and running your first code</a></li>\r
  13   <li><a href="#tools">LeJOS NXJ Tools</a></li>\r
  14   <li><a href="#limitations">Known limitations in leJOS</a></li>\r
  15   <li><a href="#bugs">Known bugs in leJOS</a></li>\r
  16   <li><a href="#nxjbugs">Known bugs and limitations in leJOS NXJ</a></li>\r
  17   <li><a href="#documentation">Documentation</a></li>\r
  18   <li><a href="#license">License</a></li>\r
  19   <li><a href="#questions">Questions and Problems</a></li>\r
  20 </ul>\r
  21 <h1><a name="what_is_lejos">What is leJOS NXJ?</a></h1>\r
  22 <p>leJOS (pronounced like the Spanish word "lejos" for "far") is a
  23 tiny Java-based operating system that has been ported to the following platforms:</p>\r
  24 <ul>\r
  25   <li>LEGO Mindstorms NXT</li>
  26   <li>LEGO Mindstorms RCX</li>\r
  27   <li>Unix (for emulation of leJOS programs only)</li>\r
  28   </a>\r
  29 </ul>\r
  30 <p>leJOS was originally forked out of the </a><a\r
  31  href="http://tinyvm.sourceforge.net">TinyVM project</a>. <br>\r
  32 It contains a VM for Java bytecodes and additional software to load and\r
  33 run Java programs.</p>
  34
  35 These are some of the features offered:\r
  36 <ul>\r
  37   <li>Object oriented language (Java)</li>\r
  38   <li>Preemptive threads (tasks)</li>\r
  39   <li>Arrays, including multi-dimensional ones</li>\r
  40   <li>Recursion</li>\r
  41   <li>Synchronization</li>\r
  42   <li>Exceptions</li>\r
  43   <li>Java types including float, long, String, but with some restrictions</li>\r
  44   <li>Math class</li>
  45   <li>Well-documented Robotics API</li>\r
  46 </ul>\r
  47 \r
  48 <p>leJOS NXJ is the version of leJOS for the LEGO Mindstorms NXT. \r
  49 It uses the same Java VM as the RCX version, but has new drivers for the NXT hardware.\r
  50 </p>\r
  51 <p>leJOS NXJ adds lots of new capability to leJOS including a file system, a menu system,\r
  52 and support for I2C sensors, including those from third parties. The built-in tachometers in\r
  53 the NXT motors have enabled much improved control over speed, steering and navigation.\r
  54 </p>\r
  55 <p>Bluetooth and USB communications are a great improvement over the infra-red link used by the RCX.</p>\r
  56 \r
  57 <h1><a name="preliminiaries">Preliminaries</a></h1>\r
  58 <ul>\r
  59   <li>You need a Java Development Kit (JDK), preferably 1.5 or later.</li>\r
  60   <li>Your PATH must contain the JDK's bin directory.</li>\r
  61   <li>Make sure you have set JAVA_HOME properly to the root directory\r
  62 of the JDK.</li>\r
  63   <li>On systems other than Microsoft Windows, you will need to build the distribution, so your PATH must\r
  64 contain the ant binary (ant 1.7 or above).</li>
  65   <li>You need libusb installed. On Microsoft Windows you should use the libusb-Win32 filter driver.</li>
  66   <li>On Microsoft Windows and MAC OS X you will need the LEGO Mindstorms NXT software installed, as its USB drivers are used.</li>
  67   <li>On MAC OS X systems, you will need the OS X developer tools installed.</li>
  68   \r
  69 </ul>
  70
  71 The libusb filter driver for Microsoft Windows can be obtained from <a href="http://libusb-win32.sourceforge.net/#downloads">http://libusb-win32.sourceforge.net/#downloads</a>. \r
  72 This does not currently work under Windows Vista - see "Known Bugs and Limitations in leJOS NXJ" below.\r
  73 However, it works if you install on Vista under Windows XP compatibility mode:<br/>\r
  74 <ol>\r
  75 <li>Download libusb-win32-filter-bin-0.1.12.1.exe (the version current @ 27/09/07)\r
  76 <li>Right click on this file. Select Properties | Compatibility Click the "Run this program in compatibility mode" box and select "Windows XP (Service Pack2)" from the drop down list.\r
  77 <li>Right click again and select "Run as Administrator". Follow the installation instructions. Run the test program will list the usb devices plugged into your computer, but not new devices.\r
  78 </ol>\r
  79 <br/>
  80
  81 libusb for other systems can be obtained from <a href="http://libusb.sourceforge.net">http://libusb.sourceforge.net</a>.<br/><br/>
  82
  83 On Linux systems, if you are running leJOS NXJ from a non-root user, you will need to ensure that you have read and write access the NXT USB device in /dev/bus/usb.
  84 If you can identify the device in /dev/bus/usb, you can do this by:<br/><br/>
  85
  86 <em>sudo chmod a+w /dev/bus/usb/xxx/yyy</em><br/><br/>
  87
  88 However, the yyy number will count up each time the NXT is disconnected and reconnected.<br/><br/>
  89
  90 A better solution is to use udev rules or pamcomsole. How to do this varies with different Linux systems. A pamconsole solution that works on Fedora Core 5, is to create a file /etc/security/console.perms.d/60-libusb.perms with the two lines:<br/><br/>
  91
  92 <code>\r
  93 &lt;usbdevices&gt;=/dev/bus/usb/*/*<br/>
  94 &lt;console&gt; 0600 &lt;usbdevices&gt; 0644 root
  95 </code>\r
  96 <br/><br/>
  97 \r
  98 To use udev rules, set up a file such as  /etc/udev/rules.d/70-lego.rules and populate it with the following lines: <br/><br/>\r
  99 \r
 100 <code>\r
 101 # Lego NXT<br/>\r
 102 BUS=="usb", SYSFS{idVendor}=="03eb", GROUP="lego", MODE="0660" <br/>\r
 103 BUS=="usb", SYSFS{idVendor}=="0694", GROUP="lego", MODE="0660" <br/>\r
 104 </code>\r
 105 </br>\r
 106 \r
 107 This relies on the username you are using being in the <em>lego</em> group. You can modify the file to your\r
 108 requirements. The two vendors are LEGO and Atmel (for the samba driver used in firmware update mode).\r
 109 You may need to restart udev.\r
 110 \r
 111 <h1><a name="installation_and_set_up">Installation and Set Up</a></h1>\r
 112 \r
 113 <ol>
 114   <li>Extract the files from the distribution. A lejos_nxj subdirectory will be created.</li>\r
 115   <li>Set the environment variable <em>NXJ_HOME</em> to the full path of the lejos_nxj\r
 116 directory.</li>
 117   <li>Add the lejos_nxj/bin directory to your PATH.</li>\r
 118   <li>On Linux and Unix systems, depending on your privilege settings you might need to\r
 119 adjust the execution permissions in the <em>bin</em> directory.</li>\r
 120 </ol>\r
 121 On Linux and Unix systems, you will have to build the distribution first. To do so,\r
 122 switch to the <em>build</em> folder and run <code>ant</code>. You  will need to ensure that the\r
 123 packages that leJOS NXJ is dependent on are on your system. These include libusb-dev,\r
 124 gcj and libbluetooth-dev.\r
 125
 126 <h1><a name="using-lejos">Using leJOS NXJ</a></h1>
 127 <ul>\r
 128   <li>Flash the leJOS NXJ firmware using <em>nxjflash</em>.</li>
 129   <li>Compile using <em>nxjc</em> instead of <em>javac</em>.</li>
 130   <li>Link, upload and run programs using <em>nxj</em>.</li>
 131   <li>Exceptions: Use <em>nxj --verbose</em> to get information on methods and special classes used by your program. Exceptions are shown on the NXT as Method:XXXX, CLASS:YY, where XXXX = method_signature and YY = exception_class_index</li>
 132 </ul>
 133
 134 <p>Your NXT must be plugged into the USB, switched on, and in firmware update mode to run nxjflash. Note that the standard LEGO firmware will be overwritten and all existing data lost. You can reinstall the LEGO firmware using the LEGO Mindstorms software.
 135 </p>
 136 To go into firmware update mode press the reset button (at the back of the NXT , upper left corner) for more than 4 seconds.
 137 Your NXT will audibly tick when it is firmware update mode.
 138 <br/><br/>\r
 139 \r
 140 <p>To run nxjflash, open a command window, and type <em>nxjflash</em></p>\r
 141 \r
 142 <p><em>nxjflash</em> will write the Java VM and the leJOS NXJ start-up menu to the flash memory of your NXT. It will create an empty user flash area. When the flash procedure has finished, leJOS NXJ will start up and an empty menu will be displayed.\r
 143 </p>
 144 <p>You can switch the NXT off at any time, including when a program is running, by pressing the orange and dark gray buttons (ENTER + ESCAPE) together.To switch it back on just press the orange button. The leJOS NXJ start-up menu will be displayed.
 145 </p>\r
 146 \r
 147 If your NXT freezes at any time, remove and re-insert a battery.
 148
 149 <h1><a name="compiling">Compiling and running your first code</a></h1>
 150
 151 To compile, link and download the Tune sample:
 152
 153 <ul>
 154   <li>Open a command window</li>
 155   <li>Check that java and lejos_nxj are on your PATH</li>\r
 156   <li>Check that the NXJ_HOME environment variable is defined</li>
 157   <li>Change to the lejos_nxj\samples\Tune directory</li>
 158   <li>Type <em>nxjc Tune.java</em></li>
 159   <li>Check that your USB cable is connected</li>\r
 160   <li>Check that the NXT is turned on</li>\r
 161   <li>Type <em>nxj -r Tune</em></li>
 162  </ul>
 163
 164 <p>After a few seconds, you should hear an ascending tone sequence indicating that the program uploaded OK. You will then hear a tune play. When it has finished the leJOS NXJ menu will be displayed.</p>
 165 \r
 166 <p>When you switch your NXT back on, select "Files" and press ENTER and you will see "Tune.nxj" in the files menu</p>\r
 167 \r
 168 <p>You can navigate through the leJOS NXJ menus using the left and right buttons. You select a menu item by pressing ENTER, and exit from a menu by pressing ESCAPE. There are 3 menus: Files, Bluetooth ands System. To select a program, go to the Files menu, scroll down to your program and press the ENTER button. You will then see a sub-menu that lets you execute or delete the program.</p>\r
 169 \r
 170 <h1><a name="tools">LeJOS NXJ Tools</a></h1>\r
 171 <p>The following tools are available with leJOS NXJ:</p>\r
 172 \r
 173 <ul>\r
 174 <li><em>nxjflash</em> - flashes the firmware</li>\r
 175 <li><em>nxjc</em> - compiles a Java program for leJOS NXJ</li>\r
 176 <li><em>nxj</em> - links, uploads and optionally runs a leJOS NXJ program</li>\r
 177 <li><em>nxjlink</em> - links a program</li>\r
 178 <li><em>nxjupload</em> - uploads and optionally runs a program</li>\r
 179 <li><em>nxjbrowse</em> - explorer for NXJ files</li>\r
 180 <li><em>emu-lejosrun</em> - emulate a leJOS NXJ program on Unix</li>\r
 181 </ul>\r
 182 \r
 183 <p><em>nxj</em>, <em>nxjupload</em> and <em>nxjbrowse</em> can be used over Bluetooth or USB.\r
 184 By default they try to use USB first, and if this fails, they try Bluetooth</P>\r
 185 \r
 186 <p>Use the <em>--usb</em> flag to select usb only, or <em>--bluetooth</em> for Bluetooth only.</p>\r
 187 \r
 188 <p><em>nxjbrowse</em> displays a list of all the NXTs that it finds, and allows you to select one to connect to. \r
 189 <em>nxj</em> and <em>nxjupload</em>, try each NXT they find in turn until they successfully connect to one. \r
 190 To pick a specific NXT to connect to by name, use the <em>--name</em> flag.</p>\r
 191 \r
 192 <p>You can connect to a specific NXT by address, using the <em>--address</em> flag. If you specify the address, a Bluetooth inquiry will not be done,\r
 193 and the connection will be much faster. Use <em>nxjbrowse</em> to list the addresses of your NXT devices. An address is 12 hex digits with optional colons\r
 194 between the hex pairs.</p>\r
 195 \r
 196 <p>The leJOS NXJ tools can use different comms driver to connect to the NXT. The only driver available for USB is NXTCommLibnxt, \r
 197 which uses David Anderson's libnxt library and the libusb open source library. This works on all operating systems. \r
 198 For Bluetooth on Windows, NXTCommBluecove, which uses the Bluecove open source library, is used. \r
 199 On Linux and MAC OS X, NXTCommBluez, which uses the open source Bluez project, is used for Bluetooth.</p>\r
 200 \r
 201 <p>A future version of leJOS NXJ is expected to support the LEGO Fantom API, which should work for both USB abd Bluetooth.</p>\r
 202 \r
 203 <p>The properties file,lejos_nxt/bin/nxj.properties, can be modified to select different comms drivers,\r
 204 but for this release the defaults are the only available drivers.</p>\r
 205 \r
 206 <p><em>nxjbrowse</em> lists the files on the NXT and includes their size, and start and end pages. \r
 207 It can be used to delete, upload and download programs and other files. \r
 208 It can also run programs, change the name of the NXT and defrag the files,\r
 209 moving them all to the start of user flash memory. Changing the name of the NXT only works over USB.</p> \r
 210 <h1><a name="limitations">Known limitations</a></h1>\r
 211 Due to size constraints, some Java language\r
 212 features have been omitted. Others just haven't been implemented yet.\r
 213 Known limitations with all versions of leJOS are: </a>\r
 214 <ul>\r
 215   <li>Switch statements are not supported</li>\r
 216   <li>Arithmetic operations on variables of type long are not\r
 217 supported, although you can cast ints to longs and vice versa</li>\r
 218   <li>Maximum array length is 511</li>\r
 219   <li>The instanceof operation will always be true for interfaces. In\r
 220 bytecode, CHECKCAST succeeds on all interface classes (which is a bit\r
 221 unsafe)</li>\r
 222   <li>The instanceof and checkcast operations are rejected by the\r
 223 linker when they are performed on array classes (e.g. b instanceof\r
 224 byte[])</li>\r
 225   <li>There are no objects of type java.lang.Class, which means that\r
 226 the ".class" construct won't work. Class.forName() throws\r
 227 ClassNotFoundException at all times. As a consequence, reflection is\r
 228 not supported by leJOS</li>\r
 229   <li>Most JDK APIs are unavailable</li>\r
 230   </a>\r
 231 </ul>\r
 232 <h1><a name="bugs">Known Bugs</a></h1>\r
 233 <p>The following bugs apply to all versions of leJOS:</p>\r
 234 <ul>\r
 235  <li>MONITOREXIT ignores null objects (it assumes\r
 236 MONITORENTER has handled them). Furthermore, it doesn't check monitor\r
 237 validity. Until this bug is fixed (actually, at all times) all monitors\r
 238 should be constants</li>\r
 239   <li>Initializers (static or otherwise) are not implicitly\r
 240 synchronized. This could lead to access of statics before they are\r
 241 initialized, when multiple threads use a class</li>\r
 242   </a>\r
 243 </ul>\r
 244 <h1><a name="nxjbugs">Known Bugs and Limitations in leJOS NXJ</a></h1>\r
 245 <p>The following bugs and limitations apply to the current version of leJOS NXJ:</p>\r
 246 \r
 247 <ul>\r
 248 <li>Occasionally, after flashing the firmware with with nxjflash, the battery level reads as 0.0 and buttons do not respond. If this happens, a battery must be removed and re-inserted. It is not necessary to repeat the nxjflash.\r
 249 </li>\r
 250 <li>leJOS NXJ does not work out of the box on Windows Vista systems. This is due to limitations in libusb-win32 that the leJOS  NXJ Windows USB tools, including nxjflash, rely on. Installing libusb in windows XP compatibility mode should cure the problem.\r
 251 </li>\r
 252 <li>Bluetooth does not work on MAC OS X systems, and the ant build files for MAC OS X are largely untested.  See the forums on the leJOS web site for the latest state of leJOS on MAC OS X.\r
 253 </li>\r
 254 <li>Occasionally, after pressing the orange (ENTER) button to start leJOS NXJ, the LCD remains blank. If this occurs, and is not due to low batteries, it is necessary to shut down leJOS, by pressing the orange and dark gray buttons (ENTER + ESCAPE), and try again.\r
 255 </li>\r
 256 <li>Only one file can be open at a time.\r
 257 </li>\r
 258 <li>leJOS NXJ only supports program upload and download, tools such as nxjbrowse, and LEGO communications Protocol commands when the start-up menu is running, not when a user program is running, unless a user program explicitly starts the LCPBTResponder thread.\r
 259 </li>\r
 260 <li>The number of files that can be uploaded to lejos NXJ is limited by the fact that the whole file table must fit into two 256-byte pages. If the average filename length is 15 characters, approximately 20 files are supported.\r
 261 </li>\r
 262 <li>The maximum filename length is 20 characters.\r
 263 </li>\r
 264 <li>Not all LEGO Communications Protocol command are supported, and the semantics of some of them are different from that of the standard LEGO firmware. In particular only one file can be open at a time and the file handle is always 0.\r
 265 </li>\r
 266 <li>The leJOS NXJ USB driver does not return a unique serial number for each NXT, in the way that the standard LEGO software does. The effects of this are not known, but it may be the cause of lejos NXJ not working with the LEGO fantom API over USB.\r
 267 </li>\r
 268 <li>Java streams over USB are never closed down, and are always open.\r
 269 </li>\r
 270 <li>Reading buttons is not very reliable unless your code takes steps to wait for button readings to stabilize. See the TextMenu code for how to do this.\r
 271 </li>\r
 272 <li>The RCX limitations of the Java VM also apply to NXJ.\r
 273 </li> \r
 274 <li>Sound volume cannot be controlled when playing tones.\r
 275 </li>\r
 276 <li>Support for sound sample files is limited to 8-bit WAV files with a sample rate of 11k.\r
 277 </li>\r
 278 <li>Data aborts occur if there is a failure in the NXJ VM. If a data abort occurs, it is necessary to remove and re-insert a battery.\r
 279 </li>\r
 280 <li>leJOS NXJ does not work with the LEGO Mindstorms PC software, or the LEGO Mindstorms Fantom API.\r
 281 </li>\r
 282 <li>On Windows, using the Bluecove library, NXTs that have been paired with the PC are in the list of available NXTs, even when they are not switched on. This does not happen with Bluez on Linux.\r
 283 </li>\r
 284 <li>Is usually necessary to pair your NXT using the Operating System before it can be connected to by the lejOS NXJ PC tools and libraries.\r
 285 </li>\r
 286 <li>Discovery of Bluetooth devices is slow, taking at least 10 seconds. It is slower still with Bluez on Linux. For Java streams connections from user programs, you can connect directly by Bluetooth address, which is much faster.\r
 287 </li>\r
 288 <li>To get permissions to the lejos NXJ usb devices from non-root users on Linux, you typically need to user pamconsole or udev rules. The instructions for doing this are not very explicit.\r
 289 </li>\r
 290 </ul>\r
 291 <h1><a name="documentation">Documentation</a></h1>\r
 292 The API docs for leJOS NXJ is included in the download. You can also access them on the leJOS web site.\r
 293 <h1><a name="license">License</a></h1>\r
 294 We are continuing to release under the Mozilla Public License\r
 295 (see the LICENSE file). The nxjflash utility using David Anderson's libnxt
 296 which is release under a GPL v2 license (see COPYING in the libnxt directory).\r
 297 <h1><a name="questions">Questions and Problems</a></h1>\r
 298 Please direct feedback to the lejos-discussion\r
 299 mailing list mailto:lejos-discussion@lists.sourceforge.net. <br>\r
 300 To subscribe, see </a><a\r
 301  href="http://lists.sourceforge.net/lists/listinfo/lejos-discussion">http://lists.sourceforge.net/lists/listinfo/lejos-discussion</a>.\r
 302 <p> Feel free to take a look at the <a href="http://www.lejos.org">LeJOS\r
 303 website</a> or its <a href="http://sourceforge.net/projects/lejos">project\r
 304 page</a>. </p>\r
 305 \r
 306 <p>There are forums on the web site that can be used to ask questions, share information on projects, etc.</p>\r
 307 </body>\r
 308 </html>\r