melizalab/jack_rhd2000

JACK driver for the Intan RHD2000 eval board

jack_rhd2000 is a driver that lets you use an Intan RHD2000 eval board as a data source for the JACK realtime audio toolkit. It is currently under development.

Requirements

• POSIX-compliant operating system
• JACK audio connection kit, version 0.124 (http://jackaudio.org)
• An Intan RHD2000 eval board (http://intantech.com)
• From Intan's download page, the Rhythm C++ API source code (specifically the main.bit file) and the USB drivers for your operating system (specifically libokFrontPanel.so). The last version of the FPGA code tested with this driver was the 130302 release.
• Scons (http://scons.org)

Compilation

To compile the driver, you will need a copy of the JACK source code, specifically the engine headers, which are not installed as part of the JACK development package. Thus, in addition to installing the JACK client headers and libraries, you need to download jack-audio-connection-kit-0.124.1.tar.gz from the JACK website and unpack the tarball in this directory, and create a symbolic link with ln -s jack-audio-connection-kit-0.124.1 jack.

To compile, you'll then run scons -Q

Installation

Rename main.bit to rhythm_130302.bit. Put jack_rhd2000.so, libokFrontPanel.so, and rhythm_130302.bit in the same directory. This can be the directory where the other JACK drivers live.

Usage

JACK_DRIVER_DIR=<driver dir> jackd -d rhd2000

Additional options can be appended to this command to configure the driver:

• -d: specify the serial number of the Opal Kelly device to connect to. By default, the driver will connect to the first device.

• -F: specify the path to the Intan RHD2000 eval board firmware. By default, the driver will look for a file called "rhythm_130302.bit" in the same directory as the driver

• -r: specify the sampling rate, in Hz. Default is 30000 Hz. Only some values are supported by the hardware, so if the requested value is not available the driver will choose the nearest one

• -p: specify the period size, in frames. This option sets the amount of time the driver will wait before pulling data off the driver. Larger values produce more stable behavior, but increase latency.

• -I: configure the driver to leave additional samples in the eval board's FIFO. This increases latency, but may help to reduce buffer overruns.

RHD2000 chips on each of the four SPI ports can be configured with the -A, -B, -C, and -D options. The arguments to these options are a comma-delimited list of up to 5 values. If less than 5 values are supplied, the defaults are used. The values are as follows:

1. A hexadecimal number controlling which amplifiers to power up. According to the Intan documentation, turning off amplifiers can reduce thermal noise. Default is 0xffffffff, which corresponds to 32 1's and turns on all amplifiers. 0xffff would only turn on the first 16.

2. A floating point number to set the highpass filter cutoff frequency, in Hz. Only some values are supported by the hardware, so the driver will choose the closest one if the requested value isn't available. Default is 100 Hz.

3. A floating point number to set the lowpass filter cutoff frequency, in Hz. Default is 3000 Hz.

4. A floating point number to set the highpass filter cutoff of the DSP integrated into the RHD2000 chip. Default is 1 Hz.

5. The SPI cable length, in meters, or 0 to auto-detect any connected chips. Default is to auto-detect.

On startup, the driver will attempt to connect to the Opal Kelly board, upload the firmware, and detect/configure the connected amplifier chips. If no chip is connected to an SPI port, or if '0' is used as the argument to a port's configuration option, the port will be disabled. If these steps are successful, the driver will create JACK ports for each enabled RHD2000 channel and for the eight analog inputs on the eval board.

Building from source

To build the driver from source, you need

• a modern c++ compiler
• the JACK source tree for the currently installed JACK version

The test programs require boost (http://http://www.boost.org; >= 1.42)

License and Warranty

Copyright (c) 2013 C Daniel Meliza. See COPYING for license information.

This Software is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License, version 2, along with this program; if not, see http://www.gnu.org/licenses.

Additional notes

The driver achieves low latency by reading data from the eval board's FIFO as soon as a complete period is available. Due to the long and variable latency of the USB bus, this may take a substantial proportion of the period. Using a linux kernel patched for realtime preemption can greatly reduce the variance of the time it takes to get data off the USB bus, but it's still rate-limited so that a single RHD2000 amp takes 4.2 out of the available 33 ms in a 1024 frame period.

jack_rhd2000's Issues

need to recover voltages from float data

We're wondering if it is possible to recover the voltage data from the floating point data that gets read into jack.

error compiling driver

scons complains about missing driver.h.

kjbrown@sonoftweet:~/src/jack_rhd2000$ scons
scons: Reading SConscript files ...
scons: done reading SConscript files.
scons: Building targets ...
g++ -o driver/jack_rhd2k_driver.os -c -DSERVER_SIDE -fpermissive -Wall -g2 -fPIC -Ilib -Ijack -Ijack/include -Ijack/config driver/jack_rhd2k_driver.cpp
driver/jack_rhd2k_driver.cpp:41:20: fatal error: driver.h: No such file or directory
compilation terminated.
scons: *** [driver/jack_rhd2k_driver.os] Error 1
scons: building terminated because of errors.

32 channel head stage in RHD2000 input B seen as A2

Transferred from melizalab/jill#13:

I have two 32 channel single ended headstages plugged into the RHD2000 eval board. One is plugged into port A, one into port B on the board.

Starting jackd with:

jackd -d rhd2000 -A 0xffffffff,1,15000,1,0

should only activate the 32 channels on port A1, however, 32 more channels show up in A2. See output below. I get the same result if I start jackd with

jackd -d rhd2000 -A 0xffffffff,1,15000,1,0 -B 0xffffffff,1,15000,1,0

output:

jackd 0.122.0
Copyright 2001-2009 Paul Davis, Stephane Letz, Jack O'Quinn, Torben Hohn and others.
jackd comes with ABSOLUTELY NO WARRANTY
This is free software, and you are welcome to redistribute it
under certain conditions; see the file COPYING for details

JACK compiled with System V SHM support.
loading driver ..
RHD2K: initializing driver
opal kelly driver: /home/dmeliza/src/jack_rhd/driver/libokFrontPanel.so
FPGA bitfile: /home/dmeliza/src/jack_rhd/driver/rhythm_130302.bit
RHD2K: scanning SPI ports
RHD2000 Controller:
Opal Kelly Front Panel version: Feb 1 2012 17:18:14
Opal Kelly device ID: Opal Kelly XEM6010
Opal Kelly device serial number: 000000050D2
Opal Kelly device firmware version: 3.1
FPGA frequency: 100 MHz
Rhythm version: 1
Sampling rate: 30000 Hz
FIFO data: 0/67108864 words (0% full)
Analog inputs enabled: 72
MISO lines:
A1: no amplifier connected
A2: no amplifier connected (off)
B1: no amplifier connected
B2: no amplifier connected (off)
C1: no amplifier connected (off)
C2: no amplifier connected (off)
D1: no amplifier connected (off)
D2: no amplifier connected (off)
period = 1024 frames (34.133 ms)
FIFO buffering = 0 frames (0 ms)
RHD2K: attaching driver
RHD2K: scratch buffer size=180224 bytes
RHD2K: registering capture port A1_0 (offset = 24)
RHD2K: registering capture port A1_1 (offset = 28)
RHD2K: registering capture port A1_2 (offset = 32)
RHD2K: registering capture port A1_3 (offset = 36)
RHD2K: registering capture port A1_4 (offset = 40)
RHD2K: registering capture port A1_5 (offset = 44)
RHD2K: registering capture port A1_6 (offset = 48)
RHD2K: registering capture port A1_7 (offset = 52)
RHD2K: registering capture port A1_8 (offset = 56)
RHD2K: registering capture port A1_9 (offset = 60)
RHD2K: registering capture port A1_10 (offset = 64)
RHD2K: registering capture port A1_11 (offset = 68)
RHD2K: registering capture port A1_12 (offset = 72)
RHD2K: registering capture port A1_13 (offset = 76)
RHD2K: registering capture port A1_14 (offset = 80)
RHD2K: registering capture port A1_15 (offset = 84)
RHD2K: registering capture port A1_16 (offset = 88)
RHD2K: registering capture port A1_17 (offset = 92)
RHD2K: registering capture port A1_18 (offset = 96)
RHD2K: registering capture port A1_19 (offset = 100)
RHD2K: registering capture port A1_20 (offset = 104)
RHD2K: registering capture port A1_21 (offset = 108)
RHD2K: registering capture port A1_22 (offset = 112)
RHD2K: registering capture port A1_23 (offset = 116)
RHD2K: registering capture port A1_24 (offset = 120)
RHD2K: registering capture port A1_25 (offset = 124)
RHD2K: registering capture port A1_26 (offset = 128)
RHD2K: registering capture port A1_27 (offset = 132)
RHD2K: registering capture port A1_28 (offset = 136)
RHD2K: registering capture port A1_29 (offset = 140)
RHD2K: registering capture port A1_30 (offset = 144)
RHD2K: registering capture port A1_31 (offset = 148)
RHD2K: registering capture port A2_0 (offset = 26)
RHD2K: registering capture port A2_1 (offset = 30)
RHD2K: registering capture port A2_2 (offset = 34)
RHD2K: registering capture port A2_3 (offset = 38)
RHD2K: registering capture port A2_4 (offset = 42)
RHD2K: registering capture port A2_5 (offset = 46)
RHD2K: registering capture port A2_6 (offset = 50)
RHD2K: registering capture port A2_7 (offset = 54)
RHD2K: registering capture port A2_8 (offset = 58)
RHD2K: registering capture port A2_9 (offset = 62)
RHD2K: registering capture port A2_10 (offset = 66)
RHD2K: registering capture port A2_11 (offset = 70)
RHD2K: registering capture port A2_12 (offset = 74)
RHD2K: registering capture port A2_13 (offset = 78)
RHD2K: registering capture port A2_14 (offset = 82)
RHD2K: registering capture port A2_15 (offset = 86)
RHD2K: registering capture port A2_16 (offset = 90)
RHD2K: registering capture port A2_17 (offset = 94)
RHD2K: registering capture port A2_18 (offset = 98)
RHD2K: registering capture port A2_19 (offset = 102)
RHD2K: registering capture port A2_20 (offset = 106)
RHD2K: registering capture port A2_21 (offset = 110)
RHD2K: registering capture port A2_22 (offset = 114)
RHD2K: registering capture port A2_23 (offset = 118)
RHD2K: registering capture port A2_24 (offset = 122)
RHD2K: registering capture port A2_25 (offset = 126)
RHD2K: registering capture port A2_26 (offset = 130)
RHD2K: registering capture port A2_27 (offset = 134)
RHD2K: registering capture port A2_28 (offset = 138)
RHD2K: registering capture port A2_29 (offset = 142)
RHD2K: registering capture port A2_30 (offset = 146)
RHD2K: registering capture port A2_31 (offset = 150)
RHD2K: registering capture port EV_0 (offset = 156)
RHD2K: registering capture port EV_1 (offset = 158)
RHD2K: registering capture port EV_2 (offset = 160)
RHD2K: registering capture port EV_3 (offset = 162)
RHD2K: registering capture port EV_4 (offset = 164)
RHD2K: registering capture port EV_5 (offset = 166)
RHD2K: registering capture port EV_6 (offset = 168)
RHD2K: registering capture port EV_7 (offset = 170)
RHD2K: latency callback: 1024--1024 frames
RHD2K: starting acquisition