== Cross-Triggering the Clocking Engines ==

Multi-channel CCD and IR systems often require synchronized readouts.  This is the most common use of the STARGRASP "cross-trigger" feature, though it could be used to wait for and line up other events.  When multiple "devices" are being clocked together, a hardware cross-trigger signal is typically connected between boardsets to allow this synchronization.  Even in cases where only one boardset operates two "devices" (i.e., "dev 0" and "dev 1" on the same board), there is a common crosstrigger bus present internally and it is generally advisable to use it.  This is primarily because, at a low level, there is no "go" for "dev=all".  From the scripting level, synchronized CCD readouts are set up as follows:

 1. Identify the list of all "dev's" that need to be clocked and readout, even if they are on the same boardset.  Be sure to exclude any clocking engine dev's which are not going to be clocked.
 2. Send the socket command '''[wiki:GraspSwControllerCmdSettrig settrig dev=0]''' or '''settrig dev=1''' for each of the devices in the list.  It is acceptable to use '''dev=all''' if you need to set the trigger for dev 0 and dev 1 at the same time.  If this step needs to be performed on multiple boardsets, it is acceptable to send to all controller IP addresses in parallel on separate sockets, but one ''must wait for completion before advancing to the next step.''
 3. Send the socket command '''[wiki:GraspSwControllerCmdReadout readout]''' to all boardsets.  If reading both dev's from a boardset, the '''dev=all''' syntax must be used here, because the readout command does not return until it has finished reading out.  (And with the cross-trigger, it won't begin reading out until all the boardsets which were sent '''settrig''' in step 2 have been sent their readout command.)  Once again, wait for all readout commands to return before proceeding to the final step.
 4. Repeat step 2., but with '''settrig dev=N onoff=0''' and wait for all to complete.  This is necessary if the next readout might be without crosstrigger, or might involve a different subset of devs.

=== Phase Delays ===

Using settrig causes all dev's to program their clocking engines with a wait for trigger instruction that lines everything up.  For more details of the clocking engine level, see below.  Once things are lined up, it is sometimes useful to insert a fixed delay immediately after the cross-trigger which is different for each dev in order to introduce a phase shift in the clocking and A/D sampling of one device versus another.  This trigger delay is set using the optional '''trig=''' parameter of the '''[wiki:GraspSwControllerCmdClvset clvset]''' command, which is generally configured only once, when a CCD clocking pattern is loaded.  See '''[wiki:GraspSwControllerCmdClvset clvset]''' for more information.  If phase delays are not required, '''clvset trig=0 ...''' is recommended.  Each increment of the trig parameter equals a 10 nanosecond phase delay.

=== Clocking Engine Level ===

Much of the above depends on the implementation of the CCD '''readout_app()''' code in the embedded software.  The information below is intended to facilitate IR clocking, which will be implemented slightly differently.

As stated previously, there is no ce_go(dev=all, 1) function, so if dev 0 and dev 1 need to be told to execute their clocking instructions at the same time, it is necessary to use:
{{{
  ce_go(ce0, 1);
  ce_go(ce1, 1);
}}}
The clocking engine instruction FIFOs have already been loaded before issuing the ce_go.  But if cross-triggered operation is desired, some additional steps are required before the ce_go.  First, it is necessary to insure that all clocking engines (except those which are connected to the cross-trigger bus but are not going to be readout for whatever reason) are in blocking (wait) state so that they are asserting the cross-trigger signal that tells other clocking engines to wait.  This is typically accomplished by having the previous readout or clocking sequence end in:
{{{
ce_put(ce, CE_CMD_NOTDONE1);
}}}
Next, the command sequence for the current readout in the CE FIFO should begin with:
{{{
ce_put(ce, CE_CMD_WAITDONE1);
}}}
which will release the cross-trigger, but waits for the cross-trigger bus to be released by all other dev's before proceeding to the next instruction.

=== When to Re-Trigger ===

The CCD readout clocking code asserts the NOTDONE1 state during parallel clocking, and performs WAITDONE1 again at the beginning of each set of serials.  If operating with a single boardset, this re-triggering is not necessary.  When operating multiple boardsets, however, the separate system clocks can drift and it is advisable to retrigger.  The current implementation of retriggerring every pixel row has not been optimized.