The SheevaPlug installer

The SheevaPlug installer is documented at Plug Computing and NewIT. What follows is a simplified description of the SheevaPlug Installer. We battled a little with existing documentation and installer, this is our attempt to bypass the issues that were encountered.

Even if you have the supplied plug working fine without the installer, sooner or later you will need to use it.

The instructions provided here are for a Linux host. We will soon add a similar page for a Windows host.

Overview

The NAND RAM on the plug contains 3 entities of importance, namely; a boot image & environment, the kernel image and the root file system. The NAND maybe formatted as a JIFFS2 file system (which is the factory default), the alternative file system, UBIFS, provides more speed and faster boot up times. In fact we are not too sure why one would use JIFFS2 in preference.
Regardless of which file system that you are using the NAND will contain the 3 listed entities. The installer will reflash the NAND with a new boot image, kernel image or root file system. If you only wish to update the kernel then the kernels and scripts available at sheeva.with-linux.com can be used to update your plug. The SheevaPlug Installer by contrast will rewrite everything on the plug NAND, backup before you start!.
Note that the installer will also convert the NAND to a UBIFS file system.
Q. Why do I need the installer?
A. A bricked plug, a new kernel, a new boot image, a new OS or all of the above.

The README.txt in the installer package provides a reasonable description of the installer process.


Prerequisites

  • Install cu
    # apt-get install cu
  • Install libftdi
    # apt-get install libftdi1
  • Install php5-cli
    # apt-get install php5-cli
  • Install the installer. Download and unzip the archive.
  • An empty FAT32 USB stick.
  • Modified scripts for the installer. runme.php, runme.sh and uboot-dual-custom.txt from NewIT.
    Add these scripts to the installer directories. The runme.sh script is a shell version of the PHP script and is an alternative if you do not wish to install PHP. The remainder of this document assumes that you are using the runme.php that we provide.

The installer copies uboot.bin, uImage, modules.tar.gz and rootfs.tar.gz to the plug. Some improvement can be made by using more recent versions of uBoot and the kernel. For our preconfigured plugs the kernel is a 2.6.3*.* kernel from sheeva.with-linux.com. The uBoot we use (uboot.bin 3.4.27+pingtoo patch). We use the installer distribution roots.tar.gz with some minor modifications.

Before you proceed, backup! You can destroy all software on the plug.

The installer readme states:

1.  Prepare an empty USB stick that is FAT16/32 formatted.
2.  Download the installer tarball to your PC and unpack it to your working
     directory (for example: ~/work/sheevaplug-installer)
3.  Edit the ~/work/sheevaplug-installer/installer/uboot-custom.txt file to burn
     the correct MAC address according to the MAC address on the back of the
     Plug (change the ethaddr value)
4.  Populate the USB stick with a all files inside the installer directory.
    NOTE: that the files should be written to the root directory of the USB stick.
          For example if the recovery directory is sheevaplug-installer and USB
          stick mount is: /media/usb run on the host Linux PC:
          sudo cp -a ~/work/sheevaplug-installer/installer/* /media/usb/
5.  Copy the following to the USB stick root directory:
      a. Root file-system (packed into rootfs.tar.gz)
      b. Kernel (named uImage)
      c. Kernel modules (packed into modules.tar.gz)
      d. Init ramdisk (uImage.initrd)
    If you do not have all, you can download from:
      a. http://plugcomputer.org/index.php/us/resources/downloads (distro, kernel(LSP), uboot)
      b. http://plugcomputer.org/plugwiki/index.php/Main_Page     (distrio,uboot)
      c. http://sheeva.with-linux.com/sheeva                      (mainline kernel+modules)
6.  Copy the uboot image (named uboot.bin) to the ~/work/sheevaplug-installer/uboot/
    directory (use prev bullet links as sources)
7.  Safely remove the USB stick from the host PC and plug it into the Plug's USB
    host interface (not via USB HUB!)
8.  Connect the power to the Plug
9.  Connect the mini USB connector to the Plug (not via USB HUB!)
10. On Win PC, close any connected console (tera-term, tutty, RealTerm...), since
    the flash burning is done via this port
12. On the host PC, change the working directory to ~/work/sheevaplug-installer
    and run the runme.php file (or the runme.exe on Win host PC). (on Linux PC you
    should be root in order to do that) When the runme finishes it will beep to
    indicate that the flash burning process  finished.
    On Win PC:
      a. wait for the uboot.bin to be burned (you should see:
         "wrote file uboot.bin to NAND flash 0 up to offset 0x00073000 in 112.746002s")
      b. exit the runme.exe program by executing Control+C
      c. disconnect the mini USB and reconnect
      d. wait for Windows to idevntify the new inserted mini USB
      e. you can open your serial (like putty) only now.
13. On a Linux PC. if the installer is unattended, watch the console and wait until the
     whole process is done.
14. If the installer is an interactive one (like Debian network installer) then
     watch the console for messages and act accordingly.

Invocation

Our modified PHP script runme.php is invoked as:

  php runme.php [nand | mmc ] MAC

   where MAC is the MAC address of the plug (see the back of the plug).

Using the modified script means that you do not have to edit the custom script for the MAC address.

Flashing NAND
Use the "nand" option. The uboot-dual-custom.txt will be used to build a multi boot plug. The U-Boot, the kernel and the OS will be (re)written to the plug NAND.

e.g. php runme.php nand 00:50:43:01:99:99
Refer to this NewIT discussion.
This gives you a plug that will boot from NAND or boot from the SD when the SD is inserted.
We have had no reported difficulties using this invocation, all credit to New IT.

Creating an SD card with kernel and OS installed.
Whilst you can use the installer to do this, we recommend that is simpler and easier to format the card yourself and copy the required components to the card. Further, it means that you do not clobber the the NAND setup each time that you use the mmc option. All you need to do this is, a card writer on your host Linux machine (or use a SheevaPlug) and the provided prepsd.sh script. The initrd in the installer partitions and formats the SD cards as follows:
 echo -e "n\np\n1\n\n+4M\nn\np\n2\n\n\nw\n" | fdisk /dev/mmcblk0
 mkfs.ext2 -L shvplug-uImage /dev/mmcblk0p1
 mkfs.ext3 -L shvplug-rootfs /dev/mmcblk0p2
Performing this operation in a shell script is a bit quicker and allows you to correct any errors that may be encountered. Consult the provided prepsd.sh script for more details.

Flashing the plug with TFTP

Copy the file uboot.bin to your host system TFTP server. Then start your SheevaPlug, connect the serial console and type the following commands:

setenv serverip 192.168.20.37 # IP of your TFTP server
setenv ipaddr 192.168.0.33
bubt uboot.bin

The upgrade process will ask whether you want to change the environment, the correct answer is no


Flashing the plug with a USB stick

Copy the file uboot.bin to your USB stick, then:

usb start
fatload usb 0:1 0x0800000 uboot.bin
nand erase 0x0 0xa0000
nand write.e 0x0800000 0x0 0xa0000



Back
 
Spinifex Computing Copyright © 2011 Spinifex Computing Pty. Ltd. All rights reserved.