README

libfreespace Build info
Updated 8/2/2013

General Information
===================

This document describes the build process for libfreespace-examples.


Required Tools
===================

The tools required to build the examples are the same as the tools required to
build libfreespace. This is because the examples build the libfreespace library
and use the libfreespace source. See the README for libfreespace and ensure
that libfreespace builds on your machine before proceeding to the examples.

Folder Hierarchy
===================

The build process relies upon a fixed directory structure between
the different projects.  The structure should be:
    <base>/libfreespace
    <base>/libfreespace-examples
where <base> represents your fully-qualified base directory.  For example, you
could use <base> = c:/Hillcrest/. Note that the packaged source releases
contain version numbers in their names. To build under Windows, you need
to remove those numbers. If you are building from the bazaar repository,
you do not need to make any changes.

This folder hierarchy is necessary because the libfreespace-examples build
the libfreespace library and draw upon the libfreespace source.


Getting the files
===================

To correctly check out all of the repositories, navigate to the <base>
directory and use the following command:
    bzr branch lp:libfreespace libfreespace
    bzr branch lp:libfreespace-examples libfreespace-examples

If you find this doesn't work, try:
    bzr branch lp:~libfreespace-devteam/libfreespace/cmake libfreespace
    bzr branch lp:~libfreespace-devteam/libfreespace-examples/cmake libfreespace-examples

If still it does not seem to work, try the standalone flag:
	bzr branch --standalone lp:~libfreespace-devteam/libfreespace-examples/cmake libfreespace-examples

Building
===================

Launch cmake-gui.

Fill in the "Where is the source code:" entry. This will be the location of the
libfreespace directory. (e.g. c:\Hillcrest\libfreespace-examples 
or ~\Hillcrest\libfreespace-examples)

Fill in the "Where to build the binaries" entry. This can be anywhere but a
reasonable location is c:\Hillcrest\build\libfreespace-examples or 
~\Hillcrest\build\libfreespace-examples

If some configuration data opens up when you enter the build directory, it means
that the directory already had a build in it. You can reset the build directory
by selecting File > Delete Cache.

Click "Configure". You will be prompted to select a generator for this project.
Choose any of the supported generators:

Windows:
    Visual Studio 8 2005
    Visual Studio 9 2008
    Visual Studio 10
    Visual Studio 11

Linux:
	Unix Makefiles

At this point, all the configuration settings will be red. This is the time to 
make any changes to the settings that are displayed. Not all settings are
required, however some important ones are:

Windows:

The WINDDK_DIR variable. If your WinDDK is installed in a typical location then
cmake should be able to detect it for you. A typical setting is:
    C:\WinDDK\7600.16385.1

If using Visual Studio 8 or 9, the VC8_INCLUDE or VC9_INCLUDE variable. If your
Visual Studio installation is in a typical location cmake should be able to 
detect it for you. A typical setting is:
    C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\include

Linux:
	
The LIBUSB_1_INCLUDE_DIR and LIBUSB_1_LIBRARY variables. These should be
automatically detected by cmake but if they are not you may need to point
them at your libusb installation.

There are other configuration settings available:

CMAKE_INSTALL_PREFIX :
	The installation directory where the CMake install project will install to.
	This is initiated by building the "INSTALL" project in the VS solution.
	Default is typically "C:\Program Files (x86)\libfreespace"
LIBFREESPACE_BACKEND :
    Specify an alternate backend on some paltforms. On Linux, valid values are
    'hidraw' and 'libusb'
LIBFREESPACE_CODECS_ONLY : (ON/OFF)
    Build only the libfreespace codecs
LIBFREESPACE_CUSTOM_INSTALL_RULES :
    CMake file to customize install rules when libfreespace is built as part of
    a larger project
LIBFREESPACE_DOCS_ENABLED : (ON/OFF)
    Enabled doxygen docs as build target
LIBFREESPACE_DOCS_INTERNAL : (ON/OFF)
    Generate doxygen for src files (in addition to API)
LIBFREESPACE_HIDRAW_THREADED_WRITES : (ON/OFF)
    Enable writes in a backend thread when using hidraw
LIBFREESPACE_LIB_TYPE : (SHARED/STATIC)
    The type of library to create
LIBFREESPACE_ADDITIONAL_MESSAGE_FILE :
    Reserved for Hillcrest use. An additional HID message definition file.

Set whatever configuration settings you wish, then click "Configure" until all
red bars are gone. If a red bar persists, it means that setting will need to
be set manually.

Once the red bars are gone click "Generate".

In order to compile the project:

Windows:

There should be a Visual Studio project under the "Where to build the
binaries" location. The project will be called libfreespace-examples.sln .

Open this project. Press F7 to build all. There should now be a group of executables
in the "Debug" folder. Each of these executables is one of the libfreespace examples.

Linux:

There should be a Makefile in the build directory.
In order to build the library simply open a terminal window, cd to the build
directory and use the make command. This should create a group of executables
in the build directory. Each of these executables is one of hte libfreespace
examples.

Example:
    cd ~/Hillcrest/build/libfreespace-examples
    make


If you wish to use the "INSTALL" feature of cmake:

Windows:

You will probably have to start Visual Studio using administrator privileges. 
Then right click the "INSTALL" project and click "Build". There will now be a 
libfreespace build in the install directory pointed to by CMAKE_INSTALL_PREFIX.

Linux:

You can use the install target of the Makefile. You may need administrator 
priveleges in order to do so. This will install libfreespace in the directory 
pointed to by CMAKE_INSTALL_PREFIX.

Example:
    cd ~/Hillcrest/build/libfreespace-examples
    sudo make install


Descriptions of Examples
========================

There should be 8 executables total. The current libfreespace examples are:

(1) communication_example
        Prints out messages received from a connected Freespace device.
(2) data_rate_example
        Displays sensor data rate information for individual sensors on a 
        Freespace device, allows the user to request a sensor fusion rate,
        and measures the data rate of MotionEngine data packets.
(3) enable_mouse_example
        Turns on mouse events for a connected Freespace device. This allows
        the device to behave as a mouse and move the cursor on the screen.
(4) firmware_version_example
        Displays the firmware version of connected Freespace devices, and 
        responds to hotplug events, such as disconnecting or reconnecting 
        devices on the fly.
(5) game3d_example
        Calculates the yaw, pitch, roll, and acceleration of a connected 
        Freespace device.
(6) motion_example
        Monitors the acceleration of a connected Freespace device.
(7) motion_example_async
        Monitors the acceleration of multiple Freespace devices, and can handle 
        hotplug events.
(8) power_mgmt_example
        Displays the devices Activity Classification and Power Management Flags, 
        which provide information about power consumption.


Documentation
=============

To make the doxygen documentation: 

Windows:
You can build the libfreespace-docs project in the libfreespace-examples solution.
    1) Open an explorer window to your build directory
    2) Open libfreespace-examples.sln
    3) Right click on the libfreespace-docs project and click "Build"
    4) You can open the documentation by returning to the explorer window, and
    opening docs > html > index.html

You can also build the documentation from the command line by opening a command
window in your build directory:
    1) Open an explorer window to your build directory
    2) Shift-(Right Click) on the window and select "Open command window here"
    3) In the command window, enter:
        cd libfreespace/doc
        doxygen Doxyfile
    4) From here you can open it using:
        ./html/index.html

Linux:
You can make the libfreespace-docs target of the libfreespace-examples Makefile.
    1) Open a terminal window and navigate to the build directory.
    2) Enter  "make libfreespace-docs"
    4) From here you can open it using Firefox (or any other browser):
        firefox ./libfreespace/doc/html/index.html

You can also build the documentation using doxygen directly:
    1) Open a terminal window and navigate to the build directory.
    2) Navigate to the "doc" directory by using:
        cd libfreespace/doc
    3) Build the Doxygen documentation by using:
        doxygen Doxyfile
    4) From here you can open it using Firefox (or any other browser):
        firefox ./html/index.html

Troubleshooting
===============

Linux:

USB CONFIGURATION:

libusb requires the Kernel to have USB support enabled.  Specifically:

Support for Host side USB must be enabled in the kernel.
Support for USB device filesystem

At least one USB Host Controller Driver must be enabled.

These options can be found under Device Drivers, USB Support using
make menuconfig.

Depending on how your system is configured, you may need to tweak
some settings to enable access to the USB port.  The following are
options to try:

1.  If using an old version of Linux, USBFS may need to be mounted

    You can check if USBFS is mounted by issuing:

    cat /proc/bus/usb/devices

    with at least one USB device attached.
    If the file does not exist, issue the following command:

    mount -t usbfs /dev/bus/usb /proc/bus/usb

2.  The permissions on the /dev/bus/usb/[bus]/[device] file may be too
    restrictive.  Try running as root to see if this fixes the problem.
    If it does and you don't want to run as root, update the udev configuration.
    For example, edit or add /etc/udev/rules.d/99-local.rules and add the line:

    SUBSYSTEM=="usb", ATTR{idVendor}=="1d5a", MODE="0666"

3.  If you're running on a system that uses HAL to auto-load drivers, 
    you may want to keep it from loading the HID drivers while debugging
    to avoid mouse movement.  To do this, create a file in /etc/hal/fdi/preprobe
    with the contents: