HOWTO

Ubuntu Armedeus HOWTO:

• Talk to linux on the armadeus using a serial line:

  First, plug in your USB<>Serial converter to your computer, and then
  connect a null-modem serial cable from the serial converter to the
  armadeus.  Make sure the armadeus is powered up

  To talk to the armadeus, we use two vt100 serial terminal emulator 
  programs.  Here's how you install them:

	> sudo apt-get install gtkterm ckermit

  You will need to have access to the serial device, which means you need to 
  be in the "dialout" group.  Add yourself with this command:

	> sudo usermod -a -G dialout $USER

  ○ Setting up gtkterm

    Fire up gtkterm:

	> gtkterm

    You will need to set up gtkterm to use the right port and baud rate.  Go 
    to the "Configuration -> Port" menu item.  Select "/dev/ttyUSB0" as the 
    port and select "115200" as the speed.

    At the gtkterm prompt, hit the enter⏎ key.  You should see a login
    prompt:

	Welcome to the Armadeus development environment.
	armadeus login: █

    Type in

	> root

    And hit enter⏎.  It should return "# █".  You are now at the linux 
    prompt on the armadeus, logged in as root.

    You will want to save your configuration.  Go to 
    "Configuration->Save configuration" and type in "armadeus".  You can now 
    load this configuration when you restart GTKTerm by going to  
    "Configuration->Load configuration" and selecting "armadeus"

    You probably want to exit the login shell by typing

	# exit

  ○ Setting up kermit

    You can connect to the armadeus with kermit in the containing this howto
    by typing:

	> kermit -y configs/kermrc -c

    It will then output

	Connecting to /dev/ttyUSB0, speed 115200
	 Escape character: Ctrl-\ (ASCII 28, FS): enabled
	Type the escape character followed by C to get back,
	or followed by ? to see other options.
	----------------------------------------------------
	█

    Hit the enter⏎ key and you should either see the linux login prompt or
    a shell prompt "# █".  If you are in login prompt, you can login to root
    by typing "root".  If you want to quit kermit, type 

	"ctrl-\" followed by "Q"

    You can access the online documentation in kermit by typing
 
	"ctrl-\" followed by "?"

    This displays other commands that kermit accepts.

    The "-y configs/kermrc" option tells kermit to use a custom 
    initialization file.  If you want these settings to always be loaded, 
    type at the ubuntu shell:

	> cp configs/kermrc ~/.kermrc

    I prefer kermit over gtkterm, because a real terminal program lets me 
    scroll back in history while gtkterm does not.

  ○ Set Up kermit & screen

    I personally find the fact that kermit only allows one terminal to 
    connect to the armadeus to be annoying when moving back and forth between
    workstations.  So I suggest using "screen" to solve this problem.

    Screen allows for session management of shell commands.  Under screen,
    a shell command can be disconnected and then connect to again later.

    To use screen to allow multiple shells to connect to a kermit session, 
    you need to set a configuration:

	> echo multiuser on >> ~/.screenrc

    Now if when you want to start kermit type:

	> screen -S KERMIT kermit -y configs/kermrc -c

    You can disconnect from the screen session by typing 

	"ctrl-a" followed by "d"

    Now that screen is set up, if you want to connect to kermit using
    another shell terminal type:

	> screen -x KERMIT

    Be aware that all of the screen sessions will be mirror images of 
    one another.  Also, using kermit like this will break "make install" 
    commands that invoke kermit.

• Set Up Networking & TFTP for sending files to the Armadeus

  ▶ TFTP
    First thing is that you need to download the tftp server in Ubuntu:

	> sudo apt-get install tftpd xinetd

    Next, you need to set up the tftp server directory.  This is essentially 
    a drop-box.  The following sequence of commands makes one of these 
    directories, along with an appropriate set of permissions:

	> sudo mkdir -p /srv/tftp
	> sudo chmod 777 /srv/tftp
	> sudo chown nobody.src /srv/tftp

    You'll also need to set up tftp's configuration file.  A suitable settup 
    is available in the configs/ directory, which you can copy to your
    system:

	> sudo cp configs/tftp /etc/xinetd.d/

    Next, you'll need to restart xinetd.d, which controls tftpd

	> sudo /etc/init.d/xinetd restart

    To verify that tftpd is working, type:

	> netstat -a | grep tftp

    Which will return:

	udp        0      0 *:tftp                  *:*

    For testing purposes, we will want to put a test file in /srv/tftp:

	> echo "Hello world tftp" >> /srv/tftp/hello

    Now to retrieve this file is a matter of getting the correct

  ▶ Networking

    In practice, there are two ways to network the armadeus: DHCP and 
    assigned IP.

    ◈ DHCP

      Use gtkterm or kermit to connect to the armadeus, and log in as root.
      The type at the prompt on the armadeus:

	# udhcpc

      This will start a dhcp client on eth0; you can verify that it has been
      assigned by typing:

	# ifconfig eth0

      You can use the same command in linux to figure out Ubuntu's IP 
      address.  Once you know ubuntu's IP address, you can use tftp to copy
      "hello" as follows:

	# tftp -g -r hello <UBUNTU_IP>

      *** The file we put in /srv/tftp should now be in the current ***
      *** working directory on the armadeus.  Type "cat hello" to   ***
      *** verify this.                                              ***

      Finally, if you want the armadeus to always boot up and connect to
      the web with DHCP, then copy the contents of "configs/interfaces" to
      "/etc/network/interfaces" on the Armadeus

    ◈ Assigned IP

      A DHCP network connection is not always available or desirable; 
      for instance you may just want ubuntu to talk to the armadeus with an
      ethernet crossover cable, or through an ethernet hub without a router.

      You can assign the armadeus ethernet card to the ip address 
      "192.168.0.3" using the following:

	# ifconfig eth0 192.168.0.3 up

      On my Ubuntu computer, my physical ethernet card is device "eth1".  To
      assign it an ip address, I use the same command as the armadeus:

	> sudo ifconfig eth0 192.168.0.2 up

      To copy "hello" now from Ubuntu's /srv/tftp/, type at the armadeus:

	#  # tftp -g -r hello 192.168.0.2

• Install the Armadeus Toolchain
  
  The armadeus toolchain is a convenient collection of cross compilers, 
  embedded linux kernels and examples distributed by the armadeus 
  manufacturers.

  You will first need to download a lot of development software:
	> sudo apt-get install build-essential gcc g++ autoconf automake \
                               libtool bison flex gettext patch subversion \
                               texinfo wget git-core libncurses5 \
                               libncurses5-dev zlib1g-dev liblzo2-2 \
                               liblzo2-dev libacl1 libacl1-dev \
                               uuid-dev libglib2.0-dev libnetpbm10-dev

  You should get the latest stable release, v3.3:

  http://downloads.sourceforge.net/project/armadeus/armadeus/armadeus-3.3/armadeus-3.3.tar.bz2

  You can also get a snapshot of the latest version with git.  Details on 
  how to do this can be found here:

  http://www.armadeus.com/wiki/index.php?title=Toolchain#Get_Armadeus_software

  I recommend the stable release.  Once it's downloaded, untar it and change 
  into that directory:

	> tar jxfv armadeus-3.3.tar.bz2
	> cd armadeus-3.3
  
  You'll need to configure the toolchain for your board.  If you are like 
  me, you have the apf27:

	> make apf27_defconfig

  

• Flash the Latest Version of Linux onto the Armadeus

• Install the XILINX WebPack for Bitmap Synthesis

  To do this, I followed the instructions here:

  http://www.armadeus.com/wiki/index.php?title=ISE_WebPack_installation_on_Linux

  The first step is to make sure that the following packages are installed 
  in ubuntu:

	> sudo apt-get install libstdc++5 libmotif3 libxp6 libcurl3

  The next step is to download whatever the latest version of the Xilinx 
  ISE.  Go here and download the linux version:

  http://www.xilinx.com/ise/logic_design_prod/webpack.htm

  I recommend making a new account; this will ensure that you have a license
  for the WebPack software.

  As of January 10, 2011 The WebPack is 3.5 GB, so I recommend when 
  downloading that you find something else to do for ~16 hours.

  <FIXME: FINISH TUTORIAL>

• Install GHDL + GTKWave for Bench Tests

• Install SciPy for Plotting HETE SXC Simulations