Angstrom

About

Manual

FAQ

RoadMap

Ångström Manual

This is intended to grow to be a useful resource for people wanting to use Ångström, it assumes at least some basic knowledge of Linux and familiarity with the hardware of your own device.

This is not a primer for Linux or embedded systems, there are many good resources for such things on the Internet, please use e.g. Google.

This is not the bug tracker - please submit issues to it, and check it regularly to be up-to-date with known issues and the resolution.

This is also not the FAQ, so please don't put random wisdom (like yesterday's bugs) here, let's make this a clean reference.

Note to editors: Please remember that this document is intended to be the Ångström distribution manual. Many users will judge it accordingly. Please exercise due attention when editing the manual, if in doubt, ask on Ångström mailing lists first. Change comments are mandatory when making changes. Please do not use "GUI" mode for editing this page. Thank you.

TableOfContents(3)

1. Overview

1.1. What is Ångström?

1.2. Why was Ångström created?

1.3. Who is creating Ångström?

2. Getting Started

As any modern distribution, Ångström is fully package-based. However, as interaction with the device during initial setup phase is difficult, Ångström is bootstrapped using an "image", which is essentially a set of core packages already merged into archive or filesystem image. This image is installed using device-specific means, and provides basic Ångström functionality.

Adhering with the Ångström's aim of flexibility and best practices of Linux system management, the images provide only core packages, allowing users to customize system to their needs by easily installing any required software from a wealth of Ångström feeds. However, as a convenience to users, different kinds of images are provided, for example, with (core packages of) different GUI environments pre-installed.

2.1. Downloading

Current production Angstrom release is 2007.12. It is available from the following location:

Under this web directory you will find subdirectories for individual machines. Within each machine directory, you will find few kinds of images representing different Ångström configurations.

x11-gpe and following images are big and provided for selected devices which come with large secondary storage (like microdrive). If there are no such images for your device, you do not lose anything: you can easily install any software you need from the feeds (see below).

If you are in doubt which image to choose, use x11-image: it is intended as a starting point for majority of users, offering basic GUI tools to control the device and devoid of application software which not every user may need, thus offering good compromise between usability, size required, and free space available.

Each image type is provided in different formats, among them:

Note that some specific device may not use all of the image formats above. Please follow installation instructions for your device and use the image format as described there. On the other hand, advanced users may need another image format for advanced setups.

Generally, builds available for individual devices, as well as image kinds and formats may vary from machine to machine, though Ångström maintainers and machine mentors strive to provide consistent and complete coverage for each machine.

2.2. Installing

Unfortunately, embedded devices vary greatly in their architecture and system software, and as of now, no generic installation procedure suitable for all of them is available.

The links below point to the installation instructions for different supported machines (Zauruses, iPaqs and other PocketPCs/!WindowsMobiles, Router/NAS boxes, etc.)

See also the UsingAngstrom page.

2.3. First Steps After Installing

Once you have installed Ångström and booted into the system, you are highly recommended to upgrade system from the feed to get the latest security and bug fixes since the release has been made. To do this, you need to run the following commands in terminal: 

ipkg update
ipkg upgrade

However, for this to work, you must be connected to the Internet to be able to download updates. See "Networking" section below to help with setting it up.

2.4. Known Issues

Ångström is an agile distribution, and issues are resolved quickly, so the authoritative location for their list and status is the bug tracker. Known issues for the current release is available here, it is structured by different machine families and specific machines, and software environments.

3. User Interfaces

Ångström provides two main interfaces, a console, which works for any device (including display-less devices, using serial line or SSH) and a graphical user interface (GUI). While different GUIs are potentially possible, and this time only GPE (GPE Palmtop Envirionment) has "supported" status. Visit FAQ and wiki for information on alternative GUIs.

When booting a device which has GPE installed, it is possible to stop the GUI from starting up and remain in the console environment; this is important if there is a configuration problem which makes the GUI hard or impossible to use. Such problems might be pointer calibration, screen resolution, rotation or refresh problems.

If Ångström was installed with only the console UI, it is possible to add GPE by installing the relevant packages, after which a reboot should bring up the GPE setup and login screens.

3.1. Internationalization and Localization

Few definitions:

Ångström is targetted at the wide user community throughout the world, so provides good i18n and l19n support, with basic i18n support available out of the box with standard X11 GUI images. As a contemporary Linux system, Ångström uses UTF-8 encoding. Ångström images come with English UTF-8 locale (en_GB) which is suitable to get good i18n support. Make sure that you select "English(Great_Britain)" when logging into X11 session.

3.1.1. Fonts

Ångström GUI images by default come with ttf-dejavu-* font packages, which provide fonts for Latin, Cyrillis, and Hebrew scripts.

3.1.2. Virtual On-screen Keyboards

x11-based images come with two virtual keyboards:

Each of them allows to install and configure additional localized layouts for different languages. Few layouts are shipped by default with the both keyboards.

3.1.3. Physical Keyboard

<to be filled in>

3.1.4. Internationalized Filenames Support

Ångström supports i18n filenames out of the box, as long as they are UTF-8 encoded. Most X11 GUI applications display and allow to use such names without any issues. There are some important exception however: please see below. Of course, there should fonts available for the characters used in filenames, see Fonts above.

3.1.5. Libc Locale Configuration

To get further regarding l19n support than generic i18n above, one need to configure proper locale for libc (C runtime library). Angstrom images come with en_GB locale preinstalled (this was apparently not the best choice, as most people would expect en_US to be default-available).

You select the locale for session when logging into X, "Language" dropdown. After Ångström install, it will contain two choices: "English(C locale)" (just "English" in older builds) and "English(Great_Britain)". Make sure you avoid "English(C locale)" as does not actually offer any i18n, limiting used charset to ASCII.

To install more libc locales, use packages with names locale-base-LL-VV, where LL is language code and VV is variant code, both converted to lowercase e.g.: 

ipkg install locale-base-en-us

Once package installed, a new choice will be available in X11 login.

3.1.6. I18n Input in X Terminal

Make sure you have real locale, not "C" one to have i18n filenames to be printed properly.

There's known issue with i18n input in gpe-terminal (included in Ångström images) and rxvt. In short, it doesn't really work.

Xterm has issues too.

Only vte is known to work, in the sense that doing "cat >foo" you can then type i18n chars. However, even with vte you cannot type i18n characters in the shell prompt. This is assumed to be shell issue, which filters such chars (note that using tab completion, one can get i18n filename into commandline).

3.1.7. Localized messages for applications

For this to work, you must install locale for the corresponding language. Then, for each application you are interested in, you should install package <app>-locale-LL to get translated messages.

4. Communications & Networking

4.1. General Networking Setup

4.1.1. Router/Host setup

One of the first things you want to do after installing an Ångström release is to connect to Ångström's site on the Internet and get the latest updates for security and important bug fixes. If you will connect to the Internet "directly" (for example, via GPRS) or via a dedicated router (for example, using WiFi or Ethernet), you usually don't need to do additional configuration "on the other end", assuming your GPRS account is enabled and router already setup to serve other computers.

However, many people with conventional PDA devices will connect using USB to the desktop or laptop computer. In this scenario, your host computer will serve as a router for your Ångström device, and so must be configured accordingly: you must enable IP forwarding and NAT (Network Address Translation, also known as "masquerading") on it. Please consult your Linux distribution manual on how to make such changes permanent, to be able to connect the device to the Internet without manual setup in the future. Following commands will work for any Linux system (root privileges required), but only until reboot.

NAT all outgoing traffic to the Internet (eth0 would be the external interface): 

iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
echo "1" >/proc/sys/net/ipv4/ip_forward

Windows users need to enable ICS (Internet Connection Sharing) to achieve the similar functionality. Note: * windows will change your LAN's IP address and set up DHCP * you can only share Internet access with one internal interface (which could be the LAN, Bluetooth, or wireless), unless you find a third party tool to set it up * if you are already using ICS for a different interface, consider the use of a simple proxy such as AnalogX's, for giving other networks access to the Internet

4.1.2. Ångström device setup

To access the Internet using domain names, you need to setup DNS server properly (unless you use DHCP and it will be provided by the server).

X11 GUI configuration:

Main menu -> Settings -> Network Setup, enter root password if being asked for, select global tab. Fill in "DNS server" field.

4.2. Networking using USB

A USB networking is so far the most common network methods available for embedded devices. If a device has USB port, it usally can use USB networking too. Subsection below describe how to configure support both on an Angstrom device and host to which it connects.

4.2.1. USB Slave (a device running Ångström)

4.2.1.1. X11 configuration

Main menu -> Settings -> Network Setup, enter root password if being asked for, select usb0 tab. Fill in parameters as you need them.

4.2.1.2. Console configuration/Troubleshooting

To bring up the device, you need to load the relevant kernel modules (g_ether and a UDC driver, which is platform-specific). You can check using the lsmod command. If they haven't already been loaded, load them with the following commands: 

modprobe g_ether

NOTE: Kernels for some devices may have g_ether and usbnet drivers builtin. Builtin drivers are not shown in lsmod output (as they are not modules). In this case, just proceed with ifconfig -a as described below.

You should then find that ifconfig -a will list the device usb0 and it can be configured as normal; if you add the relevant section to the interfaces file (or use the GPE network configuration tool), you can simply run the command "ifup usb0" to set it up. This can be short-circuited a bit by editing the /etc/network/interfaces file to make it read thus: 

iface usb0 inet static
      pre-up modprobe g_ether
      address 192.168.129.201
      netmask 255.255.255.0
      gateway 192.168.129.1
      post-down rmmod g_ether

4.2.2. USB Host (usually a PC)

modprobe cdc_ether
modprobe usbnet

or 

modprobe g_ether
modprobe usbnet

When the device is plugged in, a new network device should appear on each, either usbd0 or usb0; use ifconfig, route etc to configure. Configuration files can be set up to configure the devices when they come up:

4.2.2.1. Debian

Add an entry to /etc/network/interfaces like: 

iface usb0 inet static
        address 192.168.129.1
        network 192.168.129.0
        netmask 255.255.255.0
        broadcast 192.168.129.255

4.2.2.2. Gentoo

Entry to /etc/conf.d/net: 

config_usb0=( "192.168.129.1" )

4.2.2.3. SuSE

Create file /etc/sysconfig/network/ifcfg-usb0: 

    BOOTPROTO='static'
    STARTMODE='auto'
    USERCONTROL='yes'
    NAME='Sharp Zaurus'
    IPADDR='192.168.129.1'
    BROADCAST='192.168.129.255'
    NETMASK='255.255.255.0'
    NETWORK='192.168.129.0'
    PREFIXLEN=''

4.3. Bluetooth

4.3.1. Overview

Ångström uses the standard 2.6 kernel Bluetooth modules (which were derived from [http://www.bluez.org/ bluez]). Userspace commands used to control/access Bluetooth hardware are hciconfig, hcitool, rfcomm, l2ping etc. Before establishing a Bluetooth connection with another computer, either for rfcomm or pand, it is necessary to pair the two. Bluetooth uses a PIN, or password, for incoming pairing requests it is set in the /etc/bluetooth/pin file, and for outgoing requests by the utility "passkey-agent".

4.3.2. Networking using Bluetooth

There are two ways to make a network using Bluetooth: one is to use point-to-point protocol (ppp) over the rfcomm (serial-like link), the other is to use PAN. This is a very brief summary to give you an understanding of the processes involved, there are many places where this is documented more fully!

PPP over rfcomm was previously popular with PDAs like Palms and some WindowsMobile/PocketPC/WinCE devices. It's not so efficient, but is useful if you're connecting the device to a Windows computer. On the Ångström device you need to create the appropriate files in /etc/ppp and then trigger the ppp connection using the command "pppd call XXX" (XXX being the profile); this then results in a "ppp0" device appearing.

If the called device is correctly set up, the ppp0 device will end up with the correct IP address and default route, and the local DNS resolver will probably also be set correctly, otherwise use "ifconfig ppp0", "route add default gw x.x.x.x" to tweak settings.

PAN/PAND is best for making a Linux-to-Linux connection; simply run "pand -listen" on one end, and "pand -connect xx:xx:xx:xx:xx:xx" on the other where the xx's are the MAC address of the other device (use hciconfig -a to find out the MAC). When connected, use "ifconfig bnep0" to set the IP address. Use "route add" to make routes (e.g. route add default gw 192.168.129.1"), just as with any other network connection. You might also need to tweak /etc/resolv.conf on the Ångström device so it can resolve names into IP addresses. It should be possible to create a bnep0 entry in /etc/network/interfaces file for this.

In both cases, it is likely that you are using the other end of the Bluetooth connection as a gateway to allow the Ångström device to access the internet (e.g. access mail, browse the web, install from software feeds), so if the remote box is running Linux you may want to set up masquerading on its external/outbound interface and thus allow the Ångström device to access hosts and networks other than the gateway (hint, use "iptables -t nat -I POSTROUTING -o eth0 -j MASQUERADE". Don't forget to turn on ipv4 forwarding with "echo 1 > /proc/sys/net/ipv4/ip_forward"!). The equivalent in Windows is Internet Connection Sharing, accessed through the properties for the external interface.

4.4. Networking using wifi/802.11

4.4.1. Overview

Ångström-supported machines come with variety of WiFi hardware - it may be builtin or use extension cards/devices, etc. Different kernel drivers may be needed to support different hardware. The list below names some well-known drivers and their capabilities (describing which specific card model needs which driver is outside the scope of this manual):

Not all base installs of Ångström include wireless-tools, so if the iwconfig or iwspy commands are missing, be sure to install the wireless-tools package. wpa_supplicant tool is also a separate package.

When the wifi card is active, "ifconfig -a" should indicate the presence of the wifi0 and wlan0 devices if using hostap driver.

4.4.2. Usage

As with the other network interfaces, wireless interfaces are configured in the /etc/network/interfaces file. Commonly one would wish to configure a wireless interface using dhcp. As such an entry as follows is needed in /etc/network/interfaces: 

iface wlan0 inet dhcp
     wireless_mode managed

If an essid and wep encryption are used the entry would look as follows: 

iface wlan0 inet dhcp
     wireless_mode managed
     wireless_essid youressid
     wireless_key   yourwepkey

To use WPA/PSK encryption the entry would look as follows: 

iface wlan0 inet dhcp
# start wpa_supplicant
     wpa-conf /etc/wpa_supplicant.conf
     wpa-driver hostap

Note:I have found rf010804.hex in /lib/firmware on the newer images. Change the line above if needed.

Create a wpa_supplicant.conf in /etc if none exists: 

#/etc/wp_supplicant.conf
ctrl_interface=/var/run/wpa_supplicant
ctrl_interface_group=0
eapol_version=1
ap_scan=1
fast_reauth=1
network={
     ssid="(your SSID)"
     proto=WPA
     pairwise=TKIP
     psk= (quoted text or hexadecimal number)
     priority=1
}

Additional information on wpa_supplicant may be found here: http://linux.die.net/man/5/wpa_supplicant.conf

If configured properly you can bring up the interface with the following command: 

ifup wlan0

The interface can be brought down with: 

ifdown wlan0

4.4.3. Manual settings

iwconfig wlan0 mode managed key [WEP key]
iwconfig wlan0 essid "[ESSID]"
ifconfig wlan0 up
ifconfig wlan0 [IP address] netmask [subnetmask]
route add default gw [IP of default gateway] (usually the IP of the Access Point)
echo nameserver [IP address of DNS server]  >>  /etc/resolv.conf
ping www.yahoo.fr

(if you receive a reply you have access)

4.5. Network Security

If you are using a public wireless network, or connecting your machine using ethernet to an untrusted network, you may want to use a firewall on your device to protect it from network intrusion; Ångström's kernel includes a set of modules which control network traffic called "netfilter" which uses the command "iptables" to manage the configuration. This configuration needs to be set up each time the machine boots up.

Using "iptables" on Linux is a separate subject out of scope of this manual. But a trivial firewall to protect your computer, allowing only outbound traffic and related inbound packets thus: 

iptables -P OUTPUT ACCEPT
iptables -P INPUT DROP
iptables -A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT

To make this happen on boot-up, create a script with these lines, put it into /etc/init.d/firewall, and make soft links to the script from the rc3.d and rc5.d directories.

5. Installing Software and Package Management

Out of the box, Ångström provides standard means to manage software on the system - using Package Manager, which allows to install specially prepared software archives (packaged) from both local storage and network repositories, remove them as needed, query and search available and installed packages, etc.

Ångström is a Debian-like distribution, but instead of using "apt", you use "ipkg" for package management. Note that it is best to only use ipkg to manage software and not tamper with the files manually.

Assuming that your computer has access to the Ångström feeds, then you would find a mail program using the command "ipkg search mail" and then install the one you want (whether the character/command-line interface like "mutt" or go GUI with claws-mail). More often, you will want to see a list of what is available, using "ipkg list | less".

As with any Linux distro, there are oftentimes different packages available to perform some task, however, they often require different levels of resources (e.g. command line mail vs. GUI, command line mp3 playback vs XMMS); the key thing with Ångström is whether you have opted for any GUI support at all (GPE, Opie or Qtopia) or whether you are strictly command line, as by installing a package dependant on GPE when your system is set up for Opie would load it up with many GPE libraries and components. The key therefore is to read the package description and do not use packages with the word "opie" in them when you are GPE based and vice-versa!

The software packages are stored in files whose name ends .ipk; this is a compressed format, containing files to be installed as well as metadata and support scripts. They have to be installed as root. NOTE: .ipk is de facto package format for Embedded Linux, and many other distros use it for their packages too. However, packages from different systems are not compatible. In particular, Ångström maintainers cannot guarantee system stability if packages not from the official feeds are being used.

5.1. Installing packages over a network

Most users will want to install packages from the official Ångström feeds. This is recommended and the most convenient way. Of course, this requires network connectivity to be available.

As root, use the command "ipkg update" to download the feed indices, then use "ipkg search XYZ" (or "ipkg list | grep -i XYZ") to search for a package with XYZ in the name, then "ipkg install XYZABC" (without the ipk suffix) to actually install it.

5.2. Installing new software packages from local filesystem

If you have ipk package available locally, command "ipkg install /dir/dir/xyz.ipk" will install it. Note that in local install mode, dependencies are not resolved automatically and must be explicitly specified.

5.3. Removing packages

The base install has the package database already set up, so that you can remove packages from the base install if wished (assuming that your computers file storage is writable); use the command "ipkg remove XXX" to deinstall the package.

6. Common and Specific Tasks

6.1. Configuration Files - editing manually

The network configuration file is /etc/network/interfaces - this follows the Debian syntax whereby an interface can be static or dhcp. As well as the basic configuration entries, you can add "pre-up mycommand" to run a script before bringing up the interface, and a "post-up" to be run afterwards.

The software package management uses files in /etc/ipkg - it is best to leave this alone unless you REALLY know what you are doing, the ipkg command gives very powerful control over packages, including forced reinstallation.

6.2. Upgrading to newer releases of Ångström

You will need access to the repository of files, either through the network or locally, and ensure that you have set up the version you are upgrading to. IT IS VITAL THAT YOU MAKE A BACKUP BEFORE UPGRADING! Rendering your device unbootable/unstable and loss of data is entirely your risk.

First update your package lists by entering "ipkg update". Then simply issue the command "ipkg upgrade". It is probably useful to log the results using "ipkg upgrade 2>&1 | tee /var/log/ipkgupgrade.log".

On a Zaurus (at least spitz/borzoi), if the upgrade includes a change in your kernel, you will have to re-flash the kernel separately from the ipkg upgrade. That is, download the current kernel image zImage-XXXXX.bin, and updater.sh.version and place on a (VFAT formatted) SD or CF card as zImage.bin and updater.sh. Do not have the hdimage.bin on the card. Then re-flash by following the same steps you took to flash it originally. Without the hdimage, flashing will be quite quick. It will then re-boot with the new kernel, and should configure the modules that were installed by the upgrade.

6.3. Installing GPE onto Console Image

ipkg update

Install the kdrive X-server. 

ipkg install xserver-kdrive

or use the imageon server for Zaurus C7x0 image users. 

ipkg install xserver-kdrive-imageon

And finally installing the following will give you a fully working X GUI + base GPE environment. 

ipkg install task-base-extended angstrom-x11-base-depends angstrom-gpe-task-base angstrom-gpe-task-settings libesd0

AngstromManual (last edited 2008-04-28 03:07:51 by LexLanda)