Isomet Modular Synthesiser (iMS) API  v1.4.2
iMS API
Public Types | List of all members
iMS::SignalPath Class Reference

Controls Signal routing and other parameters related to the RF output signals. More...

#include <include\SignalPath.h>

Public Types

enum  AmplitudeControl { AmplitudeControl::OFF, AmplitudeControl::EXTERNAL, AmplitudeControl::WIPER_1, AmplitudeControl::WIPER_2 }
 Selects Amplitude Control source for each of the 4 RF Channel outputs. More...
 
enum  ToneBufferControl { ToneBufferControl::HOST, ToneBufferControl::EXTERNAL, ToneBufferControl::EXTERNAL_EXTENDED, ToneBufferControl::OFF }
 Selects Control Source for the Local Tone Buffer. More...
 
enum  Compensation : bool { Compensation::ACTIVE = true, Compensation::BYPASS = false }
 Controls whether to use the Compensation Look-Up Table path for pixel data. More...
 
enum  SYNC_SRC {
  FREQUENCY_CH1, FREQUENCY_CH2, FREQUENCY_CH3, FREQUENCY_CH4,
  AMPLITUDE_CH1, AMPLITUDE_CH2, AMPLITUDE_CH3, AMPLITUDE_CH4,
  AMPLITUDE_PRE_COMP_CH1, AMPLITUDE_PRE_COMP_CH2, AMPLITUDE_PRE_COMP_CH3, AMPLITUDE_PRE_COMP_CH4,
  PHASE_CH1, PHASE_CH2, PHASE_CH3, PHASE_CH4,
  LOOKUP_FIELD_CH1, LOOKUP_FIELD_CH2, LOOKUP_FIELD_CH3, LOOKUP_FIELD_CH4,
  IMAGE_ANLG_A, IMAGE_ANLG_B, IMAGE_DIG
}
 Selects a source of Synchronous Output Data. More...
 
enum  SYNC_SINK { ANLG_A, ANLG_B, DIG }
 The Synchronous Output to which to assign Synchronous Data. More...
 
enum  ENCODER_MODE { QUADRATURE, COUNT_DIRECTION }
 Selects the type of encoder connected to the Synthesiser. More...
 
enum  VELOCITY_MODE { FAST, SLOW }
 Selects the method of velocity calculation. More...
 
enum  ENCODER_CHANNEL { CH_X, CH_Y }
 Selects which of two available encoder channels. More...
 

Public Member Functions

Constructor & Destructor
 SignalPath (const IMSSystem &ims)
 Constructor for SignalPath Object. More...
 
 ~SignalPath ()
 Destructor for SignalPath Object.
 
RF Output Control
bool UpdateDDSPowerLevel (const Percent &power)
 Scales the DDS device (Direct Digital Synthesis RF signal generator) power up & down. More...
 
bool UpdateRFAmplitude (const AmplitudeControl src, const Percent &ampl)
 Scales the Digital Potentiometer mixer drive level up & down. More...
 
bool SwitchRFAmplitudeControlSource (const AmplitudeControl src)
 Selects the amplitude control source for all 4 RF channels. More...
 
bool UpdatePhaseTuning (const RFChannel &channel, const Degrees &phase)
 Applies a constant Phase offset to one of the 4 RF Channels. More...
 
bool SetChannelReversal (bool reversal)
 Reverses the channel order of the 4 RF Outputs. More...
 
bool EnableImagePathCompensation (SignalPath::Compensation amplComp, SignalPath::Compensation phaseComp)
 Enables / Disables the programmed amplitude and phase Compensation Functions for Image Playback. More...
 
bool EnableXYPhaseCompensation (bool XYCompEnable)
 Configures Beam Steering Phase Compensation for X/Y Deflector Mode. More...
 
Calibration Functions
bool SetCalibrationTone (const FAP &fap)
 Bypasses Controller Data and Compensation Tables and plays a fixed tone for calibration purposes. More...
 
bool ClearTone ()
 Stops the tone playback and restores the signal path configuration to the Controller and Compensation Tables. More...
 
Synchronous Output Control
bool AssignSynchronousOutput (const SYNC_SINK &sink, const SYNC_SRC &src) const
 Selects the source of data for the 2 Analog and 12 Digital output signals that operate synchronously with the Image Pixel Clock. More...
 
bool ConfigureSyncDigitalOutput (::std::chrono::nanoseconds delay=::std::chrono::nanoseconds::zero(),::std::chrono::nanoseconds pulse_length=::std::chrono::nanoseconds::zero())
 Configures the Synchronous Digital Output data. More...
 
Local Tone Buffer Functions
bool UpdateLocalToneBuffer (const ToneBufferControl &tbc, const unsigned int index, const SignalPath::Compensation AmplitudeComp=SignalPath::Compensation::ACTIVE, const SignalPath::Compensation PhaseComp=SignalPath::Compensation::ACTIVE)
 Use these functions to output tones from the Local Tone Buffer, control their selection and compensation. More...
 
bool UpdateLocalToneBuffer (const ToneBufferControl &tbc)
 
bool UpdateLocalToneBuffer (const SignalPath::Compensation AmplitudeComp, const SignalPath::Compensation PhaseComp)
 
bool UpdateLocalToneBuffer (const unsigned int index)
 
Velocity / Encoder Compensation Functions

Some iMS Synthesisers include dual optical encoder inputs and built in tracking filters that can be used to monitor the velocity of a moving object in two dimensions, compensate the RF frequency by a scaled amount to alter the AOD deflection angle and hence remove distortion from the target feature.

Each of the 2 encoder inputs has a pair of RS422 receivers and can be configured to work with both quadrature (for best precision) and clock + direction style encoder signals. The encoder inputs are passed through a glitch filter to remove any excursions < 30ns before being decoded to extract a pulse train and to identify direction of travel.

This information is fed into a tracking loop filter that both attenuates noise from the signal and calculates an estimate for the encoder velocity (in encoder ticks per second). The filter has a number of parameters that can be adjusted for optimum performance. The transfer function of the filter is:

H(s) = ((kp / I.ki).s + 1) / ( (1 / I.ki).s^2 + (kp / I.ki).s + 1)

where:

  • kp = the proportion gain coefficient
  • ki = the integral gain coefficient
  • I = a constant correction factor = 65535 / 687 = 95.393
  • s = the Laplace operator

The resulting X and Y velocity estimates are applied to the pixel subsystem where they are scaled by a gain coefficient and used to offset the RF channel output frequency from the value requested by Image data, Single Tone or Tone Buffer. The offset is applied as follows:

  • (1) If X/Y Phase compensation is enabled (see EnableXYPhaseCompensation), offsets from Encoder input X are applied to RF Channels 1 and 2, offsets from Encoder input Y are applied to RF Channels 3 and 4.
  • (2) If X/Y Phase compensation is not enabled, offsets from Encoder input X are applied to all RF Channels and Encoder input Y is ignored.

Note that negative gains are allowed which result in frequency offsets in the opposite direction.

bool UpdateEncoder (const VelocityConfiguration &velcomp)
 UpdateEncoder enables the Encoder velocity offset correction and updates the parameters. More...
 
bool DisableEncoder ()
 Turns off the Velocity Compensation process. More...
 
bool ReportEncoderVelocity (ENCODER_CHANNEL chan)
 Retrieves the current angular velocity of the requested encoder channel. More...
 
Event Notifications
void SignalPathEventSubscribe (const int message, IEventHandler *handler)
 Subscribe a callback function handler to a given SignalPathEvents event. More...
 
void SignalPathEventUnsubscribe (const int message, const IEventHandler *handler)
 Unsubscribe a callback function handler from a given SignalPathEvents event. More...
 

Detailed Description

Controls Signal routing and other parameters related to the RF output signals.

The iMS Signal Path consists of Frequency, Amplitude, Phase and Synchronous Output data driven by the Controller, or generated internally by the Synthesiser, passing through the Compensation Tables, and driven by the DDS device to result in 4 RF signal outputs along with analogue and digital synchronous outputs.

This class provides functions that control the routing options of that data and functions that control the attributes of the signals within the signal path.

Author
Dave Cowan
Date
2015-11-03
Since
1.0

Member Enumeration Documentation

Selects Amplitude Control source for each of the 4 RF Channel outputs.

The RF signal outputs from the Synthesiser feature channel bandwidth filtering and an RF mixer with a selectable control source. The mixer input can be routed to one of two digital potentiometers on the Synthesiser, which act as amplitude controls, turned off, or to an external signal input (scalable range from 0 - 15V) for signal modulation.

Enumerator
OFF 

Turn RF outputs off.

EXTERNAL 

Route RF mixer inputs to analogue modulation external signals.

WIPER_1 

Connect RF mixer inputs to digital pot wiper 1.

WIPER_2 

Connect RF mixer inputs to digital pot wiper 2.

enum iMS::SignalPath::Compensation : bool
strong

Controls whether to use the Compensation Look-Up Table path for pixel data.

The Synthesiser includes a Compensation system for correcting amplitude non-linearities in the RF signal path, generating inter-channel phase data for beam steered applications, and synchronous digital and analogue output signals all as a function of the current active pixel frequency. The Compensation table can be in circuit (active) or bypassed for both the normal pixel path from the Controller Image and also for the Local Tone Buffer used on the Synthesiser.

Since
1.1
Enumerator
ACTIVE 

Use the Compensation Look-up Path.

BYPASS 

Do not use the Compensation Look-up Path.

Selects which of two available encoder channels.

The Rotary Encoder input has two channels, each comprising a pair of RS422 differential signals. The signal pairs are decoded by the rotary encoder block into a sequence of forward and reverse pulses which are processed to calculate a tick velocity, which can be converted to angular velocity through knowledge of the number of pulses per revolution (ppr) of the encoder.

Normally, only the first encoder is used and the velocity value used to compensate the frequency on all 4 channels of the synthesiser. However, in the case where the Synthesiser is configured for X/Y deflection, the first encoder input affects Synthesiser channels 1 and 2 and the second encoder input affects Synthesiser channels 3 and 4.

Since
1.4

Selects the type of encoder connected to the Synthesiser.

The preferred mode of operation is quadrature, in which the two encoder signals output a pulse train in which the second electrically leads or lags the other by 90 degrees, depending on the direction of rotation. This mode gives the best resolution.

The alternative mode: Count+Direction ouputs a single pulse train with the second signal indicating the direction of rotation ('1' = forward, '0' = reverse)

Since
1.4

The Synchronous Output to which to assign Synchronous Data.

Since
1.1

Selects a source of Synchronous Output Data.

Since
1.1

Selects Control Source for the Local Tone Buffer.

The Local Tone Buffer (LTB) in the synthesiser contains 256 individually selectable TBEntry Entries. Each entry contains Frequency, Amplitude and Phase data for each of the 4 channels independently. The index into the LTB can be chosen from either software control, or one of two external control modes. In the standard external control mode, the 4 PROFILE input signals are used to index the first 16 TBEntrys in the LTB. In the extended external control mode, the 4 PROFILE input signals are used in conjunction with the GPI1 and GPO1 control signals to enable selection of all 256 LTB TBEntries as 16 "pages" of 16 Entries each.

If none of these 3 modes is selected, the normal Image Path drives the Synthesiser outputs.

Since
1.1
Enumerator
HOST 

The Local Tone Buffer is routed to the Synthesiser. Index updates are controlled from host software.

EXTERNAL 

The Local Tone Buffer is routed to the Synthesiser (first 16 entries only). LTB is indexed from PROFILE pin inputs.

EXTERNAL_EXTENDED 

The Local Tone Buffer is routed to the Synthesiser (all 256 entries available). Index page and Entry select controlled from PROFILE pin inputs.

OFF 

Local Tone Buffer not used. Synthesiser outputs from Image data.

Selects the method of velocity calculation.

The rotary encoder input is connected to a tracking loop filter which calculates the current angular velocity of the encoder shaft, in ticks / second. The loop filter can generate two different estimates of the current velocity with different characteristics, without altering the behaviour of the filter response.

The first is the closest approximation to the filter state and has a fast response but a higher noise profile which may lead to low level frequency modulation on the DDS output signal.

The second has a much slower response (typically 1-2 orders of magnitude) but a cleaner spectrum.

Since
1.4

Constructor & Destructor Documentation

iMS::SignalPath::SignalPath ( const IMSSystem ims)

Constructor for SignalPath Object.

An IMSSystem object, representing the configuration of an iMS target must be passed by const reference to the SignalPath constructor.

The IMSSystem object must exist before the SignalPath object, and must remain valid (not destroyed) until the SignalPath object itself is destroyed.

Once constructed, the object can neither be copied or assigned to another instance.

Parameters
[in]imsA const reference to the iMS System
Since
1.0

Member Function Documentation

bool iMS::SignalPath::AssignSynchronousOutput ( const SYNC_SINK sink,
const SYNC_SRC src 
) const

Selects the source of data for the 2 Analog and 12 Digital output signals that operate synchronously with the Image Pixel Clock.

Since
1.1
bool iMS::SignalPath::ClearTone ( )

Stops the tone playback and restores the signal path configuration to the Controller and Compensation Tables.

Returns
true if the clear tone request was sent successfully
Since
1.0
bool iMS::SignalPath::ConfigureSyncDigitalOutput ( ::std::chrono::nanoseconds  delay = ::std::chrono::nanoseconds::zero(),
::std::chrono::nanoseconds  pulse_length = ::std::chrono::nanoseconds::zero() 
)

Configures the Synchronous Digital Output data.

Synchronous Digital output data is usually time aligned with the update of RF Channel data output and remains valid for the duration of the image pixel clock period. There are two options to this:

(1) The assertion of Synchronous Digital output data can be delayed with respect to the RF signal by any number of nanoseconds that is less than 655360ns and has a minimum resolution of 10ns. (2) The synchronous digital output bits can be set to "pulse mode" - they return to inactive after a defined time period. The period may be any number of nanoseconds that is less than 655360ns and has a minimum resolution of 10ns.

Parameters
[in]delaythe number of nanoseconds to delay the onset of synchronous digital output data
[in]pulse_lengththe width of the digital output data pulse (or zero to disable)
Returns
true if the syncronous digital output data configuration request was sent successfully
Since
1.4
bool iMS::SignalPath::DisableEncoder ( )

Turns off the Velocity Compensation process.

Since
1.4
bool iMS::SignalPath::EnableImagePathCompensation ( SignalPath::Compensation  amplComp,
SignalPath::Compensation  phaseComp 
)

Enables / Disables the programmed amplitude and phase Compensation Functions for Image Playback.

Image Pixel data pass through a Compensation process in the Synthesiser which performs amplitude corrections and phase adjustment for beam steering applications as a function of the programmed frequency. The Compensation tables must be programmed either from software, or from a look-up table stored in the Synthesiser FileSystem. If no compensation table has been programmed, or the application does not wish to use Compensation, the process can be bypassed by calling this function with the appropriate settings for amplitude and phase.

Parameters
[in]amplCompSet to SignalPath::Compensation::BYPASS or SignalPath::Compensation::ACTIVE for amplitude compensation (frequency dependent correction)
[in]phaseCompSet to SignalPath::Compensation::BYPASS or SignalPath::Compensation::ACTIVE for phase compensation (frequency dependent beam steering)
Returns
true if the compensation request was sent successfully
Since
1.3
bool iMS::SignalPath::EnableXYPhaseCompensation ( bool  XYCompEnable)

Configures Beam Steering Phase Compensation for X/Y Deflector Mode.

Normal phase beam steering configures the 4 RF Channel outputs for incremental phase adjustment so that channel 1 has zero phase, channel 2 has a frequency dependent phase offset with respect to channel 1, channel 3 has twice the phase offset and channel 4 has three times the phase offset.

In an X/Y deflector configuration, the first two channels are assigned to deflector X and the second two channels to deflector Y. In this case, both channels 1 and 3 have zero phase, channels 2 and 4 have a single frequency dependent offset with respect to those channels.

Parameters
[in]XYCompEnableSet to true to enable X/Y style phase beam steering (split channels)
Returns
true if the XY Phase Setting request was sent successfully.
Since
1.3
bool iMS::SignalPath::ReportEncoderVelocity ( ENCODER_CHANNEL  chan)

Retrieves the current angular velocity of the requested encoder channel.

Whilst enabled, the encoder inputs are continuously monitored for activity and any movement is converted by the tracking loop filter into an estimate of velocity in number of encoder ticks per second. Note that for a quadrature encoder, a single tick is defined as an edge of either type (rising or falling) on either signal input, to guarantee maximum possible resolution, thus there are 4 ticks to a single pulse on one signal input.

This function allows application software to request the current velocity estimate of either encoder channel. The result is reported to the software in the SignalPathEvents::ENC_VEL_CH_X and ENC_VEL_CH_Y events.

Parameters
[in]chanwhich of the two encoder channels to request the velocity from (X or Y).
Returns
true if the encoder velocity report request was sent successfully
Since
1.4
bool iMS::SignalPath::SetCalibrationTone ( const FAP fap)

Bypasses Controller Data and Compensation Tables and plays a fixed tone for calibration purposes.

In order to calibrate the RF output signal path and the AO Device, it is sometimes useful to play a fixed calibration tone. This can be achieved using this function, which disconnects the Controller from the signal path along with the Compensation Tables and immediately plays a pure tone on all 4 RF Channels simultaneously at the Frequency, Amplitude and Phase Offsets specified by the input argument. The fixed tone will remain on the output until cleared.

Bug:
In v1.0 SDK calibration tone amplitude would be 25% of value provided in fap. Corrected in 1.1.0.
Parameters
[in]fapa FAP triad specifying the output tone to be played back.
Returns
true if the calibration tone request was sent successfully
Since
1.0
bool iMS::SignalPath::SetChannelReversal ( bool  reversal)

Reverses the channel order of the 4 RF Outputs.

Sometimes, usually to simplify cable routing, it is desirable to order the 4 RF outputs in 4-3-2-1 configuration instead of 1-2-3-4. This can be achieved by setting the channel reversal configuration bit, using this function.

Parameters
[in]reversalSet true to enable the channel reversal (Channel 1 outputs Channel 4 data and vice versa)
Returns
true if the reversal update request was sent successfully
Since
1.0
void iMS::SignalPath::SignalPathEventSubscribe ( const int  message,
IEventHandler handler 
)

Subscribe a callback function handler to a given SignalPathEvents event.

SignalPath can callback user application code when an event occurs that affects the signal path. Supported events are listed under SignalPathEvents. The callback function must inherit from the IEventHandler interface and override its EventAction() method.

Use this member function call to subscribe a callback function to a SignalPathEvents event. For the period that a callback is subscribed, each time an event in SignalPath occurs that would trigger the subscribed SignalPathEvents event, the user function callback will be executed.

Parameters
[in]messageUse the SignalPathEvents::Event enum to specify an event to subscribe to
[in]handlerA function pointer to the user callback function to execute on the event trigger.
Since
1.0
void iMS::SignalPath::SignalPathEventUnsubscribe ( const int  message,
const IEventHandler handler 
)

Unsubscribe a callback function handler from a given SignalPathEvents event.

Removes all links to a user callback function from the Event Trigger map so that any events that occur in the SignalPath object following the Unsubscribe request will no longer execute that function

Parameters
[in]messageUse the SignalPathEvents::Event enum to specify an event to unsubscribe from
[in]handlerA function pointer to the user callback function that will no longer execute on an event
Since
1.0
bool iMS::SignalPath::SwitchRFAmplitudeControlSource ( const AmplitudeControl  src)

Selects the amplitude control source for all 4 RF channels.

Selects the analogue control source to apply to the RF mixer in the output signal conditioning for all 4 RF Channels: digital pot 1, digital pot 2, external analogue modulation or turned off

Parameters
[in]srcThe Amplitude Control Source selection
Returns
true if the source select update request was sent successfully
Since
1.0
bool iMS::SignalPath::UpdateDDSPowerLevel ( const Percent power)

Scales the DDS device (Direct Digital Synthesis RF signal generator) power up & down.

The RF signal generator device on the Synthesiser converts frequency, amplitude and phase data into the 4 RF signals that drive the output of the Synthesiser. The device can be configured to scale the analogue output power up & down. This function performs the power scaling between 0% (minimum power) and 100% (maximum power)

Parameters
[in]powerthe percentage of maximum power at which the DDS should drive RF signals into the output signal conditioning
Returns
true if the power update request was sent successfully
Since
1.0
bool iMS::SignalPath::UpdateEncoder ( const VelocityConfiguration velcomp)

UpdateEncoder enables the Encoder velocity offset correction and updates the parameters.

Calling this function will enable the velocity correction capability of the Synthesiser or update the parameters of the velocity correction according to the values in the VelocityConfiguration struct

Parameters
[in]velcompContains the values with which to configure the Velocity Correction process
Returns
true if the Encoder Update request was sent successfully
Since
1.4
bool iMS::SignalPath::UpdateLocalToneBuffer ( const ToneBufferControl tbc,
const unsigned int  index,
const SignalPath::Compensation  AmplitudeComp = SignalPath::Compensation::ACTIVE,
const SignalPath::Compensation  PhaseComp = SignalPath::Compensation::ACTIVE 
)

Use these functions to output tones from the Local Tone Buffer, control their selection and compensation.

The Local Tone Buffer in the Synthesiser stores a set of 256 TBEntry's, each comprising of a FAP per each of the 4 output channels. The LTB can be inserted in the Synthesiser output signal path, replacing the Image data deriving from a connected Controller. Multiple ToneBuffers can be stored in Synthesiser non-volatile memory and any one of these can be recalled by host software and if one of them is marked with the filesystem 'default' flag, it will be loaded into the LTB at startup causing the Signal Path to be routed to the LTB.

In order to determine which method is used to provide the tone index for the LTB (Host Software, External 16-entry and External 256-entry), update the LTB buffer using one of the methods containing a ToneBufferControl parameter.

In order to change the currently selected LTB index (only in Host Software control mode), use one of the methods containing the index parameter.

The LTB outputs may be injected into the Synthesiser signal path either before or after the CompensationTable Look-Up Table. If before (true), amplitude compensation is applied to the signal amplitudes, if after (false), use the methods containing the AmplitudeCompensation parameter.

Parameters
[in]tbcSelect LTB Control Source
[in]AmplitudeCompindicates whether to apply LUT Compensation to Tone amplitude data
[in]PhaseCompindicates whether to apply LUT Compensation to Tone phase data
[in]indexIn Host Software control mode, select which LTB index to use
Returns
true if update was successful
Since
1.1
bool iMS::SignalPath::UpdateLocalToneBuffer ( const ToneBufferControl tbc)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bool iMS::SignalPath::UpdateLocalToneBuffer ( const SignalPath::Compensation  AmplitudeComp,
const SignalPath::Compensation  PhaseComp 
)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bool iMS::SignalPath::UpdateLocalToneBuffer ( const unsigned int  index)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bool iMS::SignalPath::UpdatePhaseTuning ( const RFChannel channel,
const Degrees phase 
)

Applies a constant Phase offset to one of the 4 RF Channels.

The 4 RF Channels can be 'tuned' to offset phase discrepancies in, for example, cable length differences by setting up a constant phase offset that will be added to the RF signal output of that channel

Parameters
[in]channelThe RF Channel to apply the offset to
[in]phaseThe amount of constant phase offset to apply, in degrees
Returns
true if the phase offset update request was sent successfully
Since
1.0
bool iMS::SignalPath::UpdateRFAmplitude ( const AmplitudeControl  src,
const Percent ampl 
)

Scales the Digital Potentiometer mixer drive level up & down.

The 2 digital potentiometers on the Synthesiser can be selected to apply a DC drive level to the IF input of a wideband RF mixer in the output channel signal conditioning, thereby acting as an amplitude control voltage.

This function sets the drive level of the 2 digital potentiometers. The AmplitudeControl input determines which potentiometer is updated, if it is set to anything other than WIPER_1 or WIPER_2, the request is ignored and the function returns false.

Parameters
[in]srcWhich of the two digital potentiometers to update
[in]amplthe percentage of maximum amplitude scaling to update the potentiometer to
Returns
true if the amplitude update request was sent successfully
Since
1.0

The documentation for this class was generated from the following file: