Isomet Modular Synthesiser (iMS) API  v1.4.2
iMS API
Tutorial 1(a): Setting up a project and connecting to an iMS

Tutorial 1(a): Setting up a project and connecting to an iMS

This tutorial will demonstrate a simple example for creating a new software project in Visual Studio 2013/2015, how to reference the API and write a simple application that connects to the iMS. In part (b) we extend the example to play back an image that can be observed on a spectrum analyzer or oscilloscope.

Prerequisites

You will need to have available:

Step 1

Connect the iMS system to your PC's USB port. Apply power to the iMS.

Start up Visual Studio 2013. From the "Community 2013" window, press Start -> New Project... Expand the Installed Templates to see under "Visual C++" -> "Win32" and select "Win32 Console Application"

tut1_step1.jpg
New Project Wizard
Choose a location to suit you and give the project a name such as "iMS_tutorial1". Make sure the "Create a directory for solution" box is checked.

Step 2

In the Application Wizard that comes up, select "Next" (not "Finish") then ensure the box next to "Empty Project" is checked. Click Finish.

tut1_step2.jpg
Create Empty Project

Step 3

Right click on "Header Files", select Add -> Existing Item...

tut1_step3.jpg
Add Existing Item
then navigate to where you have downloaded the Isomet iMS SDK, in the /include subdirectory and select all of the header (*.h) files. Click "Add".

tut1_step3b.jpg
Add API Header files

Step 4

Right Click on "Source Files", select Add -> New Item...

tut1_step4.jpg
Add New Source File
In the Add new item dialog box, select "C++ File (.cpp)" and click Add. You can call the source file anything you like, but the default "Source.cpp" is fine.

tut1_step4b.jpg
Add New C++ File

Step 5

The new source file will open in the main editor window in Visual Studio. Add the following code to get started:

// These are the API header files we will need in this tutorial
#include "ConnectionList.h"
#include "IMSSystem.h"
#include "SystemFunc.h"
#include "ImageOps.h"
#include "Compensation.h"
// These are the C++ standard library headers we will need
#include <cstdio>
#include <cstdlib>
#include <iostream>
#include <fstream>
#include <thread>
#include <vector>
// All API classes are defined in the iMS namespace. For convenience, we can declare this here
using namespace iMS;
int main(int argc, char* argv)
{
// End application with success code
std::cout << "Press ENTER to finish";
std::cin.get();
return 0;
}

Step 6

We now have a blank source file to work in, but we need to configure Visual Studio to know how to compile against the software library. Right click against the project name (iMS_tutorial1 - the line BELOW "Solution 'iMS_tutorial1'") and select properties.

tut1_step6.jpg
Additional Include Directories
Select "Configuration Properties -> C/C++ -> General" and next to "Additional Include Directories" click the arrow to the right of the drop down box and "<Edit...>". Click the icon for "New Line" and the "..." button on the right to bring up a "Select Directory" dialog box.

tut1_step6b.jpg
Select Directory
Browse to the folder where the SDK header files were included (/include) and click Select Folder then "OK".

Step 7

From the Property Pages, now expand "Linker -> General" and select "Additional Library Directories" and go through the same process to add a reference to the SDK folder containing the 32-bit DLL (/lib/i386)

tut1_step7.jpg
Select DLL Directory
In the Property Pages, navigate to "Linker -> Input" and click on the arrow next to "Additional Dependencies" followed by "Edit...". In the text box type in "iMSLibrary_dbg.lib" This is a reference to the 32-bit debug mode DLL which you can use for application development. Click OK then OK again to close the property pages.

tut1_step7b.jpg
Additional Dependencies

Step 8

The last step in setting up the project is in Windows Explorer to copy the .dll iMSLibrary_dbg.dll from /lib/i386 to the project folder you created: (e.g. C:\temp\iMStutorial1\iMStutorial1). It should be in the same folder as the source file Source.cpp.

Step 9

Now we will add some code to search for an iMS System and try to connect to the first one that we find

In the main function, copy the following code and insert before the "return 0;" line:

// These two lines initialise the iMS Connection and scan the host for all connected iMS's
ConnectionList * connList = new ConnectionList();
std::vector<IMSSystem> fulliMSList = connList->scan();
IMSSystem myiMS;
if (fulliMSList.size() > 0) {
// Get the first iMS that we find
myiMS = fulliMSList.front();
// and connect to it.
myiMS.Connect();
std::cout << "Connecting to IMS System on port: " << myiMS.ConnPort() << " ... ";
if (!(myiMS.Synth().IsValid()) || !(myiMS.Ctlr().IsValid())) {
// There was a problem trying to initialise the iMS. We didn't find a valid system.
std::cout << "FAILED!" << std::endl;
// Tidy up and return with a failure code
delete connList;
std::cout << "Press ENTER to finish";
std::cin.get();
return -1;
}
else
{
// Everything OK.
std::cout << "SUCCESS!" << std::endl;
// All USER CODE goes here.
std::cout << "Press ENTER to finish";
std::cin.get();
}
}
else {
// There was a problem trying to discover an iMS. Check the USB connection and power.
std::cout << "No iMS Found." << std::endl;
// Tidy up and return with a failure code
delete connList;
std::cout << "Press ENTER to finish";
std::cin.get();
return -1;
}
// All done for now. Disconnect from the iMS and tidy up
myiMS.Disconnect();
delete connList;
return 0;
}

This code will create a connection list (see ConnectionList.h) that knows how to communicate with an iMS system on all supported connection types. We then ask the list to scan these connections to discover any iMS's connected to the host. Any that it finds are returned in an array complete with all the information that we were able to find out about them (configuration, model numbers, serial numbers etc). If none were found, the application aborts and exits.

In this example, the first iMS in the array is connected to, but you could be more specific by interrogating the iMS's serial numbers or other data - see the documentation for IMSSystem.h for more detail.

The application displays the message "Connecting to IMS System on port: " with a string descriptor of the connection port, and tests that it has a valid connection with both a synthesiser and a controller. If not, it will abort and warn the user.

You can run this application (press F5) and it should show the "Connecting" message then exit successfully. Your first iMS application!

Continue to Tutorial 1(b): Programming and Playing an Image