Debian

From Openmoko

(Difference between revisions)
Jump to: navigation, search
(Bluetooth: then what?)
(add a remark that zhone is dead and phoneui-apps should be used instead)
 
(183 intermediate revisions by 45 users not shown)
Line 1: Line 1:
 
{{Languages|Debian}}
 
{{Languages|Debian}}
= Installation =
 
There are "official" instructions on how to install [http://wiki.debian.org/DebianOnFreeRunner Debian on FreeRunner] or [http://wiki.debian.org/DebianOnNeo1973 Debian on Neo1973] (see the [http://lists.linuxtogo.org/pipermail/smartphones-standards/2008-August/000232.html original announcement]).
 
  
Previous information (partly outdated, now) on how to install Debian manually has been moved to [[Manual Debian]].
+
Debian is a ''universal operating system'' used on many other embedded devices, and also on home computers. Using Debian on the FreeRunner gives access to the Huge army of software packaged in the Debian repositories, already compiled for the Neo's arm(v4) processor. Moreover, one can build one's own source files for programs without having to learn the OpenEmbedded way. For example compiling natively is a snap with Debian, just apt-get gcc&libc-dev.
  
See also : http://www.debian.org/ to know more about Debian.
+
For an existing Debian/Ubuntu user, choosing Debian for Neo FreeRunner makes phone a very familiar, trustworthy and flexible place to hack in.
  
From time to time the Debian packages may be broken, which will cause the install.sh script to fail. Since waiting for the packages to be fixed can take quite a lot of patience, [http://dgym.homeunix.net/projects/freerunner/debian-install/ here] is an alternative method of getting Debian installed on the FreeRunner.
+
'''The bulk of information related to running Debian on FreeRunner is supposed to be at [http://wiki.debian.org/ wiki.debian.org]. For all installation, support or bug reporting needs please see [http://wiki.debian.org/DebianOnFreeRunner DebianOnFreeRunner] in the Debian wiki.'''
  
= System =
+
''The current method of installation, install.sh, is not fail-proof. Work is progressing on a real debian-installer support.'' Please be sure Bash is installed before trying install.sh. The main reason why install.sh fails is because it installs debian unstable which is constantly in motion.
== Password ==
+
  
The default root password is blank. You should change that as soon as you can:
+
== Screenshot for Manual ==
# passwd
+
It might be useful to improve this manual with screenshots. You can create screenshots on Debian with [http://www.imagemagick.org ImageMagick]:
If entering a blank password does not work at first, try rebooting. If still no success, boot to 2008.08/2007.02, chroot to the micro SD card and set a new password.
+
  # sudo apt-get install imagemagick
  
== Speeding up booting ==
+
Then you can take a screenshot of the full screen with the '''import'''-command:
'''Note''': By default, Debian is already configured to write limited messages to the console during boot.  Does this actually speed things up anymore?
+
  
What's good for every linux booting is also good for our debian on the freerunner: booting in quiet mode. To do so by default just boot your Neo FreeRunner in NOR-Flash and execute this configure-script: [http://paste.ubuntuusers.de/391456/ configure-uboot.sh].
+
  # import -window root screenshot.jpg
  
It changes default booting to quiet-mode and adds another boot-option to boot without quiet-mode for debugging purpose.
+
If you take the screenshot with some delay you have to add the pause parameter (e.g. waiting for  10sec)
  
== Suspend ==
+
import -pause 10 -window root screenshot.jpg
 +
 +
== Installation Debian on Freerunner ==
 +
The following steps are a quick installation guide with and installed [[SHR]] on your freerunner and [[Qi]] as bootloader already installed on your freerunner. For further information refer to the [http://wiki.debian.org/DebianOnFreeRunner Debian on Freerunner Wiki] from which this short summary is derived from.
  
'''Note''': As of Sep. 15 2008, suspend works 'out-of-the-box'; installing apm and the idle clock configuration changes do not seem to be necessary any more.  Press the power button for two seconds (in zhone) or run 'apm -s' to suspend.
+
{{Note|The installation script for Debian, used in the following manual, stopped on SHR with errors. To run a complete Debian installation process it might be necessary to flash the FR with current minimal rootfs for SHR again. You could also try in your [[SHR]] distribution to remove some software packages with [[opkg]] (not tested). Recommended to flash memory with a minimal [[SHR]].}}
 +
The following manual was successful with a fresh flash of [[SHR]] in NAND memory.
  
To make suspend available you have to install apmd:
+
=== Installing Qi ===
apt-get install apmd
+
The following manual needs [[Qi]] to be installed as bootloader. If you more options for using the bootloader usethe [http://wiki.debian.org/DebianOnFreeRunner Debian on Freerunner Wiki] for further details.
After that you can suspend your phone with:
+
   apm -s
+
Switch off you freerunner (if necessary) and start NOR uBoot by pressing AUX and Power-On at the same time and then start [[dfu-util]] on your desktop computer with the following parameters for GTA2:
and make it wake up again with pressing the power button.
+
   # dfu-util -a u-boot -R -D [http://wiki.openmoko.org/wiki/Qi#Download qi-s3c2442-master-hist_3b8513d8b3d9615e.udfu]
 +
See [[Flashing the Neo FreeRunner]] or [[Flashing the Neo 1973]] for more details on flashing your phone.
  
 +
=== Online Script Installation ===
 +
==== Login to Freerunner with SHR ====
 +
Login to your freerunner with the booted SHR distribution:
 +
# ssh -X -l root 192.168.0.202
 +
and an [[USB Networking]] connection (e.g. IP-address 192.168.0.202 of your freerunner). Change the IP-address if your network settings differ from this IP-address. Prepare SHR so that you have a working internet connection from your freerunner. This is necessary because SHR will download the Debian packages.
  
Issues:
+
==== Script Installation and Running install.sh ====
* [[User:Wuth|Wuth]] 06:28, 17 August 2008 (UTC): I found that apmd was already installed by using the official debian installation procedure, but that the kernel didn't support apmI haven't yet resolved this issue.  [[User:Wuth|Wuth]] 05:31, 7 September 2008 (UTC): Worked fine on second installPerhaps this is no longer a problem.
+
Run the following commands from shell in SHR after ssh-login to freerunner:
 +
# wget -O install.sh http://pkg-fso.alioth.debian.org/freerunner/install.sh
 +
  # chmod +x install.sh
 +
  # TASKS="ALL" QI=true ./install.sh all
 +
The following commands above assumes that you have [[Qi]] installed and you want to use a single partition for Debian on freerunner. The SD card (2GB suggested) will be formated by the script.   
 +
* If you want to install Debian with different installation parameters or
 +
*  if you ran into network problems or errors during installation
 +
please see [http://wiki.debian.org/DebianOnFreeRunner DebianOnFreerunner-Wiki] for further details and support.
  
* [[User:Phyce|Phyce]] 21:33, 20 August 2008 (UTC)  installed apm without problems; apm -s shutdowns the freerunner but I couldn't wake it up with power button... I had to remove the battery to boot again. suspend/resume was working quite reliably with latest kernels on ASU.
+
{{Note|The installation could take more than 90 minutes to complete and you will download approximately 250MB on your freerunnner. Time for installation is depending on network speed.}}
  
To wake up successfully, the idle-clock of the SD card needs to be enabled right before suspend. It can be disabled again right after resume (this reduces GPS interference). Write into /etc/apm/suspend.d/00sd_idleclk
+
After successful installation you will see:
<pre>
+
  I: Unmounting - done
#!/bin/sh
+
  I: All done!
echo 1 > /sys/module/glamo_mci/parameters/sd_idleclk
+
  Now reboot, and hope for the best!
touch /home/root/.profile
+
Shutdown SHR operating system with:
</pre>
+
# shutdown -h now
and into /etc/apm/resume.d/00sd_idleclk
+
Press power on button to start Debian via Qi:
<pre>
+
#!/bin/sh
+
echo 0 > /sys/module/glamo_mci/parameters/sd_idleclk
+
</pre>
+
These are from -stacy on the community list.
+
  
And anotherone from [[User:Morlac|Morlac]]: (more debianish i think ;) <br />
+
=== debian4freeunner.tar.gz ===
etc/apm/scripts.d/sd_idleclk and corresponding link in /etc/apm/event.d<br />
+
The online installation process sometimes fails. It is be helpful to an tar.gz-image for Debian that could be extracted to a SD-card with an installed bootloader [[Qi]]
(don't forget to chmod +x /etc/apm/scripts.d/sd_idleclk)
+
  
<pre>
+
One such tarball is available here (add others if you have):
#!/bin/sh
+
SD_IDLECLK="/sys/module/glamo_mci/parameters/sd_idleclk"
+
[ -e "${SD_IDLECLK}" ] || exit 0
+
  
case "${1},${2}" in
+
http://people.debian.org/~timo/NeoFreeRunner/ (Debian_NeoFreeRunner_minimalrootfs_20120321.tar.xz)
(suspend,*)
+
echo 1 > ${SD_IDLECLK}
+
touch /etc
+
;;
+
(resume,suspend)
+
echo 0 > ${SD_IDLECLK}
+
;;
+
esac
+
  
exit 0
+
Note that it is a ''minimal'' rootfs, meaning that your first job is to connect to the device over USB cable and install more packages to your liking. Some basic libraries/daemons like FSO2 and omhacks are available, though, and the X starts (pretty much empty) by default via /root/.xsession. Root password is the default 'changeme'.
</pre>
+
  
== Time ==
+
==== First Login on Debian ====
 
+
Your Linux Desktop has created RNDIS/Ethernet Interface, configure the interface as in [[USB Networking]] explained:
The default time zone is UTC.  Reconfigure it by running
+
RNDIS/Ethernet Gadget
<pre>
+
Now you can login on Debian (if booted) with:
# dpkg-reconfigure tzdata
+
  # ssh -X -l root 192.168.0.202
</pre>
+
{{Note|'''(SSH Known Hosts)''' If you have installed other distributions on your Freerunner before, edit '''<tt>.ssh/known_hosts</tt>''' and remove old key for your freerunner. }}
To set the clock manually do something like
+
The default password is ''"changeme"'', so change the password directly after first login on your Freerunner with:
<pre>
+
  neo# passwd
# date -s 00:33
+
Then run an update for apt-get
</pre>
+
  neo# apt-get update
If you have a network connection, do something like
+
This could take several minutes depending on network speed.
<pre>
+
# apt-get install ntpdate
+
# ntpdate-debian
+
</pre>
+
 
+
Issues:
+
* That's probably not sufficient to keep the clock accurate.  It might be worth configuring some form of NTP.
+
** Setting the clock could be done via GPS: [[Getting_GPS_console_output_with_gllin#GPRMC_message]]
+
 
+
== WLAN ==
+
=== wifi GUI ===
+
 
+
If you don't want to mess up with configuration files and is looking for an easy gui for wireless configuration, then wifi-radar or wicd is what you are looking for.
+
 
+
<pre>apt-get install wifi-radar
+
wifi-radar</pre>
+
 
+
or
+
 
+
<pre>apt-get install wicd
+
wicd-client -n</pre>
+
 
+
If you are looking for more, read on...
+
 
+
=== Installing prerequisites ===
+
 
+
Make sure the following packages are installed:
+
<pre>apt-get install wireless-tools wpasupplicant dhcp3-client</pre>
+
 
+
=== Example configurations ===
+
 
+
==== Single network configuration ====
+
 
+
Assuming your wireless router uses WPA security and DHCP,
+
edit <code>/etc/network/interfaces</code> to include a section like this:
+
<pre>
+
auto eth0
+
iface eth0 inet dhcp
+
wpa-driver wext
+
wpa-ssid "MyWirelessName"
+
wpa-psk "MyWirelessPassword"
+
</pre>
+
Where, of course, you're using the name of your wireless network and it's password
+
instead of ''MyWirelessName'' and ''MyWirelessPassword''.
+
 
+
You can test by running
+
<pre>
+
# ifup eth0
+
</pre>
+
You can determine your IP address by running
+
<pre>
+
# ifconfig eth0
+
</pre>
+
Issues:
+
* only works if in presence of wireless network on boot, or when manually running <code>ifup eth0</code>
+
* booting away from wireless network is slower because waits for DHCP to time out
+
* does not reestablish connection when leaving wireless area and then returning
+
* does not support multiple wireless networks or open hotspots that you may travel between
+
 
+
Once wpa_supplicant has begun managing your wifi interface, you should type "wpa_action eth0 stop" instead of "ifdown eth0".
+
 
+
==== Roaming configuration ====
+
 
+
'''Todo''': Which of the issues that single network configurations suffer from are addressed by WPA roaming mode?  Would ifplugd / guessnet help, or just make things more complicated?
+
 
+
* Roaming from network to network is not automatic.  Instead, you need to manually run "wpa_action eth0 stop; ifup eth0" to switch networks
+
 
+
===== wpa_supplicant.conf =====
+
 
+
To configure WPA to roam between wireless networks, you will need to create a new configuration file:
+
 
+
/etc/wpa_supplicant/wpa_supplicant.conf
+
 
+
a template for this file (and more documentation) is available in:
+
 
+
/usr/share/doc/wpasupplicant/examples/wpa-roam.conf
+
 
+
You'll need to add networks to this file.  Examples:
+
 
+
* WEP:
+
<pre>
+
network={
+
      ssid="MySSID"
+
      key_mgmt=NONE
+
      wep_key0="abcdefghijklm"
+
#      wep_key0=6162636465  # <- no quotes, so hex number
+
      wep_tx_keyidx=0
+
      id_str="MySSID"
+
}
+
</pre>
+
* No key:
+
<pre>
+
network={
+
      ssid="SomeNetwork"
+
      key_mgmt=NONE
+
}
+
</pre>
+
* WPA:
+
<pre>
+
network={
+
      ssid="Example WPA Network"
+
      psk="mysecretpassphrase"
+
      id_str="home"
+
}
+
</pre>
+
 
+
===== /etc/network/interfaces =====
+
 
+
Next, you'll need to edit /etc/network/interfaces.  This lets you configure your wireless networks to use dhcp, or other appropriate TCP/IP settings:
+
<pre>
+
auto eth0
+
iface eth0 inet manual
+
wpa-driver wext
+
wpa-roam /etc/wpa_supplicant/wpa_supplicant.conf
+
 
+
# MySSID comes from an id_str above.
+
iface MySSID inet dhcp
+
 
+
# default is what's used if there is no id_str setting.
+
# so the 'SomeNetwork' network will use DHCP.
+
iface default inet dhcp
+
 
+
iface home inet static
+
# static interface settings, or whatever...
+
</pre>
+
 
+
Finally, if you want attempts to access the internet to default to eth0 (and not usb0), then comment out this line under usb0 adapter configuration:
+
 
+
<pre>
+
gateway 192.168.0.200
+
</pre>
+
 
+
For some reason, I had to reboot for the id_str settings to take effect.  However, you should now be able to use "ifup eth0" to associate with the access point and "wpa_action eth0 stop" to down the wifi adapter.
+
 
+
=== Further reading ===
+
 
+
To use all the possibilities of <code>wpasupplicant</code> like roaming and automatic connection to different networks,
+
you should read <code>/usr/share/doc/wpasupplicant/README.Debian.gz</code>
+
 
+
== [[Bluetooth]] ==
+
The FreeRunner uses the standard Linux bluez stack, installed with
+
# apt-get install bluez-utils
+
There is also a module missing from /etc/modules, which is critical to getting your device recognized. (kudos to johnsu01 on irc.freenode.net:#openmoko-debian for the find)
+
# echo ohci-hcd >> /etc/modules
+
The first time you try this, you can also
+
# modprobe ohci-hcd
+
The only atypical part of using bluetooth on the FreeRunner is turning it on, which can be done with
+
# echo 1 > /sys/bus/platform/devices/neo1973-pm-bt.0/power_on
+
# echo 0 > /sys/bus/platform/devices/neo1973-pm-bt.0/reset
+
Then the device should be visible using
+
# hcitool dev
+
 
+
The rest of the steps are easy...???
+
 
+
== Better Xorg ==
+
By default debian uses fbdev... But we can use Xglamo:
+
<pre>apt-get install xserver-xglamo</pre>
+
after that edit /etc/X11/xorg.conf and change the line
+
<pre>Driver          "fbdev"</pre>
+
to:
+
<pre>Driver          "Xglamo"</pre>
+
and if you want to run xserver as normal user:
+
<pre>chmod u+s /usr/bin/Xglamo</pre>
+
 
+
with that you:
+
*can use xrandr
+
*don't have the pointer callibration bug with the rotated mode
+
*have better performances
+
 
+
== Running X as normal user ==
+
1. Create a new user
+
<pre>
+
# useradd -m -G audio,dialout,floppy,video,staff username
+
# passwd username
+
</pre>
+
 
+
2. Edit /etc/init.d/zhone-session (or /etc/init.d/xfce if you are using xfce, see over) and change USER=root to USER=username in it. Then to make sure changes are not lost on upgrade, run
+
<pre>
+
dpkg-divert --add /etc/init.d/zhone-session
+
</pre>
+
This will make new versions of /etc/init.d/zhone-session be written to /etc/init.d/zhone-session.distrib
+
 
+
3. Edit <code>/etc/X11/Xwrapper.config</code> and change <code>allowed_users=console</code> to <code>allowed_users=anybody</code>
+
 
+
4. Make apm setuid root so that zhone can do suspend and make it only executable for users in the staff group
+
<pre>
+
dpkg-statoverride --update --add root staff 4750 /usr/bin/apm
+
</pre>
+
It would also be possible to use sudo, but then you would have to edit /usr/bin/zhone.
+
 
+
5. Note that, if you ran zhone as root first, you may have to change ownership or remove /tmp/zhone.log, as a normal user is not able to write to a file owned by root.
+
 
+
== Sound ==
+
Make sure to put your user in the audio group ("adduser <username> audio").
+
 
+
If there is no error but no sound, try these state files:
+
[[Talk:Manual_Debian#Sound]]
+
 
+
== How to replace the default kernel with a recent openmoko kernel ==
+
 
+
If you would like to update to a new kernel, here is a short summary of what to do to update the kernel to an actual OM kernel. But only do this if you know what you are doing.
+
At the moment there is a little problem in the question which kernel to use. Hopefully it will be solved in the near future.
+
 
+
The original openmoko kernel works fine except for the fact that suspending with zhone doesn't work. But this kernel supports different really nice usb gadgets. :)<br>
+
download stable: http://downloads.openmoko.org/releases/Om2008.9/<br>
+
download testing: http://downloads.openmoko.org/daily/
+
 
+
The new FSO3 kernel works fine and suspend/resume with zhone is also possible. But this kernel still has no loadable usb gadget modules (17-Sep-2008 01:39). :/<br>
+
download testing: http://downloads.freesmartphone.org/fso-testing/images/<br>
+
download unstable: http://downloads.freesmartphone.org/fso-unstable/images/
+
# Download a recent'' kernel'' and ''rootfs'' (tar.gz) from one of the above mentioned sources. It's your decision if you want suspend or usb gadget modules at the moment.
+
# Backup your running kernel like <code>mv /boot/uImage.bin /boot/uImage.bin.old</code>, then <br>copy the downloaded uImage file to the freerunner as <tt>/boot/uImage.bin</tt>.
+
# Backup your actual modules like <code>mv /lib/modules/2.6.24 /lib/modules/2.6.24.old</code>, then <br>extract the downloaded rootfs tar.gz to a temporary directory and copy <tt>lib/modules/2.6.24</tt> from the temp directory to <tt>/lib/modules/2.6.24</tt> on the FreeRunner.
+
# Run a <code>depmod -a</code>.
+
# Do a <code>chown -R root.root /lib/modules/2.6.24</code> because the owner from the tar.gz is something else.
+
# This step is only needed for the OM kernel but it doesn't harm the FSO kernel setup. Add "g_ether" Module to /etc/modules like <code>echo g_ether >> /etc/modules</code>. I read in an email, that the module "ohci-hcd" is also needed for some bluetooth functions, but i don't know this for real. I inserted it to my modules file to be on the safe side.
+
# Reboot and hope everything works as expected. :)
+
--[[User:Pini]]
+
* Sun Sep 28 15:01:46 UTC 2008: Actually suspend/resume doesn't work anymore on the Neo Freerunner with the FSO3 kernel starting from september 16th. It does work with the Om2008.8 kernel from september 3rd.
+
* Mon Oct 20 15:30:56 UTC 2008: working suspend/resume is back with FSO kernel 2.6.24+r10.1 from october 17th.
+
 
+
= Software =
+
You can install <tt>[http://packages.debian.org/search?keywords=dselect dselect]</tt>(~2.2MB) or <tt>[http://packages.debian.org/search?keywords=aptitude aptitude]</tt>(~12MB) to visually inspect the available debian packages using the desktop's console.<br>
+
Also the gtk-based package-manager <tt>[http://packages.debian.org/search?keywords=synaptic synaptic]</tt>(~15.7MB) is probably working.<br>
+
Finally, on constrained systems, just issue the command:
+
<pre>grep -e Package: -e Description /var/lib/dpkg/available|more</pre>
+
== Web Browser ==
+
[http://lists.openmoko.org/nabble.html#nabble-td781547 Arne Anka suggested] trying the light-weight webkit-based [http://en.wikipedia.org/wiki/Midori_(browser) midori] browser:
+
<pre>apt-get install midori</pre>
+
 
+
If you think Midori is quite slow on Freerunner try Links2.
+
 
+
<pre>apt-get install links2</pre>
+
 
+
Run as:
+
 
+
<pre>xlinks2</pre>
+
 
+
== TangoGPS ==
+
{{main|TangoGPS}}
+
== e-book reader ==
+
{{main|FBReader}}
+
 
+
Evince is also available in debian, and handles pdf, djvu, cbz, and other formats.
+
 
+
There is also a hack to convert drm protected adobe ebooks to .cbz files readable with evince, which is mentioned on the mailing list.
+
 
+
== XFCE ==
+
 
+
xfce is small and lightweight and so is quite fast for the FreeRunner.
+
 
+
<pre>apt-get install xfce4
+
cp /etc/init.d/zhone-session /etc/init.d/xfce</pre>
+
 
+
Then you may hack /etc/init.d/xfce making
+
 
+
<pre>PROG_FSO=/usr/bin/startxfce4</pre>
+
 
+
Customize the boot process (this may have to be redone when zhone-session is updated):
+
 
+
<pre>update-rc.d -f zhone-session remove
+
update-rc.d -f xfce defaults</pre>
+
 
+
edit your /etc/hosts to have :
+
 
+
<pre>127.0.0.1 localhost debian-gta02</pre>
+
 
+
Start XFCE !
+
 
+
<pre>/etc/init.d/zhone-session stop
+
/etc/init.d/xfce start</pre>
+
 
+
The desktop takes a while to start but once up was snappy as can be expected.
+
I've not yet looked at the reason for the seemingly too slow start for the desktop.
+
 
+
zhone is available from the "Office" menu in xfce.
+
The matchbox keyboard is available in "Accessories".
+
 
+
If you want to display the screen on the long side (ie rotated, 4:3 aspect), add the following to the /etc/X11/xorg.conf in both the Device and InputDevice sections :
+
 
+
<pre>Option          "Rotate"                "CCW"</pre>
+
 
+
and then (re)start xfce.
+
 
+
If you want to be able to shutdown/restart the device, add the following line to ''/etc/sudoers'' (don't forget to replace ''username'' with your actual username):
+
<pre>username localhost = NOPASSWD: /usr/sbin/xfsm-shutdown-helper</pre>
+
 
+
=== Using matchbox-window-manager with XFCE ===
+
 
+
XFCE's window manager is poorly configured for use with the FreeRunner.  Fortunately, matchbox's window manager is compatible with xfce.  To use the matchbox window manager, arrange to run the following commands at X startup.  If you followed the instructions above to run X as a normal user, put this in ~/.xinitrc:
+
 
+
<pre>#!/bin/sh
+
 
+
zhone &
+
matchbox-keyboard-toggle &
+
exec matchbox-window-manager -use_titlebar no -use_cursor no &
+
xfce4-session</pre>
+
  
 +
== Debian Showcase: Desktop Environments And Applications ==
  
{{Todo|And if I didn't run X as a normal user?}}
+
=== fbpanel + Matchbox ===
  
== Using matchbox-window-manager with fbpanel as normal user without gdm ==
+
It is not really a Desktop environment, but using fbpanel with Matchbox you can have a fast, lightweight, gtk2 desktop panel.
fbpanel is a fast, lightweight, gtk2 desktop panel.
+
[[Image:Debian_fbpanel_zhone.png|right|thumb|150px|Debian with fbpanel, matchbox-window-manager and Zhone running, default settings]]
[[Image:Debian_fbpanel_zhone.png|right|thumb|300px|Debian with fbpanel, matchbox-window-manager and Zhone running]]
+
[[Image:Debian5.png|right|thumb|150px|Custom matchbox theme and fbpanel configuration.]]
<ol><li>Follow http://wiki.openmoko.org/wiki/Debian#Running_X_as_normal_user</li>
+
<li>Customize the boot process:
+
<pre>sudo cp /etc/init.d/zhone-session /etc/init.d/xserver
+
sudo nano /etc/init.d/xserver</pre>
+
Find (all in one line)
+
<pre>start-stop-daemon --start --pidfile ${PIDFILE}
+
--make-pidfile --background --exec /bin/su --
+
--login --command "${PROG_XINIT} ${PROG_XSESSION} ${PROG_FSO}
+
-- $X_OPTIONS" $USER</pre>
+
Change it to (all in one line):
+
<pre>start-stop-daemon --start --pidfile ${PIDFILE}
+
--make-pidfile --background --exec /bin/su --
+
--login -c "startx" ${USER}</pre>
+
Add script to daemons:
+
<pre>sudo update-rc.d -f zhone-session remove
+
sudo update-rc.d -f xserver defaults</pre></li>
+
  
<li>Install fbpanel:
+
Quick howto:
<pre>sudo apt-get install fbpanel</pre></li>
+
<ol><li>Install fbpanel:
<li>Customize configs:
+
<pre>sudo apt-get install fbpanel hicolor-icon-theme</pre></li>
<ol><li><pre>~/.xinitrc</pre>
+
<li>Customize the X startup process:
 +
<pre>~/.xsession</pre>
 
<pre>
 
<pre>
 
#!/bin/sh
 
#!/bin/sh
Line 442: Line 126:
 
type = genmon
 
type = genmon
 
config {
 
config {
Command = echo -e $(grep "MemFree" /proc/meminfo | awk '{printf "%0.2f", $2 / 1024}') "|" $(cat /proc/loadavg | awk '{print $3}') "|" $(apm | awk '{print $5}')
+
Command = echo -e $(grep "MemFree" /proc/meminfo | \
 +
awk '{printf "%0.2f", $2 / 1024}') "|"\
 +
$(cat /proc/loadavg | awk '{print $3}') "|" \
 +
$(apm | awk '{print $5}')
 
PollingTime = 60
 
PollingTime = 60
 
TextSize = small
 
TextSize = small
Line 448: Line 135:
 
}
 
}
 
}</pre>
 
}</pre>
 +
[[Image:Debian6.png|right|thumb|150px|Custom edje Zhone theme. Click to enlarge]]
 
After 'killall fbpanel' it will show: free mem in megabytes | loadavg | battery % left.</li>
 
After 'killall fbpanel' it will show: free mem in megabytes | loadavg | battery % left.</li>
<li>Default theme is ugly. You can change it and / or make font's bigger:
+
<li>Default theme is ugly. You can change it and / or make fonts bigger:
 
<pre>~/.gtkrc-2.0</pre>
 
<pre>~/.gtkrc-2.0</pre>
 
<pre>sudo apt-cache search gtk2-engines
 
<pre>sudo apt-cache search gtk2-engines
 
sudo apt-get install gtk2-engines gtk-theme-switch
 
sudo apt-get install gtk2-engines gtk-theme-switch
 
DISPLAY=:0 gtk-theme-switch2</pre>
 
DISPLAY=:0 gtk-theme-switch2</pre>
Now choose your theme, font and save it. To see changes do 'killall fbpanel'.</li></ol></li></ol>
+
Now choose your theme, font and save it. To see changes do 'killall fbpanel'. (killall requires psmisc package to be installed)</li></ol>
  
= Miscellaneous =
+
=== Illume ===
== Making the cursor invisible ==
+
[[Image:Debian_illume_zhone.png|right|thumb|150px|Debian with illume, and Zhone running]]
 +
[[Image:Debian_illume_zhone_kb.png|right|thumb|150px|Debian with illume, and Zhone running, with the on-screen keyboard visible]]
 +
[[Illume]], the desktop environment used in recent openmoko distribution releases, is also available under Debian.  It's part of the Enlightenment window manager version 17 (which is currently in the alpha stage of development), which the Debian FSO package maintainers have placed in their repository.  If you have a Debian FSO system running, you can use the following commands to install illume.
  
=== Using matchbox ===
+
apt-get install e17
  
Matchbox has an option, <code>use_cursor</code>, that can be used to control whether to show the cursor.
+
Then use the following commands to ensure that it starts on boot.
For the default setup, edit <code>/usr/bin/zhone-session</code> and change the matchbox command to
+
matchbox-window-manager -use_titlebar no -use_cursor no
+
  
=== Using unclutter ===
+
apt-get remove zhone-session
 +
apt-get install nodm
 +
 +
mv /root/.xsession /root/.xsession.backup
 +
cat << END > /root/.xsession
 +
#!/bin/sh
 +
zhone &
 +
enlightenment_start
 +
END
  
Unclutter is a program that hides the cursor after a period of inactivity. To use unclutter, install it
+
'''Update 03/2012: zhone is a dead end. For current Debian, install phoneui-apps instead, which support the FSO2 now default in Debian.'''
#apt-get install unclutter
+
and choose ''Yes'' to the question <code>Start unclutter automatically?</code>. To change settings edit
+
<code>/etc/default/unclutter</code>.
+
  
=== Changing the cursor ===
+
<br style="clear:both" />
To make the cursor invisible create a file called empty.cursor with this content:
+
<pre>
+
#define empty.cursor_width 16
+
#define empty.cursor_height 16
+
static unsigned char empty.cursor_bits[] = {
+
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00};
+
</pre>
+
Now you can execute:
+
xsetroot -cursor empty.cursor empty.cursor
+
and the cursor will be invisible. To make this permanent you have to invent something ;) It must be executed after zhone has finished starting up.
+
  
== Running X applications on your desktop in nested X server ==
+
=== LXDE ===
Sometimes it is helpful to have a big screen, keyboard and mouse. You can run X applications in a nested X server window.
+
On your desktop install the nested X server application Xephyr (better that Xnest)
+
apt-get install xserver-xephyr
+
Run a nested X server as display :1
+
Xephyr :1 -ac -br -screen 480x640 -reset -terminate &
+
Now you are able to run apps on your Neo which will display on your desktop PC. Make sure to set the display, for example if "mydesktop" is your desktop hostname
+
DISPLAY=mydesktop:1 xfce4-session &
+
  
== Using the mouse and keyboard from your desktop on the OM device ==
+
If you want a really nice desktop enviroment but you think XFCE is too fat, you can try to install [http://en.wikipedia.org/wiki/LXDE LXDE]. It give to you the GTK comfort, but use only a fraction of the ram needed by XFCE.
=== Method 1: xsession export (works with a linux host) ===
+
[[Image:Debian_lxde_zhone.png|right|thumb|300px|Debian with lxde and Zhone running]]
If you are running Linux (or a similar xorg capable operating system) on your Desktop, you can export your xsession to the openmoko device and use your mouse and keyboard on the Neo screen. A little program called x2x makes it even possible to do this simultaneously on the fly. When activated you just move your mouse to the edge of your monitor and then the mouse cursor continues on the screen of your openmoko device. If you select a window on the OM, the input of your keyboard is automatically entered in that window. You can even use the clipboard to copy data from tour desktop to OM and in the reverse direction.
+
To install it:
 +
<pre>apt-get install lxde</pre>
  
Configure your desktop computer to export your xsession:
+
to launch it create a <code>/etc/init.d/lxde</code> script in the same way descripted for xfce4, replacing <code>startxfce4</code> occurrences with <code>startlxde</code>.
On your desktop (with root permissions):
+
<div style="clear:right;">&nbsp;</div>
Make sure that sshd is installed and in /etc/ssh/sshd_config you have set
+
X11Forwarding yes
+
  
In K/Ubuntu sshd is in the package openssh-server.
+
=== OpenOffice.org ===
 +
[[Image:Freerunner_Debian_runs_openoffice3.jpg|right|thumb|300px|Debian running OpenOffice.org 3]]
  
On your OM device install x2x (with root permissions)
+
Did we already mention you can install ''anything'' in Debian?
apt-get install xauth x2x
+
Now open a new X terminal on your desktop computer. You MUST be the same user that is running the xsession on your desktop (i.e. do not su to root or another user in your x terminal!). Use the same username that is running an xsession on your OM device. Assuming that you have a usb networking connection to OM (with standard configuration) on the user prompt of your desktop type:
+
user@desktop:~$ ssh -X openmoko@192.168.0.202 "/usr/bin/x2x -east -to :0.0"
+
Hit return and enter your password. The xterm window will be unresponsive after that, but keep it open until you disconnect your OM device.
+
  
Now move your mouse cursor across the right edge of your monitor. It should enter the screen of your OM device from the left. Of course you can also use -west, -north or -south, depending on your preference where you place your OM.
+
<br style="clear:both" />
  
If computer says:
+
=== XFCE ===
sh: /usr/X11R6/bin/xauth: No such file or directory
+
The debian installation script installs by default the matchbox window manager. It doesn't feature a desktop environment. '''xfce''' is a small and lightweight desktop environment and so is quite fast for the FreeRunner.
X11 connection rejected because of wrong authentication.
+
x2x - error: can not open display localhost:11.0
+
  
It means you haven't installed xauth on your OM. So on your OM (with root permissions)
+
<pre>apt-get install xfce4</pre>
apt-get install xauth
+
  
=== Method 2: synergy (works with a windows/linux host) ===
+
Edit your .xsession to launch xfce4 at X startup :
With this method you can have the following functionality:
+
* Mouse moves from screen edge to the next screen
+
* Keyboard types on the focused window
+
* Clipboard is transferred as well
+
* Connect as many computers and screens you wish
+
* Connect windows computers too
+
  
All devices/computers in question should be able to install [http://synergy2.sourceforge.net synergy].
+
<pre>#!/bin/sh
Windows computers can use an installer exe.
+
xfce4-session</pre>
Debian devices have a package ready to be used.
+
<pre>
+
apt-get install synergy quicksynergy
+
</pre>
+
quick synergy will appear in your XFCE programs menu (Accessories->QuickSynergy).
+
Run it, switch to the "Use" tab, enter the IP address of the computer with the mouse and keyboard you wish to use, and press Execute.
+
  
In the windows host, (or linux) run the synergy after installation,
+
Edit section [Failsafe Session] of /etc/xdg/xfce4-session/xfce4-session.rc (or ~/.config/xfce4-session/xfce4-session.rc) to handle the auto-started apps. For example:
and configure it to share its keyboard and mouse(server),
+
<pre>[Failsafe Session]
configuration is fairly simple, you add all the hostnames of the devices/computers that ever would be joined to the "screens" list, and create 2 links for each connection.
+
Count=3
 +
Client0_Command=xfce4-panel
 +
Client0_PerScreen=False
 +
Client1_Command=xfdesktop
 +
Client1_PerScreen=False
 +
Client2_Command=zhone
 +
Client2_PerScreen=True</pre>
 +
Start XFCE !
  
If your desktop's hostname is homepc, and the device's is debian_gta02, and i place the device to the left of the desktop, the links would look like this:
+
<pre>/etc/init.d/nodm restart</pre>
<pre>
+
homepc is right of debian_gta02
+
debian_gta02 is left of homepc
+
</pre>
+
Now move back to the main screen, and press Start.
+
  
That should be it, in windows you should have an icon with a yellow lightning in it when synergy is connected and working.
+
The desktop takes a while to start but once up was snappy as can be expected.
Synergy supports connection of more then one screen so one could set up a full lab with only one keyboard and mouse :)
+
I've not yet looked at the reason for the seemingly too slow start for the desktop.
  
= Support =
+
zhone is available from the "Office" menu in xfce.
 +
The matchbox keyboard is available in "Accessories".
  
Debian is supported on the linux to go
+
If you want to display the screen on the long side (ie rotated, 4:3 aspect), add the following to the /etc/X11/xorg.conf in both the Device and InputDevice sections :
[http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/smartphones-userland smartphone mailing list]
+
  
= Known Issues =
+
<pre>Option          "Rotate"                "CCW"</pre>
  
== apt-get segmentation fault ==
+
and then (re)start xfce.
  
Whenever you get a segmentation fault while using apt-get or aptitude, clean the database so it will rebuild it
+
If you want to be able to shutdown/restart the device, add the following line to ''/etc/sudoers'' (don't forget to replace ''username'' with your actual username):
rm /var/cache/apt/*.bin
+
<pre>username localhost = NOPASSWD: /usr/sbin/xfsm-shutdown-helper</pre>
  
= Why use debian =
+
''' Using matchbox-window-manager with XFCE '''
  
The point of debian on the freerunner is that you get a huge army of software in a repository, all compiled for the arm processor.
+
XFCE's window manager is poorly configured for use with the FreeRunner.  Fortunately, matchbox's window manager is compatible with xfce.  To use the matchbox window manager, modify ~/.xsession as follows:
  
Debian is used on many other embedded devices too and so there's a much larger repository of software already available than in the 2008.8 opkg archives.
+
<pre>#!/bin/sh
 +
exec matchbox-window-manager -use_titlebar no -use_cursor no &
 +
xfce4-session</pre>
  
You can build your own things without need to play with openembedded.
+
== Derivative Distributions of Debian ==
  
For example compiling natively is a snap w/ debian, just apt-get gcc&libc-dev (on gentoo too) and not so easy w/ om images :) (borked compiler, borked headers).
+
Several distributions are sharing Debian's infrastructure - this is long known. For the Openmoko,  
 +
* [[Fyp]] extends the basic Debian installation while avoiding the need of an SD
 +
* [[Hackable1]] focuses on GNOME Mobile integration
 +
* [[Mer]] : based on [[Maemo]] ; see demo and download image at http://www.newlc.com/en/mer-best-maemo-debianubuntu-mobiles-watch-freerunner-demo
 +
* [[QtMoko]] - Debian with Qt Extended Improved plus configuration changes put manually on top of it
 +
* [[Telefoninux]] http://telefoninux.projects.openmoko.org/index.html
 +
* [[Deb19]] - pre-configured, ready to copy to SD, Debian with improvements. No install.sh required.
  
[[Category:Debian]]
+
[[Category:Debian| ]]

Latest revision as of 05:48, 26 March 2012


Debian is a universal operating system used on many other embedded devices, and also on home computers. Using Debian on the FreeRunner gives access to the Huge army of software packaged in the Debian repositories, already compiled for the Neo's arm(v4) processor. Moreover, one can build one's own source files for programs without having to learn the OpenEmbedded way. For example compiling natively is a snap with Debian, just apt-get gcc&libc-dev.

For an existing Debian/Ubuntu user, choosing Debian for Neo FreeRunner makes phone a very familiar, trustworthy and flexible place to hack in.

The bulk of information related to running Debian on FreeRunner is supposed to be at wiki.debian.org. For all installation, support or bug reporting needs please see DebianOnFreeRunner in the Debian wiki.

The current method of installation, install.sh, is not fail-proof. Work is progressing on a real debian-installer support. Please be sure Bash is installed before trying install.sh. The main reason why install.sh fails is because it installs debian unstable which is constantly in motion.

Contents

[edit] Screenshot for Manual

It might be useful to improve this manual with screenshots. You can create screenshots on Debian with ImageMagick:

 # sudo apt-get install imagemagick

Then you can take a screenshot of the full screen with the import-command:

 # import -window root screenshot.jpg

If you take the screenshot with some delay you have to add the pause parameter (e.g. waiting for 10sec)

import -pause 10 -window root screenshot.jpg

[edit] Installation Debian on Freerunner

The following steps are a quick installation guide with and installed SHR on your freerunner and Qi as bootloader already installed on your freerunner. For further information refer to the Debian on Freerunner Wiki from which this short summary is derived from.

NOTE: The installation script for Debian, used in the following manual, stopped on SHR with errors. To run a complete Debian installation process it might be necessary to flash the FR with current minimal rootfs for SHR again. You could also try in your SHR distribution to remove some software packages with opkg (not tested). Recommended to flash memory with a minimal SHR.


The following manual was successful with a fresh flash of SHR in NAND memory.

[edit] Installing Qi

The following manual needs Qi to be installed as bootloader. If you more options for using the bootloader usethe Debian on Freerunner Wiki for further details.

Switch off you freerunner (if necessary) and start NOR uBoot by pressing AUX and Power-On at the same time and then start dfu-util on your desktop computer with the following parameters for GTA2:

 # dfu-util -a u-boot -R -D qi-s3c2442-master-hist_3b8513d8b3d9615e.udfu

See Flashing the Neo FreeRunner or Flashing the Neo 1973 for more details on flashing your phone.

[edit] Online Script Installation

[edit] Login to Freerunner with SHR

Login to your freerunner with the booted SHR distribution:

# ssh -X -l root 192.168.0.202

and an USB Networking connection (e.g. IP-address 192.168.0.202 of your freerunner). Change the IP-address if your network settings differ from this IP-address. Prepare SHR so that you have a working internet connection from your freerunner. This is necessary because SHR will download the Debian packages.

[edit] Script Installation and Running install.sh

Run the following commands from shell in SHR after ssh-login to freerunner:

# wget -O install.sh http://pkg-fso.alioth.debian.org/freerunner/install.sh
# chmod +x install.sh
# TASKS="ALL" QI=true ./install.sh all

The following commands above assumes that you have Qi installed and you want to use a single partition for Debian on freerunner. The SD card (2GB suggested) will be formated by the script.

  • If you want to install Debian with different installation parameters or
  • if you ran into network problems or errors during installation

please see DebianOnFreerunner-Wiki for further details and support.

NOTE: The installation could take more than 90 minutes to complete and you will download approximately 250MB on your freerunnner. Time for installation is depending on network speed.


After successful installation you will see:

 I: Unmounting - done
 I: All done!
 Now reboot, and hope for the best!

Shutdown SHR operating system with:

# shutdown -h now

Press power on button to start Debian via Qi:

[edit] debian4freeunner.tar.gz

The online installation process sometimes fails. It is be helpful to an tar.gz-image for Debian that could be extracted to a SD-card with an installed bootloader Qi

One such tarball is available here (add others if you have):

http://people.debian.org/~timo/NeoFreeRunner/ (Debian_NeoFreeRunner_minimalrootfs_20120321.tar.xz)

Note that it is a minimal rootfs, meaning that your first job is to connect to the device over USB cable and install more packages to your liking. Some basic libraries/daemons like FSO2 and omhacks are available, though, and the X starts (pretty much empty) by default via /root/.xsession. Root password is the default 'changeme'.

[edit] First Login on Debian

Your Linux Desktop has created RNDIS/Ethernet Interface, configure the interface as in USB Networking explained:

RNDIS/Ethernet Gadget 

Now you can login on Debian (if booted) with:

 # ssh -X -l root 192.168.0.202
NOTE: (SSH Known Hosts) If you have installed other distributions on your Freerunner before, edit .ssh/known_hosts and remove old key for your freerunner.


The default password is "changeme", so change the password directly after first login on your Freerunner with:

 neo# passwd

Then run an update for apt-get

 neo# apt-get update

This could take several minutes depending on network speed.

[edit] Debian Showcase: Desktop Environments And Applications

[edit] fbpanel + Matchbox

It is not really a Desktop environment, but using fbpanel with Matchbox you can have a fast, lightweight, gtk2 desktop panel.

Debian with fbpanel, matchbox-window-manager and Zhone running, default settings
Custom matchbox theme and fbpanel configuration.

Quick howto:

  1. Install fbpanel:
    sudo apt-get install fbpanel hicolor-icon-theme
  2. Customize the X startup process:
    ~/.xsession
    #!/bin/sh
    export GTK_MODULES=libgtkstylus.so
    zhone &
    xsetroot -solid black
    matchbox-keyboard-toggle &
    matchbox-window-manager -use_titlebar yes &
    # -use_titlebar yes to minimize & toggle between apps
    # fbpanel's taskbar does not work with matchbox-window-manager
    #~/bin/auxlaunch &
    while true;
    do
    fbpanel;
    sleep 1;
    done;
    
  3. Read http://fbpanel.sourceforge.net/docs.html#config
    ~/.fbpanel/default
    mkdir ~/.fbpanel
    cp /etc/fbpanel/default ~/.fbpanel/default
    nano ~/.fbpanel/default
    

    Remove section with 'taskbar' plugin - it's useless with matchbox-window-manager. You may add plugin 'cpu'

    Plugin {
    type = cpu
    }

    Also, plugin 'genmon' is useful:

    Plugin {
    type = genmon
    config {
    Command = echo -e $(grep "MemFree" /proc/meminfo | \
     awk '{printf "%0.2f", $2 / 1024}') "|"\
    $(cat /proc/loadavg | awk '{print $3}') "|" \
     $(apm | awk '{print $5}')
    PollingTime = 60
    TextSize = small
    TextColor = darkblue
    }
    }
    Custom edje Zhone theme. Click to enlarge
    After 'killall fbpanel' it will show: free mem in megabytes | loadavg | battery % left.
  4. Default theme is ugly. You can change it and / or make fonts bigger:
    ~/.gtkrc-2.0
    sudo apt-cache search gtk2-engines
    sudo apt-get install gtk2-engines gtk-theme-switch
    DISPLAY=:0 gtk-theme-switch2
    Now choose your theme, font and save it. To see changes do 'killall fbpanel'. (killall requires psmisc package to be installed)

[edit] Illume

Debian with illume, and Zhone running
Debian with illume, and Zhone running, with the on-screen keyboard visible

Illume, the desktop environment used in recent openmoko distribution releases, is also available under Debian. It's part of the Enlightenment window manager version 17 (which is currently in the alpha stage of development), which the Debian FSO package maintainers have placed in their repository. If you have a Debian FSO system running, you can use the following commands to install illume.

apt-get install e17

Then use the following commands to ensure that it starts on boot.

apt-get remove zhone-session
apt-get install nodm

mv /root/.xsession /root/.xsession.backup 
cat << END > /root/.xsession
#!/bin/sh
zhone &
enlightenment_start
END

Update 03/2012: zhone is a dead end. For current Debian, install phoneui-apps instead, which support the FSO2 now default in Debian.


[edit] LXDE

If you want a really nice desktop enviroment but you think XFCE is too fat, you can try to install LXDE. It give to you the GTK comfort, but use only a fraction of the ram needed by XFCE.

Debian with lxde and Zhone running

To install it:

apt-get install lxde

to launch it create a /etc/init.d/lxde script in the same way descripted for xfce4, replacing startxfce4 occurrences with startlxde.

 

[edit] OpenOffice.org

Debian running OpenOffice.org 3

Did we already mention you can install anything in Debian?


[edit] XFCE

The debian installation script installs by default the matchbox window manager. It doesn't feature a desktop environment. xfce is a small and lightweight desktop environment and so is quite fast for the FreeRunner.

apt-get install xfce4

Edit your .xsession to launch xfce4 at X startup :

#!/bin/sh
xfce4-session

Edit section [Failsafe Session] of /etc/xdg/xfce4-session/xfce4-session.rc (or ~/.config/xfce4-session/xfce4-session.rc) to handle the auto-started apps. For example:

[Failsafe Session]
Count=3
Client0_Command=xfce4-panel
Client0_PerScreen=False
Client1_Command=xfdesktop
Client1_PerScreen=False
Client2_Command=zhone
Client2_PerScreen=True

Start XFCE !

/etc/init.d/nodm restart

The desktop takes a while to start but once up was snappy as can be expected. I've not yet looked at the reason for the seemingly too slow start for the desktop.

zhone is available from the "Office" menu in xfce. The matchbox keyboard is available in "Accessories".

If you want to display the screen on the long side (ie rotated, 4:3 aspect), add the following to the /etc/X11/xorg.conf in both the Device and InputDevice sections :

Option          "Rotate"                "CCW"

and then (re)start xfce.

If you want to be able to shutdown/restart the device, add the following line to /etc/sudoers (don't forget to replace username with your actual username):

username localhost = NOPASSWD: /usr/sbin/xfsm-shutdown-helper

Using matchbox-window-manager with XFCE

XFCE's window manager is poorly configured for use with the FreeRunner. Fortunately, matchbox's window manager is compatible with xfce. To use the matchbox window manager, modify ~/.xsession as follows:

#!/bin/sh
exec matchbox-window-manager -use_titlebar no -use_cursor no &
xfce4-session

[edit] Derivative Distributions of Debian

Several distributions are sharing Debian's infrastructure - this is long known. For the Openmoko,

Personal tools

Installation

There are "official" instructions on how to install Debian on FreeRunner or Debian on Neo1973 (see the original announcement).

Previous information (partly outdated, now) on how to install Debian manually has been moved to Manual Debian.

See also : http://www.debian.org/ to know more about Debian.

From time to time the Debian packages may be broken, which will cause the install.sh script to fail. Since waiting for the packages to be fixed can take quite a lot of patience, here is an alternative method of getting Debian installed on the FreeRunner.

System

Password

The default root password is blank. You should change that as soon as you can:

  1. passwd

If entering a blank password does not work at first, try rebooting. If still no success, boot to 2008.08/2007.02, chroot to the micro SD card and set a new password.

Speeding up booting

Note: By default, Debian is already configured to write limited messages to the console during boot. Does this actually speed things up anymore?

What's good for every linux booting is also good for our debian on the freerunner: booting in quiet mode. To do so by default just boot your Neo FreeRunner in NOR-Flash and execute this configure-script: configure-uboot.sh.

It changes default booting to quiet-mode and adds another boot-option to boot without quiet-mode for debugging purpose.

Suspend

Note: As of Sep. 15 2008, suspend works 'out-of-the-box'; installing apm and the idle clock configuration changes do not seem to be necessary any more. Press the power button for two seconds (in zhone) or run 'apm -s' to suspend.

To make suspend available you have to install apmd: apt-get install apmd After that you can suspend your phone with:

 apm -s

and make it wake up again with pressing the power button.


Issues:

  • Wuth 06:28, 17 August 2008 (UTC): I found that apmd was already installed by using the official debian installation procedure, but that the kernel didn't support apm. I haven't yet resolved this issue. Wuth 05:31, 7 September 2008 (UTC): Worked fine on second install. Perhaps this is no longer a problem.
  • Phyce 21:33, 20 August 2008 (UTC) installed apm without problems; apm -s shutdowns the freerunner but I couldn't wake it up with power button... I had to remove the battery to boot again. suspend/resume was working quite reliably with latest kernels on ASU.

To wake up successfully, the idle-clock of the SD card needs to be enabled right before suspend. It can be disabled again right after resume (this reduces GPS interference). Write into /etc/apm/suspend.d/00sd_idleclk

#!/bin/sh
echo 1 > /sys/module/glamo_mci/parameters/sd_idleclk
touch /home/root/.profile

and into /etc/apm/resume.d/00sd_idleclk

#!/bin/sh
echo 0 > /sys/module/glamo_mci/parameters/sd_idleclk

These are from -stacy on the community list.

And anotherone from Morlac: (more debianish i think ;)
etc/apm/scripts.d/sd_idleclk and corresponding link in /etc/apm/event.d
(don't forget to chmod +x /etc/apm/scripts.d/sd_idleclk)

#!/bin/sh
SD_IDLECLK="/sys/module/glamo_mci/parameters/sd_idleclk"
[ -e "${SD_IDLECLK}" ] || exit 0

case "${1},${2}" in
(suspend,*)
echo 1 > ${SD_IDLECLK}
touch /etc
;;
(resume,suspend)
echo 0 > ${SD_IDLECLK}
;;
esac

exit 0

Time

The default time zone is UTC. Reconfigure it by running

# dpkg-reconfigure tzdata

To set the clock manually do something like

# date -s 00:33

If you have a network connection, do something like

# apt-get install ntpdate
# ntpdate-debian

Issues:

WLAN

wifi GUI

If you don't want to mess up with configuration files and is looking for an easy gui for wireless configuration, then wifi-radar or wicd is what you are looking for.

apt-get install wifi-radar
wifi-radar

or

apt-get install wicd
wicd-client -n

If you are looking for more, read on...

Installing prerequisites

Make sure the following packages are installed:

apt-get install wireless-tools wpasupplicant dhcp3-client

Example configurations

Single network configuration

Assuming your wireless router uses WPA security and DHCP, edit /etc/network/interfaces to include a section like this:

auto eth0
iface eth0 inet dhcp
wpa-driver wext
wpa-ssid "MyWirelessName"
wpa-psk "MyWirelessPassword"

Where, of course, you're using the name of your wireless network and it's password instead of MyWirelessName and MyWirelessPassword.

You can test by running

# ifup eth0

You can determine your IP address by running

# ifconfig eth0

Issues:

  • only works if in presence of wireless network on boot, or when manually running ifup eth0
  • booting away from wireless network is slower because waits for DHCP to time out
  • does not reestablish connection when leaving wireless area and then returning
  • does not support multiple wireless networks or open hotspots that you may travel between

Once wpa_supplicant has begun managing your wifi interface, you should type "wpa_action eth0 stop" instead of "ifdown eth0".

Roaming configuration

Todo: Which of the issues that single network configurations suffer from are addressed by WPA roaming mode? Would ifplugd / guessnet help, or just make things more complicated?

  • Roaming from network to network is not automatic. Instead, you need to manually run "wpa_action eth0 stop; ifup eth0" to switch networks
wpa_supplicant.conf

To configure WPA to roam between wireless networks, you will need to create a new configuration file:

/etc/wpa_supplicant/wpa_supplicant.conf

a template for this file (and more documentation) is available in:

/usr/share/doc/wpasupplicant/examples/wpa-roam.conf

You'll need to add networks to this file. Examples:

  • WEP:
network={
       ssid="MySSID"
       key_mgmt=NONE
       wep_key0="abcdefghijklm"
#      wep_key0=6162636465  # <- no quotes, so hex number
       wep_tx_keyidx=0
       id_str="MySSID"
}
  • No key:
network={
       ssid="SomeNetwork"
       key_mgmt=NONE
}
  • WPA:
network={
       ssid="Example WPA Network"
       psk="mysecretpassphrase"
       id_str="home"
}
/etc/network/interfaces

Next, you'll need to edit /etc/network/interfaces. This lets you configure your wireless networks to use dhcp, or other appropriate TCP/IP settings:

auto eth0
iface eth0 inet manual
wpa-driver wext
wpa-roam /etc/wpa_supplicant/wpa_supplicant.conf

# MySSID comes from an id_str above.
iface MySSID inet dhcp

# default is what's used if there is no id_str setting.
# so the 'SomeNetwork' network will use DHCP.
iface default inet dhcp

iface home inet static
# static interface settings, or whatever...

Finally, if you want attempts to access the internet to default to eth0 (and not usb0), then comment out this line under usb0 adapter configuration:

gateway 192.168.0.200

For some reason, I had to reboot for the id_str settings to take effect. However, you should now be able to use "ifup eth0" to associate with the access point and "wpa_action eth0 stop" to down the wifi adapter.

Further reading

To use all the possibilities of wpasupplicant like roaming and automatic connection to different networks, you should read /usr/share/doc/wpasupplicant/README.Debian.gz

Bluetooth

The FreeRunner uses the standard Linux bluez stack, installed with

  1. apt-get install bluez-utils

There is also a module missing from /etc/modules, which is critical to getting your device recognized. (kudos to johnsu01 on irc.freenode.net:#openmoko-debian for the find)

  1. echo ohci-hcd >> /etc/modules

The first time you try this, you can also

  1. modprobe ohci-hcd

The only atypical part of using bluetooth on the FreeRunner is turning it on, which can be done with

  1. echo 1 > /sys/bus/platform/devices/neo1973-pm-bt.0/power_on
  2. echo 0 > /sys/bus/platform/devices/neo1973-pm-bt.0/reset

Then the device should be visible using

  1. hcitool dev

The rest of the steps are easy...???

Better Xorg

By default debian uses fbdev... But we can use Xglamo:

apt-get install xserver-xglamo

after that edit /etc/X11/xorg.conf and change the line

Driver          "fbdev"

to:

Driver          "Xglamo"

and if you want to run xserver as normal user:

chmod u+s /usr/bin/Xglamo

with that you:

  • can use xrandr
  • don't have the pointer callibration bug with the rotated mode
  • have better performances

Running X as normal user

1. Create a new user

# useradd -m -G audio,dialout,floppy,video,staff username
# passwd username

2. Edit /etc/init.d/zhone-session (or /etc/init.d/xfce if you are using xfce, see over) and change USER=root to USER=username in it. Then to make sure changes are not lost on upgrade, run

dpkg-divert --add /etc/init.d/zhone-session

This will make new versions of /etc/init.d/zhone-session be written to /etc/init.d/zhone-session.distrib

3. Edit /etc/X11/Xwrapper.config and change allowed_users=console to allowed_users=anybody

4. Make apm setuid root so that zhone can do suspend and make it only executable for users in the staff group

dpkg-statoverride --update --add root staff 4750 /usr/bin/apm

It would also be possible to use sudo, but then you would have to edit /usr/bin/zhone.

5. Note that, if you ran zhone as root first, you may have to change ownership or remove /tmp/zhone.log, as a normal user is not able to write to a file owned by root.

Sound

Make sure to put your user in the audio group ("adduser <username> audio").

If there is no error but no sound, try these state files: Talk:Manual_Debian#Sound

How to replace the default kernel with a recent openmoko kernel

If you would like to update to a new kernel, here is a short summary of what to do to update the kernel to an actual OM kernel. But only do this if you know what you are doing. At the moment there is a little problem in the question which kernel to use. Hopefully it will be solved in the near future.

The original openmoko kernel works fine except for the fact that suspending with zhone doesn't work. But this kernel supports different really nice usb gadgets. :)
download stable: http://downloads.openmoko.org/releases/Om2008.9/
download testing: http://downloads.openmoko.org/daily/

The new FSO3 kernel works fine and suspend/resume with zhone is also possible. But this kernel still has no loadable usb gadget modules (17-Sep-2008 01:39). :/
download testing: http://downloads.freesmartphone.org/fso-testing/images/
download unstable: http://downloads.freesmartphone.org/fso-unstable/images/

  1. Download a recent kernel and rootfs (tar.gz) from one of the above mentioned sources. It's your decision if you want suspend or usb gadget modules at the moment.
  2. Backup your running kernel like mv /boot/uImage.bin /boot/uImage.bin.old, then
    copy the downloaded uImage file to the freerunner as /boot/uImage.bin.
  3. Backup your actual modules like mv /lib/modules/2.6.24 /lib/modules/2.6.24.old, then
    extract the downloaded rootfs tar.gz to a temporary directory and copy lib/modules/2.6.24 from the temp directory to /lib/modules/2.6.24 on the FreeRunner.
  4. Run a depmod -a.
  5. Do a chown -R root.root /lib/modules/2.6.24 because the owner from the tar.gz is something else.
  6. This step is only needed for the OM kernel but it doesn't harm the FSO kernel setup. Add "g_ether" Module to /etc/modules like echo g_ether >> /etc/modules. I read in an email, that the module "ohci-hcd" is also needed for some bluetooth functions, but i don't know this for real. I inserted it to my modules file to be on the safe side.
  7. Reboot and hope everything works as expected. :)

--User:Pini

  • Sun Sep 28 15:01:46 UTC 2008: Actually suspend/resume doesn't work anymore on the Neo Freerunner with the FSO3 kernel starting from september 16th. It does work with the Om2008.8 kernel from september 3rd.
  • Mon Oct 20 15:30:56 UTC 2008: working suspend/resume is back with FSO kernel 2.6.24+r10.1 from october 17th.

Software

You can install dselect(~2.2MB) or aptitude(~12MB) to visually inspect the available debian packages using the desktop's console.
Also the gtk-based package-manager synaptic(~15.7MB) is probably working.
Finally, on constrained systems, just issue the command:

grep -e Package: -e Description /var/lib/dpkg/available|more

Web Browser

Arne Anka suggested trying the light-weight webkit-based midori browser:

apt-get install midori

If you think Midori is quite slow on Freerunner try Links2.

apt-get install links2

Run as:

xlinks2

TangoGPS

Main article: TangoGPS


e-book reader

Main article: FBReader


Evince is also available in debian, and handles pdf, djvu, cbz, and other formats.

There is also a hack to convert drm protected adobe ebooks to .cbz files readable with evince, which is mentioned on the mailing list.

XFCE

xfce is small and lightweight and so is quite fast for the FreeRunner.

apt-get install xfce4
cp /etc/init.d/zhone-session /etc/init.d/xfce

Then you may hack /etc/init.d/xfce making

PROG_FSO=/usr/bin/startxfce4

Customize the boot process (this may have to be redone when zhone-session is updated):

update-rc.d -f zhone-session remove
update-rc.d -f xfce defaults

edit your /etc/hosts to have :

127.0.0.1 localhost debian-gta02

Start XFCE !

/etc/init.d/zhone-session stop
/etc/init.d/xfce start

The desktop takes a while to start but once up was snappy as can be expected. I've not yet looked at the reason for the seemingly too slow start for the desktop.

zhone is available from the "Office" menu in xfce. The matchbox keyboard is available in "Accessories".

If you want to display the screen on the long side (ie rotated, 4:3 aspect), add the following to the /etc/X11/xorg.conf in both the Device and InputDevice sections :

Option          "Rotate"                "CCW"

and then (re)start xfce.

If you want to be able to shutdown/restart the device, add the following line to /etc/sudoers (don't forget to replace username with your actual username):

username localhost = NOPASSWD: /usr/sbin/xfsm-shutdown-helper

Using matchbox-window-manager with XFCE

XFCE's window manager is poorly configured for use with the FreeRunner. Fortunately, matchbox's window manager is compatible with xfce. To use the matchbox window manager, arrange to run the following commands at X startup. If you followed the instructions above to run X as a normal user, put this in ~/.xinitrc:

#!/bin/sh

zhone &
matchbox-keyboard-toggle &
exec matchbox-window-manager -use_titlebar no -use_cursor no &
xfce4-session


TODO: And if I didn't run X as a normal user? (See: To-Do List)

Using matchbox-window-manager with fbpanel as normal user without gdm

fbpanel is a fast, lightweight, gtk2 desktop panel.

Debian with fbpanel, matchbox-window-manager and Zhone running
  1. Follow http://wiki.openmoko.org/wiki/Debian#Running_X_as_normal_user
  2. Customize the boot process:
    sudo cp /etc/init.d/zhone-session /etc/init.d/xserver
    sudo nano /etc/init.d/xserver

    Find (all in one line)

    start-stop-daemon --start --pidfile ${PIDFILE}
    --make-pidfile --background --exec /bin/su --
    --login --command "${PROG_XINIT} ${PROG_XSESSION} ${PROG_FSO}
    -- $X_OPTIONS" $USER

    Change it to (all in one line):

    start-stop-daemon --start --pidfile ${PIDFILE}
    --make-pidfile --background --exec /bin/su --
    --login -c "startx" ${USER}

    Add script to daemons:

    sudo update-rc.d -f zhone-session remove
    sudo update-rc.d -f xserver defaults
  3. Install fbpanel:
    sudo apt-get install fbpanel
  4. Customize configs:
    1. ~/.xinitrc
      #!/bin/sh
      export GTK_MODULES=libgtkstylus.so
      zhone &
      xsetroot -solid black
      matchbox-keyboard-toggle &
      matchbox-window-manager -use_titlebar yes &
      # -use_titlebar yes to minimize & toggle between apps
      # fbpanel's taskbar does not work with matchbox-window-manager
      #~/bin/auxlaunch &
      while true;
      do
      fbpanel;
      sleep 1;
      done;
      
    2. Read http://fbpanel.sourceforge.net/docs.html#config
      ~/.fbpanel/default
      mkdir ~/.fbpanel
      cp /etc/fbpanel/default ~/.fbpanel/default
      nano ~/.fbpanel/default
      

      Remove section with 'taskbar' plugin - it's useless with matchbox-window-manager. You may add plugin 'cpu'

      Plugin {
      type = cpu
      }

      Also, plugin 'genmon' is useful:

      Plugin {
      type = genmon
      config {
      Command = echo -e $(grep "MemFree" /proc/meminfo | awk '{printf "%0.2f", $2 / 1024}') "|" $(cat /proc/loadavg | awk '{print $3}') "|" $(apm | awk '{print $5}')
      PollingTime = 60
      TextSize = small
      TextColor = darkblue
      }
      }
      After 'killall fbpanel' it will show: free mem in megabytes | loadavg | battery % left.
    3. Default theme is ugly. You can change it and / or make font's bigger:
      ~/.gtkrc-2.0
      sudo apt-cache search gtk2-engines
      sudo apt-get install gtk2-engines gtk-theme-switch
      DISPLAY=:0 gtk-theme-switch2
      Now choose your theme, font and save it. To see changes do 'killall fbpanel'.

Miscellaneous

Making the cursor invisible

Using matchbox

Matchbox has an option, use_cursor, that can be used to control whether to show the cursor. For the default setup, edit /usr/bin/zhone-session and change the matchbox command to matchbox-window-manager -use_titlebar no -use_cursor no

Using unclutter

Unclutter is a program that hides the cursor after a period of inactivity. To use unclutter, install it

  1. apt-get install unclutter

and choose Yes to the question Start unclutter automatically?. To change settings edit /etc/default/unclutter.

Changing the cursor

To make the cursor invisible create a file called empty.cursor with this content:

#define empty.cursor_width 16
#define empty.cursor_height 16
static unsigned char empty.cursor_bits[] = {
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00};

Now you can execute: xsetroot -cursor empty.cursor empty.cursor and the cursor will be invisible. To make this permanent you have to invent something ;) It must be executed after zhone has finished starting up.

Running X applications on your desktop in nested X server

Sometimes it is helpful to have a big screen, keyboard and mouse. You can run X applications in a nested X server window. On your desktop install the nested X server application Xephyr (better that Xnest) apt-get install xserver-xephyr Run a nested X server as display :1 Xephyr :1 -ac -br -screen 480x640 -reset -terminate & Now you are able to run apps on your Neo which will display on your desktop PC. Make sure to set the display, for example if "mydesktop" is your desktop hostname DISPLAY=mydesktop:1 xfce4-session &

Using the mouse and keyboard from your desktop on the OM device

Method 1: xsession export (works with a linux host)

If you are running Linux (or a similar xorg capable operating system) on your Desktop, you can export your xsession to the openmoko device and use your mouse and keyboard on the Neo screen. A little program called x2x makes it even possible to do this simultaneously on the fly. When activated you just move your mouse to the edge of your monitor and then the mouse cursor continues on the screen of your openmoko device. If you select a window on the OM, the input of your keyboard is automatically entered in that window. You can even use the clipboard to copy data from tour desktop to OM and in the reverse direction.

Configure your desktop computer to export your xsession: On your desktop (with root permissions): Make sure that sshd is installed and in /etc/ssh/sshd_config you have set X11Forwarding yes

In K/Ubuntu sshd is in the package openssh-server.

On your OM device install x2x (with root permissions) apt-get install xauth x2x Now open a new X terminal on your desktop computer. You MUST be the same user that is running the xsession on your desktop (i.e. do not su to root or another user in your x terminal!). Use the same username that is running an xsession on your OM device. Assuming that you have a usb networking connection to OM (with standard configuration) on the user prompt of your desktop type: user@desktop:~$ ssh -X openmoko@192.168.0.202 "/usr/bin/x2x -east -to :0.0" Hit return and enter your password. The xterm window will be unresponsive after that, but keep it open until you disconnect your OM device.

Now move your mouse cursor across the right edge of your monitor. It should enter the screen of your OM device from the left. Of course you can also use -west, -north or -south, depending on your preference where you place your OM.

If computer says: sh: /usr/X11R6/bin/xauth: No such file or directory X11 connection rejected because of wrong authentication. x2x - error: can not open display localhost:11.0

It means you haven't installed xauth on your OM. So on your OM (with root permissions) apt-get install xauth

Method 2: synergy (works with a windows/linux host)

With this method you can have the following functionality:

  • Mouse moves from screen edge to the next screen
  • Keyboard types on the focused window
  • Clipboard is transferred as well
  • Connect as many computers and screens you wish
  • Connect windows computers too

All devices/computers in question should be able to install synergy. Windows computers can use an installer exe. Debian devices have a package ready to be used.

apt-get install synergy quicksynergy

quick synergy will appear in your XFCE programs menu (Accessories->QuickSynergy). Run it, switch to the "Use" tab, enter the IP address of the computer with the mouse and keyboard you wish to use, and press Execute.

In the windows host, (or linux) run the synergy after installation, and configure it to share its keyboard and mouse(server), configuration is fairly simple, you add all the hostnames of the devices/computers that ever would be joined to the "screens" list, and create 2 links for each connection.

If your desktop's hostname is homepc, and the device's is debian_gta02, and i place the device to the left of the desktop, the links would look like this:

homepc is right of debian_gta02
debian_gta02 is left of homepc

Now move back to the main screen, and press Start.

That should be it, in windows you should have an icon with a yellow lightning in it when synergy is connected and working. Synergy supports connection of more then one screen so one could set up a full lab with only one keyboard and mouse :)

Support

Debian is supported on the linux to go smartphone mailing list

Known Issues

apt-get segmentation fault

Whenever you get a segmentation fault while using apt-get or aptitude, clean the database so it will rebuild it rm /var/cache/apt/*.bin

Why use debian

The point of debian on the freerunner is that you get a huge army of software in a repository, all compiled for the arm processor.

Debian is used on many other embedded devices too and so there's a much larger repository of software already available than in the 2008.8 opkg archives.

You can build your own things without need to play with openembedded.

For example compiling natively is a snap w/ debian, just apt-get gcc&libc-dev (on gentoo too) and not so easy w/ om images :) (borked compiler, borked headers).