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:

  1. Open the mailbox for the appropriate function by sending the appropriate command (for _cmd, use from enum class MailboxCmd either OpenImageIndex, OpenPat or OpenPatVarExp)

  2. Write the desired data to the mailbox using the setPatternDispLUTData method.

  3. 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: 0>, _bitDepth=1, _LED=<MailboxLED.None_: 0>, _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()