embedded operant control system
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
drivers work on documentation Mar 20, 2015



A Beaglebone Black cape for controlling auditory operant experiments. The cape has 9 low-power outputs, 3 high-power outputs


  • board : Eagle schematics and board diagrams for cape and auxiliary boards
  • gerber : gerber files for most recent revision of the board, ready to be printed
  • bom : parts you need
  • dts : BeagleBone Black device tree files and eeprom data
  • datasheets : datasheets for all parts
  • sketchup : sketchup for parts to hold beam-break detectors and cue LED
  • drivers : patches to add audio support to the linux kernel

Getting started

If you already have a working Beaglebone Black (BBB), an assembled cape, and μSD card with the software pre-installed, you should be able to get started fairly quickly. First make sure you can boot off the μSD card. Plug the card in the slot, then hold down the button near the slot while plugging in the BBB. You'll know that the computer booted off the card because the heartbeat LED (right under "USER LEDS") will not be flashing. You should be able to connect to the BBB over the USB cable, and the hostname will be arm (you can change this later).

Power down the BBB, unplug it, and plug the starboard cape into the BBB's headers, taking care to align the pins and seat them firmly.

CRITICAL: you will see that you now have two power connectors. One is on the BBB and takes 5VDC; the one on the starboard cape takes 12VDC. DO NOT MIX THESE UP: 12V in the 5V connector will destroy the BBB. You can power the BBB and some of the functions of the cape from a 5V adapter, but in normal operation you should power the cape and the attached peripherals with a 12V, 5A adapter (see the BOM).

Now power the BBB back up. You should see the four indicator lights in the center of the cape light dimly at first and then extinguish, indicating that the headers pins have been configured correctly. You're now ready to go.

Interacting with peripherals

If you're using decide to run operant experiments, you don't need to worry about how the inputs and outputs are accessed through Linux, but if you want to test things out or learn more about the internals, this section is for you.

Low-power outputs

The starboard has 9 low-power (50 mA) outputs suitable for driving cue LEDs. The connectors for these outputs are on the left side of the board, near the DIP switch. Each connector is intended to go to a 3-color LED, but in point of fact these lines can be used to control any device that operates at 3.3V and draws no more than 50 mA. The outputs are given symbolic names and can be manipulated using files under /sys/class/leds. Each line appears as a subdirectory with a name like starboard:left:red that indicates the intended position and color of the cue light. These names also correspond to the text on the cape: CCUE indicates the center cue. The four pins in the connector correspond to red, green, blue, and the common 3.3V supply. Consult the schematics for more information on how these outputs operate.

You can manipulate the outputs by writing to files. For example, to turn on the center green cue, run echo 1 > /sys/class/leds/starboard\:center\:green/brightness. Echo 0 into the same file to turn the LED off. You can also set up the output to flash at specified intervals or generate events of fixed duration by writing different values to the trigger file.

High-power outputs

The starboard also has 3 high-power outputs that operate at 12VDC and up to 6A (limited by the power supply). These outputs are intended to run house lights, motors, and solenoids. These also use the gpio-led driver and can be activated using the same syntax as the low-power outputs.

The starboard::lights output uses PWM, which allows its brightness to be changed incrementally. The frequency is set much higher than the fusion frequency for birds or humans; brightness is controlled by manipulating the duty cycle. This is straightforward: echo 128 > /sys/class/leds/starboard\:\:lights/brightness for half power. 0 is off and 255 is full power.


There are four inputs that can be used to detect instrumental responses. These lines are monitored by the Linux kernel as if they were keyboards. Two input devices are created, one for the response keys (/dev/input/event2) and the other for the hopper up detector (/dev/input/event1). You can test the inputs by running evtest on either one of the files. When the center pin of the switch is grounded, you should see a key down event.


Cape and breakout boards

You can obtain printed circuit boards from a number of fabrication companies. We recommend OSHpark for small runs. Simply zip the gerber files with the same base name together and upload to OSHpark. You may also be able to find some of the designs shared on that site.

PCB assembly is relatively straightforward. You can reflow SMD components with an oven or a lab hot plate. Headers and pin connectors have to be hand-soldered.

Response detectors

Four GPIOs are configured to detect instrumental responses using switches or infra-red beam-break detectors. In the former case, the switch should be a single-pole, single-throw that closes the connection between board pin 3 and board pin 4 or 5 (ground). For a beam-break detector, power needs to be delivered to a 5 mW IR LED (see BOM) and an integrated photologic detector. The output pins should be connected as follows (colors refer to wires in standard telephone wire, a cheap option for making these connections):

| Board Pin | Wire | Signal | Connect to | |-----------+--------+----------------------+-------------------------------------| | 1 | yellow | +5V | OPL820 +5V (pin nearest tab) | | 2 | green | +5V, current-limited | OP133 anode (pin connected to case) | | 3 | red | detector out | OPL820 middle pin | | 4 | black | GND | OPL820 GND (furthest from tab) | | 5 | white | GND | OP133 cathode (pin nearest tab) |


Suggested connections. Note that the red and blue wires cross between the cape and the breakout board.

| Board Pin | Wire | Signal | Breakout board pin | |-----------+-------+-----------+--------------------| | 1 | black | GND | + | | 2 | blue | blue LED | b | | 3 | green | green LED | g | | 4 | red | red LED | r |