Wednesday 30 May 2012

Set up your Raspberry Pi like a pro

In my day job, I've developed on several Linux based embedded platforms and without exception, they have all been set up for general development along the same lines - a physical serial connection / terminal and a root filesystem accessed via an exported NFS directory. Also the Raspberry Pi, unlike most embedded systems I have used, has the added bonus of an X server - so you can also export the desktop via VNC. Following these instructions, I've managed to get the physical connections on the Pi board down to just a USB power lead (connected to a PC laptop) and a wifi dongle or ethernet cable, making it far more portable - Play with a RasPi on the train!

I'm using Fedora Linux (16/17) as a host, and I think you should too :) However, the instructions are almost identical for other flavours of Linux (Ubuntu, Debian, Mint etc), and should be nearly the same for Mac. If you're using any Microsoft based OS's, then you'll have to dig a bit deeper elsewhere - or preferably install Linux (hey, it's free!), maybe even use a 'live' Linux distro.

Here's how to get all this running on your Raspberry Pi. Note that all commands are run on the host PC, not the RasPi unless stated otherwise - and you can do each section individually, there's no dependencies between them if you only want an NFS root filesystem, for example.

Debian Squeeze

I've chosen to get this set up initially with the reference Debian Squeeze distro (currently debian6-19-04-2012.zip), available direct from the Raspberry Pi website - RaspberryPi.org/downloads. That way there should be plenty of help available in case trouble arises.
Follow the notes given by eLinux.org to get the Debian image onto an SD memory card, connect up the power/ethernet or wifi dongle/HDMI display and we'll go from there...

Serial Output & Terminal

A serial (aka 'UART') connection isn't strictly necessary to get the board running or playing with a running system, but it's essential if you're going to attempt to use different home-built kernels or anything low level that could possibly break, or cause not to run, the display to any more complicated devices such as a HDMI TV. For just a few £'s from ebay (search for "USB TTL UART" and make sure you get one with a lead that has individual pin connectors, as shown in the pic below), you don't need to think about getting a soldering iron warm. The Debian distro we're using supports serial output / a terminal without changing any code, so all you need to do is:

* Connect the serial dongle between your host and RasPi: Three pins are needed to be connected, GND (Ground), TXD (transmit) and RXD (receive). They should be marked on the USB dongle, and looking at the GPIO pinout diagram here, the GND is connected to P1-06, TXD to P1-08 and RXD to P1-10 - as in the picture below. It might be worth trying to swap TXD and RXD if you initially get no output. The small red USB dongle pictured obviously slots into a USB port on your host PC.


* Start a terminal program on your host: On Fedora, I use minicom (install from the command line (CLI) using 'sudo yum install minicom'). If running for the first time, run with 'sudo minicom -s', select 'Serial port setup' on the menu, then press to change the device to /dev/ttyUSB0 , the press to change 'Hardware flow control' to 'No' and again to exit (don't change anything else). Back at the menu select 'Save setup as dfl' and then 'Exit'. From now on you can start minicom from the CLI with just 'sudo minicom'. Make sure you have the USB dongle plugged in whenever you run minicom, otherwise it will complain about not finding ttyUSB0.

* Power on the Pi as normal: and you should see almost the same text scrolling down the terminal screen as appears on the TV connected via HDMI. Result! - Now give the TV back to the family...


N.B. TODO - Currently on Debian Squeeze, the syslog trace from the init.d scripts isn't shown over UART. This is something that would be good to fix, as we ideally want as much verbose information on UART as possible if something goes wrong.

NFS root filesystem

Any Linux distribution needs a root filesystem to work, and Debian is no exception. At present, this filesystem is sitting on a partition on the SD card inserted into the Raspberry Pi and we want to copy it to the host PC. Why? It's much faster and easier to transfer, edit and view files on the PC than on the Pi (also saving precious Pi processing power), you can back then up (perhaps in a versioning system such as git), and access a larger filesystem space than can fit onto a meagre SD card amongst other reasons. Note that an SD card still needs to be inserted into the Pi, containing the bootloader and Linux kernel code (Getting the kernel to boot over NFS requires a more advanced bootloader such as uboot, a FreeBSD developer has some notes here). To get this running, I had to do the following:

* Copy the Debian Pi root filesystem to the host PC: Make a new directory on the host PC, at the root of the filesystem, e.g. 'sudo mkdir /nfsexports'. Take your SD card containing the RasPi Debian image, and insert it into the host PC. Two new media devices should be mounted automagically, make a note of where by checking the tail end of the CLI command 'dmesg' - mine reports /dev/sdb1 -> /dev/sdb3 as recently found, then run 'df -h':

mark@marke ~]$ df -h
Filesystem                    Size  Used Avail Use% Mounted on
rootfs                         50G   16G   35G  31% /
devtmpfs                      3.9G     0  3.9G   0% /dev
tmpfs                         3.9G  860K  3.9G   1% /dev/shm
/dev/mapper/vg_marke-lv_root   50G   16G   35G  31% /
tmpfs                         3.9G   49M  3.9G   2% /run
tmpfs                         3.9G     0  3.9G   0% /sys/fs/cgroup
tmpfs                         3.9G     0  3.9G   0% /media
/dev/sda1                     497M  184M  289M  39% /boot
/dev/mapper/vg_marke-lv_home  406G  141G  244G  37% /home
/dev/sdb1                      75M   28M   47M  37% /media/95F5-0D7A
/dev/sdb2                     1.6G  1.2G  298M  81% /media/18c27e44-ad29-4264-9506-c93bb7083f47

 Mine shows device 2 of the 3 (/dev/sdb2) as mounted on /media/18c27e44-ad29-4264-9506-c93bb7083f47/. This long directory is the one for which you'll need to copy the contents into the nfsexports directory created earlier with the CLI command 'sudo cp -ap /media/18c27e44-ad29-4264-9506-c93bb7083f47/* /nfsexports/' - obviously replace the directory names with your own. Make sure you use this CLI version, and not the GUI - the 'sudo' and 'p' options passed to the cp command are important.

* Install an NFS server on the host PC: There are lots of guides on the web for installing and setting up an nfs server, so if you get into trouble, have a google. A quick guide is; On Fedora, run the CLI command 'sudo yum install nfs-utils libnfsidmap'. Once installed, edit the file /etc/exports to export the Pi root directory, for me this is what /etc/exports looks like:

/nfsexports  192.168.2.223(rw,sync,no_root_squash)

Where the IP address 192.168.2.223 is the ip address of my RasPi. There can be wildcards in this address, so you could export it as 192.168.2.* for everything on your local subnet, or even just * for access to everyone (although this is not recommended). To finally export the directory, start the nfs server, 'sudo systemctl start nfs-server.service'. To test, I'd make sure that your host PC firewall and SE-Linux is disabled, and run 'sudo mount -t nfs localhost:/nfsexports' where localdir is a local host PC directory. If successful, you should see the entire root filesystem present in .

* Point the RasPi towards the NFS server: Now we need to tell the RasPi to use our exported rootFS, not the one on the SD card. We can do this by modifying a file located on the SD card. If you have the SD card still inserted into your host PC, run 'df -h' again and take a look at the other mounted partition, /dev/sda1 in my case, which is mounted on /media/95F5-0D7A. So I'm going to edit this file, /media/95F5-0D7A/cmdline.txt, which initially looks like:

dwc_otg.lpm_enable=0 console=ttyAMA0,115200 kgdboc=ttyAMA0,115200 root=/dev/mmcblk0p2 rootfstype=ext3 rootwait

And change it to your equivalent of (with no return characters, all one line):

dwc_otg.lpm_enable=0 console=ttyAMA0,115200 kgdboc=ttyAMA0,115200 console=tty1 ip=192.168.2.223:192.168.2.225:192.168.2.1:255.255.255.0:rpi:eth0:off root=/dev/nfs nfsroot=192.168.2.225:/nfs4exports,vers=3 rw rootwait

Here, you'll need to change the two instances of '192.168.2.225' to the IP address of your host PC, and '192.168.2.223' to the IP address you want to give your RasPi - make sure that the first three address digits (192.168.2) are the same for both, and also the '192.168.2.1' matches your router IP.

* Fix some annoying issues with Debian: (TODO - fix this!) Further to the above, I've had to fix some issues with the Debian init.d scripts that froze startup from NFS (without reaching the 'login:' prompt). I had to rename the following files present in the exported root NFS in the directory at /nfsexports/etc/rc2.d/ - S14portmap, S15nfs-common, S17ifplugd, S17rsyslog, S17sudo, S18cron and S18ntp. If you find this is an issue for you too, change the 'S' character in front of these files to 'K', e.g. S14portmap to K14portmap. I'd be interested in any feedback anyone has on this issue...

* Boot the RasPi with an NFS root: Now just unmount the SD card ,and reinsert into the RasPi before powering on again. Watch as the RasPi boots to a prompt from NFS (possibly...!).

Added bonus - export a desktop via VNC

The final step to totally ditching the TV in favour of your PC/laptop screen is to export the raspi desktop via VNC to view and control on the host PC:

* Install a vncserver on the RasPi: Now on the fresh RasPi prompt before you, (not the host!), login (username pi, password raspberry) and install tightvncserver with 'sudo apt-get install tightvncserver'. Enter a VNC password when prompted, but don't bother with a view-only password. To run the server so that you can log into it remotely, type 'vncserver :1 -name RasPi -depth 16 -geometry 1680x1050'. Feel free to play with the geometry or pixeldepth, but bear in mind bigger numbers may mean slower performance.

* Look at the RasPi desktop on your host PC: Fedora should have a ready-installed remote desktop viewer, imaginatively named ' Remote Desktop Viewer'. Find it in your applications list and start it. Select the menu item Remote->Connect and change the protocol to VNC, and add your RasPi IP address and xserver ID in the Host: box (for me, this was 192.168.2.223:1 :


...then click 'Connect' at the bottom of the dialog box. You should be then prompted for the VNC password you chose for the RasPi earlier. Enter it, and bask in the glory of the Raspberry Pi desktop:


* Happy hacking!