winIDEA SDK
Installation and usage of winIDEA SDK

Introduction

This document contains instructions for installation and usage of winIDEA SDK for all supported languages. Common steps are described in the first section, language specific instructions are given next. The following languages are currently supported:

General instructions

Documentation

API documentation with samples is accessible from winIDEA menu Help | Contents. It is also part of SDK zip file, which can be downloaded from iSYSTEM web page. In this case unzip also ZIP files in folder documentation. Then open file index.html in web browser. Save its location to browser bookmarks for future reference.

Installers and libraries

SDKs also contain installers or libraries, which we need to use isystem.connect from other languages. The exact instructions are given for each language below.
If you'd like to know the version number of the already installed module, print string returned by function getModuleVersion(). See instructions for each language for an example.

Examples

Each SDK has examples, which demonstrate usage of isystem.connect and testIDEA. All examples are based on winIDEA project stored in folder targetProjects. This folder contains sources, winIDEA workspace file (*.xjrf), and download file. The sources enable you to change and compile projects, but if you don't have compiler available, you can still try scripts and testIDEA with the bundled download file.
If you'd like to build this project for your target, edit project settings in winIDEA. There is also flag USE_FLOAT_TYPE in projectDefs.h, which you can comment if you don't have floating point libraries available for your compiler.
Additional change you may need to make is changing stack addresses in testIDEA File | Properties | Stack usage or deactivate stack measurements.

List of target example projects:

  • Workspace SampleSTM32.xjrf contains project for STM32.
  • Workspace SampleSTM32-qemu.xjrf contains project, where winIDEA is configured to run code in emulator. The emulator does not support analyzer (coverage and profiler).

Folder itest

This folder contains support files for isystem.test API and testIDEA:

  • templates for Python script generation
  • XML Style sheets and CSS files for test reports
  • XML Schema for test reports

Which language?

If you can't decide about which language to use for winIDEA SDK, this section may help you. Usually the following criteria is important:

Which language do you already know and use?


Many people decide accoding to this answer. It enables a quick start, but may not be the best in long term. Don't be afraid of learning new computer languages.

What do you want to implement?

If you only want to write short scripts for testing and development, scripting language is preferred, because it offers the highest productivity. If you intend to write full blown IDE on top of winIDEA SDK, then some of compiled, statically typed languages would be better.

For scripting languages we recommend Python. It is integrated into winIDEA, it has very readable syntax and many good libraries, and it is one of the most popular languages these days.

For compiled languages we recommend Java. It is used by Eclipse so also our Debug plug-in for Eclipse is implemented in Java. Most development tools for Java are free and it also has many good libraries. Java libraries can be used by other languages running in JVM, like Groovy (scripting) and Kotlin. They are also used in Matlab.


Language Modules



Python

Documentation

Folder documentation in the downloaded zip file contains file isystem-connect-python-doc.zip. This file contains documentation for isystem.connect utilities for Python and instructions for using isystem.connect from Python. If SDK was installed with winIDEA setup, this file is already unzipepd.

Installation

Installation instructions are available here.

To see version of the installed isystem.connect module, execute the following code: 

import isystem.connect as ic
print(ic.getModuleVersion())

Examples

Folder examples contains several example scripts. They can be run from winIDEA or from command line. Examples using analyzer do not run when emulator is used.



Java

Documentation

This folder contains API documentation.

Installation

To create your own project, copy files from lib folder to your Java project, and add the code, which loads the dll to your code. See examples/IConnectJavaSample, method main() for example on how to load the dll.

Add also the jar file from lib folder to your classpath.

To see version of the installed isystem.connect module, execute the following code: 

System.out.println("Version of isystem.connect: " +
                   si.isystem.connect.connect.getModuleVersion());

Examples

Folder examples contains Eclipse project, which you can add to Eclipse workspace and build and run it.


jdoc and IConnectJavaSource.zip

jdoc folder contains API documentation generated with Javadoc tool. Please note that this documentation is autmatically translated from C++ code comments in doxygen format. Since Doxygen supports more tags than Javadoc, translated result is not 100% equal to the original

  • especially some formatting may be lost. Therefore it is recommended to use API doc in the documentation folder as a primary source. However, documentation in jdoc folder can be used when seeking for help from Java IDE, for example Eclipse.

File IConnectJavaSource.zip contains zipped sources with code comments, which can be used by Java IDE.

Eclipse configuration

Eclipse can show Javadoc API and method comments in Help view and a tootip-like window. This can be acheived by right clicking the project in Package Explorer view and selecting Java Build Path | Libraries | IConnectJNI.jar, properties Source attachment and Javadoc location as shown in the image below:

Set values for 'Source attachment' and 'Javadoc location' for IConnectJNI.jar in build path.

Source attachment should point to IConnectJavaSource.zip file from SDK, and Javadoc location should point to jdoc folder from SDK.



C#

Documentation

This folder contains API documentation.

Installation

To use winIDEA SDK from C# application, you have to add libraries from lib folder to the project. Add .NET assembly IConnectCSLib.dll to References section of your C# project.

It is very important to use the right isystemConnect.dll from SDK lib folder: either from lib/win32 or lib/x64. Depending on your target platform, you must
copy the right isystemConnect.dll to your project or other folder on Windows DLL search path. The BadImageFormatException is most likely indication of wrong isystemConnect.dll version.

To see version of the installed isystem.connect module, execute the following code: 

Console.WriteLine("\nVersion of isystem.connect: " + isystemConnect.getModuleVersion());

Examples

Example in examples folder is build with Visual Studio 2017.



Matlab

isystem.connect for Matlab is based on isystem.connect for Java. The API is therefore the same, but there are few exceptions:

  • libraries can not be loaded directly with java.lang.System.loadLibrary() call. Use the provided ICLoader class from ISystemConnectLoader.jar instead. See also examples.
  • enumeration constants can not be accessed directly as in Java, but you have to use javaMethod call instead. For example: 
    IConnectDebug.EAccessFlags.fMonitor
    can be accessed with: 
    fMonitorEnum = javaMethod('valueOf',
                          'si.isystem.connect.IConnectDebug$EAccessFlags',
                          'fMonitor');

    Documentation

Folder documentation contains API documentation. Unzip it and bookmark file index.html in your web browser.

Installation

Unzip the SDK file, then copy the lib folder to your preferred location. Then you should add ISystemConnectLoader.jar and IConnectJNI.jar to Matlab's static or dynamic Java classpath path and load the library. This procedure is described below, but it is also implemented in the example script icInit.m, which is part of the SDK.

Loading the library

Before using winIDEA SDK API, we must load the library. java.lang.System.loadLibrary() call may not be executed from Matlab window, but we should use si.isystem.connect.mutil.ICLoader instead. Example: 

javaaddpath('..\lib\ISystemConnectLoader.jar');
javaaddpath('..\lib\IConnectJNI.jar');
loader = si.isystem.connect.mutil.ICLoader;

Now we can load native libraries from paths stored in java.library.path. It is important to use '/' as separator here. Current directory ('.') should be in java.library.path, and we must NOT specify the extension. Example: 

loader.loadLibraryFromSysPath('../lib/IConnectJNI');

Another possibility is loading from absolute path. In this case we must also specify extension .dll, for example: 

loader.loadLibraryAbs('d:\lib\IConnectJNI.dll');

Setting of java.library.path in Matlab is described in Matlab documentation. We can get the current value in Matlab with: 

java.lang.System.getProperty('java.library.path')

Please note that IConnecJNI.dll and IConnectJNI.jar files are the same as for Java, so we may keep only one copy of these two libraries on the system. See also the example script icInit.m from the SDK.

Examples

Folder examples contains m-files, which we can run and use as startup for our projects. This folder also contains the file librarypath.txt, which sets the java.library.path system variable, if we start Matlab in this directory. Otherwise we have to add the current directory to librarypath.txt, or modify the file icInit.m to load the isystem.connect native library IConnectJNI.dll from absolute path.

To run examples, first run the script icInit.m to load required libraries. Then you can run other scripts.

Typical script

The first step in using winIDEA SDK is establishing connection to winIDEA: 

cMgr = si.isystem.connect.ConnectionMgr();
cMgr.connect();

Then we instantiate other classes, depending on operations we want to perform. For example, if we want to execute debug operations (reset, run, runUntilFunction, ...), we instantiate class CDebugFacade: 

debug = si.isystem.connect.CDebugFacade(cMgr);

Now we can call methods: 

debug.download();
debug.runUntilFunction('main');
debug.waitUntilStopped();

Documentation of all classes and their methods is available at iSYSTEM web page.

Simulink

There are no general Simulink blocks provided with isystem.connect calls, but you can use Matlab function block and call isystem.connect methods from there.