Isomet Modular Synthesiser (iMS) API
v1.4.2
iMS API
|
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 &l) |
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:
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:
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... | |
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.
|
strong |
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.
|
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.
Enumerator | |
---|---|
ACTIVE |
Use the Compensation Look-up Path. |
BYPASS |
Do not use the Compensation Look-up Path. |
|
strong |
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.
|
strong |
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)
|
strong |
The Synchronous Output to which to assign Synchronous Data.
|
strong |
Selects a source of Synchronous Output Data.
|
strong |
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.
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. |
|
strong |
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.
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.
[in] | ims | A const reference to the iMS System |
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.
bool iMS::SignalPath::ClearTone | ( | ) |
Stops the tone playback and restores the signal path configuration to the Controller and Compensation Tables.
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.
[in] | delay | the number of nanoseconds to delay the onset of synchronous digital output data |
[in] | pulse_length | the width of the digital output data pulse (or zero to disable) |
bool iMS::SignalPath::DisableEncoder | ( | ) |
Turns off the Velocity Compensation process.
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.
[in] | amplComp | Set to SignalPath::Compensation::BYPASS or SignalPath::Compensation::ACTIVE for amplitude compensation (frequency dependent correction) |
[in] | phaseComp | Set to SignalPath::Compensation::BYPASS or SignalPath::Compensation::ACTIVE for phase compensation (frequency dependent beam steering) |
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.
[in] | XYCompEnable | Set to true to enable X/Y style phase beam steering (split channels) |
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.
[in] | chan | which of the two encoder channels to request the velocity from (X or Y). |
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.
[in] | fap | a FAP triad specifying the output tone to be played back. |
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.
[in] | reversal | Set true to enable the channel reversal (Channel 1 outputs Channel 4 data and vice versa) |
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.
[in] | message | Use the SignalPathEvents::Event enum to specify an event to subscribe to |
[in] | handler | A function pointer to the user callback function to execute on the event trigger. |
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
[in] | message | Use the SignalPathEvents::Event enum to specify an event to unsubscribe from |
[in] | handler | A function pointer to the user callback function that will no longer execute on an event |
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
[in] | src | The Amplitude Control Source selection |
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)
[in] | power | the percentage of maximum power at which the DDS should drive RF signals into the output signal conditioning |
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
[in] | velcomp | Contains the values with which to configure the Velocity Correction process |
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.
[in] | tbc | Select LTB Control Source |
[in] | AmplitudeComp | indicates whether to apply LUT Compensation to Tone amplitude data |
[in] | PhaseComp | indicates whether to apply LUT Compensation to Tone phase data |
[in] | index | In Host Software control mode, select which LTB index to use |
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.
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
[in] | channel | The RF Channel to apply the offset to |
[in] | phase | The amount of constant phase offset to apply, in degrees |
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.
[in] | src | Which of the two digital potentiometers to update |
[in] | ampl | the percentage of maximum amplitude scaling to update the potentiometer to |