This project contains example programs to demonstrate various capabilities of libfreespace.
C C++ CMake Shell
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


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:
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


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 

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:

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

	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:


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:

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

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:

	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"
    Specify an alternate backend on some paltforms. On Linux, valid values are
    'hidraw' and 'libusb'
    Build only the libfreespace codecs
    CMake file to customize install rules when libfreespace is built as part of
    a larger project
    Enabled doxygen docs as build target
    Generate doxygen for src files (in addition to API)
    Enable writes in a backend thread when using hidraw
    The type of library to create
    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:


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.


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

    cd ~/Hillcrest/build/libfreespace-examples

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


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.


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 

    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.


To make the doxygen documentation: 

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:

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




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: