Introduction

This document describes how to install an
OpenWrt
kernel and rootfs on the internal NAND flash of the
Seagate FreeAgent DockStar™
so that it will boot into OpenWrt at power-on, with no USB storage
device required.

The main method presented here does not require opening the case or
attaching a serial cable, just using the Linux command line on the
DockStar. But I also describe a method that does use a serial cable
to interact with the u-boot bootloader. This was the approach I
initially used to get OpenWrt working on the DockStar, but it should
only be necessary now if the first approach fails for some reason.

Important: if possible, do not connect your DockStar
to the outside Internet prior to re-flashing. Otherwise the factory
firmware will automatically "phone home" and modify itself, making it
more difficult to connect via ssh.

Insert the USB drive in the DockStar, mount it somewhere, and change
to that directory:

# mount /dev/sda1 /mnt
# cd /mnt

Make a backup of the factory firmware onto the USB drive if you think
you might want to restore it some day.

Set the magic u-boot parameters. These are case-sensitive, so make
sure you type them correctly.

# ./blparam arcNumber=2097
# ./blparam mainlineLinux=yes

Now you're ready to flash the kernel and rootfs images onto your
DockStar. WARNING: perform the following steps in exactly this
order, and double-check everything you type before
hitting return. If you overwrite the u-boot partition by
mistake, you will brick your DockStar and you will have to
use a JTAG cable to recover.

Erase the rootfs_data partition so that OpenWrt will
create a jffs2 overlay filesystem there when it boots. It's OK if
this step fails with a "read-only filesystem" error.

# flash_eraseall /dev/mtd3

That's all there is to it. Unmount and remove the USB drive and
power-cycle the DockStar. It should reboot into OpenWrt.

If you're using my pre-built images, it will request an IP address via
DHCP. If you compiled your own firmware and
didn't change the default configuration, it will use the static
address 192.168.1.1.

Upgrading the firmware with new OpenWrt images

After you've installed OpenWrt on your DockStar, configured it to
your liking, and used it for a while, you will eventually want to
upgrade the firmware (to a new OpenWrt release, or a custom build with
additional kernel modules, for example).

I've used the following procedure to upgrade my DockStar from one
version of OpenWrt to another.

Make a backup of your DockStar, because you will be re-flashing it to
the default configuration. I use rsync for this.

Copy at least the /etc/config directory. Depending on
your setup you may want to back up additional files. It's also useful
to save the list of additional packages you've installed:

# opkg list_installed

Build or download the new firmware (uImage and rootfs) that you want
to flash. Make sure the files are padded to a 128K multiple.
Transfer them to the /tmp directory on the DockStar using
scp,rsync, or a USB drive.

Login to the DockStar and execute the following. You may need to
install the mtd-utils package on your DockStar if
the flash_eraseall and nandwrite utilities
are not found.

Miscellaneous tips and tricks

Here are some things I've found helpful when using my DockStar with OpenWrt.

Configuring the LEDs

You can use the Luci web interface
(under System > LED Configuration)
to set up the LEDs, or edit /etc/config/system.
For example, I have my green LED configured to blink on
network activity using the following settings:

If you're not using the top connector for a
Seagate FreeAgent Go™ drive,
I recommend a female 5-pin mini-USB to female USB adapter
(available
here
or
here).
They fit well and make the top connector more useful for conventional
USB devices. It would be nicer if they came in white, but you can't
beat the price.

Building your own OpenWrt kernel and root filesystem images

You need to build your own OpenWrt kernel and root filesystem image,
because OpenWrt's Marvell Kirkwood target currently supports only the
Sheevaplug, which has a different NAND flash layout.

Use make menuconfig to configure the build system for a kirkwood
target. Add squashfs in the target images section. Also select
built-in luci and ntpclient packages.

Use make kernel_menuconfig to add built-in SCSI disk, USB
EHCI, USB storage, and ext2 filesystem support. (This step isn't
required, but I recommend it. It will allow you to boot from a USB
flash drive if the root filesystem on internal flash is corrupted.)

Rebuild the kernel with make at the top level. The kernel
image will be in bin/kirkwood/openwrt-kirkwood-uImage.

Pad the kernel image to a multiple of 128K bytes:

# dd if=openwrt-kirkwood-uImage of=dockstar-uImage bs=128k conv=sync

Prepare the rootfs image.
Do not use the squashfs file in bin/kirkwood.
(It is a combined image with both the kernel and the root filesystem.)
Instead, cd to build_dir/linux-kirkwood and run the
command

Connect your DockStar to your network and use a terminal program like
minicom to connect to it (speed 115200, no flow control). Power-on the
DockStar. You should see the u-boot output as it boots. Type any
character to interrupt the boot sequence:

Use the setenv command in u-boot to set the
ipaddr and netmask variables for the
DockStar's IP address, and the serverip variable
to the IP address of your TFTP server.
Check that you have connectivity by doing

CE>> ping $(serverip)

Now you're ready to flash the kernel and rootfs images onto your
DockStar. WARNING: perform the following steps in exactly this
order, and double-check everything you type before
hitting return. If you overwrite the u-boot partition by
mistake, you will brick your DockStar and you will have to
use a JTAG cable to recover.

Type reset, or just power-cycle the DockStar. It should
boot into OpenWrt.

Troubleshooting

While getting this to work, I occasionally observed incorrect writes
to the rootfs partition. If your kernel boots but fails to find the
root filesystem due to errors in the squashfs root partition, that
might be the problem. (But that symptom can also be caused by flashing
a squashfs image that is not 128K-aligned, so check that also.) The
following steps may allow you to recover.

If you didn't do the "recommended" part of configuring your kernel
(enabling support for USB storage and ext2), do it now, then rebuild
the kernel and re-flash it.

Format a USB drive with one partition containing an ext2
filesystem. As root, un-tar the contents of
bin/kirkwood/openwrt-kirkwood-rootfs.tar.gz onto the USB
drive, and also copy the dockstar-rootfs
image onto the drive (as a regular file).