Isomet Modular Synthesiser (iMS) API
v1.4.2
iMS API
|
In Tutorial 1(a): Setting up a project and connecting to an iMS you learnt how to set up an iMS project in Visual Studio 2013 with the correct references to the iMS API and library, and wrote a simple program that connected to an iMS system. If you completed that tutorial successfully, you can now continue to create an example image and watch it playing on the iMS RF output.
You will need:
This tutorial will illustrate two of the key concepts required to understand the operation of an iMS System: Compensation Tables and Image Output.
Compensation Tables provide the system designer with a method for adjusting RF drive signal output according to frequency dependent effects in the output signal chain. They can also be used to generate analog and digital outputs for system requirements that are linked to frequency output.
Each table consists of a look-up function of 2^N entries (N can be read from iMS::IMSSynthesiser::Capabilities::LUTDepth). Each entry is linearly spaced from the lowest Frequency supported by the Synthesiser to the highest.
There are four tables: one for amplitude compensation, one for phase steering, one for analog system output and one for digital system output.
For this example, we will create an amplitude table that steps down every 10MHz from 50MHz to 100MHz. This is a contrived example that can act as a template for your own requirements.
In the source code that you created in part 1(a), insert the following code after the comment line "All USER CODE goes here..."
Here, the first line of code creates a new blank compensation table called 'table'. We then attempt to open a file called tutorial1.lut
which contains a previously generated copy of the look-up table. If the application finds it, it will load the contents of the file instead of regenerating them.
If not, a second new table is created this time with the amplitude initialised to a default value of 100%. A for-loop uses CompensationTable::iterator to address each of the points, determining their frequency and adjusting the amplitude to create a 'stairstep' effect at 10MHz intervals as the frequency rises from 50MHz to 100MHz
Once the table is complete, it is saved to disk to enable it to be recalled on the next program run.
The final two lines call the CompensationTable Downloader class, initialising it with the newly created table, then start it downloading the table to the hardware.
A primary feature of the iMS System is its ability to store and playback one or more RF images. An RF image can be downloaded to an iMS Controller and then played back under the control of an internal or externally supplied clock, initiated by software or some external trigger signal. Each image contains a sequence of 'image points', from just a few up to many millions. Each image point contains information for Frequency, Amplitude and Phase (known as an 'FAP triad') for up to 4 RF channels plus some synchronous data that can be output externally to drive other hardware in the system. Some Controllers support multiple images that can be arranged into complex sequences - these are called 'image files.'
For this tutorial, we will generate a simple single 4096-point image which linearly ramps up from 50MHz to 100MHz then loops around and repeats indefinitely. We will then play this back at a slow 1kHZ internal clock rate so that the output ramp time is 4.1sec which can be observed on test equipment. It is a contrived example, barely useful in AO equipment, but which serves to explain the fundamental principles.
Copy and paste the following source code after the code you added in part 1:
In the first few lines, an empty image is created along with a single FAP triad initialised to 50MHz, 100% amplitude with no phase offset. the upper and lower bounds of the sweep are defined as 'lf' and 'uf' MHz objects.
A for-loop is used to create the 4,096 image points that will make up the new image. First the frequency is set according to its linear position in the ramp sweep. Then, a new image point is created from the FAP triad (the triad is replicated across all 4 channels of the image point), and it is appended to the Image.
Finally, the image's default internal clock rate is declared to be 1kHz.
That's it - all that is required to create a simple image!
To use the image, it must be downloaded to the Controller then instructed to play back. Some Controllers do not support simultaneous playback and download, so the next two lines create an ImagePlayer object that is just used to send a Stop command to the hardware. The stop command is issued with a StopStyle::IMMEDIATELY property to terminate any ongoing playback straightaway. If this wasn't used, the default behaviour would be to stop the playback only after the final point in the image/
Following on from this, an ImageDownload object is created and initialised with the image we have just generated. This uses the same large binary object mechanism (see BulkTransfer.h) as the Compensation Table downloader to send the image to memory in the Controller.
Next, we create an ImagePlayer with its configuration initialised to repeat the image forever, until stopped on request by software. We also want to add in a pause of half a second after each repeat so it is clear to the observer that the image has completed.
The download and playback configuration done, we just await confirmation from the user before instructing the iMS and its Image Player to begin playing.
Connect a spectrum analyser or oscilloscope to any of the RF outputs on the iMS System. You should observe the following pattern:
std::cin.get()
line so that the example runs smoothly from image download into playback without user input and you will find that playback may not start on some hardware configurations.idl.StartDownload()
asks the Image Downloader to begin the download process. In fact, the function spawns a thread in the background that performs the bulk download of the image data, and returns immediately to user code. The API can trigger callbacks to the user application that indicate when a download has started, finished and whether it was successful or failed. It can also perform a post-download verify to check that the image contents were downloaded correctly. We will cover these in a later tutorial when we look at the Message Handling system.player.Play()
function is called, the ImagePlayer realises it cannot continue, and returns without beginning the image playback.Play()
function returns true
on a successful play attempt, so the simplest solution is to replace the code line player.Play()
; with while
(!player.Play()); This will repeat the function call until it succeeds. For a more elegant solution that doesn't block user code, see the future tutorial on Message Handling.