elua/doc/en/installing_avr32.txt

// $$HEADER$$
Installing eLua on the AVR32 CPUs from Atmel
--------------------------------------------
http://www.atmel.com/products/AVR32/[AVR32] is a family of high performance 32-bit CPUs from http://www.atmel.com[Atmel].
They were built as direct competitors for the various ARM core implementation on the market, and offer very good
performance (91 MIPS @ 66MHz) and power efficiency (1.3mW/MHz). Atmel claims that their AVR32 core outperforms ARMv5 
(in ARM and Thumb mode) in terms of both performance and code size. It's a proprietary architecture (so it's only implemented by Atmel), 
yet it has a very good support package, and an open source toolchain based on GCC, which made it an ideal candidate for the first 
non-ARM (and also the first big-endian) eLua target. Atmel also sells a number of development boards based on their AVR23 CPUs. 
The one used for eLua is the _ATEVK1100 board built around the _AT32UC3A0512 AVR32 MCU (512k internal Flash/64k internal ARM).
It's a very powerful board, featuring (among other things) an external 32 MByte SDRAM memory, which is more than enough to run lots and
lots of eLua programs.

NOTE: eLua version 0.8 added support for the AVR32 based _ATEVK1101 and _Mizar32 boards. The instructions below apply for the _ATEVK1101
board too; for _Mizar32 read the note xref:buildnote[here].

Prerequisites
-------------
Before you'll be able to use eLua on the AT32UC3A0512 CPU, make sure that:

* you're using Linux or Windows. It's easier to install and use Atmel's programming software on Windows, so use the Windows version if you want to save
  yourself from quite a bit of hassle.
* you've installed Atmel's http://www.atmel.com/dyn/products/tools_card.asp?tool_id=3886[FLIP programming software], which is what you will need
  in order to burn your eLua image. Installation in easy under Windows (you just need to run a setup package), but it's quite tricky under Linux. 
  The next paragraph outlines the procedure for installing FLIP on Linux.
* you have your eLua image for the AT32UC3A0512 CPU (link:building.html[built] or link:downloads.html[downloaded]). Note that unlike other 
  platforms, the ATEVK1100 needs a .hex file for programming and not a .bin.

Installing FLIP in Ubuntu Linux
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[[buildnote]]
IMPORTANT: The instructions below are somewhat hard to put into practice and reports suggest that they don't work well on all Ubuntu versions.
For updated (and simpler) instructions on how to make FLIP work under Linux and for alternative Linux programming software check
http://code.google.com/p/mizar32/wiki/FlashingFirmware[the Mizar32 wiki page].

Follow the steps below to install FLIP under Linux:

1. download the Linux version of FLIP from http://www.atmel.com/dyn/products/tools_card.asp?tool_id=3886[the Atmel FLIP page]. Save it 
  (or move it later) to your _/usr/local/_ directory (you need to have superuser privileges to do that). At the moment of writing this tutorial, 
  the latest FLIP version is 3.2.1, so this is what we're going to use here.

2. untar the FLIP archive: 
+
------------------------------------
$ cd /usr/local
$ sudo tar xvzf flip_linux_3-2-1.tgz
------------------------------------
+
This will create the _/usr/local/flip.3.2.1_ directory.

3. you need to install OpenJDK if it is not installed:
+
------------------------------------
$ sudo apt-get install openjdk-6-jre
------------------------------------

4. edit _/usr/local/flip.3.2.1/bin/batchisp3.sh_ and add the two bolded lines before at the beginning of the file:
+
[subs="quotes"]
-------------------------------------------------
#!/bin/bash -f

*export JAVA_HOME=/usr/lib/jvm/java-6-openjdk/jre/*
*export FLIP_HOME=/usr/local/flip.3.2.1/bin/*

if [ "$FLIP_HOME" = "" ]; then
-------------------------------------------------

5. you need to edit a binary file this time (_/usr/local/flip.3.2.1/libatlibusbdfu.so_). This happens because FLIP comes compiled for RedHat 
   by default and Ubuntu has different system paths. See http://www.avrfreaks.net/index.php?name=PNphpBB2&file=viewtopic&t=56562[this topic]
   for full details. All you have to do is change all the */sys/bus/usb* strings inside _libatlibusbdfu.so_ to */dev/bus/usb*.

6. add the FLIP directory to your PATH:
+
---------------------------------------------
$ export PATH=/usr/local/flip.3.2.1/bin:$PATH
---------------------------------------------

7. FLIP interferes with a program that comes pre-installed on Ubuntu system, called *brltty*. It's meant to help the visually 
  impaired, so if you don't need it simply remove it (as it seems to interfere with a lot of other USB devices too):
+
----------------------------
$ sudo apt-get remove brltty
----------------------------

Burning eLua to the EVK1100 board
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
After you installed FLIP and added it to your $PATH, burning the eLua image should be quite easy:

* connect your ATEVK1100 board with the PC using an USB cable.
* put your board in DFU mode (this is required for FLIP interaction). To do this:
+
  1. press *on* the on-board joystick and keep it pressed
  2. press the RESET button on the board briefly
  3. release the RESET button
  4. release the joystick

* if you're using Windows and it asks you for a driver, you should install it manually from __c:\Program Files\Atmel\Flip <version>\usb__
* execute this from the command line (the command is the same on Windows and Linux, with a single exception: the FLIP executable name is *batchisp3* in Linux 
  and *batchisp* (without a 3) in Windows):
+
--------------------------------------------------------------------------------------------------------------------------------------------------
$ batchisp3 -hardware usb -device at32uc3a0512 -operation erase f memory flash blankcheck loadbuffer <image name>.hex program verify start reset 0
--------------------------------------------------------------------------------------------------------------------------------------------------

That's all, your eLua image is (finally) installed on your ATEVK1100 board.

// $$FOOTER$$