To use the FCam API, first you'll need a development environment for the Nokia N900.

This page describes how to set everything up, assuming very little background knowledge about N900 development. Most of these instructions duplicate documentation from Nokia and the Maemo project - we'll try to point to those documents as appropriate, for those who want more information.


Executive Summary:

Here's the short version for people who are already very familiar with N900 development and have a development environment set up. All three packages mentioned below are available in the maemo extras repository, and also our download page.

  1. Install the package "fcam-drivers" on your N900. Reboot it.
  2. Install the package "fcam-dev" in your development environment, either through Maemo extras, by downloading the latest fcam-dev Debian package from our download page, or by downloading FCam.zip (which has examples and documentation) from our download page.
  3. To look at our examples, get the "fcam-dev" source package, either through Maemo extras, or by downloading FCam.zip from our download page.
  4. You might want to have a look at the package "fcamera", which is a more complete example of a camera application using FCam.

Step 0 - Choose your path

There are several development environments for the Nokia N900. We'll describe how to set everything up using Nokia's new Nokia Qt SDK.

You'll need both your development machine and your N900 on hand to complete all the steps below, and a USB cable to connect the two. (You can connect the two over WiFi instead, but we won't describe that here.)

You can also write, compile, and test your code either from the Qt Creator IDE, or a command line. We'll describe both options, so pick the path you prefer. This is entirely a matter of personal preference, and the first few steps are the same either way.

If you already have an N900 you're developing on with the Nokia Qt SDK, you can skip ahead to Step 6 and start setting up FCam.

Next up :

Steps 1 - 5: Setting up for development
Step 1 - Download the Nokia Qt SDK

First, you need to set up your development environment. Nokia's recently released Qt SDK 1.0.2 comes with everything you'll need to build and run applications for the N900. That includes the Qt Creator IDE, and compilers and libraries it needs for building programs for the N900. The SDK is available for Windows and Linux, and a beta version is available for Mac OS X 10.6.

Download the installer for your operating system here: Nokia Qt SDK Installer. The online installers are small initial downloads, and they'll then download everything else needed during installation. The other option is to download the much larger full installer, which won't require a network connection during installation.

Once you've downloaded the installer, run it. You'll need to select a destination directory for the SDK, and a few other options. For a detailed walk-through of the steps (on Windows), see Nokia's Getting Started Guide.

Platform-specific notes:


It's safest to install the SDK on the C: drive to a directory that contains no spaces in the filename. So don't install it under "Program Files", for example. There are some reports that projects located on a different drive from the SDK don't build properly in Qt Creator, so to be safe, install the SDK to the same drive as your code. The default option offered by the installer, C:\NokiaQtSDK, is a safe choice.

Mac OS X

Yes, you need OS X 10.6 (Snow Leopard). Not even the installer will run on 10.5 or older. If upgrading to 10.6 is not feasible for you, you have a couple of choices: You can set up a Linux virtual machine, such as the ones available from Nokia here. Or you can follow the command-line path instead.

You also need Apple's XCode development environment installed. Otherwise, many basic build tools like 'make' will be missing, and they are not included in the SDK. XCode is a free download from Apple, and is also on the DVD that comes with any Mac.

Step 2 - Update the N900

Now that the Nokia SDK is installed, you need to get your N900 ready. First, make sure you've updated your N900 to version 1.3 (20.2010.36-2) or later. Otherwise software you build in Qt Creator will not run on the device at all. You can check your firmware version by going to Settings->About product (at the very bottom of the Settings page).

There are several ways to update the firmware, but the easiest is going to the N900 Application Manager, and selecting Update. It'll think about it for quite some time, so make sure battery has enough charge, or the device is plugged in. Other ways to update include using the desktop Nokia Software Updater, and as a last resort, a manual reflash using Nokia's flasher tools and a firmware image. Those options won't be detailed here.

Once you have the latest firmware, continue to the next step.

Step 3 - Installing Mad Developer

You need to install an application on the N900 called Mad Developer, which sets up the N900 side of the Qt Creator <-> N900 link for running and debugging programs.

The latest Mad Developer release, which is still in final testing, simplifies several of the setup steps, so you need to enable the Maemo extras-testing repository on your N900 in order to get this latest version:

Activating extras-testing
In the Application Manager:
  1. Tap the title bar to bring up the menu
  2. Select 'Application catalogs'
  3. Select 'New'
  4. Enter a catalog name of 'Maemo extras-testing'
  5. Enter a web address of http://repository.maemo.org/extras-testing
  6. Enter a distribution of 'fremantle'
  7. Enter components of 'free non-free'
  8. Select 'Save'
  9. Tell the Application Manager to update. This may take a while.

Once you have extras-testing set up, go to the Application Manager, then Download. You can either select 'All' and start typing mad-developer and select it when it appears, or select the Development section, and scroll down to mad-developer. If you don't see a Development section, or you can't find mad-developer under All, try updating Application Manager first. You should see Mad-developer version 2.1 or higher.

When mad-developer installs, it'll ask you to create a root password for your N900 (if you haven't already before). Select a password that's secure (use both letters and numbers, preferably), but one that you can type on the N900 keyboard.

Technical note

Normally, programs on the N900 run under the default user account, 'user'. Some programs, however, need to run under the root account, which has more privileges. mad-developer sets up an ssh server for a secure encrypted link between your development machine and the N900, which requires the root account to be set up.

In addition, mad-developer sets up a new 'developer' account, to cordon off development work from the regular user. This is useful in that the main user's settings, files, and so on won't be affected by development work. On the other hand, once you're done writing an application, you'll have to set it up again on the regular user side.

While getting everything set up, there's a good chance you'll need to access the N900 root account directly yourself. To do so, the easiest option is to install the rootsh application on your N900, which lets you switch your X Terminal to the root account.

To install rootsh, go to the Application Manager->Download->All, and type rootsh (make sure it's all lower case, the N900 might try to autocorrect you). Install rootsh. From now on, if you to access the root account, you can just type root in a N900 X Terminal.

That covers all the software you need to install on the N900. Next we'll connect up the N900 and your development machine.

Step 4 - Set up the connection

Plug your N900 into your development machine with a USB cable. Select 'PC Suite Mode' on the dialog that appears on your N900. In fact, whenever this dialog appears while you're developing on the N900, select 'PC Suite Mode'. Depending on your operating system, various messages may pop up on your PC. You can read the getting started guide installed along with the Nokia Qt SDK for these steps as well, it can be found in <SDK Root Directory>\readme\creator-developing-maemo.html, under 'Setting Up Network Connectivity on Development PC'.

Mac OS X

A message should pop up saying a new network connection has been detected. Select the 'Network preferences' option, or if no such message appears, go to System Preferences->Network yourself.

In Network preferences, set the Configure field to 'Manually', and type in the IP Address field. Type in the Subnet mask field. Then select 'Apply'. You've now configured the Mac side of the Mac<->N900 virtual network connection.

You can also refer to the documentation here for this section of the setup.

Windows XP
Windows 7

Now switch back to MAD Developer on the N900.

The next steps are also described here with screenshots. (It applies to all operating systems, despite the page name.)

Windows only:
Once MAD Developer is running, click on 'Manage Usb'. In the dialog that appears, look at the USB Module in use. If it is not 'Windows network', click on 'Windows network'. You'l have to select PC Suite again in the dialog that appears. Then click 'Close'.
In the MAD Developer main window, the 'Edit' button on the usb0 row should be enabled. Click on it. In the dialog that appears, make sure that the IP Address is set to, the Netmask is set to, and the Peer IP is set to These are the defaults we'll assume for the rest of this guide. Once you've verified that the fields match, click on 'Configure'. If you need to change any of these values due to conflicts with existing devices, remember to substitute your values throughout the rest of this document.

Back in the main window again, the IP address and Netmask should appear on the usb0 row. The N900 is now configured to talk to your desktop machine.

Troubleshooting tips
Sometimes the N900 networking subsystem can get confused about the state of the USB network connection. If you have problems with Qt Creator not being able to communicate with the N900, the following set of steps might help resolve the problem (you'll need rootsh installed, as described earlier):
  1. Start or switch to MAD Developer.
  2. Click 'Developer XTerm'.
  3. In the terminal window that opens, type root, followed by enter.
  4. Type ifdown usb0, followed by enter.
  5. Type ifup usb0, followed by enter.
  6. Close the X Terminal with the top-right X button.
This will reset the USB network connection, hopefully resolving the problem.

Now you're ready to start up Qt Creator, or to open a command-line window. Pick your path!

Step 5 - GUI - Setting up Qt Creator

Start up Qt Creator, the IDE for the Nokia Qt SDK. To test that everything works, we're going to build and run a sample Qt application on your N900.

In the welcome screen that appears, click the 'Choose an example...' dropdown, and select the very first example, Animation Framework->Animated Tiles. A 'Project setup' dialog should appear, asking you to list the targets for your project.

Each target is a different platform to run your application on. For now, select the 'Qt for Fremantle PR1.3 Devices (Nokia Qt SDK)' checkbox under 'Maemo', and uncheck everything else. That's the target for the N900. Then click 'Finish' or 'Done'.

Qt Creator should now switch to the Edit view, showing the list of files in the Animated Tiles example on the left, the source code for the main.cpp file in the center, and documentation for the example on the right. On the bottom left is a toolbar with buttons to build and run the example.

Click the hammer icon, which starts a build of the example for the Maemo target. A small progress bar will appear, and in a short while will complete. You can see the compilation log by clicking on the 'Compile Output' button the bottom of the window.

If you now click on the large green arrow, which is the Run button, and wait a while, you'll be greeted with the following message:

Remote Execution Failure
Error running initial cleanup: Could not connect to host.
That's because Qt Creator isn't yet set up to connect to your N900. We've set up the virtual network, but we still need to let Qt Creator know about it.

(The next steps are also described by Nokia here, with screenshots. If you look at those instructions, don't create the configuration for the emulator, just for the device. Also note that you shouldn't close the MAD Developer password dialog until after you've deployed the public key.)

In Qt Creator, go to the Tools menu, and select Options. (On Mac OS X, go to Qt Creator menu->Preferences instead). In the Options dialog that appears, select the Projects entry on the list on the left. Then click on the 'Maemo Device Configurations' tab on the right. This is where we'll add your N900 to the list of devices that Qt Creator knows about.

Click on 'Add'. Most of the fields in the dialog should now be enabled. Change the 'Name' field to something more useful, like 'N900'. Then switch 'Authentication type' to 'Password'.

On your N900, bring up MAD Developer again, and select 'Developer Password'. A dialog will appear with a short random password to the left of the 'Close' button. Don't close this dialog until you're told to.

In Qt Creator, enter this password into the Password: field. Then click the 'Test' button on the right. If everything goes right, in a few moments you should see a dialog box appear that starts with 'Device configuration successful'. This means everything is configured correctly, and Qt Creator can communicate with your N900.

What if you get a failure message in the dialog? Here are a few things to try:

However, the developer password isn't very secure, and will only work while the MAD Developer dialog is open. For security (and ease of use), you'll want to let Qt Creator and the N900 create encrypted connections using an SSH key pair. If you already have a pair of SSH keys, you can just use them here.

If you don't have a pre-existing pair, click the 'Generate SSH Key...' button. In the dialog that appears, click the 'Generate SSH key' button, and then 'Save public key...'. Place the file somewhere convenient - Qt Creator prefers the .ssh directory under your user account. Also save the private key with 'Save private key...' button. Then close the dialog.

Now click the 'Deploy Public Key...' button, and select the 'id_rsa.pub' public key file that you just saved, or that you already had. A dialog should pop up telling you the key was deployed to the N900 successfully.

Switch the Authentication type back to 'Key' in Qt Creator, and click the now-enabled 'Browse' or 'Choose' button next to the 'Private key file' field. Locate the 'id_rsa' private key file you just saved above (or already had), and select it. On the N900, press 'Close' in MAD Developer to close the password dialog.

Press 'Test' again in Qt Creator. You should get the same successful test dialog as before. You've now set up a secure link between Qt Creator and your N900. (This is more vital when you're using WiFi to connect to you N900, but Qt Creator doesn't make distinctions between connection types.)

Click 'OK' to close the Options dialog. The example project will automatically pick up on the new device we configured, since none existed before. You can go ahead and click the big green Run arrow, and Qt Creator will deploy and run the example on your N900. If everything is set up correctly, you should see flying Qt boxes all over the N900 screen in a few moments.

Setting up the run target explicitly

If you already have other targets set up in Qt Creator (like the Maemo emulator), you'll have to tell the Animated Tiles project about your new device. Select the 'Projects' tab on the left, and then select the 'Run' button on the floating 'Maemo' window. Select the 'Add' dropdown, and from it 'New Maemo Run Configuration'. Give the new configuration a useful name, like 'Run on the N900', and in the Device configuration dropdown, select the N900 you just set up in Options.

Note that console text output from the application will be displayed on the bottom of the screen if you have the 'Application Output' view selected.

You can also run your application with a remote debugger, using the Arrow+Magnifying Glass icon on the left. To switch between Debug and Release builds of the example, click the PDA-looking icon above the Run arrow, and click on the Build dropdown.

Now that Qt Creator and your N900 are connected up, it's time to get FCam itself set up. First up are the N900 drivers for FCam.

Step 5 - Command-line - Set up MADDE

The Nokia Qt SDK comes with a full command-line Maemo development system, called MADDE. For those who don't like IDEs, MADDE is the easiest way to build software for the N900.

MADDE uses two tools, mad and mad-admin. Depending on your operating system, setting up a terminal with access to those tools varies:


Since Window's built-in command interpreter (cmd.exe) is fairly painful, we recommend you use the MADDE terminal installed by the SDK. In the Start menu, the SDK added a Nokia Qt SDK entry, and inside it you'll find a link to 'MADDE Terminal'. Select it to start up the terminal.

The MADDE terminal is more unix-like than the standard Windows command-line. While it understands normal Windows paths (C:\Program Files), you might be more productive using a more unix-like notation (/c/Program Files) as you can use TAB to autocomplete those paths. Also note that you can't switch drives by typing in just D: as you can in cmd - instead, the cd command switches both directories and drives. (So you'd want to type cd d: instead.)

For those familiar with unix-like shells, MADDE terminal is based on rxvt.

Mac OS X

The SDK installer places mad and mad-admin in <SDK_Root>/Maemo/4.6.2/bin. You'll want to add this to your PATH variable so you can use both from the terminal command line.

Open up .profile or ~/.bash_profile in your user folder in a text editor (or create such a file if one doesn't already exist). Add a line PATH=~/NokiaQtSDK/Maemo/4.6.2/bin:$PATH (assuming you installed the SDK to ~/NokiaQtSDK, otherwise adjust the SDK path).

Now open a new terminal window (the old ones won't update on their own), and type mad. You should see help for the command appear.

mad and mad-admin are installed in <SDK Root>/Maemo/4.6.2/bin. Add this to your user account's path, or create symlinks to the programs in an appropriate location.

To verify that your development system can communicate with your N900, try logging in remotely to it from the MADDE command line, by typing: ssh root@, followed by enter, and provide the root password you selected earlier when prompted. You should then be logged into your N900 as the root user. Type exit, followed by enter, to close the remote connection.

If you want to avoid having to enter the password each time you ssh into your N900, you can copy your public key to the phone. First, create a directory for .ssh on N900: mkdir ~/.ssh and then copy the public key to that folder from your computer: scp ~/.ssh/id_rsa.pub root@


Steps 6 - 10: Setting up FCam
Step 6 - Installing the FCam drivers

Your N900 needs to have the FCam drivers package installed to run FCam applications.

If you've already installed and ran FCamera, our sample application, you're all set, as it comes with the needed drivers. Move on to the next step. Otherwise, you can either

  1. Just install FCamera in the Application Manager, reboot your N900 once you've done so, and skip the rest of this step, or...
  2. Read on to just install fcam-drivers, in case you really don't want FCamera.

The fcam-drivers package is in the the Maemo community software repositories, called extras, which is accessible by default by your N900. Unfortunately, since fcam-drivers is not an application on its own, it's not visible directly in Application Manager.

Instead, you'll have to use command-line tools to install it. Make sure you have Rootsh installed, and then start the X terminal application. Type root followed by enter, to switch to the root user. This is required to install new software with the terminal.

Then type apt-get install fcam-drivers followed by enter. After a short while, a dialog box should appear, informing you that you'll need to restart your phone for the new drivers to take effect; select 'I agree', and then Accept.

Alternate method - Download from the project page

As a fallback, you can also download the package directly from our Download page. As of this writing, a direct link to the latest Debian install package is here. You can use wget on the command line to download the package:

Open the X terminal application, and type root followed by enter, to open a root terminal. If you don't already have wget, install it with: apt-get install wget

Then download the drivers package with:

wget --no-check-certificate https://garage.maemo.org/frs/download.php/8910/fcam-drivers_1.0.7-1_armel.deb
You'll need to modify that URL if 1.0.7 is no longer the most recent version of the fcam drivers. Next, type the following to install the driver package:
dpkg -i fcam-drivers_*.deb

Once installation is complete, you'll need to restart your N900 to have the updated drivers take effect. To repeat:

Reboot your N900!
Once the driver installation is complete, you need to restart your N900.

Once the N900 is restarted, start up MAD Developer again, and repeat the USB configuration steps from Step 4. To recap:

With the drivers installed, you're ready to set up the development package.

Step 7 - Get the FCam development library

Now you'll need to get FCam on your development machine, which you'll need to download from our project page.

Our project's download page is here. Select the newest fcam-dev release that ends in .zip.

Create a directory called FCam where you'd like the library to live, and extract the zip file into it. Note: You'll have to type this location into your project files, so make sure you know where you're putting the library. For the rest of this guide, we'll assume you've extracted FCam into C:\Development\FCam. Adjust as appropriate for your operating system and personal preferences.

To be safe, make sure the FCam library and the Nokia Qt SDK are both on the C: drive. We've seen strange errors if they are not.

The development package contains:

Next, you'll set up help for FCam inside Qt Creator, or access it through a web browser.

Step 8 - GUI - Set up help in Qt Creator

The development package includes a Qt Creator help file that you can use to get inline help on the FCam API.

To use the help file, start up Qt Creator. Then open the Tools menu, and select 'Options' (on a Mac, find the 'Preferences' dialog instead). In the left-hand pane of the Options dialog, select 'Help'. Select 'Documentation' in the tabs on the right. Click the 'add' button on the right side, and browse to C:\Development\FCam\doc. Select FCam.qch, and hit Ok until you're back in the main Qt Creator window.

Now, restart Qt Creator to enable the new help file.

Technical note
Qt Creator doesn't move or copy FCam.qch anywhere - it accesses it right from where it is. So don't move it without telling Qt Creator the new location.

We're now ready to open an example program and build it!

Step 9 - GUI - Build example 1

FCam comes with a set of example programs that demonstrate how to use the API. They build up in complexity, so we'll start with the simplest one, example1.

If you still have the animatedtiles example open in Qt Creator, close it and any other projects first (File menu->Close All Projects).

In Qt Creator, open C:\Development\FCam\examples\example1\example1.pro (File menu->Open File or Project...).

Example1 is a very short program that simply starts up the N900 camera, and takes a single full-resolution image, which it stores in the N900 photos directory with the name 'example1.jpg'.

Hold up your N900, and open the lens cover. When the built-in camera app launches, close it - you can't run the built-in camera application at the same time as an FCam application, since the both need exclusive access to the camera.

Point your N900 at something to photograph, click the run button in Qt Creator, and wait. Once example1 has finished building and running, you should see 'Finished running remote process' in blue in the application output window. You can put the N900 down now.

Go to the N900 Photos application. You should see a new image there, with the name 'example1.jpg'.

If example1 doesn't appear to run correctly, here are some things to check:

For more information on how to get started on Qt look here and here.

That's it! For final notes, go to the next step.
Step 8 - Command Line - Access the help pages

FCam comes with prebuilt HTML help files that document the API in detail. You can find the top-level help file in C:\Development\FCam\doc\html\index.html. The documentation is built directly from source code comments using the Doxygen system.

Step 9 - Command line - Build example 1

The FCam example programs can be found in C:\Development\FCam\examples. There's a top-level Makefile to build all of them, but we'll start by just building example1.

The example programs build up in complexity, demonstrating various features of the FCam API. The first program simply takes a single full-resolution photograph, and stores it in the usual place for N900 photographs so that it's viewable by the built-in galley application.

Open a command-line window, and go to C:\Development\FCam\examples\example1. The directory contains a Makefile, a project file for Qt Creator, and example1.cpp. We want to compile example1 for the N900, so we'll need to invoke the cross-compiler installed by the SDK.

This can be done simply by prepending the normal build commands with mad. So to build example1, simply type mad make. This will build the executable example1, and place it in C:\Development\FCam\examples\bin.

To copy the executable over to your N900 and to run it, we'll use scp and ssh. You can simply type scp ../bin/example1 root@, using your N900 root password when prompted, to copy example1 to the device. Then you can use ssh to log into the N900 remotely, with ssh root@ and your root password.

Once logged in, you should open the N900 lens cover, and then close the built-in camera application when it starts up. After it closes, type ./example1, point your N900 at something to photograph, and hit enter. Example1 will run, take a picture, and save it as example1.jpg in your N900 photo gallery.

If example1 doesn't appear to run correctly, here are some things to check:

If you want to do on-device debugging from the command line, the simplest method is to install gdb on your N900. This can be done with apt-get install gdb in the root shell. Then you can debug example1 with gdb example1.

Technical note

Typing in the root password all the time can get annoying, and you might want to test your application in a regular user account instead.

MAD Developer creates a developer account that you could use instead. For convenience, you'll want to use a ssh keypair to remove the need to type a password each time you scp or ssh to the N900.

If you already have an ssh keypair (id_rsa and id_rsa.pub) somewhere, you can use those. If you don't, open up your Mad-enabled terminal, and type ssh-keygen. The program will prompt you to save 'id_rsa' (the private key) and 'id_rsa.pub' (the public key) somewhere. Save them to ~/.ssh.

Next, scp id_rsa.pub to your N900, and place it in /home/developer/.ssh/. If you already have an authorized_keys file in this directory, open id_rsa.pub and copy the single line in it to the end of the authorized_keys file. Otherwise, just rename id_rsa.pub to authorized_keys.

That should be it - now if you ssh from your terminal window using ssh developer@, you won't need to type in your password, and you can test your code under a non-root account.

Assuming example1 worked, you have everything set up to develop with FCam. See the last step for some final notes.

Step 10 - Done!

Great, everything is now set up and ready to go. You can keep going through the example programs to see how they work. The final example, example7, uses Qt to bring up a live viewfinder. If you want to use it as a basis for your own project, copy example7 to your own development location. Just make sure you modify the Qt project file to point to the FCam API headers and library by editing example7.pro:

Open example7.pro, and change the INCLUDEPATH line to INCLUDEPATH += C:\Development\FCam\include. Then on the LIBS line, change -L../.. to -LC:\Development\FCam

To build the Qt project on the command line, first type mad qmake, then mad make. Using Qt Creator, simply open the next project file and click the build button.

Or you can get our sample application, fcamera, and use it as a basis for your own work. It has a lot more features than example7, so it's a richer basis for further development. Of course, that means it'll take a bit longer to come to grips with it as well.

Either way, we hope you enjoy using FCam. Please post feedback, bugs, and so on to the FCam forums, bug tracker, and mailing list.