Harvey Lab Mouse VR

Developed by members of the Harvey Lab (http://harveylab.hms.harvard.edu/) and the HMS Research Instrumentation Core (http://instrumentation.hms.harvard.edu/).

Table of Contents

1. Overview
2. Main Components
3. Getting started
4. Build Guide
5. Screen Assembly
6. Ball Cup Assembly
7. Ball Sensor Software
8. Reward system
9. Behavior PCB Overview
10. Software
11. FAQs
12. Appendix

Overview

Main components

Harvey Lab miniaturized mouse VR rig for virtual navigation and decision-making tasks

The VR setup is comprised of several independent assemblies:

1. The screen assembly: a laser projector projects onto a parabolic screen surrounding the mouse. This is the basis for the visual virtual reality.

2. Ball cup assembly: an air-supported 8" styrofoam ball that the mouse can run on, with associated ball cup, sensors, and electronics

3. Reward delivery system and lick sensor: lick spout, liquid reward reservoir, solenoid, and associated electronics

4. Enclosure: A box surrounding the behavioral setup.

Each of these components is independent of the others: i.e. just the screen could be used in combination with a different treadmill and reward delivery system. The electronics for the ball sensors, reward delivery, and lick detection are all mounted on the same PCB. If only one or two of these functions are needed, you do not need to populate the entire PCB.

The screen assembly is designed to be small enough to be mounted within a standard 19" server rack, which could easily fit 3 rigs stacked vertically (or two + monitor and keyboard station).

Screen and ball cup assemblies:

Getting started

All the parts for the assemblies are listed in this google sheet: https://docs.google.com/spreadsheets/d/1hkXaeRBd7GJPuhIFjeKkEIziQik9mlkZpzjhxGrkA7A/edit?usp=sharing

The build guide (below) contains detailed schematics of the various assemblies, as well as additional notes about part requirements and alternative parts.

Getting help

Open an issue or email Noah.

Build Guide

Projector

Update 2021-02-18:

This back projection screen assembly was originally designed for use with the Celluon Picobit laser projector (released in 2016). This projector (along with our recommended alternative laser projectors) has been discontinued and Celluon no longer produces laser projectors. The advantage of laser projectors is that they can project onto a curved surfaces with the image in focus across the entire surface. We can no longer recommend these however due to their inavailability.

We now recommend using the Texas instruments LightCrafter DLP 3010 EVM: https://www.ti.com/tool/DLPDLCR3010EVM-G2. The DLP 2010 may also work. Both will require some modifications to the mirror positioning - we will update the designs accordingly in the future (once I am back in lab to test) but get in touch if you need advice.

The LightCrafters will be supported for longer than typical consumer projectors, have greater programmability, and have some some nice user features such as the ability to easily display calibration images and independently shut off Red green and blue LEDs in the software, which could be great for imaging applications - getting rid of that hard-to-block red light without a filter. Some groups have also added LEDs of desired wavelength - for example UV (this was using DLP3010). They also have fairly low input lag: from coarse tests it appears to be comparable to a standard dell desktop monitor (5-15 ms), although if this is important for you please conduct your own tests.

The differences in focus across the screen are fairly subtle even to the human eye, so we do not expect this to impact visually-guided navigation or studies of mouse visual responses. Please see appendix for pictures of a modified screen assembly used with a DLP3010 (Oleksandr Radomskyi, Santiagio Rompani Group, EMBL, Rome).

Thanks to Oleksandr Radomskyi and Santiagio Rompani for sharing information about using Lightcrafters with these designs.

OLD INFO - see update above:

The projector should be a laser projector so that the image is in focus across the entire curvature of the screen. In terms of laser projectors compatible with this design, we like the Celluon PicoPro, Celluon PicoBit, or the LaserBeamPro (in that order of preference). The LaserBeamPro can exhibit burn-in. Avoid the Sony portable laser projector due to lag. The projector throw ratio matters: get one with 1.4:1 (pretty standard for the small laser projectors). Projectors with greater divergence will work as well. Get a projector that projects straight out i.e. the light for the horizontal center line of the projected image should be at the same elevation as the body of the projector. Some projectors (especially short throw) are designed to project upwards from a table or desk, this will not work with the setup.

If you wish to use DLP projectors, we've done some basic testing of them but have not trained mice with them. The image is slightly out of focus in certain places, but it is not a serious issue. The main issue with DLP projectors is that most do not project straight out of the projector - they project slightly upwards with build in keystone correction. This has two main effects. First, the projector will need to be mounted at a slight angle relative to the top piece of the VR setup (ask Noah if this isn't clear). Second, due to the keystone correct and the angle of mounting, the transformation functions will need to be adjusted appropriately within whatever VR software you are using (if you wish to know exactly where on the screen things are being displayed).

Note that the laser cut mount for the projector included in these designs is specifically for the PicoBit. It will also work with the PicoPro and laser beam pro if you remove the top "alignment" piece and stick the projector to the bottom piece using double sided tape or velcro (the height and geometry works, you will just need to center the image by eye when you stick down the projector).

If you want to test out a DLP projection with this design, this projector: https://www.amazon.com/dp/B078PC1QS5/ref=sspa_dk_detail_5?psc=1 has the right throw. I'm not sure if it projectes straight out from the projector or slightly upwards. Parts of the projected image will be out of focus due to projecting onto a curved surface, but this might not be so bad for the mouse. If you do try it, let us know how it works!

Screen Assembly

Parts list and notes

The parts are listed in the "screen assembly" section of the parts list google doc: https://docs.google.com/spreadsheets/d/1hkXaeRBd7GJPuhIFjeKkEIziQik9mlkZpzjhxGrkA7A/edit?usp=sharing

Mirrors

These should be approximately 1/4" thick and first surface if possible. Non first surface mirrors will result in some double image "ghosting" but otherwise will work with the design. Acrylic mirrors can be used to save money and time - these can easily be laser cut. Note that acrylic mirrors typically do not have surfaces as smooth as glass and the projected image may appear textured as a result.

Rails, brackets, and t-nuts

McMaster or Thorlabs or any other 80-20 style rail materials should work. Note that Mcmaster t-nuts / fasteners are not compatible with thorlabs rails as they have slightly different slot dimensions. Thorlabs t-nuts are compatible with McMaster t-slotted framing. Only the 15" Horizontal rails need to be 1/4-20 end tapped.

Acrylic

Any 1/4" acrylic that can be easily laser cut should work fine. It does not need to be matte or black. Opaque acrylic is best to block stray light. Stray light and reflections can also be blocked on any type of acylic using pieces of the black flocked self adhesive paper

Part Preparation

These steps will take approximately one hour.

For part preparation you will need the following equipment:

• Power drill

• 1/4-20 thread cutting tap

• Laser cutter with at least 12 x 24" bead, power to cut through 1/4 inch acrylic. (There are online services that will do this cutting for you if you don't have access to a laser cutter. We've been quoted around $400 for cutting these designs, although there may be cheaper options).

Steps: 1. Laser cut the parts. The file you should need is https://github.com/HarveyLab/mouseVR/blob/master/Hardware/BackProjection/vrRig_laserCutter_allParts.pdf. The scale in the document should be 1:1, inch units, but a small 1x1" scale square is included. Ensure that it is 1" on each side, and scale parts uniformly if necessary. Arrange the parts for cutting. eg, for cutting on two 18 x 32" pieces of acrylic:

2. Tap holes in the laser cut parts. All round holes in the laser cut parts are either 0.26" through holes, or 0.2-0.21 holes that should be 1/4-20 tapped. It is safe to assume that if a 1/4-20 screw does not fit through it, it should be tapped. Refer to the parts drawings if you are unsure. Don’t worry about tapping perfectly perpendicular to the face of the acrylic - we use a hand drill and eyeball it and that works fine for us. Use a blade to clear out waste acrylic from the parabola-shaped screen slots in the top and bottom pieces.

3. Cut screen film to size: Using a ruler and a pair of scissors, cut out a rectangular piece that is approximately 21.3 x 12 inches.

4. If using McMaster rails or 80-20 that needs to be cut to length, cut 4 pieces 18" in length for the legs, and 2 pieces 15" in length for the cross braces. Hand tap the ends of 15" pieces with the 1/4-20 thread cutting tap.

5. If using self-adhesive black flocked paper, cut two ~ 7.5 x 4" pieces.

Assembly

Assembly takes approximately one hour.

Refer to the figure below for a visual guide.

Steps:

1. Add corner brackets to the bottom piece. Place the bottom piece (parabolic screen slot, no holes or cutout in center) flat on the table and screw four 1" brackets into it as illustrated using 3/8"-long low profile screws.

2. Attach sides using the 1" brackets and 3/8"-long low profile screws. The long flat edges of the sides should be on the bottom. Stick the cut black-flocked paper / felt pieces to the inside of the sides closest to the screen. Attach four more 1" brackets as illustrated.

3. Attach top piece. Screw into place from the inside using the 1" brackets and 3/8"-long low profile screws.

4. Assemble the projector mount. To make sure that you aren’t messing it up, screw the projector onto the larger of the two pieces using a 3/8"-long 1/4-20 screw through the center hole in the base mount into the threaded hole on the bottom of the projector. Make sure it is in the orientation such that the fan on the bottom of the projector is fully visible through the cutout in the acrylic (you may need to flip the acrylic base over). Screw the top piece of the mount into place as illustrated and then attach the entire thing to the screen assembly using 1/2" (or longer) 1/4-20 screws.

5. Join the two sides with the end-tapped 15" rails. Ensure that you are using the right holes and not the holes reserved for the legs (arranged in vertical pairs 1" apart).

6. Flip the assembly over. Insert each leg into place, attaching it to the inside of the assembly using t-nuts or fasteners (see this note). Set the height of the screen by adjusting the length that each leg sticks out of the box. Attach the right angle brackets to the base of each leg using t-nuts /fasteners.

7. Repeat for all four legs. Use a ruler or measuring tape to ensure that all legs are the same height.

8. If using the acrylic base, attach to the right angle brackets using 3/8"-long low profile screws. The part of the base that connects the two sides should be at the back of the assembly, away from the screen.

9. Flip the assembly upright. If you are assembling in its final position, bolt the screen assembly down to a breadboard or air table and insert the two mirrors. Put tape of pieces of black flocked adhesive paper over the openings in the sides to prevent the mirrors from slipping out. CRITICAL STEP: the glass first surface mirrors come with a blue protective film on the coated side. Remove this film and ensure that the coated side ("first surface") is facing towards the screen. Both sides will appear reflective but only one side has the reflective coating. If you plan on moving the assembly, skip this step and insert the mirrors once it is in its final position.

10. Slide the screen into the parabola-shaped slots. If it does not fit, there may be waste acrylic stuck in these slots - this can be easily removed with a box cutter or other blade. cutting a slight V into one of the horizontal edges of the screen can help with insertion. Once the screen is in place, use binder clips, tape, or glue along the top edge to secure it. Trim away excess screen. We also often apply black tape along the vertical edges of the screen to stick it to the sides of the box and block out stray light from the projector.

Ball cup assembly

Parts list and notes

The parts are listed in the "screen assembly" section of the parts list google doc: https://docs.google.com/spreadsheets/d/1hkXaeRBd7GJPuhIFjeKkEIziQik9mlkZpzjhxGrkA7A/edit?usp=sharing

3D printed ball cup

The ball cup (https://github.com/HarveyLab/mouseVR/blob/master/Hardware/BallCupAssembly/harvey_ballCup_ADNS9800_Vers1_1.ipt) should ideally be printed from a strong plastic that has good chemical resistance and can be easily cleaned.

We get ours 3D printed by 3Dsystems using the follow specifications:

Process: Selective Laser Sintering (SLS)

Part: https://github.com/HarveyLab/mouseVR/blob/master/Hardware/BallCupAssembly/harvey_ballCup_ADNS9800_Vers1_1.ipt

Material: Glass-filled Nylon (Duraform GF)

Finish: Standard (Coated). Liquid proof entire part with cyanacrylate. Inside of the cup should eb extra smooth.

Unit price: ~800 USD (prices vary depending on quantity).

These are expensive but work very reliably in our hadns, can be easily cleaned, and have never needed to be replaced even after years of use.

If you do wish to use a cheaper material and/or printing technology, rigidity - specifically resistance to warping over time - is the most important material charachteristic. My guess is that ABS or a stiff nylon would work. Good chemical resistivity is recommended but not absolutely required. It is good practice to clean the ball cup regularly. Most prosumer or professional FDM, SLA, or SLS 3D printers should provide sufficient resultion for this part. The inside of the ball cup should be as smooth as possible, so lower quality printers may work as well together with some post processing such as sanding or solvent smoothing on the inside of the cup.

See FAQs for more details.

3D printed ball cup base

The ball cup base (https://github.com/HarveyLab/mouseVR/blob/master/Hardware/BallCupAssembly/low_profile_noiseAttachment.ipt) does not require as tight tolerances, surface finish, or chemical resistance. We get ours printed in house and probably any material is fine.

Styrofoam ball

The ball cup is designed for an 8" stryrofoam ball. You can buy these on amazon or at most craft stores, but the tolerances will not be great. https://www.wecutfoam.com/ may offer slightly higher quality balls. We lathe our our 8" balls from open cell styrofoam blocks.

Hardware Assembly

Follow these steps to assemble the sensors:

1. Sand down the back of a blue connector so that it fits into the sensor board in the orientation shown in the picture below (notch in blue plastic should face away from center of board).

2. Solder the connector onto the board

3. Attach the plastic lens to the sensor board with epoxy. Apply epoxy only to the back of the board, where the small pins of the lens assembly protrude through the holes in the board. While the epoxy hardens, place the sensor lens-down on a flat surface to ensure that the lens assembly is seated correctly.

4. Use a 2-56 tap to tap the screw holes in the ball cup. Alternately, just use a 2-56 screw to self-tap.

5. Put the sensors into the holes in the ball cup (oriented such that the connector pins fit into the cutaway next to the sensor hole). Make sure that the sensor "slots in" all the way and sits flush with the ball cup. Any failure to make the sensor completely flat/tangent to cup surface will lead to erroneous measurements. Fix in place with the screws.

6. Make ribbon cables to attach the sensors to the board. Do this by cutting lengths of ribbon cable and press fitting the connectors into the ribbon cable using a vice. Secure both sides of the connectors with the included clips. Make sure that the orientation of the connectors with respect to the colored edge of the cable is the same on both ends. Double check with a multimeter.

7. In the the base, file down a small notch for the ribbon cable to exit along the edge where the cup and base meet.

8. Orient the ball cup so that one sensor is behind the mouse (it doesn’t really matter which axis is which but it is good to be consistent across rigs).

9. Screw the thorlabs posts and post holders in place on either side of the base, and bolt down the ball using 8-32 screws. Adjust the height of the posts so that the ball cup sits firm and snug on the base. Once you've tested everything, you can put a piece of electrical tape around the seam to make it more air-tight.

10. Attach the air supply. Screw the duct hose fittings onto each end of the duct hose. Place the rubber stopper into one duct hose fitting and slide the other duct hose fitting onto the attachment point in the base (it should fit tightly). Connect the rubber stopper end of the duct hose to pressurized air using 1/4" tubing. It can be useful to have a pressure gauge & regulator between the wall air and the duct hose, as well as an air filter. You should have at least 4 feet of duct hose in order for the ball to float properly. Add more duct hose to dampen the sound.

11. Populate the the behavior circuit board. Refer to the behavior PCB section of the guide. At the very least, you need the teensy and the ribbon cable headers. If you want an analog ball signal (as opposed to reading it directly from the teensy) you will also need the RC smoothing circuit (smoothing PWM output of the teensy) and whatever header(s) you will use to read that out (National instruments or BNC).

.

Ball sensor software

1. Download this repo (all files required): https://github.com/HarveyLab/SPI_Mouse_Control/tree/master

2. Install the Arduino IDE and Teensyduino. Note that software will not work for all versions of Arduino IDE and Teensyduino (confirmed does not work with latest arduino/teensyduino as of April 2018 - it will compile and run but give erroneous output). An installer for verified working versions (Arduino 1.8.2, Teensyduino 1.36) is located here: https://github.com/HarveyLab/mouseVR/tree/master/Software/BallSensor. It is highly recommended you use these versions.

3. Connect the teensy via USB, and make sure you can identify it in the arduino software. If you are unsure at this step, read documentation and/or use trial code available from teensyduino (documentation: https://www.pjrc.com/teensy/td_usage.html)

4. Locate the debugMode.ino file in the repo (in dual-sensor) and open it. Be sure the 'ADNS9800_SROM' file is in the same folder (i.e. don't change the location of these files from how it is in repo).

5. Open the serial monitor (be sure to monitor the com port your teensy is using), and then verify/upload the code

6. As the teensy reboots, it will print information over the serial port. Verify that the 'Product ID' for both chip 1 and chip 2 is 0x33 (hexadecimal) or 51 (decimal). See images of expected output, below. If it is not, there is a low-level problem with teensy to sensor communication, usually due to incorrect wiring: immediately unplug teensy from USB to prevent sensor burn-out and review entire wiring setup to be sure pin/cable orientation is not accidentally flipped. If correct product ID is observed, proceed...

7. After booting up, the teensy will continue to live-print various information over the serial port, including the Product ID (should be constant, indicates if connection is valid), a temporally-integrated measure of velocity on pitch, roll, and yaw axes, and indicators of the image quality received by both sensors ('Squal' 1 & 2, see ADNS9800 manual included in repo for more information).

8. Verify by rotating the ball that the correct axis of rotation is inferred from the sensor (errors here usually indicate accidentally swapping Chip 1 & 2), and that the image quality from both sensors is reasonable and of similar level.

9. Once debugging is complete, locate and open the quietOp.ino file from the dual-sensor folder of repo, and verify/upload the code as before. This code will print out information over the serial port at chip boot-up only, and is preferred for running the circuit when not actively debugging. Once this code has been uploaded and the chip has rebooted the first time, the teensy will automatically re-load this program whenever it is dis-/re-connected from a power source.

Note, the discretization-resolution of the sensors can be controlled by modifying lines 116 & 121 of quietOp.ino. This involves a trade-off between the dynamic range of the PWM-channel and the smallest-detectable movement, and is set to default at 0x10 (range 0x01 - 0x29). Be sure any modification is applied to both chips equally, or rotational axes will no longer be properly de-mixed.

Expected output from debugMode.ino upon startup:

Example expected output of debugMode.ino for stationary ball:

intP,R,and Y are the pitch, roll, and yaw values.

Reward system

Lick detection circuit

Behavior PCB Overview

The behavior PCB has the circutry to monitor two lick inputs (for example if using lick left / lick right setup), control two independent solenoid valves for dispensing liquid reward, and interface with ball movement sensors.

You can read sensors and control valves using (a) the teensy directly (with serial communication) (b) a USB-3001 NIDAQ plugged into the board (c) some combination of the teensy and the NIDAQ.

Options for reading in licks:

1. Read in licks as an analog signal exactly like the ball signal. Note you may miss licks this way if your sampling rate is low.
2. Attach the lick output to a counter channel on your DAQ & read the counter channel (not sure if these boards are capable of having counter channels or not) http://www.ni.com/academic/students/learn-daq/digital/
3. Set up a counter on the teensy and read directly from the teensy using serial communication

Options for controlling reward valve:

1. Control using the DAQ analog output (User 3 and/or 4). Set duration of valve opening in your matlab code (e.e. write a giveReward function). You wil need to install jumpers (see fig below) if you haven't already.
2. Control using teensy triggered by DAQ (User 3 and/or 4, always accesible to teensy, even w/out jumpers present)
3. Control using teensy triggered by serial communication

NIDAQ connections

Getting started

The parts are listed in the "behavior electronics" section of the parts list google doc: https://docs.google.com/spreadsheets/d/1hkXaeRBd7GJPuhIFjeKkEIziQik9mlkZpzjhxGrkA7A/edit?usp=sharing

The files to get the circuit board printed are in https://github.com/HarveyLab/mouseVR/tree/master/BehaviorElectronics/HarveyBehaviorPCB_v1.2 We use 4pcb.com

The top will be screen printed with parts codes that you can look up in the bill of materials here: https://github.com/HarveyLab/mouseVR/blob/master/BehaviorElectronics/HarveyBehaviorPCB_v1.2_BOM.xlsx

Also refer to the board schematic here: https://github.com/HarveyLab/mouseVR/blob/master/BehaviorElectronics/HarveyBehaviorPCB_v1.2.pdf

Final board should look like this:

VR rig details

Mouse positioning relative to the screen: You can place the mouse further back to allow for more room for equipment and this seems to be fine for behavior.

Very approximate visual field coverage with the placement of the mouse as above:

Software

ViRMEn transformation functions

We use the ViRMEn virtual reality engine: https://pni.princeton.edu/pni-software-tools/virmen.

https://github.com/HarveyLab/mouseVR/blob/master/Software/Virmen/transformations/fliptransformCyl_NPparab.m Is an example of a ViRMEn transformation function that works reasonably well with this setup. It isn't the most accurate but looks fairly good to me and I've had good mouse behavior. Some people have approximated the parabola as a cylinder which can speed things up. If you're doing something that requires knowing exactly where in the visual field something is presented, don't rely on this function.

FAQs

What are the computer hardware requirements?

The projector is driven simply as another monitor, so this really depends on the VR software that you are using and the complexity of the worlds that you need to render. Consult the documentation for whatever visual stimulus or VR software you are using: Our computers use GTX 1060 cards (https://www.amazon.com/GR8-II-T044Z-Desktop-i5-7400-GeForce/dp/B06WLHT15C is one model we have used successfully) but this is overkill for most of the worlds we render. Integrated graphics are a bad idea and will likely result in <60FPS. For ViRMEn we suggest at least a 3.00GHz CPU and 8GB of RAM.

What are the pros and cons of using this setup over multiple monitors?

The pros (+) and cons (-) of multiple monitors:

(+) slightly better availability and choice of different screen types and resolutions. may be better if you care about precise visual stimulus timing as gaming monitors are available w/ high frame rates and low input lag.

(+) Potential to be more compact (although this design is already very compact).

(-) Requires either better graphics card to drive 3+ monitors or additional hardware such as "triple head-to-go" (which may complicate transformation functions and introduce lag - you'd need to test).

(-) Bezels: not a big deal for navigation stuff, but does disrupt things like whole-field optic flow, visual RF mapping in same experiment, etc. May be less immersive.

(-) May be harder to correct for illumination across visual field as that can vary w/ angle that the mouse is seeing the screen from.

(-) Less flexible configuration - with our design you can cut holes, notches, slots into any part of the screen etc to fit optics, microscopes, cameras, etc. You can easily resize the screen and adjust design. We have found this to be very useful.

The projector also has the advantage that it's easy to apply filters to the output of the projector. For example: dimming the brightness uniformly with an ND filter, or applying a short-pass filter to attenuate hard-to-light-block red wavelengths (that the mouse can't see anyway) during imaging experiments.

We have used both a 3 monitor setup and this design and have not found a difference in terms of behavior.

Many of these parts are expensive for our lab - are there cheaper alternatives?

In many cases there are cheaper alternatives. Some of these are listed in the parts list.

For example:

Ball cup: May be printed with cheaper materials / quality than the quote listed. We have not explored this. See ball cup section in this guide for more details.

Projector: Low resolution DLP mini projectors are very cheap! Using different projectors may require some small modifications to the hardware. See projector section for more details.

Thorlabs: most of these parts can be replaced with equivalents from McMaster, 80-20, amazon, etc.

First surface mirrors: First surface mirrored acrylic is also available for much cheaper and can be laser cut. There will be a slight textured look to the projected image (due to surface not being as flat) but it is subtle and I'm pretty sure it wouldn't influence behavior.

Acrylic: There are cheaper sources than Canal Plastics for the acrylic. It does not need to have high thickness tolerances and it does not need to be black - any color will work.

I want to use metric screws / hardware - are these deisgns compatible?

We haven't tested this but it should be! Use M6 screws / taps in place of 1/4-20. Please let us know if this works! Everything was desinged in inches, so if units appear undefined for a particular drawing, please assume inches.

How do I order the behavior PCBs

We use 4pcb.com $33 per board special: https://www.4pcb.com/pcb-prototype-2-4-layer-boards-specials.html

1. Select 2 layer, 5 day turn

2. Sign into your account (or create one)

3. Step 1 of 4: upload files. Upload the .zip file in https://github.com/HarveyLab/mouseVR/tree/master/BehaviorElectronics

4. Part#: HarveyBehaviorPCB_v1 Rev#: 1.2 X dim(in): 8 Y dim(in) 4.95 Soldermask: both side silkscreen: top side layers: 2 Quantity: 10 (or whatever you want > 3) Multiple Images: No Ship methoid: your choice ITAR: No

5. Enter shipping and billing info

6. Comments: STUDENT

How do you calibrate the ball sensors?

First, make sure that the sensors are oriented the same way as we have them and offset by 90 degrees in yaw. Make sure that the sensor sits flush with the ball cup. Any failure to make the sensor completely flat/tangent to cup surface will lead to erroneous measurements. Note that the part of the sensor chip with the ribbon cable socket should be towards the top of the ball! See the ball cup assembly section of the guide for more info.

The teensy outputs velocity signals for pitch, roll, and yaw in arbitrary units. The magnitude of these readings can vary depending on a bunch of different things including (I think) the distance of the ball from the sensors. It is recommended that you somewhat regularly check calibration since the styrofoam balls naturally wear down over time and this change in size can influence the readings. It shouldn't drift by a huge amount, but better to be safe.

Calibration is very simple and we do it regularly. Hook everything up, set up your VR software and movement function, and rotate the ball by a set amount in pitch, roll, or yaw. Pitch corresponds to forward running and we typically use roll for either lateral or view angle changes. After rotating by a set amount (for example, 2 ball rotations), note the distance travelled in the virtual environment (either in view angle degrees or translational movement). Knowing the circumference of the ball (~63.8 cm), you can set gain(s) in your vr software appropriately such that you have a certain number of vr_units per cm.

What factors are important for mouse positioning relative to the ball and the screen?

Note that positioning on the ball and relative to the screen can be thought of as pretty much independent of each other. If you want to change the positioning relative to the screen i'd recommend moving the ball cup assembly, and not repositining the mouse relative to the ball. More about the factors that go into the positioning:

1. Positioning on the ball. This positioning has been optimized in the early days of Chris's lab for good mouse behavior and ball control. For tasks in which the mouse needs to turn/steer, we typically use roll for side-to-side translation or view angle and pitch for forward movement. If the mouse is sitting towards the top of the ball it will often result in the mouse spinning the ball mostly in yaw (it may be hard to imagine this but once you have a mouse on the ball you'll see what I mean). Placing the mouse further back on the ball increases rotation in pitch and encourages forward running. I believe steering is also aided by this slightly further-back position. If your task requires turning or steering I'd recommend starting with this position and adjusting from there. If you are just using a linear track & a yaw/roll blocker then the ball becomes a treadmill and positioning is not quite as important.

2. Positioning relative to the screen. One factor to consider here is the focal distance of the mouse's vision. Everything beyond about 5 inches is in focus for the mouse (reference?). I'm not sure how detrimental it would be to have parts of the screen closer than this and thus out of focus. We discussed increasing the peripheral coverage when designing the VR and decided that it wasn't worth it for what we use it for. 210 deg of visual coverage is fine for behavior and we get nice place cells with it as well. If you decide to move the ball closer to the screen, you may want to create a small cutout in the bottom of the screen so that the ball doesn't hit into it, or just raise the screen by a bit.

Troubleshooting

Appendix

Part drawings / dimensions:

Screen assembly

Modified screen assembly with Texas Instruments DLP3010

From Oleksandr Radomskyi, Santiagio Rompani Group, EMBL, Rome

Ball cup

Ball cup base

Enclosure

Slide out

low profile drawer slides mounted with laser cut acrylic for pulling the ball cup assembly away from the screen in order to more easily mount the mouse and access the ball cup for cleaning. Slides should not be used with ephys or imaging due to instability and vibrations.

Contributors: Noah Pettit, Matthias Minderer, Selmaan Chettih, Charlotte Arlt, Jim Bohnslav, Pavel Gorelick, Ofer Mazor, Christopher Harvey.