Isomet Modular Synthesiser (iMS) API
v1.4.2
iMS API
|
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().
| ||||
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" | |
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... | |
Provides System Management functions not directly related to RF signal generation or signal path control.
|
strong |
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. |
|
strong |
Synthesiser Master Clock Reference Mode.
|
strong |
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.
|
strong |
|
strong |
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)
Enumerator | |
---|---|
INTERNAL |
Drive Update Signal internally (default) |
EXTERNAL |
Drive Update Signal from external update source. |
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.
[in] | ims | A const reference to the iMS System |
bool iMS::SystemFunc::ConfigureNHF | ( | bool | Enabled, |
int | milliSeconds, | ||
NHFLocalReset | reset | ||
) |
Configure the Not Healthy Flag mechanism.
[in] | Enabled | Turns the mechanism on or off (default: on) |
[in] | milliSeconds | The timeout interval for the NHF timer (default: 500msec) |
[in] | reset | The behaviour to perform when a the Communications is determined to be "Not Healthy" (default: NO_ACTION) |
bool iMS::SystemFunc::EnableAmplifier | ( | bool | en | ) |
Enables the RF Amplifier.
[in] | en | true turns on the RF Amplifier, false turns it off |
bool iMS::SystemFunc::EnableExternal | ( | bool | enable | ) |
Enables the External Equipment Optoisolator.
[in] | enable | true turns on the Optoisolator |
bool iMS::SystemFunc::EnableRFChannels | ( | bool | chan1_2, |
bool | chan3_4 | ||
) |
Selectively enables channels 1&2 and channels 3&4.
[in] | chan1_2 | true turns on channels 1 and 2, false turns them off |
[in] | chan3_4 | true turns on channels 3 and 4, false turns them off |
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.
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
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
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.
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
[in] | mode | The reference clock mode to set |
[in] | ExternalFixedFreq | the frequency of the external reference clock, if using Fixed mode |
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.
[in] | src | INTERNAL for most scenarios, set to EXTERNAL for external update signal applications |
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.
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.
[in] | message | Use the SystemFuncEvents::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::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
[in] | message | Use the SystemFuncEvents::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 |