Frequently Asked Questions

The API changed between the 0.4 release and the 0.5 release to add support for the FSP200 series of Freespace processors while also simplifying the application implementation.  For details, see the migration guide.

No. Freespace devices expose a standard mouse interface that will work with all major operating systems.

Not automatically. Freespace devices expose multiple USB interfaces. libfreespace only accesses the control interface. The standard mouse interface and its associated drivers are unaffected. However, it is possible to disable mouse event reporting using the libfreespace library if it fits your application needs.

The libfreespace library supports all devices that use the Hillcrest Freespace HID interface, but not all products which incorporate Freespace® motion sensing implement this interface. Supported devices include:

•     - The Hillcrest Labs Loop™ Pointer
•     - The Hillcrest Labs Freespace Reference Kit (FSRK)
•     - Freespace remote controls from Universal Electronics, Inc.
•     - Kodak HD Theatre remote control
•     - ZillionTV remote control

The following products do not expose the Freespace HID interface and do NOT work with libfreespace:

•     - Logitech MX Air

Depending on the device, Freespace may be implemented using a 3-axis accelerometer and either a 2-axis or 3-axis rotational sensor. The former are referred to as 5 degree of freedom (DOF) devices and the latter as 6 DOF devices. Both implementations work well for pointing. 6 DOF devices work better for general motion control applications that use libfreespace to access body and user frame reports. The additional rotational sensor axis on 6 DOF devices measures roll.

The production version of the Loop is a 5 DOF device. The FSRK 3 is a 6 DOF device.

Download and extract the Windows binary distirbution file somewhere. Under your development tree is not a bad place for it.

Ensure that the include directory is visible by the compiler. Under VisualStudio 2005, right click on your project and select ‘‘Properties.” Under “C/C++,” select “General,” and add the libfreespace include directory to the “Additional Include Directories” field. Next, select “Linker” (on the left) and “Input” under that. Add the libfreespace.lib file to the “Additional Dependencies” field, and lastly, copy the libfreespace.dll to your bin directory, (Release or Debug).

You will need to download the source code and compile on your own machine. The source is always available at http://libfreespace.hillcrestlabs.com/content/download. Additionally, you may check out pre-release software at https://launchpad.net/libfreespace/. Check the README.win32 file in the archive for instructions on building.

This only happens if you installed the Mac OSX kernel patch that comes with libfreespace and your Loop has the 1.0.0 version of firmware. The first production run of Loops were all programmed with 1.0.0. This issue has been fixed in later versions of the Loop firmware, but we currently do not provide a mass market tool for upgrading firmware. To work around this issue, it is recommended to uninstall the kernel patch when not using libfreespace. Applications that use libfreespace are not affected by the issue.

We understand that some users are concerned that the LGPL 2.1 may require them to distribute their application code if they statically link to libfreespace. This is not the case. We view dynamic and static linking similarly and do not want to inhibit the use of libfreespace on platforms or systems that lack shared library support. A simple guideline is that if you modify or add any source files that are used in making the libfreespace library, the LGPL will apply.

libfreespace uses libusb to communicate with Freespace devices, so it should work on any Linux version that is supported by libusb. We use Linux versions 2.6.15, 2.6.28 and 2.6.29 regularly at Hillcrest. Through testing we have found that unpatched versions of Linux 2.6.28 and Linux 2.6.28.1 do not work. Upgrading or applying this kernel patch fixes the problem.

First, you will either need a relatively new Linux kernel (2.6.30 or later) or a Linux distribution (i.e. Ubuntu 9.04 or later) that has already applied a patch to allow non-root users to access uevents (used by libfreespace to detect insertion and removal of Freespace devices). See this patch for more information. A simple way to check whether you have this patch is to see whether freespace_init() succeeds. All of the sample apps will error out immediately if it does not.

If the examples still don't work, the device files used to communicate over USB probably have root-only permissions. Most likely, your device files are automatically created by udevd. To fix this, add a udev rule. For example, in Ubuntu, you can do this by adding a file called /etc/udev/rules.d/99-local.rules. The contents should contain:

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

1d5a is the USB vendor ID of all Hillcrest Labs' products. If the Freespace technology is embedded in another company's product, it may have a different vendor ID. To check, run the lsusb command.