This VOCAL guide serves as an introduction to the LabMaestro Simulator, a new software tool from VPixx Technologies. This simulator allows researchers to develop, run and debug their experiment code with hardware placeholders and simulated inputs and outputs, instead of physical VPixx devices.
LabMaestro Simulator was designed for researchers who do not have access to their regular testing equipment. Whether you are working from home, or have limited access to in-demand research facilities, this tool will allow you to program your experiments offline. When connected to a physical device your code will be able to automatically take advantage of our hardware components, with minimal to no modification required.
The first section of this guide briefly outlines a typical VPixx hardware ecosystem, and describes how the LabMaestro Simulator interfaces with this system and what it replaces. In the following sections, we will post step-by-step examples of the simulator in action.
The LabMaestro Simulator is still under development, and is not yet available for download. You can follow us on Twitter or send a request to support@vpixx.com to receive updates on LabMaestro features and release dates.
This guide will also update regularly with new information and demos as they become available.
Last Updated: June 17th, 2020
Principles of Operation
A typical VPixx system consists of three major pieces: the control computer, the experiment display, and an I/O hub which connects the two.
The hub may be a standalone unit, like one of the DATAPixx I/O hubs or the PROPixx controller. Alternatively, the hub may be built into the side of your VIEWPixx or VIEWPixx /3D CRT replacement monitor.
The I/O hub has connectors for optionally sending and receiving a variety of signals to and from peripheral systems.
Lite systems can send and receive digital TTL signals on two 25-pin connectors. They can interface with recording systems like MRI machines or EEG rigs, receive digital input from RESPONSEPixx button boxes, and more.
Full systems have all the features of lite systems, plus analog I/O on another 25-pin connector, and audio I/O on three stereo jacks (microphone in, audio in, and audio out). Full systems are able to pass custom analog waveforms to neurophysiological recording rigs, record feedback from custom analog controllers, synchronize audio playback to visual stimulus onset, and more.
In this section, we will discuss three key features of the I/O hub which form the basis for our hardware synchronization abilities: video signal monitoring, the onboard clock, and the register system.
Video signal monitoring
The I/O hub sits between your graphics card and your display. This means it has access to the video signal after all rendering and processing has been completed. The hub can monitor this signal for specific events, get timestamps for these events, and treat them as triggers for outgoing signals.
Two specific events the hub can monitor for are 1) the vertical sync pulse (VSYNC), which is a component of the video signal indicating the start of a new frame; and 2) a custom series of pixels defined by the user (known as pixel sync, or PSYNC).
Because these events are detected after image rendering, they are highly precise, and serve as reliable indicators of visual stimulus onset. Generally speaking, it is much easier to align every other signal with these events than try to align video with other I/O.
VSYNC and PSYNC are highly consistent. For the PROPixx operating at 120 Hz, they occur exactly 8.33 ms before full screen illumination. For the VIEWPixx and VIEWPixx /3D monitors, timing is deterministic but differs depending on the backlight mode.
Third party displays will need to be measured with a photodiode to determine the temporal offset. This measurement can be taken prior to data collection.
Onboard clock
The I/O hub has an onboard clock that runs independently of your computer clock. This is the central timekeeping system that is used to log VSYNC and PSYNC events, as well as all other I/O sent and received by the device. This makes it extremely easy to align multiple signals and events during your experiment.
Register writes and updates
The I/O hub stores system settings and data in a series of 16-bit registers in its internal memory. Collectively, this is referred to as the device register. Your computer has a copy of these settings and data stored in its own memory, and this is called the local register.
For most of our low level software functions, any changes you write in your code only affect the local register. In order to push these commands to the device so that they can be implemented, it is necessary to perform a register write or a register update. Register writes and updates are powerful tools for synchronizing signal output, and are described in detail in our VOCAL guide Introduction to Registers and Schedules.
LabMaestro Simulator
In the LabMaestro Simulator, the physical I/O hub is replaced with a virtual VPixx device. From the perspective of the computer and your code, it’s as if a new I/O hub has been connected.
Interacting with the local register is the same as before, and you can perform certain kinds of register writes and updates to the simulated device as if it were physically present. Currently, we support the following register commands:
- register write and register update (immediate)
- register write vsync and register update vsync (on the next detected VSYNC)
Since there is no connected experiment display, users instead define a simulated refresh rate at which the test display would run. This simulated refresh rate can be used in conjunction with register write vsync, or register update vsync, to provide a rough gauge of experiment performance.
VSYNC register write and update functions using the simulator will create a minor delay (~1 frame) due to the artificial nature of the refresh rate. The same functions will work as normal when connected to actual hardware.
In general, the timing returned by the simulator is a guide only; while the sequence of events in your code is preserved in LabMaestro, it is not possible to achieve microsecond-precise timing without physical VPixx hardware.
In addition, the onboard clock is replaced with a software-based nanosecond scale timer, which can be accessed using our GetTime and SetMarker commands, just like the hardware-based clock.
The simulated device register is still under development. At present, it can recognize a subset of I/O related commands. The following functionality has been implemented:
- Receive digital input (e.g., simulated button presses, simulated MRI triggers)
- Send digital output (e.g., simulate outgoing MEG and EEG triggers)
Some examples demonstrating these features are presented below.
Finally, LabMaestro includes a user interface that can be used to simulate digital inputs and outputs, and view them on a virtual oscilloscope. There is also an interactive button box for simulating participant responses with mouse clicks.
The LabMaestro Simulator UI for signal visualization
Demo: Sending a digital TTL waveform on VSYNC
Demo: Recording button presses with the Din Log
Summary
The LabMaestro Simulator is a software tool designed to act like a virtual VPixx device. In fact, from the perspective of the computer and local register, it is as though a new VPixx device has been connected.
The simulated device register behaves somewhat differently than a physical VPixx device. First, it requires the user to set a simulated refresh rate in order to use register write vsync and register update vsync commands. Second, the simulated clocking does not attain the microsecond-precise timing of a physical VPixx device. Third, only a subset of I/O functions are available, though this list of features will expand as we continue developing this tool.
It is worth keeping in mind that temporal variability is much higher with simulated devices. Simply put, it is impossible to achieve microsecond precision and synchronization without dedicated, specialized hardware like a VPixx I/O hub. The purpose of LabMaestro Simulator is to preserve the relative sequence of programmed events, in order to give researchers a rough sense of timing and the expected behaviour of their experiment code. It is for testing and development only; we do not recommend using LabMaestro Simulator to collect data for research purposes.
The LabMaestro Simulator has been designed in such a way that researchers can program, test and debug their experiments without being connected to physical hardware. Upon connecting to a physical VPixx device, experiment code that works with this simulator should run with little or no modification required. We hope this tool will prove useful to researchers working remotely, or who have limited access to shared testing facilities.
Feedback and questions about this guide can be sent to scientist_fraser@vpixx.com. For feature requests and technical support, or to be added to a mailing list with LabMaestro updates, please email support@vpixx.com.
Cite this guide
Fraser, L., (2020, June 12). Introduction to the LabMaestro Simulator. Retrieved [Month, Day, Year], from https://vpixx.com/learn/labmaestro-simulator