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

Provides System Management functions not directly related to RF signal generation or signal path control. More...

#include <include\SystemFunc.h>

Public Types

enum  UpdateClockSource { UpdateClockSource::INTERNAL, UpdateClockSource::EXTERNAL }
 Determines whether DDS Synthesiser IC should have its update signal driven by the Synthesiser internal circuitry or from an external source (for synchronising the device to a system clock) More...
 
enum  TemperatureSensor { TemperatureSensor::TEMP_SENSOR_1, TemperatureSensor::TEMP_SENSOR_2 }
 There are two available temperature sensors in the Synthesiser System. More...
 
enum  PLLLockReference { PLLLockReference::INTERNAL, PLLLockReference::EXTERNAL_FIXED, PLLLockReference::EXTERNAL_AUTO, PLLLockReference::EXTERNAL_FAILOVER }
 Synthesiser Master Clock Reference Mode. More...
 
enum  PLLLockStatus {
  PLLLockStatus::EXTERNAL_NOSIGNAL = 0, PLLLockStatus::INTERNAL_UNLOCKED = 4, PLLLockStatus::INTERNAL_LOCKED = 5, PLLLockStatus::EXTERNAL_VALID_UNLOCKED = 8,
  PLLLockStatus::EXTERNAL_LOCKED = 9
}
 Synthesiser Master Clock Status Cast the status value reported to application code from a GetMasterClockStatus() call to PLLLockStatus to determine the current status of the Synthesiser Master Clock. More...
 

Public Member Functions

Constructor & Destructor
 SystemFunc (const IMSSystem &ims)
 Constructor for SystemFunc Object. More...
 
 ~SystemFunc ()
 Destructor for SystemFunc Object.
 
RF Amplifier Master Switches

These software switches drive signal lines in the Synthesiser which connect through to the RF Amplifier and turn on or off the high power RF Amplifier, and selectively enable pairs of RF Channels within it.

bool EnableAmplifier (bool en)
 Enables the RF Amplifier. More...
 
bool EnableExternal (bool enable)
 Enables the External Equipment Optoisolator. More...
 
bool EnableRFChannels (bool chan1_2, bool chan3_4)
 Selectively enables channels 1&2 and channels 3&4. More...
 
Pixel Interface Checksum Error Counter

The Fast Pixel Interface between the iMS Controller and iMS Synthesiser is protected by a simple checksum. Any errors that accumulate on the interface are recorded in a counter which can be read and reset from software. If the counter is non-zero, an LED can be configured to light on the Synthesiser - see function Auxiliary::AssignLED().

Parameters
[in]Resetclears the error count to zero, extinguishing the LED (default true)
Returns
true if the checksum error count request was sent successfully.
Since
1.1
bool GetChecksumErrorCount (bool Reset=true)
 
DDSUpdateClockSource
bool SetDDSUpdateClockSource (UpdateClockSource src=UpdateClockSource::INTERNAL)
 Configures DDS Update signal source The Direct Digital Synthesiser engine built into the Synthesiser requires an update signal to initiate the output of an RF signal that was previously programmed to the device from an ImagePoint, ToneBufferEntry or CalibrationTone. Normally this is handled internally by the Synthesiser electronics, in which case this should be left to Internal. In certain advanced usage scenarios (typically where the Synthesiser must be synchronised to a user supplied master clock), the update signal may be sourced externally in which case it is derived from the External Image Clock input. More...
 
Startup Configuration Programming
bool StoreStartupConfig (const StartupConfiguration &cfg)
 Store Synthesiser Default Startup Configuration to Non-volatile Memory. More...
 
Temperature Sensing
bool ReadSystemTemperature (SystemFunc::TemperatureSensor sensor)
 Reads the current temperature of the iMS. More...
 
Master Reference Clock

Some iMS Synthesisers feature a PLL (Phase Lock Loop) and high accuracy internal clock oscillator that can either be set to lock the Synthesiser master clock to a precision internal reference (<2ppm) or slave to ane externally supplied reference clock.

If set to slave to an external reference clock, there are three external modes:

1) External Manual: in which the frequency of the externally supplied clock source is programmed into the Synthesiser by application software. 2) External Auto: in which the frequency of the externally supplied clock source is measured by the Synthesiser and the PLL continually updated to lock to that frequency 3) External Failover: a modification of the "Auto" mode in which if the PLL is ever seen to lose its locked state, having previously been locked, it will switch over to the Internal precision crystal oscillator.

In all cases, the externally supplied clock may have any frequency that is a multiple of 10kHz with a minimum supported clock rate of 50kHz and a maximum of 10MHz.

bool SetClockReferenceMode (SystemFunc::PLLLockReference mode, kHz ExternalFixedFreq=kHz(1000.0))
 Sets the Master Reference Clock mode of the Synthesiser to either Internal or on of the External modes. More...
 
bool GetClockReferenceStatus ()
 Returns the current status of the master reference clock function. More...
 
bool GetClockReferenceFrequency ()
 Returns the measured frequency of the external reference clock port. More...
 
bool GetClockReferenceMode ()
 Returns the current mode of the reference clock function. More...
 
Event Notifications
void SystemFuncEventSubscribe (const int message, IEventHandler *handler)
 Subscribe a callback function handler to a given SystemFuncEvents event. More...
 
void SystemFuncEventUnsubscribe (const int message, const IEventHandler *handler)
 Unsubscribe a callback function handler from a given SystemFuncEvents event. More...
 

Communications "Not Healthy Flag"

Since
1.4.1

Communications with an iMS System can be monitored using a "Communications Not Healthy" mechanism. The iMS Controller features a timer with a configurable timeout value which resets each time a message is received from the host. If no message is received from the host within the timeout period, the host communications is considered to be in an "unhealthy" state, meaning that messages were expected but haven't arrived. The iMS System will set the Communications Not Healthy flag in any subsequent message responses that do get sent to the host, in case the problem was a temporary one, to indicate the problem to the host. The host can clear the not healthy flag and take any further action, as necessary.

In addition, if configured to do so, the iMS System can cause a local system-wide reset to attempt to re-initialise the communications, once it registers a Not Healthy condition. This will flush any communications buffers and may restart communications if the problem was a local one. This behaviour is turned off by default.

At the host end, two things must be done:

(1) Host software must be sure to send messages to the iMS System regularly, and well within the timeout limit set by the NHF timer. The message can be any simple request for status information or anything else as required. All messages will reset the timer.

(2) Host software must perform a similar type of check, looking for timed out responses to its requests to identify that communications have failed. It should then take appropriate action, resetting its communications interfaces where possible.

The mechanism is intended for high-reliability applications where uptime is important and service access is limited. It can be disabled completely if required.

enum  NHFLocalReset { NHFLocalReset::NO_ACTION = 0, NHFLocalReset::RESET_ON_COMMS_UNHEALTHY = 1 }
 The action to perform at the iMS System when a Not Healthy condition is registered. More...
 
bool ClearNHF ()
 Clear the Not Healthy Flag once normal service is resumed.
 
bool ConfigureNHF (bool Enabled, int milliSeconds, NHFLocalReset reset)
 Configure the Not Healthy Flag mechanism. More...
 

Detailed Description

Provides System Management functions not directly related to RF signal generation or signal path control.

Author
Dave Cowan
Date
2015-11-03
Since
1.0

Member Enumeration Documentation

The action to perform at the iMS System when a Not Healthy condition is registered.

Enumerator
NO_ACTION 

Do nothing other than set the NHF bit on future responses.

RESET_ON_COMMS_UNHEALTHY 

Perform a system wide reset.

Synthesiser Master Clock Reference Mode.

Since
1.4.1
Enumerator
INTERNAL 

Master Clock uses internal precision frequency reference.

EXTERNAL_FIXED 

Master Clock attempts to phase lock to an externally supplied reference clock with manually configured frequency.

EXTERNAL_AUTO 

Master Clock attempts to phase lock to an externally supplied reference clock whose frequency is automatically determined.

EXTERNAL_FAILOVER 

Master Clock attempts to phase lock to an externally supplied reference clock whose frequency is automatically determined. If the reference frequency measurement goes invalid for > 400ms, switch over to the internal frequency source until the clock reference mode is reprogrammed.

Synthesiser Master Clock Status Cast the status value reported to application code from a GetMasterClockStatus() call to PLLLockStatus to determine the current status of the Synthesiser Master Clock.

Enumerator
EXTERNAL_NOSIGNAL 

No signal detected on external reference clock input. PLL Unlocked.

INTERNAL_UNLOCKED 

Master Clock using internal clock reference but PLL Not Locked (this should only occur temporarily when switching from external to internal mode)

INTERNAL_LOCKED 

Master Clock using internal clock reference and PLL is Locked.

EXTERNAL_VALID_UNLOCKED 

Reference signal detected on external reference clock input but PLL is Not Locked to it (usually due to a frequency mismatch or non-conformal external signal reference)

EXTERNAL_LOCKED 

Reference signal detected and PLL is Locked.

There are two available temperature sensors in the Synthesiser System.

Since
1.4
Enumerator
TEMP_SENSOR_1 

Sensor 1 is adjacent to the RF stage.

TEMP_SENSOR_2 

Sensor 2 is adjacent to the DC power supplies.

Determines whether DDS Synthesiser IC should have its update signal driven by the Synthesiser internal circuitry or from an external source (for synchronising the device to a system clock)

Since
1.1
Enumerator
INTERNAL 

Drive Update Signal internally (default)

EXTERNAL 

Drive Update Signal from external update source.

Constructor & Destructor Documentation

iMS::SystemFunc::SystemFunc ( const IMSSystem ims)

Constructor for SystemFunc Object.

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

The IMSSystem object must exist before the SystemFunc object, and must remain valid (not destroyed) until the SystemFunc 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::SystemFunc::ConfigureNHF ( bool  Enabled,
int  milliSeconds,
NHFLocalReset  reset 
)

Configure the Not Healthy Flag mechanism.

Parameters
[in]EnabledTurns the mechanism on or off (default: on)
[in]milliSecondsThe timeout interval for the NHF timer (default: 500msec)
[in]resetThe behaviour to perform when a the Communications is determined to be "Not Healthy" (default: NO_ACTION)
Returns
true if the configuration request was sent successfully
Since
1.0
bool iMS::SystemFunc::EnableAmplifier ( bool  en)

Enables the RF Amplifier.

Parameters
[in]entrue turns on the RF Amplifier, false turns it off
Returns
true if the enable request was sent successfully
Since
1.0
bool iMS::SystemFunc::EnableExternal ( bool  enable)

Enables the External Equipment Optoisolator.

Parameters
[in]enabletrue turns on the Optoisolator
Returns
true if the enable request was sent successfully
Since
1.1
bool iMS::SystemFunc::EnableRFChannels ( bool  chan1_2,
bool  chan3_4 
)

Selectively enables channels 1&2 and channels 3&4.

Parameters
[in]chan1_2true turns on channels 1 and 2, false turns them off
[in]chan3_4true turns on channels 3 and 4, false turns them off
Returns
true if the enable request was sent successfully
Since
1.0
bool iMS::SystemFunc::GetClockReferenceFrequency ( )

Returns the measured frequency of the external reference clock port.

The external reference clock port is continually monitored, even if the master clock is set to Internal. This function requests the current frequency of any signal connected to the reference clock port. Note that the reference clock measurement function is limited to measure the input clock only as a multiple of 10kHz so this function will not return a value with any finer resolution than that. The value is returned as a real value (double) event and the user should subscribe to the SystemFuncEvents::MASTER_CLOCK_REF_FREQ event to retrieve the result. The returned double represents the frequency of the external reference clock to the closest value of 10kHz.

Returns
true if the frequency reference request was sent successfully
bool iMS::SystemFunc::GetClockReferenceMode ( )

Returns the current mode of the reference clock function.

This function requests from the Synthesiser the current mode in which the reference clock function is operating. The mode is returned as an integer event and the user should subscribe to the SystemFuncEvents::MASTER_CLOCK_REF_MODE event to retrieve the result. The returned integer can be cast to a SystemFunc::PLLLockReference enum to interpret the event integer

Returns
true if the mode request was sent successfully
bool iMS::SystemFunc::GetClockReferenceStatus ( )

Returns the current status of the master reference clock function.

This command issues a status request from the Synthesiser's Master Reference Clock. The status is returned as an integer event and the user should subscribe to the SystemFuncEvents::MASTER_CLOCK_REF_STATUS event to retrieve the result. The returned integer can be cast to a SystemFunc::PLLLockStatus enum to interpret the status integer

Returns
true if the status request was sent successfully
bool iMS::SystemFunc::ReadSystemTemperature ( SystemFunc::TemperatureSensor  sensor)

Reads the current temperature of the iMS.

Some iMS Synthesisers include onboard temperature sensors to monitor the temperature inside the iMS case (note this is different to the temperature readings available using the Diagnostics class that perform temperature readings on the amplifier and AO Device). Call this function to initiate a temperature reading, specifying which sensor to read from. The temperature value will be reported back to the application code using the SystemFuncEvents::SYNTH_TEMPERATURE_1 and SystemFuncEvents::SYNTH_TEMPERATURE_2 events.

Returns
true if the requst to read the iMS temperature was sent successfully
Since
1.4
bool iMS::SystemFunc::SetClockReferenceMode ( SystemFunc::PLLLockReference  mode,
kHz  ExternalFixedFreq = kHz(1000.0) 
)

Sets the Master Reference Clock mode of the Synthesiser to either Internal or on of the External modes.

Specify the desired reference clock mode. If using EXTERNAL_FIXED, also specify the external frequency

Parameters
[in]modeThe reference clock mode to set
[in]ExternalFixedFreqthe frequency of the external reference clock, if using Fixed mode
Returns
true if the mode setting command was sent successfully
Since
1.4.1
bool iMS::SystemFunc::SetDDSUpdateClockSource ( UpdateClockSource  src = UpdateClockSource::INTERNAL)

Configures DDS Update signal source The Direct Digital Synthesiser engine built into the Synthesiser requires an update signal to initiate the output of an RF signal that was previously programmed to the device from an ImagePoint, ToneBufferEntry or CalibrationTone. Normally this is handled internally by the Synthesiser electronics, in which case this should be left to Internal. In certain advanced usage scenarios (typically where the Synthesiser must be synchronised to a user supplied master clock), the update signal may be sourced externally in which case it is derived from the External Image Clock input.

Parameters
[in]srcINTERNAL for most scenarios, set to EXTERNAL for external update signal applications
Returns
true if the request to change update signal source was sent successfully
Since
1.1
bool iMS::SystemFunc::StoreStartupConfig ( const StartupConfiguration cfg)

Store Synthesiser Default Startup Configuration to Non-volatile Memory.

After every power up and reset event, the Synthesiser will inspect the non-volatile memory to see if a startup configuration is present. If it is, the configuration contents are parsed and assigned to their respective control registers. Combining this process with Default Scripts stored in the Filesystem can result in a fully specified standalone operational Synthesiser system with no software connection required. param[in] cfg A const reference to the required configuration behaviour structure. Pre-define the behaviour by setting the config structure fields to requirements.

Returns
true if the request to program the startup configuration was sent successfully
Since
1.1
void iMS::SystemFunc::SystemFuncEventSubscribe ( const int  message,
IEventHandler handler 
)

Subscribe a callback function handler to a given SystemFuncEvents event.

SystemFunc can callback user application code when an event occurs that affects the signal path. Supported events are listed under SystemFuncEvents. 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 SystemFuncEvents event. For the period that a callback is subscribed, each time an event in SystemFunc occurs that would trigger the subscribed SystemFuncEvents event, the user function callback will be executed.

Parameters
[in]messageUse the SystemFuncEvents::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::SystemFunc::SystemFuncEventUnsubscribe ( const int  message,
const IEventHandler handler 
)

Unsubscribe a callback function handler from a given SystemFuncEvents event.

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

Parameters
[in]messageUse the SystemFuncEvents::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

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