Scanbox system integration

[Updated Dec 2015]

Integrating a Scanbox-controlled microscope with your system rather pretty straightforward after you understand how the system samples external events and how it can be controlled over the network.

Monitoring external TTL events

When Scanbox runs it monitors external events on its TTL inputs.  Two TTL inputs, labeled TTL0 and TTL1, are readily available as SMA connectors on the card.  These inputs can be set to trigger an event on either rising or falling edges of the TTL signal. By default the TTL0 signal triggers events on a rising edge of the signal, while TTL1 triggers an event on both rising and falling edges. [Note: additional lines are available in the expansion header, contact me if you need more than 2.]

One simple way to monitor an external stimulus with the microscope is to have an external TTL signal that is high during the presentation of a stimulus and low otherwise.  The signal can then be connected to TTL1, which generates an event on both rising and falling edges.

The variable imask in your scanbox_config.m file allows one to select which of these TTL inputs is enabled to generate events (imask=0 disables both, imask=1 enables TTL0, imask=2 enables TTL1, and imask=3 enables both). [Let me know if you need more TTL inputs, there is one more accessible from the expansion header.]

Once you finish collecting your data Scanbox creates a file named AAA_MMM_NNN.mat in your data directory.  Here, AAA is the animal id, MMM and NNN are two 3-digit identifiers used to name your experiments. We use MMM to indicate a particular field of view and NNN one of the experiments ran at that location.  If, after running an experiment, you load one of these file you will see a Matlab variable named “info” with the following fields:

info =
frame: [1202x1 double]
line: [1202x1 double]
event_id: [1202x1 double]
resfreq: 7938
postTriggerSamples: 5000
recordsPerBuffer: 512
bytesPerBuffer: 10240000
channels: 1
ballmotion: []
abort_bit: 0
config: [1x1 struct]
messages: {0x1 cell}

The variables that code the external TTL events are frame, line and event_id. For each external event, the system time stamps the event with the frame and line at which it occurred along with its event_id.  This means that the time resolution of TTL events is the period of the resonant mirror — in our case 125us in unidirectional mode.

The events are stored in the order of arrival. Thus, frame(1), line(1) and event_id(1) contain the information for the first TTL event and so on. In this particular example the system received 1202 events. The event_id codes the TTL lines that generated the event. An event_id of 1 means that TTL0 generated the event, if event_id = 2 it means TTL1 generated an event, and if both occurred within the same frame and line the event_id will be 3. Note that by default the system TTL0 is configured to generate an event on the rising edge while TTL1 is configured to generate an event on either edge.  At the moment these choices can be changed by a firmware upgrade, but we will allow for software control soon.

Controlling the microscope over the network

A recommended experimental setup is to have 3 computers in a network:  one dedicated to the microscope, another to stimulation, and a third “master” computer that controls the entire experiment.  The master computer can tell the microscope to change the fields within the File Storage panel (animal, field and experiment ids) and instruct the microscope to start sampling.  It can then tell the stimulus computer to present the desired sequence of stimuli. The stimulus computer should be in charge of generating TTLs that represent the beginning/end of different trials or other events).  Once finished, the master computer can tell the microscope to stop sampling.

Scanbox listens to UDP network messages directed at port 7000 over the network.  In Matlab you can use the following snippet of code to open communication (replace the IP address to your own or to ‘localhost’ if you are controlling the microscope from the same machine):

sbudp = udp('', 'RemotePort', 7000);

The microscope will now take commands that consist of a single character followed by a string.
Here is a typical sequence of commands issued by the master:

fprintf(sbudp,'Axx0'); % set animal id field
fprintf(sbudp,'U010'); % set field number to 010
fprintf(sbudp,'E002'); % set experiment number to 002
fprintf(sbudp,'G');    % Go!  Start sampling
% Master tells stimulator to present sequence of trials marked by TTLs
% ...
% Metadata, such as the order of stimuli, can be sent by including messages:
fprintf(sbudp,'MTrial #001 Orientation = 20deg");
% ....
% ... and at the end you can stop the microscope
fprintf(sbudp,'S');    % Stop sampling

There are other commands the microscope accepts over the network, such as blanking the laser in-between trials in long experiments, or some that allow one to move the position of the objective.


  1. Hi Dario,

    I’ve been having trouble with some of these commands to control the microscope.
    The ‘G’ command as well as the commands for filling out the different fields have been working fine, but the ‘S’ command to stop scanning and the laser blanking commands (‘L0’ and ‘L1’) have not been working. The command stalls out and never executes.

    I’ve only been trying to run commands from the localhost for debugging so far.
    (I’m running scanbox v3.4)

      1. I was also wondering if you could link me to the documentation for the other commands that the microscope can accept over the network?

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s