Getting Started Guide

In this document you will get a short guide how to get started using and hacking on the Fawkes software.

Requirements

Fawkes focuses on development for  Linux-based systems in general, and  Fedora Linux and  CentOS/ Red Hat Enterprise Linux in particular. Other distributions like  Ubuntu and  Debian have been used successfully, but may require a little more work. The Fawkes Development team maintains many required packages within Fedora, and therefore coverage is best there. Fawkes can also be compiled and used on  FreeBSD, but some hardware plugins may not be available.

Fawkes needs a few other software libraries that have to be installed on the development system. It is our declared goal to minimize this set of libraries, but libraries allow for extending Fawkes' functionality without reinventing the wheel and lowering the amount of code to write, verify, and maintain. We do not package any 3rd party libraries in the Fawkes source tree, but rely on the target system to provide those libraries. This way the source tree remains sleek and we exploit the working force of the fine people packaging software for their favorite operating system.

See FawkesDependencies for tools and libraries that are required or recommended for operation.

Getting Fawkes

There are three ways of getting Fawkes that we describe here.

System-wide binary installation

This method is currently supported on Fedora. Fawkes has been accepted as a Fedora package and can be installed either via the graphical package install utility or via yum on the command line. Install the fawkes package to get a useful base system. To do this on the command line execute as root:

yum install fawkes

Note: If you plan to compile Fawkes from source, this method can be used to get the largest set of dependencies available on Fawkes by installing the fawkes-devenv package instead of fawkes. As its dependencies this package will pull in everything required and recommended to build Fawkes.

Afterwards continue below at Running Fawkes.

Release Tarball

You can also go to the download page and get the latest release tarball. Afterwards unpack it with the following command, adapting the version number as necessary.

tar xfj fawkes-0.4.1.tar.gz

Continue below at Compiling Fawkes.

Git Checkout

Especially if you plan to work on Fawkes and contribute code like bug fixes or plugins, you should consider using this method. First, you need to clone the repository, and then we strongly recommend to create a branch on which you will start doing your work. This can be achieved with the following commands:

git clone git://git.fawkesrobotics.org/fawkes.git
cd fawkes
git checkout -b work-branch

Of course you can choose any other branch name. Continue below at Compiling Fawkes.

Compiling Fawkes

Make sure you have installed at least the minimum requirements, better even the recommended dependencies or as much as possible listed at FawkesDependencies. On Fedora read in the section system-wide binary installation about the fawkes-devenv package to achieve this easily, without having a full binary installation otherwise. We additionally recommend using  ccache, a tool that will create an object cache and which can tremendously speedup consecutive compilation runs during development.

Afterwards go to your Fawkes source directory, named either fawkes-0.4.1 (for tarball installation, version may differ, of course) or fawkes (for git checkout). Then execute the following make command:

make -j2 clean all gui

This will build everything that can be built. The -j2 parameter assumes that you have a dual core machine and will cause parallel compilation with two job clients. On a single-core machine omit this option. If you have more cores increase this accordingly.

The Fawkes build system distinguishes building the base system and console tools (the all target) and GUI applications (the gui target). This is done for efficiency, especially when working on the robot. The clean target will ensure that the source tree is clean. It is not strictly required on the first run, but if you repeat this step, e.g. after installing more dependencies, this comes handy.

To find your way through the source tree read FawkesStructure?.

Note: On FreeBSD you need to execute gmake instead of make.

Running Fawkes

The following will assume a source-tree based installation. If you have used the system-wide setup, simply remove the ./ prefix of the commands. Otherwise we assume that you are in the bin directory of the source tree after successful compilation. Lines starting with ">" denote output by the process.

Fawkes runs as a modular monolithic system, which loads and runs plugins within the same process. Every task within this process is executed in a thread. A plugin may have one or more threads. These properties, run-time plugin support and a multi-threaded paradigm, make Fawkes a very dynamic and flexible application. Fawkes is instructed by tools that communicate with Fawkes over the network. Even if you instruct it on the same machine, it will open a local connection. Read more about Fawkes' characteristics on the about page.

To run Fawkes, we first start the main application which provides the infrastructure for plugins:

./fawkes
> 15:33:21.799269 FawkesMainThread: No timed threads exist, waiting

Fawkes has been started successfully, but since no threads have been registered for the main loop it simply waits. As a first test, turn up the sound volume and load the flite plugin, which will make your machine speak "Speech synth loaded". Use the following command:

./ffplugin -l flite
> Requesting loading of plugin flite
> Loading of flite succeeded

This will load the flite plugin. As its initialization routine it will output the sentence. The main application will print:

> 15:36:07.550514 PluginNetworkHandler: Loading plugin flite

You are now ready to start your journey into the Fawkes universe.