Developer Guide#
Attention
This section provides information related to hacking a commutator or building your own. For instructions on how to use the Coaxial Commutator, visit the Quick Start Guide and the User Guide.
Design Files#
Open Ephys commutators are open-source. Mechanical designs are available in the following repositories:
Firmware and PCB designs for all three of the commutators is available in the commutator-controller repo. Older commutator design files are available in the commutators repo.
You can use these files to build or design your own custom commutator. For example, you could design a variant with a different RF rotary joint or change the firmware to use a different communication protocol.
Important
The RF rotary joint and slip rings used in Open Ephys commutator are specified for millions of cycles without failure. If you want to replace these components, make sure you get them from a reputable manufacturer to maintain their reliability. We have found that Spinner is a very good source for high quality rotary joints.
Ordering and Manufacturing Parts#
The following sections describe how to fabricate the mechanical parts that comprise the .
Bill of Materials (BoM)#
The bill of materials is located here.
Mechanical#
We use SLS/MJF to make these parts. FDM/SLA are also fine for the enclosure.
If you don’t have a 3D printer but would still like to build your own, first seek out local 3D printing options. Many universities or libraries offer free or lower-priced 3D printing services. There are many online manufacturers that will 3D print this for you. To manufacture with these companies, it is usually required to upload an STL or STEP file. These are available in the repos linked above or can be converted from the source design files which are also available in those repos.
Note
Changing the gear ratio in your mechanical design requires also changing the gear ratio in the firmware. This can be done using the picotool config command if you have an RP2040 commutator with USB-C or flashing the firmware if you have a Teensy commutator with Micro-USB.
Electrical#
Printed circuit boards (PCBs) are boards that electrically connect a set of electronic components to create functional circuits. Those parts are soldered to the PCB to create mechanically stable electrically conductive connections. The commutator front panel is a PCB. PCB fab-houses usually require that you upload Gerber files. These Gerber files are originally generated by an eCAD (electrical computer-assisted drawing) program from the original design files. The original design files were made using KiCad which is a free and open-source eCAD program.
For ordering the electronics parts that are mounted onto the PCB, Digikey, Mouser, and Arrow are go-to vendors. Open Ephys has no affiliation with any of these companies. Some parts may be out-of-stock in which case you might need to purchase from more than one distributor if you inflexible regarding component selection. Octopart is helpful for sorting through stock at various vendors and comparing prices. The electrical components for the commutator PCB are mounted (and electrically connected) through solder joints. Soldering instructions are beyond the scope of this developer guide but there are several great guides on YouTube. If you are soldering this yourself, use the designators on the PCB’s silkscreen and the electrical components contained in the BoM (also labelled with designators) to match solder land patterns to electrical components. This is how you know where to solder each component. You can also get PCBs pre-assembled by PCB assemblers. For this you need to use an eCAD software to generate a properly formatted BoM and Pick n’ Place file.
Programming Custom Firmware#
Note
The following content is true for the newer commutator versions with the RP2040. For older versions, refer to the dropdown at the end of this section.
The microcontroller on the commutator controller is an RP2040. First acquaint yourself with running programs on the RP2040 by following the “getting started with Pico guide”
Install git if you don’t already have it. Navigate to the directory where you would like to develop the commutator firmware. Clone the commutator firmware and its dependency by running:
git clone --recurse-submodules https://github.com/open-ephys/commutator-controller.git
A serial monitor displays serial messages between the commutator and the computer. A serial monitor in VS Code should be available after following the “getting started with Pico” mentioned above. Confirm the following settings in the serial monitor are true before trying to send commands to the commutator:
Baud rate: 115200
Port: set the port that corresponds to the commutator. You can easily find which port that is by disconnecting/reconnecting the commutator and notice which port disappears/reappears in the process.
Line Ending: LF
Commands can be sent to the commutator by entering them in the VS Code Serial Monitor input field. Refer to the Remote Control page of the User Guide for more information on the commands.
Commutators with Micro-USB
Commutator firmware can be uploaded to the device using the Arduino IDE.
Note
You will need to add the Teensyduino add-on to the Arduino IDE to program
the Teensy inside the commutator. When installing Teensyduino, you should opt to install the
bundled libraries as well. This takes care of installing AccelStepper
library rather than having to install it manually. ArduinoJSON can be
installed through the Arduino IDE’s package manager.
It runs on a Teensy 3.2 or Teensy LC. To compile this firmware and program the microcontroller, the following dependencies are required:
The Teensy is a microcontroller development board (much like the Arduino for those who are familiar). It is the brains of the commutator. To directly control the commutator via computer, it helps to learn to interface with the Teensy. To do that:
Download the Arduino IDE
Install the Arduino IDE’s Teensy plugin, Teensyduino
Install relevant Arduino libraries: AccelStepper and Arduino JSON
Open the Arduino IDE’s serial monitor
Set correct COM port to which the Teensy is connected and set the serial monitor baud rate to 9600
Send a command to the commutator according to the communication below.
The serial monitor displays messages between the commutator and the computer to which the commutator is connected. To send commands to the commutator through the serial monitor, type in the Arduino IDE’s Serial Monitor input field. The commutator’s Teensy is pre-programmed to receive specific commands in the JSON format. Refer to the Remote Control page of the User Guide for more information on that. Other serial monitors can be used (see Termite for instance), but these instructions recommend the Arduino IDE because the Arduino IDE is already quite common in the open-source and science community. It also allows the user to program the Teensy in a convenient way if that is desired. Commutator firmware can be modified to accept other command formats.
Assembly#
Gather the materials listed in the BOM for the commutator.
Visually inspect to confirm that all the components on the PCB are properly soldered.
If you have access to a multi-meter, check for shorts between power supply rails and ground, and confirm the power rails are at their proper voltages.
Plug a USB cable into the PCB and ensure that the LED and capacitive sense buttons work. Unplug the USB cable.
Insert the SMA rotary joint and fasten it with three M2.5 screws 10mm long to the case.
Insert the stepper motor and fasten it to the case with four M2.5 screws 6mm long.
Connect the stepper motor to the 4-pin connector on the back of the commutator front panel.
Fasten the commutator PCB to the case with four M2.5 screws 6mm long.
Insert the gears onto the rotary joint rotor and motor rotor. Glue them in place such that the gears are properly meshed. Clamp to ensure the gears do not mis-align during the curing process.
Plug the USB cable into the commutator and try a few manual turns. If the commutator is turning the wrong way, remove the PCB and flip the motor connections