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.
Contents:
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.
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.
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.
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.
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.
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:
http://repository.maemo.org/extras-testing
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.
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.
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'.
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 192.168.2.14 in the IP Address field. Type 255.255.255.0 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.
192.168.2.14 in the 'IP address' entry,
and 255.255.255.0 in the 'Subnet mask' entry.
Leave the other entries blank. Then click 'OK', and 'OK'
again.
192.168.2.14 for the 'IP
address' field, and 255.255.255.0 for the
'Subnet mask:' field.
ifconfig usb0 192.168.2.14Now 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.)
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.
root, followed by enter.ifdown usb0, followed by enter.ifup usb0, followed by enter.Now you're ready to start up Qt Creator, or to open a command-line window. Pick your path!
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:
(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.
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.
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.
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.
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@192.168.2.15, 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@192.168.2.15:~/.ssh/authorized_keys
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
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.
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
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:
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.
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.
The development package contains:
Next, you'll set up help for FCam inside Qt Creator, or access it through a web browser.
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.
We're now ready to open an example program and build it!
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'.
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.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.
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@192.168.2.15:, 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@192.168.2.15 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 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.
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@192.168.2.15, 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.
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.