Introduction

The Oak USB sensor devices are HID class USB device. Most modern operating systems support HID devices out of the box, including Linux. Although Toradex does not provide support for Linux, this page contains some resources that will help you getting started with using your Oak Sensors under Linux.

Sample code

A sample application can be downloaded from the Toradex website : Download The sample code.

This application has been developed on a Intel x86 platform running Ubuntu Linux 8.04. It has also been tested and compiled on the most current Linux distributions: Mandriva One 2009, OpenSuse 11, Fedora 9.

Technical notes

Source code information

The sample application, written in C++, is provided with a classic configure script for easy building. The KDevelop project files are also provided. Source and Header files can be found in the src/ subfolder:

• OakHIDBase.cpp: encapsulation of hiddev calls into more human friendly calls such as readInterruptReport() readFeatureReport(), sendFeatureReport().
• OakFeatureReports.cpp: implementation of generic feature report commands as described in the Toradex Oak Sensors datasheets.
• oaklinux.cpp: The sample application built using the functions defined in OakHIDBase.cpp and OakFeatureReports.cpp

A configuration file for generating automatic documentation using Doxygen for the project is provided.

Requirements

The sample application relies on the hiddev feature of the Linux Kernel, which is present in Linux Kernel 2.6 and above.

The kernel must be compiled with the options HIDRAW and USB_HIDDEV turned on. All tested Linux distributions had these features already turned on in their default kernel, so no recompilation should be required in most cases.

Linux device files

Under Linux, devices are represented as files in the filesystem. When a device is plugged in, a special file is created in the /dev folder or in one of its subfolders (/dev/usb/ in the case of Ubuntu). The name of the folder is of the form hiddev*, where * is a number. The sample application takes one command line argument that is the path of the device you want to use, for instance "oaklinux /dev/usb/hiddev1". You may have other HID devices connected to your computer - mice, keyboards, gaming devices, etc... - The application will tell you if the device you are trying to open is not a Toradex device.

Access right

By default some distributions (Ubuntu) do not grant read/write access to the device for standard users. There are several ways to cope with this issue:

• Run the application as root. This is not recommended.
• Modify access right using chmod with a command such as 'chmod a+rw /dev/usb/hiddev1'. This method works but the modified access rights are lost when you unplug the device.

• Modify the default access rights for hid devices by writing a udev rule. Using root privileges, create a file named 10-toradex.rules in the folder /etc/udev/rules.d and write the following line in this file:

  KERNEL=="hiddev[0-9]*", NAME="usb/%k", MODE="0666" For more information on udev, see this document.

Output devices

Interrupt Out report (useful for output devices such as the Oak Relay - 4 Channel Relay Output Card and Oak IO - 24 Digital Inputs / Outputs are not supported by the hiddev driver.