BpodWavePlayer

Description

BpodWavePlayer plays analog waveforms on trigger, using the Analog Output Module (a precision voltage DAC with a dedicated microcontroller).

After running Bpod, a BpodWavePlayer object is initialized with the following syntax:

W = BpodWavePlayer('COM3');

Where COM3 is the analog output module's serial port.

The BpodWavePlayer device is controlled in 2 ways: 
  • Setting the BpodWavePlayer object's fields
  • Calling the BpodWavePlayer object's functions
Object Fields

  • Port 
  • SamplingRate (Hz)
    • 1Hz-50kHz, affects all channels. 
    • Can be set beyond 50kHz, up to to 100kHz, automatically disabling channels 3-4.
  • OutputRange (String)
    • A string specifying voltage output range for all channels: 
      • '0V:5V'
      • '0V:10V'
      • '0V:12V'
      • '-5V:5V'
      • '-10V:10V'
      • '-12V:12V'
    • For best signal quality, use the smallest voltage range necessary for your application. 
    • An error is raised if a voltage sample in a currently loaded waveform is outside of the new range. 
    • All currently loaded voltage waveforms are automatically re-coded into bits, and sent to the device.
  • Waveforms (Cell)
    • Local copy of all waveforms loaded to microSD with loadWaveform() function.
  • TriggerMode (String)
    • A string specifying how to handle incoming bytes from Bpod:
      • 'Normal' - plays the triggered wave(s), and ignores triggers on the same channel during playback
      • 'Master' - triggers can force-start a new wave during playback.
      • 'Toggle' - starts playback. Stops playback if a channel is triggered during playback.
  • TriggerProfiles (Matrix)
    • Allow a single trigger byte to specify different waveforms to play on any subset of channels.
    • TriggerProfiles must be a 64X4 matrix. Columns are channels, rows are trigger profiles.
    • Each row specifies the waveform (1-64) to play on each channel when the row's trigger byte arrives.
    • TriggerProfiles are disabled by default. Must be enabled by setting TriggerProfileEnable
  • TriggerProfileEnable (String)
    • A string that controls how bytes from the state machine are handled, following byte 'P' (for play).
    • 'On' = second byte specifies trigger profile to play (1-64).
    • 'Off' = default trigger scheme: one waveform on multiple channels. 
      • second byte specifies bits corresponding to playback channels (bytes 1-16 = subsets of channels 1-4)
      • A third byte must follow, specifying the waveform index (1-64).
  • LoopMode (String)
    • A string specifying whether loop mode is on or off for each channel
      • 'On' loops the waveform until LoopDuration seconds, or until toggled off
      • 'Off' = plays the waveform once
  • LoopDuration (Seconds)
    • In loop mode, specifies the duration to loop the waveform following a trigger.
    • Units = seconds
  • BpodEvents (String)
    • 'Off': No feedback to the Bpod state machine
    • 'On' generates a serial event when starting playback, and again when playback finishes.
      • The event byte specifies which channels started or stopped playback during the current playback sample
      • e.g. byte 0x3 = binary 11; event indicates that channels 1 and 2 simultaneously started (or stopped) playback.
      • e.g. byte 15 = binary 1000; event indicates that channel 4 started (or stopped) playback.

Object Functions

  • loadWaveform(waveNumber, waveform)
    • Transmits a voltage waveform to the device
    • waveNumber = index of the waveform (1-64)
    • waveform = a 1xN MATLAB array of voltages (samples in volts)
      • Voltages must be in the range specified by the OutputRange field.
      • An error is raised if the waveform exceeds the allowed maximum (1M samples)
    • Function returns an error if waveform was not successfully transmitted.
  • play(channels, waveNumber)
    • Plays a waveform on any subset of channels.
    • channels = a vector indicating the output channels to trigger (e.g. [2 4] = channels 2 and 4)
    • waveNumber = index of the waveform to play on targeted channels (1-64)
    • If TriggerMode is set to 'Normal' and a waveform is playing, the play() command is ignored by the device.
    • If TriggerMode is set to 'Toggle' and a waveform is playing on a targeted channel, the waveform is stopped.
    • If TriggerMode is set to 'Master' and a waveform is playing, it is immediately replaced by the new waveform.
    • Returns an error if TriggerProfileEnable is set to 'On'; see play(triggerProfile)
    • Plays only 1 waveform per function call. For simultaneous triggering of multiple waveforms, see play(triggerProfile)
  • play(triggerProfile)
    • Plays waveforms on target channels specified by a trigger profile
    • triggerProfile = index of the trigger profile to play (1-64)
  • stop()
    • Stops all ongoing playback
  • setupSDCard()
    • Must be run before first use with a new card.
    • Creates an empty data file on the module's microSD card, where waveforms will be stored.
    • Setup may take ~1 minute, depending on the microSD card's speed. A U3 class card is strongly recommended.
Cleanup

  • Clear the BpodWavePlayer object with clear:
    W = BpodWavePlayer('COM3');
    ... % Use the wave player
    clear W
  • Clearing the object releases the serial port, so other applications can access it.
  • If a BpodWavePlayer object is created inside a MATLAB function, the object is cleared automatically when the function returns.

Comments