Java Virtual Machine version 1.5 for Korebot II
 with Khepera3 interface class

Copyright (C) 2013 K-TEAM SA

version
   1.3 2013.08.15 JT: added awt et peer
   1.2 2012.04.02 JT: corrected compilation line of 4)
   1.1 2012.01.20 JT: added interface for libkorebot and Khepera3 functions
   1.0 2012.01.09 JT: first draft


-------------------------------------------------------------------------------
--- 1) Instructions for Installing the java virtual machine on the Korebot II -

The Java virtual machine is not installed by default on the Korebot II.

  - You will find from the link below the packages files to install
   for having the Java virtual machine on the KorebotII of your KheperaIII.

	   http://ftp.k-team.com/KorebotII/software/common/java_vm/ 
	   
	   classpath-common_0.96.1-r2_armv5te.ipk
	   classpath-dev_0.96.1-r2_armv5te.ipk
	   classpath_0.96.1-r2_armv5te.ipk
	   jamvm_1.5.0-r0_armv5te.ipk
	   libgtkpeer.so
	   libjawt.so
  	   
	          

  - Download and transfer them to the robot and install them with the command: 

	    ipkg install PACKAGE_NAME
	    

	  for each, where PACKAGE_NAME, is any of the file finishing
	  by .ipk extension inside the directory of the link above.
	  Install the package javavm_ at the end.
      
  - Copy libgtkpeer.so and libjawt.so to /usr/lib/classpath onto the korebot.     
	
  - Install also the Khepera3 interface library file by copying libKhepera3.so file
	  from http://ftp.k-team.com/KorebotII/software/common/java_vm/Khepera3_java_20120120.zip
	  into the directory /usr/lib of the Korebot2.
    

-------------------------------------------------------------------------------
--- 2) Testing and start developping ------------------------------------------

You can test and start developping in Java with the instructions below:

  - install the java compiler openjdk-6-jdk (command on Ubuntu): 
		  sudo apt-get install openjdk-6-jdk
   

  a) "Hello World" example
   - Create a file Hello.java with the following lines on the computer:

		  /* Hello.java */
		  public class Hello
		  {
			  public static void main(String[] args)
			  {
				  System.out.println("Hello world!");
			  }
		  }

   
	  and compile it with the command: javac Hello.java
	  Or use your favorite java compiler.
	
   	=>  This will create a file named Hello.class

   - transfer the file Hello.class on the Korebot II and run it with:
   	 
   	 java Hello
   
	   => This should return: Hello world!
	   
	   
  b) start from the Khepere3.java example:

  - extract the sources from 
	   http://ftp.k-team.com/KorebotII/software/common/java_vm/Khepera3_java_20120120.zip 

  - modify and add your code inside the part 
	  "// main program public static void main(String[] args) "

  - compile the program with: javac Khepera3.java

  - on the Korebot2, execute this for adding the library path for finding the libKhepera3.so and other needed libs:
  		export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/lib:/usr/lib/classpath

  - transfer Khepera3.class to the Korebot2 and run it with:
		  java Khepera3  


-------------------------------------------------------------------------------
--- optionnal 3)- Instructions how to (re-)build the java virtual machine -----

The machine was build with the commands below. Execute it only if you want
to rebuild or patch the java virtual machine.

  - You need the Korebot II full toolchain  ( see Korebot II User Manual
	  and files on the dvd or there: 
	    http://ftp.k-team.com/KorebotII/software/full_toolchain/).

  Then with the commands below, build the java virtual machine and its library:

  - Open a terminal and go to the directory /usr/local/korebot2-oetools-1.0/ 

  - Execute this command to have access to the variables: source extra/profile

  - then install the java compiler on your computer (on Ubuntu):
	    sudo apt-get install openjdk-6-jdk

  - build the the classpath packages:  
	    bitbake classpath
	   
  - and the virtual machine:
	    bitbake jamvm

	  => These 2 last steps will produce the packages there: 
	     /usr/local/korebot2-oetools-1.0/tmp/deploy/glibc/ipk/armv5te
	    
		   classpath-common_0.96.1-r2_armv5te.ipk
		   classpath-dev_0.96.1-r2_armv5te.ipk
		   classpath_0.96.1-r2_armv5te.ipk
		   jamvm_1.5.0-r0_armv5te.ipk 

	  Instructions were adapted from:
	    http://wiki.gumstix.org/index.php?title=Category:How_to_-_JAVA


-------------------------------------------------------------------------------
-- optionnal 4) Instructions how to (re-)build the Khepera3 interface library -

You can rebuild the Khepera3 interface library for adding new functions
or modify parameters.

  - extract the sources from 
   http://ftp.k-team.com/KorebotII/software/common/java_vm/Khepera3_java_20120120.zip 

  - If you would like to add some new function:
    - add the declaration of the new function in Khepera3.java, in the beginning
      (under "// methods available" comment).
    
    - update the Khepera3.h header with the command: javah Khepera3
    
    - add the new declaration of Khepera3.h in libKhepera3.c and transform
      this function declaration into the definition by adding code inside.
      
  - cross-compile the interface library libKhepera3.c:
    - firstly, source the env.sh, as mentionned in the "Korebot 2 user manual",
      chapter 4.4.2.
	
	  - cross-compile with the command (one line):
	     arm-angstrom-linux-gnueabi-gcc -shared libKhepera3.c -o libKhepera3.so
	      -I /usr/lib/jvm/java-6-openjdk/include -I $INCPATH -L $LIBPATH -lkorebot  
	      
	      
	   => This will create the library libKhepera3.so.   

-------------------------------------------------------------------------------