Lightcrafter¶

API¶

To interact with the lightcrafter device directly in a python script (during compile-time of the stimulus, see section How QDSpy works), use the follwing lightcrafter class.

Note that this library requires firmware 3.0 and higher.

class Devices.lightcrafter.Lightcrafter(_isCheckOnly=False, _funcLog=None, _logLevel=2)¶

Create and initialize lightcrafter object.

Parameters:
_isCheckOnly	all functions only check parameters
_funcLog	external function for logging of the format: log(_sHeader, _sMsg, _logLevel)
_logLevel

connect(_devNum=- 1)¶

Try connecting to a lightcrafter and return immediately with an error code if it fails. A device number (_devNum) can be given if multiple lightcrafters are connected.

Parameters:
_devNum	device number (0,1,…)

disconnect()¶: Disconnects the lightcrafter.

getFirmwareVersion()¶

Get firmware version

Result:
code	0=ok or error code
data	the original data byte(s) returned by the device
info	a dictionary with following entries: applicationSoftwareRev, APISoftwareRevision, softwareConfigurationRevision, sequenceConfigurationRevision

getHardwareStatus()¶

Requests the device’s hardware status and returns a list with up to three elements:

Result:
code	0=ok or error code
data	the original data byte(s) returned by the device
info	a dictionary with following entries: initOK, DMDError, swapError, seqAbort, seqError

getLEDCurrents()¶

Get LED currents and returns these as list [code, [r,g,b]] with:

Result:
code	0=ok or error code
[r,g,b]	LED currents as PWM, 0..255

getLEDEnabled()¶

Returns state of LED pins (enabled/disabled) and if the sequence controls these pins as list [code, [isR,isG,isB], isSeqCtrl]] with:

Result:
code	0=ok or error code
[isR,isG,isB]	list of boolean values, one for each LED
isSeqCtrl	if True, the all LED enables are controlled by the sequencer and _rgb is ignored

getMainStatus(_logLev=1)¶

Requests the device’s main status and returns a list with up to three elements:

Result:
code	0=ok or error code
data	the original data byte(s) returned by the device
info	a dictionary with following entry: DMDParked, SeqRunning, FBufFrozen, FBufFrozen, GammaEnab

getSystemStatus()¶

Requests the device’s system status and returns a list with up to three elements:

Result:
code	0=ok or error code
data	the original data byte(s) returned by the device
info	a dictionary with following entry: MemoryOK

getVideoSignalDetectStatus()¶

Requests the status of the video signal received by the device and returns a list with up to three elements:

Result:
code	0=ok or error code
data	the original data byte(s) returned by the device
info	a dictionary with following entry: SigDetect, HRes, VRes, HSyncPol, VSyncPol, PixClk_kHz, HFreq_kHz, VFreq_Hz

pausePatternSequence()¶: Pauses the programmed pattern sequence.

Important

After executing this command, poll the system status.

setDisplayMode(_mode)¶

Sets the display mode of the device. Use enum class DispMode for _mode.

Parameters:
_mode	0=video display mode, Assumes streaming video image from the 30-bit RGB or FPD-link interface with a pixel resolution of up to 1280 × 800 up to 120 Hz. 1=Pattern display mode Assumes a 1-bit through 8-bit image with a pixel resolution of 912 × 1140 and bypasses all the image processing functions of the DLPC350.

setInputSource(_source, _bitDepth)¶

Defines the input source of the device. Use enum classes SourceSel and SourcePar for _source and _bitDepth, respectively.

Parameters:
_source	0=parallel interface (PP), 1=internal test pattern, 2=Flash 3=FPD-link
_bitDepth	Parallel interface bit depth 0=30, 1=24, 2=20, 3=16, 4=10, 5=8 bits

setLEDCurrents(_rgb)¶

Set LED currents.

Parameters:
_rgb	[r,g,b] with LED currents as PWM, 0..255

setLEDEnabled(_rgb, _enableSeqCtrl)¶

Enable or disable LEDs or allow sequencer to control LED pins

Parameters:
_rgb	list of boolean values, one for each LED
_enableSeqCtrl	if True, the all LED enables are controlled by the sequencer and _rgb is ignored

setPatternDispLUTAccessControl(_cmd)¶

The LUT on the DLPC350 contains a mailbox to send data to different registers. This command selects which register receives the data. To select the flash image indexes or define the patterns used in the pattern sequence for the pattern display mode:

Open the mailbox for the appropriate function by sending the appropriate command (for _cmd, use from enum class MailboxCmd either OpenImageIndex, OpenPat or OpenPatVarExp)
Write the desired data to the mailbox using the setPatternDispLUTData method.
Use this command (with MailboxCmd.Close) to close the mailbox.

Important

Before executing this command, stop current pattern sequence and after execution of this command, validate before starting sequence.

Parameters:
_cmd	0=close 1=open for flash mode 2=open for pattern mode 3=open for variable exposure pattern mode

setPatternDispLUTControl(_nEntr, _repeat, _nPatt, _nImgInd)¶

The Pattern Display LUT Control Command controls the execution of patterns stored in the lookup table (LUT).

Important

Before executing this command, stop current pattern sequence and after execution of this command, validate before starting sequence.

Parameters:
_nEntr	number of entries in the LUT
_repeat	True=repeat sequence or False=play once
_nPatt	number of patterns per sequence
_nImgInd	number of Image Index LUT Entries (Flash mode)

setPatternDispLUTData(_iImgOrPat, _trigType=MailboxTrig.Internal, _bitDepth=1, _LED=MailboxLED.None_, _invert=False, _blackFill=False, _bufSwap=False, _trigOut1High=False)¶

Define a LUT entry in a pattern display sequence.

The parameters display mode, trigger mode, exposure, and frame rate must be set up before sending any mailbox data. If the Pattern Display Data Input Source is set to streaming, the image indexes are not required to be set. Regardless of the input source, the pattern definition must be set.

If the mailbox is opened to define the flash image indexes, list the index numbers in the mailbox. For example, if image indexes 0 through 3 are desired, write 0x0 0x1 0x2 0x3 to the mailbox. Similarly, if the desired image index sequence is 0, 1, 2, 1, then write 0x0 0x1 0x2 0x1 to the mailbox. Only the parameter _iImgOrPat is relevant.

If the mailbox is opened to define the individual patterns, all parameters are relevant.

For _iImgOrPat (in pattern mode), _trigType, and _LED use the respective enum classes.

Parameters:
_iImgOrPat	flash mode: image index (0..255) pattern mode: pattern index (MailboxPat)
_trigType	from MailboxTrig
_bitDepth	bit depth, 1..8
_LED	LED combination, from MailboxLED
_invert	True=invert pattern
_blackFill	True=Insert black-fill after current pattern
_bufSwap	True=Perform a buffer swap
_trigOut1High	True=TriggerOut1 will continue to be high, allows sharing time between patterns

setPatternDispLUTOffsetPointer(_offs)¶

The Pattern Display LUT offset pointer defines the location of the LUT entries in the memory of the DLPC350.

Parameters:
_offs	LUT entry index, 0..255

setPatternDisplayDataInputSource(_src)¶

Sets the Pattern Data Input Source. Use enum class SourcePat for _src.

Important

Before executing this command, stop current pattern sequence and after execution of this command, validate before starting sequence.

Parameters:
_mode	0=Data is streamed through the 24bit RGB /FPD-link interface 3=Data is fetched from flash memory

setPatternExpTimeFrPer(_pet_us, _frp_us)¶

Set Pattern Exposure Time and Frame Period.

The pattern exposure time (_pet_us) and frame period (_frp_us) dictates the length of time a pattern is exposed and the frame period.

Either _pet_us == _frp_us, or _pet_us < (_frp_us -230 μs).

Important

Before executing this command, stop current pattern sequence and after execution of this command, validate before starting sequence.

Parameters:
_pet_us	pattern exposure time in [us]
_frp_us	frame period in [us]

setPatternTriggerMode(_mode)¶

Sets the Pattern Trigger Mode. Use enum class PatTrigMode for _mode.

Important

Before executing this command, stop current pattern sequence and after execution of this command, validate before starting sequence.

Parameters:
_mode	0=VSYNC serves to trigger the pattern display sequence 1=internally or externally generated triggers (TRIG_IN_1 and TRIG_IN_2) 2=TRIG_IN_1 alternates between two patterns, while TRIG_IN_2 advances to next pair of patterns 3=internally or externally generated triggers for variable exposure sequence 4=VSYNC triggered for variable exposure display sequence

setTestPattern(_pattern)¶

Set test pattern (video mode).

Parameters:
_pattern	0x0 = Solid field 0x1 = Horizontal ramp 0x2 = Vertical ramp 0x3 = Horizontal lines 0x4 = Diagonal lines 0x5 = Vertical lines 0x6 = Grid 0x7 = Checkerboard 0x8 = RGB ramp 0x9 = Color bars 0xA = Step bars

softwareReset()¶: Signal the device to do a software reset. This will take a couple of seconds. After the reset the device is disconnected.

startPatternSequence()¶: Starts the programmed pattern sequence.

Important

After executing this command, poll the system status.

stopPatternSequence()¶: Stop the programmed pattern sequence.

Important

After executing this command, poll the system status.

validateDataCommandResponse()¶

The Validate Data command checks the programmed pattern display modes and indicates any invalid settings.

Result:
code	0=ok or error code
data	the original data byte returned by the device
validated	True if no error nor warning occurred
info	a dictionary with following entry: PeriodSettingInvalid, LUTPatternNumberInvalid, TrigOut1Invalid, PostVectSettingsInvalid, FrPerExpDiffInvalid, isBusyValidating

waitToConnect(_devNum=- 1, _timeout=10.0)¶

Try connecting to a lightcrafter until success or the timeout. Returns an error code if it fails. A device number (_devNum) can be given if multiple lightcrafters are connected.

Parameters:
_devNum	device number (0,1,…)
_timeout	timeout in seconds

General notes¶

There are two modes for LED control, “manual” and “sequencer”. When disabling the lightcrafter LEDs in the GUI, control is switched to manual and the LEDs can be individually turned on and off (by cutting the power supply). When the LEDs are enabled in the GUI, “sequencer” is the mode of operation. Now the lightcrafter takes control and switches them depending on the way the incoming video stream (via HDMI) is interpreted.

Example scripts¶

Example script for setting up the lightcrafter in pattern mode (fixed exposure), for two times 8-bit color frames streaming via HDMI (e.g. mouse dichromatic stimulation). Here, the red LED illuminates the green bit planes, and the blue LED illuminates the blue bit planes.

import Devices.lightcrafter as lcr
import time

dev = lcr.Lightcrafter(_isCheckOnly=False, _logLevel=3)
res = dev.connect()
if res[0] is not lcr.ERROR.OK:
  exit()

dev.getFirmwareVersion()
dev.getHardwareStatus()
dev.getMainStatus()
dev.getSystemStatus()
dev.getVideoSignalDetectStatus()

dev.stopPatternSequence()

dev.setDisplayMode(lcr.DispMode.Pattern)
dev.setPatternDisplayDataInputSource(lcr.SourcePat.Parallel)
dev.setPatternDispLUTControl(2, True, 2, 1)
dev.setPatternTriggerMode(lcr.PatTrigMode.Vsync_fixedExposure)
dev.setPatternExpTimeFrPer(16666, 16666)

dev.setPatternDispLUTAccessControl(lcr.MailboxCmd.OpenPat)

dev.setPatternDispLUTOffsetPointer(0)
dev.setPatternDispLUTData(lcr.MailboxPat.G76543210,
                          lcr.MailboxTrig.ExternalPos, 8,
                          lcr.MailboxLED.Red)

dev.setPatternDispLUTOffsetPointer(1)
dev.setPatternDispLUTData(lcr.MailboxPat.B76543210,
                          lcr.MailboxTrig.None_, 8,
                          lcr.MailboxLED.Blue,
                          _trigOut1High=True)

dev.setPatternDispLUTAccessControl(lcr.MailboxCmd.Close)

res = dev.validateDataCommandResponse()
if res[0] == lcr.ERROR.OK:
  dev.getHardwareStatus()
  dev.getMainStatus()
  time.sleep(1)
  dev.startPatternSequence()
  time.sleep(1)

dev.getMainStatus()
dev.getSystemStatus()

dev.disconnect()

The following script switches the lightcrafter back to video mode.

import Devices.lightcrafter as lcr
import time

dev = lcr.Lightcrafter(_isCheckOnly=False, _logLevel=3)
res = dev.connect()
if res[0] is not lcr.ERROR.OK:
  exit()

dev.getFirmwareVersion()
dev.getHardwareStatus()
dev.getMainStatus()
dev.getSystemStatus()
dev.getVideoSignalDetectStatus()

dev.stopPatternSequence()

dev.setInputSource(lcr.SourceSel.HDMI, lcr.SourcePar.Bit24)
dev.setDisplayMode(lcr.DispMode.Video)

dev.getMainStatus()
dev.getSystemStatus()

dev.disconnect()

QDSpy 0.80 beta documentation

Lightcrafter

Contents

Lightcrafter¶

API¶

General notes¶

Example scripts¶