The libfreespace library enables rapid development of applications for Hillcrest Labs Freespace® devices. libfreespace provides access to extended information beyond mouse pointer functionality such as calibrated acceleration and rotational velocity measurements, orientation, configuration, and battery status.
C Python CMake Other
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.


General Information

This document describes the build process for libfreespace.

Required Tools

The tools required to fully build libfreespace are:

1)  git - Use a stable release.
	Ubuntu:		sudo apt-get install git

2)  Python v2.7
                Update the environment variable PATH to include the folder that
                contain python.exe.
    Ubuntu:		sudo apt-get install python

3)  Doxygen v1.8.0 (older versions will have formatting problems)
    Ubuntu:     You cannot use apt-get for doxygen because the version is too
                old. Instead, get it from the Doxygen download page.

4)  Graphviz v2.30.1
    Ubuntu:		sudo apt-get install graphviz

5)  CMake v2.8
	Ubuntu:		sudo apt-get install cmake
				sudo apt-get install cmake-gui

If using Microsoft Windows:

6)  MS Visual Studio 10 (2010) or above
	The "Express" versions work just fine, although they lack 64-bit compilers.
    Only the Visual C/C++ parts are necessary.

7)  Windows Driver Development Kit (WinDDK) 7.1.0
    The WDK can be obtained from Microsoft by following the instructions at:

    CMake will automatically look for the DDK at C:\WinDDK\7600.16385.1.
    If you install the DDK elsewhere, you can either point to it during the
    configuration process, or you can point the environment variable
    "WINDDK_DIR" to it and CMake will find it.

    At the moment, the newest WDK 8.0 is not supported.

If using Linux:

6)  GNU Make and GNU G++
    The best way to get these is to get the build-essential package.
    This should be available for most Linux distros.
    Ubuntu:		sudo apt-get install build-essential

7)  libusb
    Ubuntu:		sudo apt-get install libusb-1.0-0-dev

Getting the files

To correctly check out all of the repositories, navigate to the <base>
directory and use the following command:
    git clone


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 or

Fill in the "Where to build the binaries" entry. This can be anywhere but a
reasonable location is c:\Hillcrest\build\libfreespace 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 10  (2010)
    Visual Studio 11  (2012)
    Visual Studio 12  (2013)

	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:


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.sln .

Open this project. Press F7 to build all. There should now be a
libfreespace.lib file in the Debug directory of the build directory.


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.

    cd ~/Hillcrest/build/libfreespace

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
    sudo make install


To make the doxygen documentation:

You can build the libfreespace-docs project in the libfreespace solution.
    1) Open an explorer window to your build directory
    2) Open libfreespace.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 doc
    doxygen Doxyfile
    4) From here you can open it using

You can make the libfreespace-docs target of the libfreespace 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 ./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 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: