DISCLAIMER

If you’re reading this, a warning: this system is NOT plug-and-play. Unsurprisingly, manipulating light to specific photon counts using physical actuators is a tricky business. Even if you’re familiar with Raspberry Pi programming, it would be good to familiarize yourself (or engage someone who is familiar) with light system setup before starting this process. If you’re familiar with the light stimulus component but not the Raspberry Pi, I’d recommend making sure you can get the Raspberry Pi functional before buying equipment specific to this setup--it’s easily the cheapest component.

All this to say that this system is complex and composed of expensive components (as all traditional ERG systems are), and it may be worthwhile to work piecemeal and verify you can get each component off the ground as you go if cost is a concern. If you’d like a consultation at any point, contact me at luke.t.havens@gmail.com.

Last thing: I’m providing this open-source how-to without any guarantees, warranty, or assumed liability. Like I said, the consistent manipulation of light to specific photon counts is a tricky business--you assume all attendant liability when attempting it yourself.

/DISCLAIMER

SYSTEM SETUP -- EASIER METHOD

If you can locate ALL of the same components described in the JCPA paper, then you may be able to recapitulate the system described with minimal programming. As described above, this is still not plug-and-play--you will have to spend a great deal of time aligning system components and the like, which I do not describe in great detail. 

RASPBERRY PI

Load the raspberry pi image onto a microSD card and startup on a Raspberry Pi 3 B+. Connect all the USB components you have on hand--these may only be identified on startup. The RasPi should launch into the command line and automatically run the automation program for the system. If at any point you need to restart the automation control from the command line, use the command ‘launch.sh’. To launch the desktop, you can use the ‘startx’ command.

Once on the desktop, you can test whichever peripheral components you like by opening the ‘automation_program’ folder on the desktop. NEVER CHANGE THIS FOLDER NAME--THIS IS THE FOLDER REFERENCED IN THE AUTOSTARTUP SCRIPT. From here, verify peripherals are working by running their associated commands. See AUTOMATION PROGRAM FOLDER DESCRIPTION at end of this document for guidance on what programs do.

Regardless of how well you match components, you will have to align the neutral density (ND) filter wheels. If you use the exact same components, you may only have to modify the angle offset parameter and motor id number. Both of these values are in the respective filter libraries (bandpass and monochromator). The best test of alignment is whether the ND filters effectively balance light output, but as a first pass you should set the angle offset of each motor so that 0 degrees is at the edge of the non-filtered range of the variable ND filter. IF FILTER WHEELS DON’T MATCH, you will have to measure appropriate optical density slopes and low angle optical density values and replace those in filter_wheel_motor_control.py.

As a last setup step, you must set up communication between the RasPi and daq board, bandpass shutter, and (optional) piezo. If completely recapitulating my system, you will have to wire the appropriate bits of a PowerLab digital output/input to the appropriate RasPi pins. You will also have to wire the bandpass shutter trip wire (and optional piezo) to appropriate pins. You can find the pins used as communication output and input channels, as well as piezo and bandpass shutter channels in GPIO_daq_board_comm.py.

/RASPBERRY PI

POWERLAB

Assuming you wire the appropriate bits together in the last step of setting the RasPi up, the only remaining external feature to connect (other than amplifier) is to the high-speed shutter control via channel one analog out. 

Beyond this, troubleshoot whether communication between the RasPi and daq board is going smoothly by passing single bits back and forth. Alternatively, it is straightforward to set single bits of the digital out to particular values or read single digital in values in LabChart.

Otherwise, all you should have to do is load the LabChart file and copy it any time you want to run an experiment or open a new file with that file as the template. This will give you access to all the macros written for communication with the RasPi. 

/POWERLAB

/SYSTEM SETUP -- EASIER METHOD

SYSTEM SETUP -- HARDER METHOD

You caught me--this is coming soon. I will update this with a general guide on how to approach setting up the system with new components (RasPi 4, different daq board, etc). But as a general rule, if you’re not sure where you’d begin, proceed with extreme caution. To maintain functionality with minimal disruption, you’ll have to replace components one-to-one. The code library is designed to make this possible, but it’s not trivial.

As a quick signpost for common issues: you can use different serial adapters, but you’ll have to change the usb-serial-rules file to appropriately permanently identify them. The Raspberry Pi 3 uses a virtual usb bus, meaning that no port has a static identifier, and you have to identify serial adapters by their serial number/name, not the port they use. If you use a Raspberry Pi 4, you’re opening a whole other can of worms--it should work, but you’ll have to define your own usb-serial-rules, /launch.sh script, and crontab (or other on-startup method) for auto-running the automation program. 

/SYSTEM SETUP -- HARDER METHOD

AUTOMATION PROGRAM FOLDER DESCRIPTION

automation_central_control.py: self explanatory, this is the top-level program that coordinates control between all different components of the system. Don’t start here for verification/troubleshooting.

bandpass_filter_control.py: controls the discrete filter wheel containing band- and long-pass filters as described in the JCPA paper

bandpass_filter_library.py: Importantly, container for angle offset and ID of the motors controlling the bandpass ND filter wheel. Also a repository for photon output values of the various band- and long-pass filters. This feature is auto-populated and shouldn’t require intervention.

clear_pins.py: this is a standalone single-command program for clearing the digital pins of the RasPi. Basically, it makes sure the RasPi pins end any previous commands and clear for future communication. This works better as a standalone file, but shouldn’t require modification at any point.

error_messages.py: slight misnomer--this is the set of messages designed to display during normal overarching automation.

filter_wheel_motor_control.py: general purpose commands for controlling the Dynamixel motors that control ND filter wheel angle (and thus optical density for both monochromator and band- and long-pass filters).

GPIO_daq_board_comm.py: location of generalized communication controls between RasPi and the daq board, bandpass shutter, and (optional) piezo. Essentially all GPIO pin control functions are defined here, from low-level bit passing to high-level functions for specific communication with the PowerLab/LabChart system.

monochromator_communication.py: defines communication with the Spectral Products CM110 monochromator. In this case it only defines a function for setting monochromator wavelength, but the CM110 does have some other functions not written into this system.

monochromator_filter_library.py: analogous to bandpass_filter_library.py, but for the monochromator output. Defines angle offset and Motor ID for appropriate Dynamixel motor, as well as holds a repository of user-defined output libraries that are automatically generated via the guided system in LabChart.

/AUTOMATION PROGRAM FOLDER DESCRIPTION