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
Documentation with examples is accessible from winIDEA menu Help | Contents. It is also part of the 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 API 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 API 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 according 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 plugin 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 APU utilities for Python and instructions for using isystem.connect API from Python. If SDK was installed with winIDEA setup, this file is already unzipepd.
Installation
Installation instructions are available in winIDEA Help.
To see version of the installed isystem.connect API 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 the Debugger 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 API 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:
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 API 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
winIDEA SDK for Matlab is based on isystem.connect API 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.jarinstead.See also examples. enumeration constants can not be accessed directly as in Java, but you have to use
javaMethodcall 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, 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 API calls, but you can use Matlab function block and call isystem.connect methods from there.
LabVIEW
This Getting Started Guide assumes you are familiar with both National Instruments LabVIEW and iSYSTEM emulators and winIDEA IDE.
Concept
isystem.connect for LabVIEW includes a C# library to link LabVIEW graphical programming environment to winIDEA. It provides the user with means to interact with the program running on an embedded CPU.
isystem.connect will connect to the winIDEA through a TCP/IP based interprocess layer which allows LabVIEW to run on a different host PC than winIDEA.
System Requirements
isystem.connect for LabVIEW requires:
• winIDEA 2005 (build 9.5.61 or later)
• LabVIEW, which supports loading of .NET assemblies
Configuring winIDEA
Before you start using isystem.connect in LabVIEW, make sure a winIDEA workspace is properly configured for your target application. Connect the emulator to the target system and verify that your application is running properly under emulator control. See also winIDEA user manual about setting up the debugging environment.
Preparing isystem.connect SDK
isystem.connect API support for LabVIEW is implemented with the use of C# SDK. Download the latest SDK from the official website: winIDEA testIDEA APIs. From SDK folder copy the following files to your project directory:
• IConnectCSLib.dll and
• isystemConnect.dll
Choose the win32 or x64 version depending on your LabVIEW version. Both files need to be copied in the same folder. If they are not in the project directory, path to the dlls has to be explicitly set in Tools / Options… / Paths. Both files need to be unblocked, otherwise they won’t be successfully loaded in LabVIEW. To unblock a file, right-click the file and choose Properties. In General tab click Unblock. Click OK to save the changes.
Using isystem.connect Library
Create a new LabVIEW project. To use isystem.connect, open the Block Diagram and bring up the Functions panel. Open the Connectivity / .NET pane. Blocks from this pane may be used to utilize isystem.connect functionality.
Example
To connect to / open winIDEA, ConnectionMgr object has to be created. In order to do so, choose the Constructor Node block and place it on the Block Diagram. .NET Constructor selection window will pop-up. Click Browse… to search for the location of the IConnectCSLib.dll.
Once the IConnectCSLib.dll assembly is chosen, assembly objects will be displayed in the selection menu. Choose the ConnectionMgr object and select the desired constructor. Click OK to confirm.
To call a method from this class, create an Invoke Node block and wire the ConnectionMgr reference to the .NET Invoke Node. Invoke Node will be renamed to the reference class name and the desired method can be selected from the Method list. To connect to the last opened winIDEA / open winIDEA, use the connectMRU method.
ConnectionMgr object is needed to create other controllers, for example to open a workspace, use the CWorkspaceController:
To close winIDEA use the disconnect method from the ConnectionMgr object:
Troubleshooting
If a connection to winIDEA can not be established, check whether the isystem.connect interface has been disabled. In winIDEA open the Tools/Options/isystem.connect dialog and make sure the isystem.connect interface is enabled.
Note: This is a per-user setting. Once enabled, you can connect to winIDEA independently of the workspace used.
The isystem.connect interprocess communication layer relies on the TCP/IP protocol. While this protocol allows great flexibility, many systems and network configurations block all but the most common TCP ports for security reasons. TCP Connection Port Range specifies the range of TCP ports on which winIDEA will try to establish the isystem.connect service. If you are running multiple instances of winIDEA, every winIDEA will use one TCP port. The default port values should work fine – if this is not the case, check any firewall setting that might affect the host PC. UDP Discovery Port specifies a UDP port on which all running instances of winIDEA will respond to broadcast queries. Same firewall restrictions as for TCP ports apply here. Limit number of clients allows for limitation of allowed clients on a single winIDEA instance. If multiple clients are connected to winIDEA, their actions might conflict and/or result in lower response time. Note that unlike other settings in this dialog, this is a per-workspace setting.