The Matlab rfboard.m API

This note discribes a new API with which Matlab applications talk to the rf controller board. The controller board may talk to the an application through a host transport layer, such as Opal Kelly FrontPanel, and the EPICS transport layer. The details of the transport layer, and the details of the on-board logic needed to talk to the particular transport layer are hidden from the application by this API. Thus applications may be programmed independent of the particular transport layer in use.

The board.m API is object based, instantiated in Matlab as a reference type.

The scope of this document is to document the API syntax, and not so much the meanings or behaviors of the functions.

Functions by I/O type

Wire-in | Wire-out | Trigger-in | Trigger-out | Pipe-in | Pipe-Out

Functions by board function

Scope | Feed-forward table | Feedback table | Soft trip | Cavity tuner | Circular buffer
Interlocks | Serial number | Limiter | Readbacks | Trip stack | Network analyzer | Opal Kelly board

'Wire in' control points

These application-to-board control-point functions require three arguments (in Matlab):

1. A handle or pointer to the interface,
2. The value to be written, and
3. a third parameter that, for FrontPanel at least, specifies whether the data in the driver are to be flushed to the hardware.

The value to be written is binary, but its number of bits is dependent on the function's function. In Matlab the functions are called with the syntax:

interface.name(value, update)

sdramRdEn

Enables SDRAM read (logic 0 or 1).

sdramWrEn

Enables SDRAM write (logic 0 or 1).

sdramReset

SDRAM asynchronous reset (logic 0 or 1).

zoom

Scope and feed-forward-table zoom (0-31).

ep21Sel

The selector for the ep21 readback of wire-in control points (0-31).

debug_sel

The debug selector (0-7).

trig_out

? (logic 0 or 1)

ff_retrig

Enables automatic retriggering of output of the feed forward table (logic 0 or 1).

ff_wr_sel

Selects for write one of the two feed-forward table buffers (logic 0 or 1).

ff_rd_sel

Selects for read one of the two feed-forward table buffers (logic 0 or 1).

ff_enable

Gates the feed-forward table onto the data stream (logic 0 or 1).

limEnable

Enables the limiter (logic 0 or 1).

fb_enable

Enables feedback (logic 0 or 1).

PhaseOffset

The tuner controls' phase-offset setting (0-65535 interpreted as 0 to 2π radians).

ki

Integral gain setting (0-65535).

rot_I

The I component of the loop gain/rotation block (-32768 to 32767).

rot_Q

The Q component of the loop gain/rotation block (-32768 to 32767).

ds1825comm

?

rampinterval

Controls the duration during which the feedback ramp table outputs (0-65535).

t_scope_start

Scope trigger delay (0-2047 (I,Q) samples).

naFreq

Network analyzer phase-increment register.

naDamp

Network analyzer pre-integration damping time in DDS periods (turns).

naAcquire

Network analyzer integration time in DDS periods (turns).

naIntensity

Network analyzer intensity as power of two (0 to 15).

When setting several signals using these functions, one ordinarily provides update=false when setting all but the last, then update=true for the last one written. This way all are written to hardware simultaneously.

'Wire out' control points

These board-to-application control-point functions require two arguments (in Matlab):

1. A handle or pointer to the interface,
2. a third parameter that, for FrontPanel at least, specifies whether the data in the driver are to be updated from the hardware.

In Matlab the functions are called with the syntax:

value = name(interface, update)

In another language, such as C++, a call might look like:

value = interface.name(update)

The following are multiple-bits readbacks.

ep20

ep20 word for internal use.

ep21

ep21 word for internal use.

ffImon, ffQmon

Feed-forward setpoint I- and Q-components monitor (signed).

rlImon, rlQmon

Feedback-setpoint I- and Q-components monitor (signed). This signal is the output of the feedback setpoint table, and upstream of the soft-trip module.

dbImon, dbQmon

Debug-selector I- and Q-components monitor (signed).

PhaseError

Tuning system phase error (0-65535 interpreted as 0 to 2π radians).

TunerPosn

Tuner position (unsigned).

TSWord0, TSWord1, TSWord2,

Trip-stack words.

sdramPage

SDRAM page counter (0-32767).

vacuum

Vacuum readback.

ep2f

ep2f word for internal use.

cavImon, cavQmon

Cavity-field I- and Q-components monitor (signed).

fwdImon, fwdQmon

Forward-signal I- and Q-components monitor (signed).

revImon, revQmon

Reverse-signal I- and Q-components monitor (signed).

refImon, refQmon

Reference I- and Q-components monitor (signed).

fbImon, fbQmon

Feedback-signal I- and Q-components monitor (signed). These signals are latched from the feedback data streams just upstream of the feedbak-enable switch.

Dallas1825

Dallas DS1825-chip serial-number readout. It returns a 14-character hexadecimal string.

diImon, diQmon

di1_2-signal I- and Q-components monitor (signed). This signal is is the output of the jump5.v module in logic, which is the summed feedback and feed-forward data streams.

When retrieving several signals using these functions, one ordinarily provides update=true when retrieving the first, then update=false for the remainder. This ensures that all are sampled at the same time.

These are single-bit (logic-valued) readbacks. They take the same arguments as the others.

ScopeBusy

Scope is acquiring. Readout can begin when it is finished.

ScopeBusy_hi

Readout of the scope is in progress.

RampBusy

Feedback-setpoint table is outputting its entire table. When not outputting the entire table it is outputting its first (I, Q) pair.

ff_busy

Feed-forward table outputting its entire table. When not outputting the entire table it is outputting its first (I, Q) pair.

STTrip

The soft-trip module is tripped.

RFInhibit

The RFInhibit block is tripped.

Quench

The Quench-detector block is tripped (still a placeholder).

Vacuum

The vacuum-trip block is tripped (still a placeholder).

VacCond

Vacuum conditioning is in progress.

CTLoLimSw

The cavity tuner is at its low limit.

AVAGO2

The AVAGO2-input block is tripped. In the storage ring this input pin is used to trip the soft-trip module.

PPSTrip

Indicates the PPS block is tripped.

CTCavUV

The cavity tuner is at its up-limit.

CTFwdUV

Indicates that cavity forward power is below its low-limit threshold (too small to use).

CTUpLimSw

The cavity tuner is at its up limit.

limActive

Indicates the limiter is actively limiting.

TSArmed

Indicates that the trip stack is armed.

TSCount

The number of events recorded in the trip stack.

sdramWrap

The SDRAM wrap counter.

sdramFill

Indicates that the SDRAM is acquiring.

naBusy

Indicates that the network analyzer is busy.

Readbacks of wire ins

These functions are loopbacks in logic of the wire-in settings. They take as argument only the interface, e.g.,

val = rampintervalGet(ifc);

in Matlab syntax. The function names are the set function names with 'Get' appended. Whole words can be read using these functions:

while bits or bit fields can be read using these functions:

Host-to-board triggers (trigger ins)

These functions, too, take only the interface as argument.

count_reset(ifc);

count_reset

Global reset.

SoftTrip

Trips the soft-trip module.

STReset

Resets the soft-trip module.

ffTrig

Triggers output of the feed-forward table.

adc_start

For software initiation of scope acquisition.

data_read

Used internally to reset an address counter prior to reading out scope data.

data_write

Used internally to reset an address counter prior to writing data to the feed-forward setpoint table and the feedback setpoint table.

sdramArm

Initiates SDRAM data acquisition.

ramp_trig

Initiates output of the feedback setpoint table.

RFInhSWTrip

Software trip of RFInhibit.

RFInhSWReset

Software reset of RFInhibit.

CircBufSWTripA

Initiates acquisition by the circular buffer.

QuenchSWTrip

Software trip of the quench-detection block (placeholder only).

QuenchSWReset

Software reset of the quench-detection block (placeholder only).

ds1825update

Used during readout of the Dallas DS1825 serial-number chip.

VacSWTrip

Vacuum-block software trip (placeholder).

VacSWReset

Vacuum-block software reset (placeholder).

PPSSWTrip

PPS-block software trip (placeholder).

PPSSWReset

PPS-block software reset (placeholder).

AVAGO2SWTrip

AVAGO2-block software trip.

AVAGO2SWReset

AVAGO2-block software reset.

TSNext

Advances the trip stack during readout.

TSReset

Resets the trip-stack trip counter and re-arms the trip stack.

naStart

Network analyzer DDS start trigger. Once started, dthe DDS runs until it is stopped.

naStop

Network analyzer DDS stop trigger. Once started, dthe DDS runs until it is stopped.

Board-to-host trigger control points

These functions detect triggers from the board to the host to accommodate the FrontPanel trigger-out end points. FrontPanel does not provide a mechanism (at least in Matlab) for interrupt-driven processing, so these functions are implemented on the host side by polling. Thus these functions take two arguments, one being the interface, and the other an update flag. They return a logic value indicating whether the selected trigger occurred.

val = adc_done(ifc, update);

adc_done

Indicates that scope acquisition has finished and data can be read out.

sdramDone

Indicates that an event has triggered the circular buffer, that acquisition has completed, and data may be read.

ramp_done

Indicates that the feedback setpoint table ramp has completed.

AVAGO2Trig

Indicates that AVAGO2 trigger input has fired.

PPSEvent

Indicates that PPS trigger input has fired.

RFInhibitPulse

Indicates that RFInhibit has tripped.

STPulse

Indicates that the soft-trip ramp down has started.

QuenchTrig

Indicates tha the quench detector has tripped (placeholder).

VacTrig

Indicates tha the vacuum-fault detector has tripped (placeholder).

ffDone

Indicates that a feed-forward table output has finished.

There is some subtlety about how FrontPanel handles trigger-out end points and the update flag. When the update flag is set, a copy of all trigger events are recorded in the driver prior to returning the requested status. In logic, however, all recorded trigger events are cleared. Subsequent queries for trigger status with the update flag cleared returns the trigger status recorded in the driver at the time of the update. Later queries for trigger status with update flag set records new events since the previous update, which means that trigger events that were not queried prior are lost.

Host-to-board block transfers

These two functions transfer blocks of data from the host to the board. They take two arguments, the interface, and the data to be transferred.

ffSPTable

Transfers a 1k-word block to the feed-forward setpoint table.

ifc.ffSPTable(data);

fbSPTable

Transfers a 1k-word block to the feedback setpoint table.

ifc.fbSPTable(data);

Board-to-host block transfers

This one function transfers blocks of data from the board to the host. It takes two arguments: the interface, and the data to be transferred.

ScopeReadout

Transfers an 8k-word block from the scope to the host. The block contains data from the eight scope buffers.

data = ifc.ScopeReadout(data);

naReadout

Network analyzer data readout. Reads out the 64-word block containing the cosine and sine integrals and integration time.

data = ifc.naReadout(16);

Interface functions by board function

Scope function

zoom, zoomGet

Zoom setting.

debug_sel, debug_selGet

Debug signal selector.

ScopeBusy

Status bit indicating the scope is acquiring.

ScopeBusy_hi

Status bit indicating the is being read out.

t_scope_start, t_scope_startGet

Scope start delay setting in samples.

adc_start

Trigger in that initiates scope acquisition.

data_read

Trigger in used for scope readout.

adc_done

Trigger out that indicates scope acquisition has finished.

ScopeReadout

Reads out the data acquired by the scope by block transfer.

Feed-forward setpoint table

ffTrig

Triggers output of the feed-forward table.

ff_retrig, ff_retrigGet

Wire in that selects automatic retriggering mode.

ff_wr_sel, ff_wr_selGet

Wire in for table buffer A/B write selector.

ff_rd_sel, ff_rd_selGet

Wire in for table buffer A/B readout selector.

ff_enable, ff_enableGet

Wire in for enable.

ffImon, ffQmon

Table output readback.

ff_busy

Wire out indicating table readout is in progress.

zoom, zoomGet

Wire in for scope and ff table zoom selector

data_write

Trigger in that prepares for a host write to the table.

ffDone

trigger out that indicates table output has finished.

ffSPTable

Writes to the table.

Feedback setpoint table

fb_enable, fb_enableGet

Wire in and Wire-in readback of the feedback enable. Not directly applicable to the table.

rampinterval, rampintervalGet

Sets the rate at which the table is output in terms of clocks (x16) between I/Q pairs.

rlImon, rlQmon

Feedback-setpoint I- and Q-components monitor (signed). This signal is the output of the feedback setpoint table, and upstream of the soft-trip module.

RampBusy

Status bit indicating the table output is in progress.

data_write

Trigger in that prepares for data transfer from host to the table.

ramp_trig

Trigger in that triggers the start of output of the table.

ramp_done

Trigger out that indicates a ramp (table output) has completed.

fbSPTable

Write data to the table.

Soft-trip rampdown function

STTrip

Status bit that indicates whether the module is tripped.

SoftTrip, STReset

Trigger in for s/w trip and s/w reset of the module, respectively.

STPulse

Cavity tuner

PhaseOffset, PhaseOffsetGet

Setting and readback of the phase offset.

PhaseError

Wire out for cavity-minus-forward phase readback (includes phase offset).

TunerPosn

Wire out for the tuner position (from the PLC).

cavImon, cavQmon

Cavity field readbacks.

fwdImon, fwdQmon

Wire out for forward intensity.

CTCavUV, CTFwdUV

Wire outs for status bits for cavity and forward undervoltage, respectively.

CTUpLimSw, CTLoLimSw

Cavity tuner up and low limit, respectively.

Circular buffer

sdramRdEn, sdramRdEnGet

Bit setting and readback for SDRAM read enable.

sdramWrEn, sdramWrEnGet

Bit setting and readback for SDRAM write enable.

sdramReset, sdramResetGet

Bit setting and readback for asynchronous SDRAM reset.

sdramPage

Readout of the SDRAM page at which acquisition terminated (15 bits).

sdramWrap

Readout of the circular-buffer wrap counter since the start of acquisition (counts modulo five).

sdramFill

Status bit indicating that data are being acquired.

sdramArm

Trigger in that initiates acquisition by the circular buffer (arms it).

sdramdone

Trigger out that indicates that acquisition has stopped and data may be retrieved.

Interlocks

RFInhibit, RFInhSWTrip, RFInhSWReset

Status bit, and trigger ins for RFInhibit.

vacuum, VacTrig, VacSWTrip, VacSWReset

Status bit, trigger out, and two trigger ins for the vacuum interlock module (placeholder).

Quench, QuenchTrig QuenchSWTrip, QuenchSWReset

Status bit, trigger out, and two trigger ins for the quench interlock module (placeholder).

PPSTrip, PPSEvent, PPSSWTrip, PPSSWReset

Status bit, trigger out, and two trigger ins for the PPS interlock module (placeholder).

AVAGO2, AVAGO2Trig, AVAGO2SWTrip, AVAGO2SWReset

Status bit, triggerout, and two trigger ins for the AVAGO2 interlock input module that is used, in the storage ring, for triggering the soft-trip module.

Dallas serial-number chip

The function Dallas1825 returns a unique 14-character hexadecimal serial number from a Dallas (Maxim) DS1825 serial-number chip. At the time it is read, the interface property Build is updated, representing the code word characterizing properties of the build. See LogicConfiguration.xls for more details. The pointer to the interface resides in the global workspace.

global ifc;
sn = Dallas1825(ifc);
bld = ifc.Build;

Limiter

limEnable, limEnableGet

Setting that enables the limiter. When not enabled, the limiter passes data through without modification.

limActive

Status bit that indicates the limiter is limiting.

Readbacks

ffImon, ffQmon, ffmon

Feed-forward setpoint I- and Q-components monitor (signed).

rlImon, rlQmon, rlmon

Feedback-setpoint I- and Q-components monitor (signed). This signal is the output of the feedback setpoint table, and upstream of the soft-trip module.

dbImon, dbQmon, dbmon

Debug-selector I- and Q-components monitor (signed).

cavImon, cavQmon, cavmon

Cavity-field I- and Q-components monitor (signed).

fwdImon, fwdQmon, fwdmon

Forward-signal I- and Q-components monitor (signed).

revImon, revQmon, revmon

Reverse-signal I- and Q-components monitor (signed).

refImon, refQmon, refmon

Reference I- and Q-components monitor (signed).

fbImon, fbQmon, fbmon

Feedback-signal I- and Q-components monitor (signed). These signals are latched from the feedback data streams just upstream of the feedbak-enable switch.

diImon, diQmon, dimon

di1_2-signal I- and Q-components monitor (signed). This signal is is the output of the jump5.v module in logic, which is the summed feedback and feed-forward data streams.

PhaseError

Tuning system phase error (0-65535 interpreted as 0 to 2π radians).

TunerPosn

Tuner position (unsigned).

Vacuum

The vacuum-trip block is tripped (still a placeholder).

Trip stack

These functions are used in the function TripStack, which returns information about trip events. See that function, and type

help TripStack

TSWord0, TSWord1, TSWord2

Fourty-eight bits for readout of the trip stack.

TSArmed

Status bit indicating the trip stack is armed.

TSCount

Readout of the number of events recorded.

TSNext

Trigger-in end point that advances the event stack, which is used during readout.

TSReset

Trigger-in end point that resets the event count and arms the trip stack.

Network analyzer

These functions talk to the network analyzer logic. For reference, the Matlab function naSequenceSinglePoint uses some of these functions in the correct sequence. Also refer to the network analyzer logic and usage document.

In the following code examples, the update argument can be either true or false, determining whether the FrontPanel function UpdateWireIns is subsequently called (or in the case of naBusy, whether UpdateWireOuts is first called).

naFreq

Wire-in end point that sets the DDS phase-increment register, which determines the DDS output frequency.

ifc.naFreq(188, update);

naAcquire

Wire-in end point that sets the network analyzer integration time in DDS cycles.

ifc.naAcquire(44, update);

naDamp

Wire-in end point that sets the network analyzer damping time (delay) prior to start of integration. The unit is DDS periods (turns).

ifc.naDamp(5, update);

naIntensity

Wire-in end point that sets DDS output intensity to a power of two (0 to 15).

ifc.naIntensity(12, update);

naStart

Trigger-in end point that starts the network analyzer DDS and measurement sequence.

ifc.naStart();

naStop

Trigger-in end point that stops the network analyzer DDS.

ifc.naStop();

naReadout

Block-throttled pipe-out end point that reads out the network analyzer cosine and sine integrals and integration time. Always 64 words (128 bytes). Its one argument should always be 16.

data = naReadout(16);

Its output block of 32 int32s consists of naChans pairs of cosine and sine integrals, filler numbers, and ending with the integration time in clocks. The function blocks until a currently running acquisition finishes.

naBusy

Readback that indicates that the network analyzer is busy.

ifc.naBusy(update);

Opal Kelly functions

The initialization function GuoBo\gb_init() illustrates some of these functions.

rfboard

Constructor. Connects to an Opal Kelly board.

ifc = rfboard();

If there is more than one Opal Kelly board attached to the computer, a connection to the last of the list is returned.

load

Loads a bit file. A file dialog box opens for interactively selecting the file to be loaded.

ifc.load(filenamestring);

isopen

Tests whether the instance is connected to a board.

val = ifc.isopen();

Because the isopen FrontPanel call does not seem to work, the GetDeviceMajorVersion is used instead. It returns less than zero if no connection is present.

destruct

Closes the connection to an Opal Kelly board.

ifc.destruct();

MajorVersion

Returns the major version number of the Opal Kelly board.

v0 = ifc.MajorVersion

MinorVersion

Returns the minor version number of the Opal Kelly board.

v1 = ifc.MinorVersion

DeviceID

Returns the device ID of the Opal Kelly board.

id = ifc.DeviceID

BoardModel

Returns the model of the Opal Kelly board.

model = ifc.BoardModel

SerialNumber

Returns the serial number of the Opal Kelly board.

sn = ifc.SerialNumber

OpenBySerial

Connects to the board having the serial number of the argument.

handleofinstance = ifc.OpenBySerial(sernumstring);

SetDeviceID

Sets the device ID of the Opal Kelly board to which the instance is connected. Calls the okUsbFrontPanel_SetDeviceID FrontPanel function.

ifc.SetDeviceID('Storage Ring System 1');
ifc.DeviceID()

The following are properties of the class.

xptr

Handle to the Opal Kelly board connection. It is used with the FrontPanel API.

Build

The build code, which is set when a bit file is loaded.

Serial

The rf-board serial number provided by the Dallas chip, and set when a bit file is loaded.

fs

The sample frequency in Hz, with the NSLS-II default value coded into the source file.

h

The ring's rf bucket count, with the NSLS-II default value coded into the source file.

There are other properties whose functions are not so well established.