View source for Debian On SD

= Debian On SD =

I'm going to split this into three chunks now... standard Desktop Debian on SD using Squeeze/Lenny/Sid ( choose your poison, though only Squeeze is officially tested to work by myself, ) Emdebian GRIP install, and NAND install.

You can post feedback, bugs, etc.. on the following topics:
GP32X: http://www.gp32x.com/board/index.php?/topic/57097-debian-on-an-sd-card/
OpenPandora Boards: http://boards.openpandora.org/index.php?/topic/1819-debian-on-sd/

I'd prefer the GP32X boards as I'm slightly more active there.

= Little Note to Wiki Editors =
I change this a lot offline and then plaster the changes on during a new release.<br />
If you're going to go <span class="plainlinks">[http://www.indoorfountains.com/<span style="color:black;font-weight:normal; text-decoration:none!important; background:none!important; text-decoration:none;">Indoor Water Features</span>] changing this page, please contact me first so I don't accidentally obliterate your changes, or that you do changes to the style I've set out that I don't agree with!<br />
This may well be against the "wiki spirit" .. but I spend days/weeks typing up these changes and testing them.. so a little consideration please :)

== Desktop Debian ==
This is split into three main sections - Building from Scratch, Maintenance and Upgrades, Common Things To Do.

''' This documents the final 1.0.3 and 1.0.4 "brute force" releases. The 1.1 "debianized" release will take a while and not involve this process at all. '''

* Building From Scratch lets you customise everything from the outset, and lets you create your very own tailor-made distribution, rather than a pre-created one.
It does require a  <span class="plainlinks">[http://www.phuketproperty.com/<span style="color:black;font-weight:normal; text-decoration:none!important; background:none!important; text-decoration:none;">Phuket Real estate</span>] bit of Linux knowledge before diving in.. so if unsure, ask!

* Maintenance and Upgrades <span class="plainlinks">[http://www.youtube.com/watch?v=IOYqZ71R_aw/ <span style="color:black;font-weight:normal; text-decoration:none!important; background:none!important; text-decoration:none;">Patrick Beharelle</span>]
covers standard Debian maintenance if you're not usually a Debian user.
It'll also ( in the future ) cover how to upgrade your pre-built distribution with new drivers as the official OS gets updated.

* Common/Fun Things To Do will give you ideas on what to try in your new Debian installation. 
Remember, this is a full desktop OS you now have squeezed into your hands, and feel free to share your cool ideas!

If you don't want to build from scratch, you have two choices;
* Grab a Minimal Install and continue from [http://pandorawiki.org/index.php?title=Debian_On_SD#Desktop_Environment Desktop Environment]
* Grab a full build.

The latest minimal is available here: http://www.stuckiegamez.co.uk/apps/pandora/Debian/pandora-squeeze-minimal-1.0.2.tar.bz2 <br />
The latest full builds are: 
* LXDE - http://www.stuckiegamez.co.uk/apps/pandora/Debian/pandora-squeeze-1.0.4-grip.tar.bz2
* XFCE - http://www.stuckiegamez.co.uk/apps/pandora/Debian/pandora-squeeze-1.0.5-grip.tar.bz2

Remember to untar with permissions ( include '''p''' in your arguments to tar ) on to your ext2/3 formatted SD card.<br />
For example: '''''tar -xvjpf pandora-squeeze*.tar.bz2 -C /media/sdcard .'''''

Default User details are:<br />
username: '''pandora'''<br />
password: '''debian'''

=== Changelog ===
==== Original Proof of Concept ====
* Released - 19th October 2010
* Based on Sid
* GDM
* GNOME
* Bit slow but workable

==== Release 1.0 ====
* Released - 20th February 2011
* First release
* libts issues
* libpnd issues
* Overly fat with stuff
* Wifi issues for some people

==== Release 1.0.1 ====
* Released - 23rd February 2011
* First documented release
* libts issues persist
* Most libpnd issues fixed
* Slimmed down to ~830mb
* Made Wifi issues worse and accidentally stripped out more than needed

==== Release 1.0.2 ====
* Released - 22nd March 2011
* Replaced libts with evdev... doesn't cause X choking.
* libpnd should behave now, though the pnd services don't seem to get kicked till a terminal is opened, and even then they turn zombie.. eh?
* Added full dev setup.. so it's fat.. it's 1.2gig extracted.
* Replaced GDM with SLIM.

==== Release 1.0.3 ====
* Released - 27th March 2011
* Effectively 1.0.2 with the WiFi and Session Management bug fixed.
* Much slimmer as it's done from scratch again without the dev setup ~805mb rootfs

==== Release 1.0.4 ====
* Released - 4th April 2011
* 1.0.3 with lots of bugs fixed and based on Grip so it's got even more and super tiny in comparision.
* Contains; LXDE, GDM, Gnome MPlayer, IceWeasel ( firefox ) and Synaptic

==== Release 1.0.5 ====
* Released - 9th April 2011
* 1.0.4 with XFCE instead of LXDE and a few bug fixes ( pandora-state's rc scripts being set correctly, and console key map .. see the relevant bits below if you need them, but other than that, it's exactly the same - just with XFCE instead of LXDE )

=== Release 1.1 Proposed ===
* Expected - May 2011 ( maybe )
* libts, amongst other libraries, using OpenPandora patched version.
* Pandora specifics wrapped as Debian archives.
* Pandora specifics repo to deal with updates to drivers from mainline.
* Perhaps an updated kernel using the patches from mainline.

== Building From Scratch ==
This isn't for the feint of heart.. if you don't understand something - stop! Ask or read up on it before continuing. While I haven't mangled my Pandora or PC in any way from doing this, it's still possible to make a mess, so be careful!

This is split into many parts.. it's advised to go through this in order.

* Getting a Minimal Install from Scratch
* Desktop Environment
* Device Drivers and PNDs
* Users, First Boot Scripts and Permissions
* Reboot and Troubleshooting

=== Getting a Minimal Install from Scratch ===

There are two options here:
* Linux PC
* On Pandora

==== Linux PC ====
On a Linux PC, run debootstrap to grab the version you want. We shall be using Squeeze today:<br />
'''''sudo debootstrap --arch armel --foreign squeeze /tmp/pandora-debian ftp://ftp.uk.debian.org/debian'''''<br />
Grab a large SD card, and repartition it to have one large ext2/ext3 partition and format as normal.<br />
Copy all the files from /tmp/pandora-debian over to your new SD card partition.<br />
Put it in your Pandora.<br />
'''''sudo chroot /media/mmcblk0p1''''' -- assuming it's in your first slot.<br />
'''''/debootstrap/deboostrap --second-stage'''''<br />
... this takes a while...

==== Pandora ====
Alternatively, you can run cdebootstrap on the Pandora itself, or debootstrap from within Debian... this bypasses the need of doing the second-stage madness.<br />
Grab it from here: http://packages.debian.org/sid/cdebootstrap-static and select the armel package.<br />
Download it to /tmp preferably, but your home folder will do, or anywhere you like. For now, I shall assume you downloaded it to /tmp<br />
'''''cd /tmp'''''  -- Again, if you downloaded elsewhere, change to that directory instead.<br />
'''''ar xv cdebootstrap*.deb''''' -- We're using the archive tool to extract with verbosity our cdebootstrap package. <br />
'''''sudo tar -zxvf data.tar.gz -C /'''''  -- Now we're using tar to extract, with gzip support, again with verbosity, the file data.tar.gz, changing the Current directory to / so that it extracts systemwide on our NAND. We're running this command sudo so we have write permissions.<br />
Now we just run cdebootstrap-static with a few parameters, and wait.<br />
'''''cdebootstrap-static --allow-unauthenticated -f minimal squeeze /media/mmcblk1p1''''' -- What we're doing here, is we're allowing "unauthenticated" packages to be installed. As we don't, or probably don't, have the gnupg keychain stuff configured, all packaged will be "unauthenticated" regardless of whether they are or not. We're telling it we also want a minimal install of the squeeze release, and to install to where we have the mount point of Partition 1 of the SD card in Slot 1 - which you should have already partitioned and formatted as ext2! <br />
This takes a while... perhaps longer than doing the first stage on the PC and second-stage on Pandora.

=== Setting up Apt ===
I've forgotten about this, as mostly it'll be set to the default Debian repository, but should you want to change it: <br />
'''''sudo nano /etc/apt/sources.list'''''

UK people can set this to ''deb ftp://ftp.uk.debian.org/debian main non-free contrib'' to get pretty much everything, or can pick whichever local Debian repository they like - but be warned that not all of them have an armel repo!<br />
By default, debootstrap will likely only get main.. adding the non-free and contrib branches are optional, but bring in more stuff.

=== Desktop Environment ===
Now you have Debian, the world is yours for the taking!
Or something like that...

Debian comes with a wide variety of desktop environments and window managers; from XFCE as you use on Angstrom by default, to KDE, GNOME, LXDE, Fluxbox, Enlightenment, etc..<br />
Now's the time to choose one of them to install.. be aware that the bigger they are, the longer they'll take to install and the more resources they will eat up while in use.. as a rough guide from heavy to light:<br />
* KDE
* GNOME
* Enlightenment ( Squeeze has e16 .. and is faster than I expected )
* XFCE
* LXDE
* Fluxbox

Having recently tested KDE myself, it doesn't quite seem to work properly, so I'd avoid that for the moment... especially as it takes about ten hours to install!

We shall install LXDE as it's a bit more light weight than XFCE and still provides a reasonable mainstream environment. While I do prefer Fluxbox overall, it's a bit of a paradigm shift to use from your standard desktop machine.

If you haven't already, chroot into your environment.
You should already be root, so we'll get on with the installing.

'''''apt-get install lxde'''''

This may well take an age, so go do something else in the meantime.<br />
You may also want a login manager.. your choices are amongst XDM, GDM, KDM and SLIM to name a few. KDM is perhaps a bit heavy, whereas GDM works fairly well even though it's rather heavy too. SLIM is what you use on Pandora anyway, and XDM is rather basic but usable all the same. GDM is automatically pulled in via LXDE anyway, so we may as well just use that for now.

Additional:<br />
Installing LXDE via the above command pulls in GDM by default.. if you use ''lxde-core'' instead, it removes a lot of the stuff that pulls in random things, and if you additionally use '''''aptitude install --without-recommends lxde-core''''' it should strip out even more. You will need to manually install ''less'', ''zenity'', and ''xterm'' for example. Zenity is especially needed for all the Pandora config scripts.

1.0.3 has slimmed stuff down again.<br />
Once in the chroot jail, I've performed the following: '''''aptitude install --without-recommends lxde-core slim lxterminal zenity less xserver-xorg-video-omap3 network-manager-gnome synaptic xfce4-power-manager apmd libnotify-bin gedit epiphany-browser eject gksu gnome-bluetooth python-dbus ca-certificates xinput busybox''''' which will effectively pull in all the Debian specifics we'll be needing, gutting out a rather large amount of cruft.

Once it's done, we'll start tackling the Drivers.

=== Device Drivers and PNDs ===
We shall tackle these one at a time, as there's quite a few of them.

* X Display Driver
* SGX Drivers
* Keymap
* Nubs
* Touchscreen
* Wifi
* Bluetooth
* Kernel and Misc Bits and Pieces
* PNDs

==== X Display Driver ====
Debian has a NEON-optimised omapfb driver. We shall use this, and pinch some configuration gubbins from Angstrom.

'''''apt-get install xserver-xorg-video-omap3'''''

We now need to create an xorg.conf .. though it'll be rather minimal as we only really want to overload what graphics device setup it has, so:<br />
'''''nano /etc/X11/xorg.conf'''''<br />
 Section "Module"
 	Load	"extmod"
 	Load	"dbe"
 	Disable	"glx"
 	Disable	"dri"
 	Load	"dri2"
 EndSection
 
 Section "ServerLayout"
 	Identifier	"DefaultLayout"
 	Screen		"Screen0"
 EndSection
 
 Section "Screen"
 	Identifier		"Screen0"
 	Device			"OMAPFB"
 	Monitor			"Monitor0"
 	DefaultDepth	16
 	SubSection "Display"
 		Depth	16
 		Modes	"800x480"
 	EndSubSection
 EndSection
 
 Section "Monitor"
 	Identifier		"Monitor0"
 EndSection
 
 Section "Device"
 	Identifier		"OMAPFB"
 	Driver			"omapfb"
 	Option			"fb"		"/dev/fb0"
 EndSection

Most of this is pinched from the Angstrom xorg.conf minus the fb Option at the bottom, as our framebuffer has a different device node.

That should be all you need for basic X though.

==== SGX Drivers ====
Most of this has been pinched from http://elinux.org/BeagleBoardDebian#SGX_Video_Acceleration - why rewrite the wheel?<br />
This mostly works apart from a few caveats, so I shall repeat it here for future reference and to keep all information in one place, and I've uploaded the resulting tarballs for convenience.

You can either follow the above guide - substituting the BeagleBoard for the Pandora, or use the following preconfigured packages.<br />
'''''cd /tmp'''''<br />
'''''wget -c http://www.stuckiegamez.co.uk/apps/pandora/Debian/GFX_4_00_00_01_libs.tar.gz''''' ~20MB Libraries themselves<br />
'''''wget -c http://www.stuckiegamez.co.uk/apps/pandora/Debian/GFX_Linux_SDK.tar.gz''''' ~220MB Demos and SDK gubbins<br />

Technically, you don't really need that fat 220MB GFX_Linux_SDK tarball unless you really want it, or want to test the libraries are in place.<br />
I'll cover installing both anyway...

===== Libraries =====
'''''tar -zxvf GFX_4_00_00_01_libs.tar.gz'''''<br />
'''''chmod +x ./install-SGX.sh'''''<br />
'''''./install-SGX.sh'''''<br />
'''''rm /devmem2_0.0-0ubuntu1_armel.deb''''' - this is particularly useless to us... and why it dumps it at root, I don't know!<br />

That package contains ES2, ES3 and ES5 libraries.. we're only really interested in ES2 ( haven't tried if ES3 or ES5 would even work! ) so:<br />
'''''cd /usr/lib'''''<br />
'''''ln -s ES2.0/* .'''''<br />

Not hugely clean, but it works. For the brave, you could try ES3 or ES5 but.. you're on your own!

===== Demos/SDK =====
'''''cd /tmp'''''<br />
'''''tar -zxvf OGLES.tar.gz'''''<br />
'''''tar -zxvf OGLES2.tar.gz'''''<br />

You can't run anything yet ( well, you might since you've chrooted in via Angstrom ) so we'll leave them in /tmp for the moment - or move them elsewhere - such as /opt if you're worried about Debian wiping out /tmp on boot.

==== Keymap ====
The keymap is actually stupidly easy, and I've missed how easy it is for quite a while now!<br />
We shall steal them from Angstrom.. so open up another Terminal.<br />
As of now, I shall prefix Angstrom commands with ''Angstrom'' and Debian commands with ''Debian'' so you know which Terminal to type them in.

''Angstrom'' '''''sudo cp /etc/keymap-extension-2.6.map /media/mmcblk0p1/etc''''' - this does assume you've got your SD card mounted in slot one, and with one ext2 partition.. adjust as necessary.<br />
''Angstrom'' '''''sudo cp /etc/skel/.pndXmodmap /media/mmcblk0p1/etc/skel''''' - as above.<br />

After some fiddling, if you stick the following into ''.xsession'' it'll actually get called...
 whoami > /tmp/currentuser
 killall -1 pndnotifyd &
 exec startlxde

Of course, this is a bit hacky and hard-coded in that if you've chosen something other than lxde, you'll probably want to change that startlxde to something else!

1.0.2 does something really hacky and actually starts pndnotifyd and pndevmapperd as daemons directly.<br />
It also starts up the xfce4-power-manager for a battery meter.

1.0.3 does something else again.. it does not have the '''killall -1 pndnotifyd &''' line, instead it has the following:
 sudo /etc/init.d/pndnotifyd-init restart
 sudo /etc/init.d/pndevmapperd-init restart
And has edited /etc/sudoers.d/99_libpnd to add access to those two lines without being prompted for a password.

1.0.4 is again different, and doesn't HUP pndnotifyd at all as it seemed to work without much issue just by starting the service differently, also, due to use of GDM, we do the xmodmap at GDM's startup instead in the following manner: <br />
'''''sudo nano /etc/gdm/Init/\:0''''' - the \ is needed to use : as a character!<br />
 #!/bin/bash
 xinput set-int-prop "touchscreen" "Evdev Axis Calibration" 32 3936 125 3873 183
 xmodmap /etc/skel/.pndXmodmap
 loadkeys /etc/keymap-extension-2.6.map

The xinput line is for the evdev touchscreen configuration, if this is wrong, please run '''xinput_calibrator''' from a Terminal, and replace the line with what it gives you!

The loadkeys line also ensures that the console gets the correct keymap as well.

Thanks to chris_c for the GDM init hint, and mcobit for the loadkeys hint!

Should probably copy more over but, this'll do for now.<br />

==== Nubs ====
The nubs just require some more config stuff to be copied over, and a few rc scripts to be setup right.<br />
''Angstrom'' '''''sudo cp -R /etc/pandora /media/mmcblk0p1/etc'''''<br />
This also copies over configurations for the LCD backlight, some pmenu and mmenu stuff, and some PND configuration bits.

''Angstrom'' '''''sudo cp /etc/init.d/pandora-state /media/mmcblk0p1/etc/init.d''''' - pandora-state restores nubs and backlight settings, as well as saves them on exit.

Configuration utils come in with the PND installation below.

==== Touchscreen ====
===== Current 1.0.2/3 Release =====
1.0.2 uses evdev instead of libts for the touchscreen. This doesn't really require any configuration for the most part, but does need to be calibrated.<br />
You'll need a full dev setup on the Pandora for this, as you'll need to compile the xinput_calibrator - http://www.freedesktop.org/wiki/Software/xinput_calibrator however it's fairly trivial once all the libraries are installed.

My values, which you should put into .xsession, are as follows: '''''xinput set-int-prop "touchscreen" "Evdev Axis Calibration" 32 3936 125 3873 183''''' and you'll need xinput installed ( which you should've done above if following the 1.0.3 path. )

This is already done on 1.0.4 and xinput_calibrator is included should you need to re-run it.

===== libts for other releases =====
''Debian'' '''''apt-get install libxcb-dri2-0 xserver-xorg-input-tslib libts-bin'''''<br />
''Debian'' '''''nano /etc/profile.d/tslib.sh'''''
 #!/bin/sh
 TSLIB_TSDEVICE=/dev/input/event5
 TSLIB_CONFFILE=/etc/ts.conf
 export TSLIB_TSDEVICE TSLIB_CONFFILE

We'll do the rest of it on First Boot.<br />
This will be fixed properly when WiFi issues settle, so I can finalize a build system and re-do everything as packages - including libts with the OpenPandora-specific patches from the git.

==== Wifi ====
Wifi is fun... most of it will come in the kernel and modules/firmware pack when we get to it, but there's some ancillary scripts and things that lay in wait to catch you off guard!<br />
''Angstrom'' '''''sudo cp /etc/init.d/wl1251-init /media/mmcblk0p1/etc/init.d'''''<br />
''Angstrom'' '''''sudo cp /lib/udev/rules.d/50-compat_firmware.rules /media/mmcblk0p1/lib/udev/rules.d'''''<br />
''Angstrom'' '''''sudo cp /lib/udev/rules.d/compat_firmware.sh /media/mmcblk0p1/lib/udev/rules.d'''''

The wl1251-init script uses busybox. While you could edit the script and remove the dependency on busybox, it's probably better to just install busybox if you haven't already, so that there are less changes to deal with - seeing as it's only about 600kB.<br />
''Debian'' '''''apt-get install busybox'''''

While we don't necessarily need Network Manager, it's a damn sight more easier to use than battering iwconfig et al from the Terminal:<br />
''Debian'' '''''apt-get install network-manager-gnome'''''<br />
This'll take a long time as it pulls in quite a lot of stuff...

==== Bluetooth ====
Debian's bluetooth setup seems to kick in and work without issue.<br />
Probably need to get a clean way to toggle it on and off - as it defaults to being on.

==== Kernel and Misc Bits and Pieces ====
The kernel *should* be easy... grabbing a fresh set would've been advisable, but this doesn't seem to come with everything so we'll steal from our running system again.

''Angstrom'' '''''sudo cp -R /lib/modules/2.6.27.46-omap1 /media/mmcblk0p1/lib/modules'''''<br />
''Angstrom'' '''''sudo cp -R /lib/firmware /media/mmcblk0p1/lib/firmare'''''<br />
''Angstrom'' '''''sudo cp /boot/uImage /media/mmcblk0p1/boot/uImage'''''

==== Battery Monitor ====
You'll likely want to know how much battery power you have!<br />
''Debian'' '''''apt-get install apmd'''''<br />
''Debian'' '''''apt-get install xfce4-power-manager'''''<br />
Somewhat cheeky perhaps, but it does work! [http://www.gp32x.com/board/index.php?/topic/57653-a-guide-to-installing-lxde/page__view__findpost__p__928896 see this post]

If you add '''''xfce4-power-manager &''''' before '''''exec startlxde''''' in your .xsession, it'll start up automatically for you.

==== Misc Init Scripts and Things ====
There are a few random init scripts we need for things:<br />
''Angstrom'' '''''sudo cp /etc/init.d/led-config /media/mmcblk0p1/etc/init.d''''' - configure the LEDs properly.<br />
''Angstrom'' '''''sudo cp /etc/init.d/usb-gadget /media/mmcblk0p1/etc/init.d''''' - for initializing the usb gadget device - g_cdc for USB networking, for instance.<br />
''Angstrom'' '''''sudo cp /usr/bin/usb-gadget /media/mmcblk0p1/usr/bin'''''<br />
''Angstrom'' '''''sudo cp /etc/profile.d/op_env.sh /media/mmcblk0p1/etc/profile.d''''' - effectively just tells SDL to use tslib driver<br />
''Angstrom'' '''''sudo cp /etc/default/leds /media/mmcblk0p1/etc/default'''''<br />
''Angstrom'' '''''sudo cp /etc/default/usb-gadget /media/mmcblk0p1/etc/default'''''<br />
''Angstrom'' '''''sudo cp /etc/skel/.asoundrc /media/mmcblk0p1/etc/skel'''''<br />

And some more stuff to install in Debian:<br />
''Debian'' '''''apt-get install libnotify-bin'''''

==== PNDs ====
There are some init scripts you need for the PNDs to work. These are:<br />
''Angstrom'' '''''sudo cp /etc/init.d/pndevmapperd-init /media/mmcblk0p1/etc/init.d'''''<br />
''Angstrom'' '''''sudo cp /etc/init.d/pndnotifyd-init /media/mmcblk0p1/etc/init.d'''''<br />
''Angstrom'' '''''sudo cp /usr/bin/pnd* /media/mmcblk0p1/usr/bin''''' - there are a few pnd binaries, these include pnd_info, pnd_run, pndevmapperd and pndnotifyd.<br />
''Angstrom'' '''''sudo cp /usr/lib/libpnd.so.1.0.1 /media/mmcblk0p1/usr/lib''''' - obviously nothing'll work without the pnd libraries!<br />

There are a bunch of scripts and PNDs hiding in /usr/pandora.. we may as well grab them over as well.<br />
''Angstrom'' '''''sudo cp -R /usr/pandora /media/mmcblk0p1/usr'''''<br />

We need to do a symlink to the library properly now, and clean up some stuff.<br />
''Debian'' '''''ln -s /usr/lib/libpnd.so.1.0.1 /usr/lib/libpnd.so.1'''''<br />
''Debian'' '''''rm -rf /usr/pandora/mmenu''''' - these are just PNDs that call the programs installed in Angstrom from MiniMenu. We don't have these programs installed on Debian so, they're useless to us.<br />

==== RC Scripts ====

We also need to disable some things from running.. the first run script specifies the following:<br />
 update-rc.d -f samba remove
 update-rc.d -f xinetd remove
 update-rc.d -f avahi-daemon remove
 update-rc.d -f apmd remove
 update-rc.d -f usb-gadget remove
 update-rc.d -f banner remove
 update-rc.d -f portmap remove
 update-rc.d -f mountnfs remove
 update-rc.d -f blueprobe remove
 update-rc.d -f dropbear remove
 update-rc.d -f wl1251-init remove

We'll also need to add some bits to the rc.d script set.
===== Script Fixups =====
We need to fiddle with a few of the scripts - specifically led-config to add the dummy LSB information ( just rip it out of another script, and leave Required-Start, Required-Stop, Default-Start and Default-Stop empty, ) and pndnotifyd-init, pndevmapperd-init and pandora-state where you need to blank out the #adjust marker as it causes Debian to have fits.

If you don't do this, the nub settings won't save, for instance, and some system scripts are not guaranteed to start up.<br />
The update-rc.d program will shout at you which ones, and essentially, it's just some tidying up that needs done.

It's now recommended to use update-rc.d to put these in rather than the old heavy handed ln calls:
 update-rc.d led-config defaults 05
 update-rc.d pndevmapperd-init defaults 30 40
 update-rc.d pndnotifyd-init defaults 30 40
 update-rc.d pandora-state defaults 05

The pandora-state is different on Angstrom than Debian as it didn't start up with it's usual bindings, which was annoying!

=== Users and Permissions ===
You may be wondering why Users haven't been done till the very end.. we've edited the /etc/skel setup which will be used to create your user details.

If you have already jumped the gun and created a user previously, all changes we've done to /etc/skel will need to be mirrored in your home folder!

''Debian'' ''''''adduser <username>''''' - obviously, replace <username> with what you want; for example ''adduser pandora''.

One interesting thing I've noticed happens, is sometimes it'll happily create your user... then not give you full permissions to your own folder.. so let's beat it a bit.<br />
''Debian'' '''''chown -R <username>:<username> /home/<username>''''' - replacing <username> with your actual username; for example ''chown pandora:pandora /home/pandora''<br />

You'll probably want to use sudo, which will require you to be in the wheel group, which we are about to create:<br />
''Debian'' '''''groupadd wheel'''''<br />
There's also few groups you'd want to be in, so we'll do that now.<br />
''Debian'' '''''usermod -a -G wheel <username>''''' - you know the drill now... example; ''usermod -a -G wheel pandora''<br />
''Debian'' '''''usermod -a -G adm <username>'''''<br />
''Debian'' '''''usermod -a -G audio <username>'''''<br />
''Debian'' '''''usermod -a -G video <username>'''''<br />
''Debian'' '''''usermod -a -G plugdev <username>'''''<br />
''Debian'' '''''usermod -a -G users <username>'''''<br />
''Debian'' '''''usermod -a -G netdev <username>'''''<br />

Technically, you could've done all this in the one line with adduser, but I'd rather keep it all separate so that if we end up with extra groups, we all know how to add them.

You'll also need to do the above for every new user you create for the moment.

There's a bunch of sudoers rules that are hidden as well that we need to steal ( I completely missed these twice - my thanks to sebt3 and DJWillis for pointing me to them! I thought the #includedir line was commented out due to the # ... *facepalm* )<br />
''Angstrom'' '''''sudo cp /etc/sudoers.d/* /media/mmcblk0p1/etc/sudoers.d/'''''

Finally, /tmp can sometimes go mad so we shall fix that just now too.<br />
''Debian'' '''''chmod a+w /tmp'''''

=== Reboot and Troubleshooting ===

==== auto/boot.txt ====
We need either an autoboot.txt or a boot.txt now or we won't be able to boot up Debian.<br />
There's no difference between either, other than autoboot will cause the Pandora to automatically boot from SD if it finds it, whereas boot requires holding the right shoulder button as usual.<br />
''Debian'' '''''nano /autoboot.txt''''' - again, you could use boot.txt instead and press the right shoulder button during boot.<br />
 setenv bootargs debug root=/dev/mmcblk0p1 rw rootdelay=2 console=ttyS0,115200n8 vram=6272K omapfb.vram=0:3000K
 ext2load mmc 0:1 0x80300000 /boot/uImage
 bootm 0x80300000

Alternatively, if you remove the '''console=ttyS0,115200n8''' part, you will be able to see debug text as the system boots up.

All that's really left now is to reboot and catch any issues that may crop up!

==== First Boot ====

===== tslib calibration =====
First Boot should bring you up to GDM in all it's splendour. But Wait! The touchscreen! IT IS MADNESS!<br />
If you've a USB keyboard, you can be one step ahead and do CTRL+ALT+F1 to jump to a terminal, but we're going to assume just the Pandora so we'll carry on and login.

Once LXDE has finished loading up, press FN+ALT+F2 and type "lxterminal"<br />
'''''sudo su'''''<br />
'''''export  TSLIB_TSDEVICE=/dev/input/event5'''''<br />
'''''export TSLIB_CONFFILE=/etc/ts.conf'''''<br />
'''''ts_calibrate'''''

Touchscreen should behave itself now.<br />

===== Finish up installing any left overs =====
While root ( that's what sudo su does ) we shall finish setting up anything that didn't take during our chroot session in Angstrom ( bluetooth usually )<br/>
'''''apt-get -f install'''''<br />
'''''exit''''' - jump back to our user so we don't accidentally mess things up<br />

==== Cleanup ====
Potential clean-ups that should occur is packaging up the Pandora specific libraries and scripts into .deb files for maintenance purposes if nothing else. We can then either try and get them fed back into Debian, or provide our own Debian repo for Pandora.

The following should probably be stuffed into deb files for easier maintainability:<br />
* libpnd
* pandora specific scripts
* SGX drivers
* kernel
* modules and firmware

== Maintenance and Upgrades ==
Maintenance on Debian is very easy.. it's just a case of running '''''sudo apt-get update && sudo apt-get upgrade''''' from a console, or using Synaptic ( see below on how to install if your rootfs didn't have it. )

== Common Issues/Fun Things To Do ==
There's a wealth of power at your fingertips with Debian, so place your fun things to do here!<br />
Also, sometimes there are odd issues, so if you fix something odd, place it here too.

=== Networking ===
Networking should work effectively the same as on Angstrom, but here's a run down of what to do anyway:
* Click the LXDE menu up.
* Click System Tools -> Toggle Wifi
* Click the Network Manager app between the process bar and the clock.
* Click your network - or select "Connect to Hidden Wireless Network" if it's not there and fill out the details.
* Fill out the keyring for your passwords to go into - so you only need to remember the one ;)
* The Network Manager icon should spin and then give you a strength bar as normal once connected.

=== Synaptic ===
The 1.0.1 release did not include Synaptic.. it's back in 1.0.2 and 1.0.3<br />
To get it back for the 1.0.1 release, it's simply a case of doing:<br />
'''''sudo apt-get update''''' - if you haven't done so for a while ( as in, days, not hours )<br />
'''''sudo apt-get install synaptic'''''<br />
Then wait for a while as it downloads and installs.

You'll find Synaptic under System Tools once it's done.

=== My PNDs don't work, why?! ===
Generally, it'll be because of library differences.. I'm still trying to figure out the best way to deal with this, but you've got the Debian armel repository at your disposal, so you should be fine for a while!

1.0.2 has some library compatibility with Pandora Angstrom but it's not complete. The PNDs of Wesnoth and BattleJewels will work for example, whereas SuperTux and GravityForce do not.

Library compatibility was achieved by pulling packages manually from older revisions, symlinking some libraries and pulling stuff from experimental.. it was trial and error so, is a tad iffy.

1.0.3 and 1.0.4 do not have library compatibility as it caused extra issues in 1.0.2, you'll need to either wait for 1.1 or pull in the needed libraries yourself.

=== Wifi and Session Management is broken?! ===
Pre-1.0.3 there was an issue with this.. it should now be fixed in 1.0.3 so if you don't want to update, perform the following:<br />
'''''sudo rm -f /etc/udev/rules.d/70-persistent-net.rules'''''<br />
'''''sudo chmod +x /usr/lib/dbus-1.0/dbus-daemon-launch-helper'''''<br />
and reboot.. everything should now work properly.

=== My PNDs don't appear immediately? ===
This is an odd one.. by rights they should.. and I also don't quite understand why pndnotifyd kicks in when you open a terminal, but it does.

Therefore, if you haven't done so already, open up a terminal and then close it.. pndnotifyd then starts up and takes care of all the PND stuff for you.

This should be fixed in 1.0.4

=== I get no notifications in 1.0.3 ===
This is actually because notification-daemon hasn't been installed.

=== Packages to add in 1.1! ===
Feel free to add packages here that I should include in the next release (1.1)
* wireless-tools
* x11-xserver-utils ( I keep forgetting this.. it's for xmodmap )
* xinput - for evdev's configuration
* console-tools - for chvt
* xterm - for failsafe console
* bash-completion - tis handy to have
* aptitude - somehow I forgot this.

= Emdebian Grip =
Most of the above can be taken for Grip, with the following changes...

Why Grip? It's much smaller and targeted for embedded devices... I originally was going to use Grip actually, but it was a bit buggered at the time, though it seems to be working now.<br />
Additionally, Emdebian comes in Crush and Baked flavours... Grip is compatible with Desktop Debian, so we'll use that.. Crush is smaller again, and generally requires a cross-compiler to setup packages, and Baked is effectively what we do with Angstrom.

Emdebian could also in theory be shrunk enough to actually fit on NAND... which is something I'll be looking into - if only to document another alternative process to the Angstrom OE bitbake bonanza.

== Multistrap ==
Grip's debootstrap is slightly different... it uses multistrap instead.

This allows us to use Grip's repository as the base, and Desktop Debian's repositories for anything else we might need ( omap3 drivers, for instance. ) This is also particularly useful for us when I get around to doing Pandora specifics compiled for Debian, as then we just add that repository as well.

Anyway, we need Debian running for this - be it on your Desktop ( or Ubuntu ) or on your Pandora ( recommended, as this guide assumes this is what you're doing. )<br />
Install Multistrap - '''''sudo apt-get install multistrap'''''

You'll also need to mount an SD card somewhere manually.. I've mounted mine to /tmp/emdebian: '''''sudo umount /dev/mmcblk1p1 && mount /dev/mmcblk1p1 /tmp/emdebian'''''

=== Config File ===
'''''nano multistrap'''''
 [General]
 arch=armel
 directory=/tmp/emdebian
 cleanup=true
 noauth=false
 unpack=true
 aptsources=Grip Debian
 debootstrap=Grip Debian
 
 [Debian]
 packages=
 source=ftp://ftp.uk.debian.org/debian
 keyring=debian-archive-keyring
 suite=squeeze
 
 [Grip]
 packages=
 keyring=emdebian-archive-keyring
 source=http://www.emdebian.org/grip
 suite=squeeze

'''''sudo multistrap -f multistrap'''''

Change /tmp/multistrap to where ever you want the debootstrap to occur.<br />
'''Gotcha''''' I had issues with it complaining about unauthenticated packages, just add '''--no-auth''' to your command line and it'll continue happily.''

This shouldn't take too long ( was about half an hour on my Pandora ) and gives you a very sparse minimal rootfs of 192Mb.

The following multistrap config will give you what's in the 1.0.4 Grip rootfs
 [General]
 arch=armel
 directory=/tmp/emdebian
 cleanup=true
 noauth=false
 unpack=true
 aptsources=Grip Debian
 debootstrap=Grip Debian
 
 [Debian]
 packages=xserver-xorg-video-omap3 libxcb-dri2-0 libnotify-bin xinput
 source=ftp://ftp.uk.debian.org/debian
 keyring=debian-archive-keyring
 suite=squeeze
 
 [Grip]
 packages=lxde busybox network-manager-gnome xfce4-power-manager apmd gdm less sudo nano wireless-tools iceweasel synaptic gnome-mplayer x11-xserver-utils notification-daemon gnome-keyring
 keyring=emdebian-archive-keyring
 source=http://www.emdebian.org/grip
 suite=squeeze

You could also add packages into the Grip and Debian configuration parts, and it will automatically pull them down and install them for you, be careful with what you pull in though, as not everything has been repackaged for Grip, so it will pull down the "full fat" variants from Debian instead.

You might get errors of unconfigured packages, just chroot in and run '''''apt-get -f install''''' to finish up.. if there are warnings about proc, ignore them till you reboot into the rootfs and re-run '''''sudo apt-get -f install'''''.

== Chroot and Setup ==
Now we can just chroot in and setup as we see fit.<br />
'''''sudo chroot /tmp/emdebian''''' - again, you may have mounted your media elsewhere.<br />
'''''sudo apt-get update'''''

You can now just follow the Debian guide as above, with the added bonus of most packages will come from Grip and be pre-stripped of extra fluff.<br />
I would recommend to get as much stuff as possible downloaded in the initial multistrap however, as it will automatically clean stuff up for you.

= Debian On NAND =
First of all, <br />
'''''WARNING: DO NOT ATTEMPT THIS.'''''<br />
'''''NO, SERIOUSLY, DON'T! THIS IS UTTERLY HACKY AND IT IS ON YOUR OWN HEAD IF YOU MESS UP.'''''<br />

== Get a Debian Rootfs ==
Your NAND has about 475Mb for the rootfs to play with ( there are other partitions, remember! ), therefore Desktop Debian is a bit too large for our purposes - even 1.0.3's complete massacre still ended up too big by far; so we need to look at Emdebian, of which there are three flavours - grip, crush and baked.<br />
We'll be using Grip, so follow the guide above for at least getting a working system on SD before going anywhere near your NAND.

We can use compression to get your rootfs down by 40-50%, but I'd still be vary wary of a large rootfs!

If you're lazy, grab my pre-made Grip rootfs, which includes LXDE by default.

== Preparing the Rootfs ==
Boot into your rootfs for this, so we can ensure we're as up to date as we can be, then clean the apt cache, and then any crap we installed which we don't need any more, such as things which were installed as dependencies and the parent's been removed.<br />
'''''sudo apt-get update'''''<br />
'''''sudo apt-get upgrade'''''<br />
'''''sudo apt-get clean'''''<br />
'''''sudo apt-get autoclean'''''<br />

Additionally, you could wipe out the documentation ( if any ) and manually pull out unwanted packages. However, if you're pulling stuff out, you shouldn't have installed it in the first place! Go back to the start and do it again as punishment!

This post on the Ubuntu forums is particularly helpful: http://ubuntuforums.org/showthread.php?t=140920

Depending on your needs, you may also want to wipe out your home folder and reinstate it from /etc/skel<br />
You'll also want to wipe out tmp - '''''sudo rm -rf /tmp/*'''''

Now shut down and either place your SD card in your PC. You can do this on Pandora, but you will need a lot of space.

Copy your rootfs somewhere.. I suggest /tmp/pandora-debian<br />
'''''mkdir /tmp/pandora-debian'''''<br />
'''''sudo cp -p -r /media/my/sd/card/* /tmp/pandora-debian''''' - this will preserve Permissions and copy everything Recursively.

We need to edit the fstab so that it can boot properly, if you haven't done so already.<br />
'''''sudo nano /tmp/pandora-debian/etc/fstab'''''
 # OpenPandora fstab.
 
 rootfs               /                    auto       defaults,noatime      1  1
 proc                 /proc                proc       defaults              0  0
 devpts               /dev/pts             devpts     mode=0620,gid=5       0  0
 usbfs                /proc/bus/usb        usbfs      defaults              0  0
 tmpfs                /var/volatile        tmpfs      defaults              0  0
 tmpfs                /dev/shm             tmpfs      mode=0777             0  0
 tmpfs                /media/ram           tmpfs      defaults              0  0

This should look familiar, as it's effectively your stock fstab minus the boot partition ( we have a kernel in our rootfs, if you've followed the above guides... )

We should also get rid of the autoboot.txt or boot.txt; '''''sudo rm /tmp/pandora-debian/autoboot.txt'''''

== Creating the Image ==
You need mtd-utils in your Debian distro of choice. '''''sudo apt-get install mtd-utils'''''

Now, mkfs.ubifs can compress using either LZO ( by default ) or zlib and will get your rootfs about 40-50% smaller depending on what you choose. It's also possible to use a combination of both, which is what we will do later.. Of course, if your rootfs is full of pre-compressed stuff already, it's not really going to shrink a great deal.<br />
For a full run down on mkfs.ubifs and co, see here: http://www.linux-mtd.infradead.org/doc/ubifs.html

Download the flash kit: http://openpandora.org/firmware/pandora-flash-kit.zip and extract it to /tmp/flash. I suggest reading the README as well.

Now run these fun commands... what we're doing is we're making a ubifs image first, then making an md5 checksum.<br />
We're also favoring LZO compression meaning we're mixing zlib and LZO to get the best compression we can.<br />
'''''sudo mkfs.ubifs -r /tmp/pandora-debian -o rootfs.img -m 2048 -e 129024 -c 4042 -x favor_lzo -X 20'''''<br />
'''''md5sum rootfs.img > rootfs.md5'''''

'''STOP! If your rootfs.img is getting close to 480Mb, you might not want to try and flash it.. it may be fine, but I would recommend 450Mb as an absolute maximum.'''

== Flashing the Image ==
I shall repeat:<br />
'''''WARNING: DO NOT ATTEMPT THIS.'''''<br />
'''''NO, SERIOUSLY, DON'T! THIS IS UTTERLY HACKY AND IT IS ON YOUR OWN HEAD IF YOU MESS UP.'''''<br />

Stick the following on to a FAT32 formatted SD card:<br />
* '''boot.scr''' - from the flash kit.
* '''rootfs.img''' - the image you've just created.
* '''rootfs.md5''' - the checksum to the image.

Place it in slot 1 of your Pandora ( the left slot, ) reboot while holding the right trigger, select boot from SD, cross your fingers and pray to the Pandora Gods.

Once it's done.. reboot and see what mess you've made, assuming you get it to boot!<br />
If you haven't got it to boot, on your FAT32 flasher card, add an autoboot.txt with the following:
 setenv bootargs ubi.mtd=4 ubi.mtd=3 root=ubi0:rootfs rootfstype=ubifs rw vram=6272K omapfb.vram=0:3000K
 ubi part boot && ubifsmount boot && ubifsload ${loadaddr} uImage && bootm ${loadaddr};

As this will let you see what's gone wrong... I had to do this a few times, as I buggered it up myself...

Congratulations, you now have Debian on NAND rather than Angstrom.<br />
Also, these instructions could easily be adapted to allow you to use any other distro that boots on Pandora.

[[Category:Documentation]]
[[Category:Operating system]]
[[Category:Storage card]]
[[Category:Booting]]