Getting a Debian root filesystem on to a single-sided Balloon 3 board

Note March 2012: the procedure in this document is still useful for installing an un-configured Debian root filesystem. However, if you have a fully-configured .tar.gz file of a root filesystem, there's a quicker and easier way of uploading it. See LoadingYourRootFS.

Single-sided Balloon 3 boards do not have the communications connector fitted to the bottom of them, and early builds don't have USB host connections on the Pinko connector either. This means that the procedure described in BalloonSoftwareLoading isn't possible, because it assumes the ability to install from a USB drive.

Downloading the entire root filesystem over the serial port would take forever (for small values of forever) since the image is at least 60 megabytes. This means we've got to make do with the USB slave port, present on the JTAG connector, and some USB networking.

First, get the boot loader, FPGA image (if necessary), 'installer' image and kernel on to your board using bbl as described in BalloonSoftwareLoading.

Boot the board using 'boot flash' (which executes the 'recovery' kernel stored in NOR) and login as root (no password should be needed).

Get USB networking going using the instructions in USBNetworking. Recent versions of the Balloon 3 distribution (get the latest out of Subversion) have USB networking set up by default, so all you need to do is:

ifup usb0

Assuming you configured the host end correctly, you should now have network connectivity.

You can install the boot kernel on your board next. Mount the boot partition:

mount /mnt/boot/

You can use scp to copy stuff over to the balloon, but there are a few little wrinkles. The 'installer' image has dropbear in it, but prior to release 0.9 (April 2009) dropbear does not start automatically. You need to start it with


The second wrinkle is that dropbear won't allow connections as root where root has no password (not unreasonable), but that's exactly how the initramfs is configured. So you need to

  1. edit /etc/passwd to add an 'x' in the second field of the first line, so it looks like this:




to set a new root passwd, then exit and login again with the password. Now you should be able to ssh to the board with something like:

ssh root@

Remember that this is a ram filesystem so if you reboot/power cycle you'll have to make these changes again.

If that works you can use scp to copy the kernel into the boot partition. The details of the command will vary depending on your networking setup, but it'll be something like

scp <user>@<hostname>:balloon3/build/kernel/zImageBoot /mnt/boot/zImage

Note that the kernel needs to be called zImage, otherwise the boot loader won't find it.

Note that this process is highly unreliable because the bootldr and kernel versions of yaffs do not quite match up. If you write a second copy as zImage2 then that often makes it work. The failure mode is that bootldr cannot read the kernel image corectly and thus fails to boot.

The next part requires you to have built the 'Stage 1' Debian root filesystem or the emdebian grip rootfilesystem. This is covered in SoftwareBuilding. These are debianstage1root.tgz and emdebianroot.tgz respectively in the directory build/rootfs.

Single-sided Balloon 3 boards generally only have 64MB of RAM, so the /tmp filesystem (which is in RAM) is not large enough to hold the Debian root filesystem tar file (~70Mb). Therefore we have to put it in the root filesystem itself, temporarily. The emdebian root filesystem will fit (~17Mb) so just copying it into ram works fine.

Mount the Balloon's NAND flash root filesystem

mount /mnt/root 

and clear it

rm -rf /mnt/root/* 

Debian rootfs

The process for setting up a Debian root filesystem appears to have changed recently (as of December 2011). Here I document what I did to make it work, in the hope that it will also work for you.

Boot your Balloon to the recovery kernel.

set bootscript=exit
boot flash 

Log in as root. The utilities scp and netcat seem to have gone away, so you will need to find another way to get your root filesystem image on to the board. I used wget, having set up a web server pointing at my build tree. You could use a USB stick or something.

The file you need is build/rootfs/debianrootstrap.modules.tgz. Put it into /root.

Now untar the image:

cd /mnt/root
tar xzvf /root/debianrootstrap.modules.tgz

Configure it:

chroot /mnt/root
/var/lib/dpkg/info/dash.preinst install
dpkg --configure -a

Answer its various questions appropriately. The dash.preinst command is needed because the dash shell (new in Debian 6.0) requires a pre-installation step.

Lastly, but not leastly, set yourself a root password otherwise you won't be able to log in:

passwd root

And reboot:


Debian rootfs, old version (no longer works as of December 2011)

At the root prompt on the Balloon, use scp to copy the image. The details of the command will vary depending on your networking setup, but it'll be something like

scp <user>@<hostname>:balloon3/build/rootfs/debianstage1root.tgz /mnt/root 

Unpack the filesystem image

cd /mnt/root
tar xzvf debianstage1root.tgz 

and delete the tarfile

rm debianstage1root.tgz 

This root image is partly-configured, so it needs some Debian magic doing on it.

chroot /mnt/root
/debootstrap/debootstrap --second-stage
dpkg -i --force-confnew --force-overwrite --force-depends /var/cache/apt/archives/balloon3-config*.deb

That should leave you with a working root filesystem.

Emdebian rootfs

scp <user>@<hostname>:balloon3/build/rootfs/emdebianroot.tgz /mnt/root
cd /mnt/root
tar xzvf emdebianroot.tgz
rm emdebianroot.tgz
chroot /mnt/root
dpkg --configure -a
chmod 777 /

In order for emdebian squeeze to work properly (dash doesn't get correctly installed as standard) some extra steps are necessary:

/var/lib/dkpg/info/dash.preinst configure
apt-get update
apt-get upgrade

If dash still won't configure properly, force its hand:

cd /usr/share/man/man1/
touch sh.distrib.1.gz
ln -s sh.distrib.1.gz sh.1.gz
dpkg-divert --package dash /usr/share/man/man1/sh.distrib.1.gz --add /usr/share/man/man1/sh.1.gz
dpkg --configure dash

Why is this? Because multistrap for a foreign architecture (in this case arm) is unable to run any package installation scripts. We usually get away with this, with the single and crucial exception of dash, the default Debian shell from squeeze onwards.

Packing up a configured filesystem

It is now possible to tar up the fully installed root filesystem. The quickest way is to follow the instructions in SavingYourRootFS, but it's also possible to use tar and scp as below if you want to.

Note that you're still chroot'ed at this point.

tar cvzf debianrootfs.tgz *

To save this image on another machine, use scp, which first involves leaving the chroot environment

scp /mnt/root/debianrootfs.tgz <user>@<hostname>:<path>

Installing this filesystem on a Balloon board is then be simply a matter of copying it to /mnt/root using scp and untarring it.

using aptoncd

aptoncd -p ../build/rootfs/emdebian/sources/packages/

Balloonboard: Balloon3SingleSidedRootFS (last edited 2012-08-23 17:28:26 by ChrisJones)