Handhelds.org - Open source for handheld devices

UserPreferences

FamiliarFaq

1. Familiar Frequently Asked Questions

  1. Familiar Frequently Asked Questions
  2. Software Information
    1. So how do you use Linux on a handheld?
    2. What's the difference between Opie and GPE?
    3. What applications are available?
    4. Can I sync with Evolution, Outlook, my kitchen sink, etc.?
    5. Can I use Microsoft ActiveSync with Familiar?
    6. How is software installed in Familiar?
    7. Where is data stored in Familiar?
  3. Hardware Support
    1. Does Familiar support my handheld?
    2. What add-on devices does Familiar work with?
    3. Why does it take so long to add support for a new handheld?
  4. Using Familiar
    1. How can I make a complete backup of my Familiar system?
    2. How can I read the system log?
    3. How can I take a screenshot?
    4. How can I see the full boot messages?
    5. How can I get rid of the GPE/Opie bootsplash? I want to see the boot messages on screen
    6. Why don't some console applications support all of the usual features?
    7. How can I use the JFFS2 filesystem on a CompactFlash or SD card?
    8. What settings do I need to use to connect to the serial console?
  5. Troubleshooting
    1. When my iPAQ boots up, all I see is "please wait: booting..." and the Tux logo, and then nothing happens!
    2. Booting takes a very long time, although it does eventually start up.
    3. ipkg is not working or giving me errors!
    4. I can't get USB networking to work, or my device freezes up when I connect USB
    5. I'm running out of space in my Familiar system
    6. Help! I want to go back to PocketPC!!!!!!!!
    7. Help! My device is bricked!
    8. My iPAQ h5xxx has WiFi issues and often refuses to turn on
    9. I can connect to the bootloader via serial and I see messages when I reset, but can't type anything
    10. I am having some other problem not covered here
  6. Development
    1. How do I get started with development on Familiar?
    2. I'm not a developer, but I want to help out. What can I do?
    3. Where can I get source code?
    4. Is there some documentation on porting software?
    5. I'd like to port Linux to a new handheld, is there any information on that?
  7. Miscellaneous
    1. Familiar? Why this name?


2. Software Information

2.1. So how do you use Linux on a handheld?

There are three different sets of images provided - GPE, Opie, and bootstrap. The GPE image uses the [WWW]GPE graphical environment, and the Opie image uses the [WWW]Opie graphical environment. The bootstrap image is just the base Linux system, for console/server use only. Most people choose to install either GPE or Opie.

2.2. What's the difference between Opie and GPE?

Using one over the other is a matter of preference. Both are fully graphical user environments designed for use on a PDA, and both have a fairly wide range of applications available. If you are unsure, try both and see which one you like best.

2.3. What applications are available?

The basic PIM software (calendar, contacts, todo, notes) are provided by default in both Opie and GPE. In addition, applications for web browsing, email, chat, network setup, etc. are also available.

Lots of applications have been ported from x86 Linux, and new ones have been created to suit the handheld environment. There isn't a site tracking available applications yet, but check out the sites for each environment ([WWW]Opie/[WWW]GPE).

If you know roughly what you're looking for, you can also use [WWW]IpkgFind to search for a package.

2.4. Can I sync with Evolution, Outlook, my kitchen sink, etc.?

See [WWW]Opie's syncing howto and/or GpeSync for details about synchronisation for each environment.

The base Familiar system provides ways to get a standard TCP/IP network connection over various mediums (serial, USB, WiFi, ethernet, etc.) and most synchronisation systems work over these connections. See NetworkingConnections.

2.5. Can I use Microsoft ActiveSync with Familiar?

No. Microsoft ActiveSync is a proprietary piece of software that uses a proprietary protocol. Other pieces of software are used for synchronising data with Familiar-equipped handhelds - see the previous question.

2.6. How is software installed in Familiar?

Software installation and packaging is provided through Ipkg. It is similar to Debian's packaging system in operation - packages are downloaded on the fly, and all other required packages (dependencies) are automatically installed for you when installing a package. There are nice front-ends available for Opie and GPE that let you get the latest package lists and choose which packages to install/upgrade.

2.7. Where is data stored in Familiar?

In Familiar, all data (documents, PIM data, settings, installed software) is stored in internal flash ROM or on removable memory cards. Some other handheld operating systems store data in RAM, which is fine until the battery goes flat, at which point you lose all of your personal data, installed applications and settings. Familiar does not suffer from this problem.


3. Hardware Support

3.1. Does Familiar support my handheld?

See SupportedHandheldSummary.

3.2. What add-on devices does Familiar work with?

See IpaqHardwareCompatibility. Other devices not listed there may be supported also - if it's supported in Linux on x86, then chances are it can be supported on a handheld (assuming it can physically connect to the handheld).

3.3. Why does it take so long to add support for a new handheld?

Manufacturers do not always provide the information needed to support the hardware in each handheld, because they are unwilling or unable to do so (some have commercial interests in keeping the hardware details secret, others are bound to do so by contract). So the developers sometimes have to piece together what they can from datasheets, looking at the internals of the handhelds, and experimentation.


4. Using Familiar

4.1. How can I make a complete backup of my Familiar system?

See FamiliarBackupHowto. The process documented there will give you a jffs2 image, which you can reinstall just as you would a standard Familiar release image.

4.2. How can I read the system log?

Use the logread command (or dmesg for the kernel log only). The syslog is not written to permanent storage, because of space constraints and to reduce stress on flash memory.

Both OPIE and GPE provide ways to view the logs using their respective System Information applications.

4.3. How can I take a screenshot?

To take a screenshot you can use the scap command. Running this command will upload a screenshot to scap service on handhelds.org. You can then view the image at http://handhelds.org/scap.

Alternatively there are screenshot applets for both Opie and GPE which can use the scap service or save the screenshot locally.

4.4. How can I see the full boot messages?

  1. Get to the bootloader (reboot, or reset) and bring up the bootloader's serial console.

  2. Enter the following command at the boot> prompt.

  3. Type boot and press enter to start booting.

4.5. How can I get rid of the GPE/Opie bootsplash? I want to see the boot messages on screen

Move /etc/rcS.d/S20bootsplash to /etc/rc5.d/S98bootsplash or remove the file entirely.

As an additional step consider installing bootlogd and redirecting the output of /etc/init.d/modutils.sh > /var/log/modules 2>&1 and moving that file to /var/log/modules.last on the next boot in {{/etc/rcS.d/S10}}} that way you can catch module loading failures.

4.6. Why don't some console applications support all of the usual features?

To save space, Familiar uses [WWW]BusyBox which is specially designed to provide minimal command-line functionality for small installations. Commands such as ls, ifconfig, and even the shell itself and vi are provided by the same application - if you look in /bin and /sbin you will see that most of the stuff in there is just symlinks to busybox. Of course, one of the reasons busybox is so small is that it doesn't have all of the features of the full applications.

However, sometimes you might want the full functionality of the real application. In that case you can simply use ipkg to install the real package. You may need to use the --force-overwrite option.

4.7. How can I use the JFFS2 filesystem on a CompactFlash or SD card?

You really don't want to use JFFS2 on a removable flash memory card. Repeat after me, I really don't want to use JFFS2 on my removable flash memory card. CF/SD cards are presented to the OS as standard IDE devices, not mtd flash devices as required by JFFS2. You can use the blkmtd driver to emulate an mtd device on the card, then use JFFS2 on top of that, but you're unlikely to get any benefit by doing so. Most flash memory cards have wear-levelling built-in, so you shouldn't need to use JFFS2 anyway.

4.8. What settings do I need to use to connect to the serial console?

115200 bps, 8, N, 1, no flow control or handshaking.


5. Troubleshooting

5.1. When my iPAQ boots up, all I see is "please wait: booting..." and the Tux logo, and then nothing happens!

See FamiliarReleaseNotes.

5.2. Booting takes a very long time, although it does eventually start up.

At bootup, one of the things that is done is to run ipkg to check if there are any post-processing tasks to be done. This can take a long time. To fix this you can add an & to the end of the ipkg-cl configure command in the /etc/rcS.d/S98configure script to make it run in parallel with other processes, or even comment out that line entirely.

If that is not the problem, you could also try showing the boot messages (see above) and see at what point it stops for a long time.

5.3. ipkg is not working or giving me errors!

See FamiliarReleaseNotes. Also make sure your network configuration is correct (try pinging a known good website, etc.)

5.4. I can't get USB networking to work, or my device freezes up when I connect USB

See the UsbNet page.

5.5. I'm running out of space in my Familiar system

See FamiliarSlimDownHowto.

5.6. Help! I want to go back to PocketPC!!!!!!!!

Firstly, calm down :)

Secondly, see RestoringPocketPc. The process is fully documented there.

5.7. Help! My device is bricked!

Actually, it's probably not bricked. See RecoverBrickedIpaq for further details.

5.8. My iPAQ h5xxx has WiFi issues and often refuses to turn on

You need to update your iPAQ's WiFi firmware. See UpdateWifiH5450.

5.9. I can connect to the bootloader via serial and I see messages when I reset, but can't type anything

This is most likely because you have flow control enabled. Make sure it is disabled in your terminal program.

5.10. I am having some other problem not covered here

Firstly, check the FamiliarReleaseNotes page. If you are sure your problem is not covered there, or the solution provided there doesn't work (and you have followed the instructions correctly) then email familiar@handhelds.org (this is a public mailing list - details [WWW]here).


6. Development

6.1. How do I get started with development on Familiar?

There are two methods for compiling applications: native and cross. Native development is the same as if you were building the software on your PC for your PC - you compile software on the handheld itself, using something like NFS or a CF card to provide you with extra storage. There is some information on using NFS for this on the DevelopmentByNfs page. On the other hand, cross-development is where you build your software on your PC targeted to the handheld environment, using a cross-compiler and toolchain.

Cross-development is the easiest method use, and it is the one in use by most Familiar developers. Either you use a toolchain (see PrebuiltToolchains or BuildCrossToolchainHowto), or use OpenEmbedded. OE is recommended as it takes a lot of the hassle out of cross-compiling - it builds all of the required libraries and other dependencies for you, including some of the tools required on your PC to build other software. See OpenEmbedded for details.

6.2. I'm not a developer, but I want to help out. What can I do?

Handhelds.org needs developers, but there are many other places where the handhelds.org projects need help - documentation (preferably using the wiki) and bug tracking (each project generally has its own bugtracker, but the main one is at http://handhelds.org/bugzilla). The best thing you can do to improve Familiar is to get involved - install it on your handheld, use it, learn about it, and help us to help you if there's a problem.

6.3. Where can I get source code?

See http://www.handhelds.org/sources.html

6.4. Is there some documentation on porting software?

See some of the pages linked on the DeveloperDocuments page.

6.5. I'd like to port Linux to a new handheld, is there any information on that?

Have a look at PortingToOtherHandhelds and the [WWW]article Michael Opdenacker wrote.

7. Miscellaneous

7.1. Familiar? Why this name?

The Merriam Webster On-Line Dictionary defines "familiar" as (among other things):

We think that these definitions embody the belief behind our distribution. We hope that Familiar will turn your handheld into, well, a familiar.