VSPE

VSPE

Thank you for using Eterlogic.com products !

See also:� General description� Virtual serial ports pinout� Usage tips and scenarios� User interface� VSPE API� Command line� Known limitations and bugs� Contacting� User license agreement.� Version history� Frequently asked questions� Credits

Copyright (C) 2008-2009 Eterlogic.com. All rights reserved.

General description

VSPE main purpose

Virtual Serial Ports emulator (VSPE) is intended to help people to deal with such a thing as a serial port. Nowadays, serial ports are not used widely anymore. The reason is simple: it is a quite old stuff. Modern hardware devices as a rule connect to computers via high-speed USB ports and sometimes install their own UsbToCom driver. Serial ports are not installed in the most of new notebooks.

So why was VSPE created?

� There are plenty of specific devices that require RS232 or RS422 compatible serial ports. VSPE can help developers to create and debug applications without real hardware installed.

� Compatibility with old applications. VSPE can help people to make data stream from any source (like TCP connection, USB port and so on) visible to any program via virtual serial port.

� To create a lot of virtual serial ports working simultaneously. You can do it without installing serial ports extension board.

� To share serial port for many applications.

VSPE distinctive characteristics

VSPE has limitations described in the Known limitations and bugs section.

At current stage our main goals are:

� To provide binary data exchange between applications or devices. � To create original solutions. The Connector and the DataSplitter devices are obvious examples of such solutions: they create COM ports that can be opened more

that once. � To provide easy user interface.

Product status

VSPE current status is beta.

Product key features:

� Virtual device: connector � Virtual device: data splitter � Virtual device: pair � User mode device: TcpServer � User mode device: TcpClient � User mode device: Serial Redirector � User mode device: UDP Manager � User mode device: Bridge � Python scripting system � x86 and x86_64 processor architecture support � VSPE API (C/C++ header and static library) for native language developers � VSPE API Python bindings for Python developers � VSPE API COM interface

Requirements

� Operating system: Microsoft Windows 2000, XP, Vista

License

Virtual serial ports emulator project


of 28

10/1/2013file:///C:/Users/Administrador/AppData/Local/Temp/~hh48B1.htm

Because of Microsoft Kernel Code signing requirement, we had to purchase digital signature (price is $499 per year), that is why VSPE is not freeware for 64 bit platform. For 32 bit platform though, VSPE is free.

For more detailed information please look at User license agreement.

Feedback

We do appreciate all feedbacks that users send to us. If you have found bug or have idea how to improve VSPE, please do not hesistate to contact us (See Contacting).


Virtual serial ports pinout

Virtual serial ports have standard pinout

(painted in PaintBrush)


Usage tips and scenarios

Here we will describe the most popular VSPE usage scenarios.

Remember that you can combine virtual VSPE devices: for example, Splitter device can be connected to Connector device, and at the same time the Connector device can be exposed to local network using TcpServer device. To achieve your goal you can create chains and combination of VSPE devices. Try and improvise.

See also:� Autorun: command line shortcut� Autorun: run as service� Splitter: Share existing physical serial port between several applications� Virtual machine integration� Network bridge� One-to-Many data redirection


Autorun: command line shortcut

If you want to automatically load virtual devices configuration at Windows startup, please follow the steps shown below:

Step 1.

Create configuration and save it using "File => Save as..." command. Remember config file location (for example it can be c:/config.vspe)

Step 2.

Create windows shortcut. If you have installed VSPE at default location ("C:\Program Files\Eterlogic.com\Virtual Serial Ports Emulator") shortcut parameters must be as shown below:

� Target: "C:\Program Files\Eterlogic.com\Virtual Serial Ports Emulator\VSPEmulator.exe" -minimize -hide_splash c:/config.vspe� Start in: "C:\Program Files\Eterlogic.com\Virtual Serial Ports Emulator"




of 28


Step 3.

Move created shortcut to the "Start Menu\Programs\Startup" folder.

See also:Command line


Autorun: run as service

VSPE can be started as a service using one of App-to-service like programs.

We have successfully checked it with great NSSM tool. It is free and open source. You can download it from http://iain.cx/src/nssm

Step 1.

Install NSSM

Step 2.

Create and save VSPE configuration in file (for example, c:/config.vspe).

Step 3.

Install service: go to NSSM folder and run "nssm install VSPE_Service". Specify path to VSPEmulator.exe and configuration file and click "Install service" button.

Step 4. Run service using "net start VSPE_Service" command or reboot your computer.

That's all.

To uninstall service, go to NSSM folder and run "nssm remove VSPE_Service".




of 28


Splitter: Share existing physical serial port between several applications

Let's assume that you have GPS receiver that is already connected to your computer to the physical serial port COM1.

You have a program that opened COM1 and is now receiving GPS data. And all was fine until you wanted to run another program at the same time to get GPS data. But when you tried to run it, you got some weird message like "Can not open serial port" or something similiar. What happened ? Answer is: serial port can be opened by one application only. Serial port is an exclusive-access device type.

You have several options to deal with this situation:

� Forget about it, close the first program and run the second. And then close the second and run the first... Actually, it is not an option. � Purchase serial ports extension board. Yes, this option can work. But do you want to spend your time and money, look for free PCI slot and install extension

board ? � If you have two serial ports, you can purchase special cable that splits data from the GPS to each serial port. But if you have one physical serial port only or you

need run more than two applications, you can forget about it... � And finally, you can use software solution, for example, VSPE. It is the best option.

Step 1.

Close program that opened serial port.

Step 2.

Run VSPE and create the splitter device. Select COM1 in "Data source serial port" combo box and COM2 in "Virtual serial port".

Step 3.

Now configure all your programs to receive GPS data from COM2.

Now COM2 can be used by up to 8 different applications! Simple, isn't it ?

See also:Splitter device


Virtual machine integration

If you use virtual machine (for example VirtualBox, VirtualPC, VmWare etc), you can create virtual serial port (for example COM10) and specify it as data source for virtual machine.

It may be extremly useful for debugging / development purpose.

Here is VirtualBox settings example (take into consideration that serial port name is: "\\.\COM10"). It is explained in Frequently Asked Questions section.

VirtualBox serial port settings

See also:


of 28


Frequently asked questions


Network bridge

If you want to connect two computers via serial port you need a serial cable.

But it can be inconvenient in many cases: the cable can be too short or the computers can be located in different cities or even countries.

VSPE can solve it: just create "Network bridge" configuration that will allow you to do that. "Network bridge" is a combination of TcpServer, TcpClient and Connector (or Pair) devices.

Below is the example of such configuration that connects two computers via virtual serial port COM5 using network connection.

Computer 1� Create Connector device (COM5) � Create TcpServer device (Local Tcp Port = 5555, Source serial port = COM5)

Computer 2� Create Connector device (COM5) � Create TcpClient device (Remote TCP host = Computer 1 IP address or network name, Remote TCP port = 5555, Source serial port = COM5)

That's it, now both of your computers are connected via virtual serial port COM5.


One-to-Many data redirection

Let's assume that you have COM1, COM2 and COM3.

They can be either real or virtual serial ports (e.g. Connectors or Pairs). If you want to create data exchange: COM1<=>COM2 and COM1<=>COM3, you can use one of the following approaches:

Splitter and Serial Redirectors combination

� Create Splitter device (Data source serial port=COM1, Virtual serial port=COM5) � Create Serial Redirector (Serial port 1 = COM5, Serial port 2 = COM2) � Create Serial Redirector (Serial port 1 = COM5, Serial port 2 = COM3)

TcpServer and TcpClient combination

� Create TcpServer device (Source serial port=COM1, Local TCP port = 5555) � Create TcpClient device (Source serial port=COM2, Remote TCP host=127.0.0.1, Remote TCP port=5555) � Create TcpClient device (Source serial port=COM3, Remote TCP host=127.0.0.1, Remote TCP port=5555)


User interface

VSPE user interface is quite simple.

There are a main window and various options dialogs. The main window displays a list of created virtual serial devices.

See also:� Main window� VSPE Preferences� Create device wizard� Serial port settings dialog


Main window





of 28


Main window

The application main window displays information about created virtual devices.

Use menu or toolbar commands to create configuration.

To edit created device you need to stop emulation first.Click on "Emulation => Stop" command and click right mousebutton on device. Then click on "Properties..." menu item.


VSPE Preferences

To display preferences dialog click "View => Preferences" menu command.

All settings are stored in the Windows registry for the current user.

See also:� General tab� Advanced tab


General tab



of 28


General tab


Advanced tab

Advanced tab


Create device wizard

The wizard will help you to create desired device.

Device creation process consists of two simple steps: specifying device type and characteristics.

You can create any combinations of devices: for example you can create connector and expose it to network using TcpServer device.

See also:� Connector device� Splitter device� Pair device� TcpServer device� TcpClient device� Serial Redirector device� UDP manager device� Bridge device


Connector device

Connector is a very simple virtual device that can be opened by two clients.

After opening, clients can exchange data.

Warning: In some cases connector may not work correctly.1) The same application tries to open connector twice2) Query to device is initiated from another driver (e.g. as modem driver)

In such a case you should use Pair device.




of 28


Step 1

Step 2


Splitter device

Data splitter is intended to help share serial port data stream among many clients.

You must choose source serial port (it will act as data provider) and virtual serial port. Current VSPE version supports up to 8 client connections to the data splitter. You can check "Read only" checkbox to prevent writing in the source serial port. To adjust source serial port settings, click "Settings..." button (Serial port settings dialog) Set "Redirect modem registers" checkbox if you want clients to manage RTS/DTR modem lines. You can also define initial modem registers state (DTR and RTS).


of 28


Step 1

Step 2

See also:Splitter: Share existing physical serial port between several applications


Pair device

Pair is a simple device that consists of two logically connected virtual ports.

It is usually more popular solution than Connector device.

Step 1


of 28


Step 2


TcpServer device

TCPServer opens TCP port to deliver serial port data to network clients.

Number of clients is not limited.

This device does not create virtual serial port. It uses existing one that can be either physical or virtual (for example, Connector).

Step 1


of 28


Step 2


TcpClient device

TcpClient establishes TCP/IP connection to remote computer and transfers data from existing serial port to remote PC and vice versa.

If connection is lost it will reconnect automatically. Also you can specify read data timeout (in seconds) to automatically reconnect Tcp client.


Step 1


of 28


Step 2

Python scripting system

TcpClient device supports scripting. It means that it is customizable. All scripts must be located in Scripts folder (in VSPE installation directory).

Simple script example

#python

import TcpClient

# connect handlerdef TcpClientConnected(obj): TcpClient.SendString(obj,'==> Login')

# disconnecting handler (connection is still alive)def TcpClientDisconnecting(obj): TcpClient.SendString(obj,'==> Logout')

# disconnect handler (connection is already broken)def TcpClientDisconnected(obj): pass


Serial Redirector device

Serial Redirector can be used to establish connection between two serial ports.


Step 1


of 28


Step 2


UDP manager device

UDP manager allows to send/receive data via UDP protocol.


There are 3 entities in UDP manager: COM port, UDP local port and UDP clients.

� COM port is serial port exposed by UDP Manager. � UDP Manager waits for incoming data from UDP local port. All incoming data is redirected to COM port. � UDP clients is a set of clients. Every client has its own IP address and port. UDP Manager reads data from COM port and redirects it to UDP clients, sending UDP

packets.

So, UDP Manager work scheme is the following:

� Read data from the local UDP port and send it to COM port. � Read data from the COM port and send it to each UDP client using UDP protocol.

Step 1


of 28


Step 2

Specify local UDP port (0 if you want only to send data from COM port) and Remote clients.

Remote client properties


Bridge device

Bridge is intended to connect two data streams.

Data stream source can be file, TCP connection, serial port etc. Just set up each data stream and data will be transfered from stream 1 to stream 2 and vice versa.

Step 1


of 28


Step 2


Serial port settings dialog

Adjust serial port settings (speed, stop bits etc).

Serial port settings


VSPE API

VSPE exposes programming interface that can be useful for software developers.

See also:� VSPE API reference� Devices initialization� C/C++ Example (Native)� Python bindings� C# (COM interface)


VSPE API reference

VSPE API activation




of 28


To use VSPE API, you need activation key.Please acquire it from Eterlogic.com web site.

There are two ways to activate VSPE API. Both ways are correct.

� Use vspe_activate(key) function. Must be called every time your application runs. � Create 'vspeapi.license' file and paste your activation key. Place it in your application folder.

Required files

There are two ways of using VSPE API: native dll linking and COM interface. Both ways are appropriate. All files required for compiling are located in VSPE_API folder

Linking with VSPE API (using VSPE_API.dll)

To compile with VSPE API, do the following steps:

� Include VSPE_API.h (for C++ programmers) � Link with VSPE_API.lib

In some cases static linkage is not appropriate.To use dynamic linkage, look in MSDN for LoadLibaray and GetProcAddress functions.

Dependencies with native binding (without COM interface)

To run your application without correctly, you should either install VSPE or copy the following files to your application folder:

� Vspe_Api.dll (VSPE API core) � VspeUtils.dll (VSPE core) � KernelDevices.plg (Connector, Splitter, Pair) � UserDevices.plg (TcpServer, TcpClient etc) � KrushUtilities.dll (auxiliary dll used by GUI and userdevices.plg) � Python25.dll (Python 2.5 used by userdevices.plg)

Dependencies with native binding (without COM interface)

� Register VSPE_ComServer.dll (regsvr32 VSPE_ComServer.dll). No any additional files in the application folder required.

Standalone installation

Installation

� Add all the files mentioned in the sections above to your application setup package. � Run WixInteractor.exe on_install with administrator privileges � Register VSPE_ComServer.dll (regsvr32 VSPE_ComServer.dll)

Uninstallation

� Run WixInteractor.exe on_uninstall with administrator privileges � Unregister VSPE_ComServer.dll (regsvr32 /u VSPE_ComServer.dll)

Running compiled program

Run compiled program in the VSPE root folder only.This requirement may be removed in the future.

VSPE API header (VSPE_API.h)

// Virtual Serial Port Emulator API header// Author: Volodymyr Ter (http://www.eterlogic.com)

#ifndef _VSPE_API_H_#define _VSPE_API_H_

#ifdef VSPE_API_EXPORTS#define VSPE_API extern "C" _declspec(dllexport)#else#define VSPE_API extern "C" _declspec(dllimport)#endif

/** Activate VSPE API using activation key* \return result

*/VSPE_API bool vspe_activate(const char* key);

/* * Initialize VSPE core * \return result */VSPE_API bool vspe_initialize();

/* * Load configuration file * \param name * \return result */

of 28


VSPE_API bool vspe_loadConfiguration(const char* name);

/** Save configuration* \param name * \return result*/VSPE_API bool vspe_saveConfiguration(const char* name);

/** Create device* \param name Device name. For example "Connector", "Splitter", "Pair" etc.* \param initString device initialization string* \return deviceId*/VSPE_API int vspe_createDevice(const char* name, const char* initString);

/*

* Destroy device by deviceId* \param deviceId* \return result*/VSPE_API bool vspe_destroyDevice(int deviceId);

/** Get VSPE devices count* \return result*/VSPE_API int vspe_getDevicesCount();

/** Get VSPE deviceId by device index* \param idx device index* \return deviceId*/VSPE_API int vspe_getDeviceIdByIdx(int idx);

/** Get VSPE deviceId by COM port index* \param ComPortIdx* \return deviceId (-1 if not found).*/VSPE_API int vspe_getDeviceIdByComPortIndex(int ComPortIdx);

/** Get device information

* \param deviceId* \param name [out] device name* \param initStrng [out] device initString* \param ok [out] device state (1 = good)* \param used [out] is device used (1 = used)* \return result*/VSPE_API bool vspe_getDeviceInfo(int deviceId, const char** name, const char** initString, int* ok, int* used);

/** Reinitialize device by deviceId* \param deviceId* \return result*/VSPE_API bool vspe_reinitializeDevice(int deviceId);

/** Destroy all devices* \return result*/VSPE_API bool vspe_destroyAllDevices();

/* * Start emulation * \return result

*/VSPE_API bool vspe_startEmulation();

/* * Stop emulation * \return result */VSPE_API bool vspe_stopEmulation();

/* * Release VSPE core */VSPE_API void vspe_release();

/** Get VSPE API version information* \return result*/VSPE_API const char* vspe_getVersionInformation();

#endif

of 28


VSPE API COM interface (VSPE_ComServer.idl)

// Virtual Serial Port Emulator API header// Author: Volodymyr Ter (http://www.eterlogic.com)

import "oaidl.idl";import "ocidl.idl";

[ object, uuid(4350205d-80d8-429e-ac0c-0fc64dc42180), dual, nonextensible, helpstring("IVSPE Interface"), pointer_default(unique)]

// ========================================================================// Main VSPE interface// ========================================================================

interface IVSPE : IDispatch{

/* * Activate VSPE API using activation key * \param key Activation key * \return result */ [id(1), helpstring("method vspe_activate")] HRESULT vspe_activate([in] BSTR key, [out, retval] BOOL* Result);

/* * Initialize VSPE core * \return result */ [id(2), helpstring("method vspe_initialize")] HRESULT vspe_initialize([out, retval] BOOL* Result);

/* * Load configuration file * \param name * \return result */ [id(3), helpstring("method vspe_loadConfiguration")] HRESULT vspe_loadConfiguration([in] BSTR name, [out, retval] BOOL* Result);

/* * Save configuration * \param name

* \return result */ [id(4), helpstring("method vspe_saveConfiguration")] HRESULT vspe_saveConfiguration([in] BSTR name, [out, retval] BOOL* Result);

/* * Create device * \param name Device name. For example "Connector", "Splitter", "Pair" etc. * \param initString device initialization string * \return deviceId */ [id(5), helpstring("method vspe_createDevice")] HRESULT vspe_createDevice([in] BSTR name, [in] BSTR initString, [out, retval] BOOL* Result);

/* * Destroy device * \param deviceId * \return result */ [id(6), helpstring("method vspe_destroyDevice")] HRESULT vspe_destroyDevice([in] LONG deviceId, [out, retval] BOOL* Result);

/* * Reinitialize device * \param deviceId * \return result */

[id(7), helpstring("method vspe_reinitializeDevice")] HRESULT vspe_reinitializeDevice([in] LONG deviceId, [out, retval] BOOL* Result);

/* * Destroy all devices * \return result */ [id(8), helpstring("method vspe_destroyAllDevices")] HRESULT vspe_destroyAllDevices([out, retval] BOOL* Result);

/* * Start emulation * \return result */ [id(9), helpstring("method vspe_startEmulation")] HRESULT vspe_startEmulation([out, retval] BOOL* Result);

/* * Stop emulation * \return result */ [id(10), helpstring("method vspe_stopEmulation")] HRESULT vspe_stopEmulation([out, retval] BOOL* Result);

/* * Release VSPE core */ [id(11), helpstring("method vspe_release")] HRESULT vspe_release();

of 28


/* * Get VSPE devices count * \return result */ [id(12), helpstring("method vspe_getDevicesCount")] HRESULT vspe_getDevicesCount([out, retval] LONG* Result);

/* * Get VSPE deviceId by device index * \param idx device index * \return deviceId */ [id(13), helpstring("method vspe_getDeviceIdByIdx")] HRESULT vspe_getDeviceIdByIdx([in] LONG idx, [out, retval] LONG* Result);

/* * Get device information

* \param deviceId * \param name [out] device name * \param initStrng [out] device initString * \param ok [out] device state (1 = good) * \param used [out] is device used (1 = used) * \return result */ [id(14), helpstring("method vspe_getDeviceInfo")] HRESULT vspe_getDeviceInfo([in] LONG deviceId, [out] BSTR* name, [out] BSTR* initString, [out] LONG* ok, [out] LONG* used, [out, retval] BOOL* Result);

/* * Get VSPE API version information * \return result */ [id(15), helpstring("method vspe_getVersionInformation")] HRESULT vspe_getVersionInformation([out, retval] BSTR* result);

/* * Get VSPE deviceId by COM port index * \param ComPortIdx * \return deviceId (-1 if not found). */ [id(16), helpstring("method vspe_getDeviceIdByComPortIndex")] HRESULT vspe_getDeviceIdByComPortIndex([in] LONG ComPortIdx, [out, retval] LONG* result);};

[ uuid(d7cd1ef7-a520-457b-af9a-8ea103b95381), version(1.0),

helpstring("VSPE 1.0 Type Library")]

library VSPELib{

// ========================================================================// Interface implementations// ========================================================================

[ uuid(bf32160d-8fa7-408b-8a3c-cbfbfc19caa6), helpstring("VSPEApi Class") ] coclass VSPEApi { [default] interface IVSPE; };

};


Devices initialization

General

To create new device, you should call vspe_createDevice (or just load configuration file). This function takes two parameters: name and initString. Name is device type: for example, "Connector" or "Splitter". initString is initialization string. All parameters in initialization string are separated by ';'.

SerialSettings is special settings block in which parameters are separated by commas. It describes serial port advanced settings. � Format: Speed,DtrRts,Bits,StopBits,Parity,CustomReadIntervalTimeout � Example: 19200,0,8,1,0,0

Connector

� Initialization string example: 1;0 � Description: ComPortIndex;Emulate baud rate

Splitter

� Initialization string example: 10;1;0;19200,0,8,1,0,0;0;0;0 � Description: VirtualComPortIndex;RealComPortIndex;ReadOnly;SerialSettings;UseModemRegisters;UseRts;UseDtr

Pair


of 28


� Initialization string example: 10;11;0 � Description: ComPortIndex1;ComPortIndex2;Emulate Baud rate

TcpServer

� Initialization string example: 5555;1;19200,0,8,1,0,0 � Description: TcpPort;ComPortIndex;SerialSettings

TcpClient

� Initialization string example: 192.168.10.2;5555;1;19200,0,8,1,0,0;0;30; � Description: TcpHost;TcpPort;ComPortIndex;SerialSettings;DtrRts;ReconnectTimeout;ScriptFile

UDP Manager

� Initialization string example: 192.168.10.2;5555;1;19200,0,8,1,0,0 � Description: Host;Port;ComPortIndex;SerialSettings

Serial Redirector

� Initialization string example: 1;19200,0,8,1,0,0;2;19200,0,8,1,0,0;0 � Description: ComPortIndex1;SerialSettings1;ComPortIndex2;SerialSettings2;UseModemRegisters


C/C++ Example (Native)

C++ sample

#include <stdio.h>#include <conio.h>

// include VSPE API header and library#include "VSPE_API.h"#pragma comment(lib,"VSPE_API.lib")

int main(){

// ****************************// STEP 1 - INITIALIZATION// ****************************const char* config_file_path = "1.vspe";const char* activationKey = ""; // <----- PUT ACTIVATION KEY HERE

bool result;

// display VSPE API version info

printf("%s\n",vspe_getVersionInformation());

// activate VSPE API result = vspe_activate(activationKey);

if(result == false){ printf("VSPE API activation error");

return 1; }

// initialize VSPE python binding subsystem result = vspe_initialize();

if(result == false){ printf("Initialization error");

return 1; }

// stop current emulation result = vspe_stopEmulation();

if(result == false) { printf("Error: emulation can not be stopped: maybe one of VSPE devices is still used."); vspe_release();

return 1; }

// *********************************// Dynamically creating devices

// *********************************// Create Connector device (COM9, no baud rate emulation)int deviceId = vspe_createDevice("Connector", "9;0");if(deviceId == -1)

{ printf("Error: can not create device\n"); vspe_release();

return 1; }

// Create Splitter (COM9 => COM10) deviceId = vspe_createDevice("Splitter", "10;9;0;19200,0,8,1,0,0;0;0;0");


of 28


if(deviceId == -1) { printf("Error: can not create device\n"); vspe_release();

return 1; }

// Create Pair device (COM21 => COM22) deviceId = vspe_createDevice("Pair", "21;22;0");

if(deviceId == -1) { printf("Error: can not create device\n"); vspe_release();

return 1; }

// *********************************// Working with configuration files// *********************************

// save configuration to file result = vspe_saveConfiguration(config_file_path);

if(result == false) { printf("Error: can not save configuration"); vspe_release();

return 1; }

// load configuration from file result = vspe_loadConfiguration(config_file_path);

if(result == false) { printf("Error: can not load configuration"); vspe_release();

return 1; }

// ****************************// STEP 2 - EMULATION LOOP// ****************************

// start emulation result = vspe_startEmulation();

if(result == false) { printf("Error: can not start emulation"); vspe_release();

return 1; }

// *********************************// Extracting devices information// *********************************int i, count = vspe_getDevicesCount();for(i = 0;i<count;++i)

{int ok, used;const char* name, *initString;int deviceId = vspe_getDeviceIdByIdx(i);if(vspe_getDeviceInfo(deviceId, &name, &initString, &ok, &used))

{ printf("Detected device: %s (%s). Status: %s, Used: %s\n", name, initString, ok == 1 ? "OK" : "ERROR",

used == 1 ? "YES" : "NO"); } }

// emulation loop printf("Press any key to quit"); _getch();

// ****************************// STEP 3 - EXIT// ****************************

// stop emulation before exit (skip this call to force kernel devices continue to work) result = vspe_stopEmulation();

if(result == false) { printf("Error: emulation can not be stopped: maybe one of VSPE devices is still used.");

return 1; } // if(result == false)

// release VSPE vspe_release();

return 0;}



of 28


Python bindings

Python bindings requirements

Requirements for native bindings

� Install Python interpreter (we use version 2.5) � Install PythonWin extension � Run script from VSPE install folder or copy necessary files to the application folder

Requirements for COM bindings

� Install PythonWin extension

Python sample (native)

#python

# --------------------------------------# VSPE python subsystem usage sample# --------------------------------------

import msvcrtimport VSPE_Python

config_file_path = '1.vspe'

activationKey = ''; # <----- PUT ACTIVATION KEY HERE

# display VSPE API version informationprint VSPE_Python.vspe_getVersionInformation()

# ****************************# STEP 1 - INITIALIZATION# ****************************

# activate VSPE APIresult = VSPE_Python.vspe_activate(activationKey)if result == False:

print 'VSPE API activation error' exit(1)

# initialize VSPE python binding subsystemresult = VSPE_Python.vspe_initialize()

if result == False:print 'Initialization error'

exit(1)

# stop current emulationresult = VSPE_Python.vspe_stopEmulation()if result == False:

print 'Error: emulation can not be stopped: maybe one of VSPE devices is still used.' exit(1)

# *********************************# Dynamically creating devices# *********************************# Create Connector device (COM9, no baud rate emulation)deviceId = VSPE_Python.vspe_createDevice("Connector", "9;0");

if deviceId == -1:print 'Error: can not create device'

VSPE_Python.vspe_release() exit(1)

# *********************************# Working with configuration files# *********************************

# save configuration to fileresult = VSPE_Python.vspe_saveConfiguration(config_file_path)if result == False:

print 'Error: can not save configuration' VSPE_Python.vspe_release() exit(1)

# load configuration from fileresult = VSPE_Python.vspe_loadConfiguration(config_file_path)if result == False:

print 'Error: can not load configuration' VSPE_Python.vspe_release() exit(1)

# ****************************# STEP 2 - EMULATION LOOP

of 28


# ****************************

# start emulationresult = VSPE_Python.vspe_startEmulation()if result == False:

print 'Error: can not start emulation' VSPE_Python.vspe_release() exit(1)

# emulation loopprint 'Press any key to quit'msvcrt.getch()

# ****************************# STEP 3 - EXIT# ****************************

# stop emulation before exit (skip this call to force kernel devices work without this script)result = VSPE_Python.vspe_stopEmulation()

if result == False:print 'Error: emulation can not be stopped: maybe one of VSPE devices is still used.'

exit(1)

# release VSPE python binding subsystem before exitVSPE_Python.vspe_release()exit(0)

Python sample (COM interface)

#python

import win32com.clientimport msvcrt

vspe = win32com.client.Dispatch("VSPE.VSPEApi")activationKey = ''; # <----- PUT ACTIVATION KEY HERE

# display VSPE API version informationprint vspe.vspe_getVersionInformation()

# activate VSPE APIvspe.vspe_activate(activationKey)

# initialize VSPEvspe.vspe_initialize()

# create Connector (COM9, no baud rate emulation)vspe.vspe_createDevice('Connector','9;0')

# create Splitter (COM9 => COM10)vspe.vspe_createDevice('Splitter','10;9;0;19200,0,8,1,0,0;0;0;0')

# create Pair device (COM21 => COM22)vspe.vspe_createDevice('Pair','21;22;0')

# start emulationvspe.vspe_startEmulation()

# wait for any key ...print 'Press any key to quit'msvcrt.getch()

# stop emulationvspe.vspe_stopEmulation()

# release VSPEvspe.vspe_release()


C# (COM interface)

Add reference to VSPE_ComServer.dll and set target CPU architecture "x86".

C# example

Form1.cs


of 28


п»їusing System;using System.Collections.Generic;using System.ComponentModel;using System.Data;using System.Drawing;using System.Text;using System.Windows.Forms;using VSPELib;

namespace VSPE_API_Test{

public partial class Form1 : Form {

private VSPEApiClass vspe;

public Form1() { InitializeComponent();

vspe = new VSPEApiClass();int result;string activationKey = ""; // <----- PUT ACTIVATION KEY HERE

// display VSPE API info

label1.Text = vspe.vspe_getVersionInformation();

// activate VSPE API result = vspe.vspe_activate(activationKey);

// initialize API result = vspe.vspe_initialize(); }

private void CreateDevice_Click(object sender, EventArgs e) {

int result;

// Stop emulation result = vspe.vspe_stopEmulation();

// Deatroy all devices result = vspe.vspe_destroyAllDevices();

// Add Connector (COM9, no baud rate emulation) result = vspe.vspe_createDevice("Connector", "9;0");

// Start emulation result = vspe.vspe_startEmulation(); }

private void OnClosing(object sender, FormClosingEventArgs e) {

// Stop emulatio vspe.vspe_stopEmulation();

// Release VSPE vspe.vspe_release(); }

private void Info_Click(object sender, EventArgs e)

{// get devices countint count = vspe.vspe_getDevicesCount();string result = "Devices count: " + count.ToString() + "\n";

// enumerate devicesfor (int i = 0; i < count; ++i)

{// get device IDint deviceId = vspe.vspe_getDeviceIdByIdx(i);string name, initString;int ok, used;

vspe.vspe_getDeviceInfo(deviceId, out name, out initString, out ok, out used);

result += name + " ("+initString + ") OK=" + ok.ToString() + "\n"; }

MessageBox.Show(result); } }}


Command line

To make users life easier VSPE supports command line parameters.

For example it can be used to automatically load configuration at Windows startup. Warning: only one VSPE instance can exist at the same time !

Usage:


of 28


VSPEmulator.exe <config file path> <options>

Config file is a special file with extension ".vspe" that can be created using VSPE "Save as..." command.

Options are additional parameters that can be passed to VSPE to manage its basic behavior.

� -minimize : minimize VSPE dialog � -hide_splash : do not show splash window

Example:

Execute VSPE and automatically load configuration fileVSPEmulator.exe c:/config_files/main.vspe

Execute, load configuration file, hide splash and minimize VSPEVSPEmulator.exe c:/config_files/main.vspe -minimize -hide_splash


Known limitations and bugs

� Baud rate emulation is very rough � Serial port output buffer is pass-through (not actually emulated) � Serial port output timeouts are ignored � DataFlow control is not as fast as it could be (try to avoid sending packets that are actually larger than receiver's input buffer size)


Contacting

Contacting information

E-mail: [email protected]

Online form: http://www.eterlogic.com/Feedback.html

Forum: http://forum.eterlogic.com


User license agreement.

You should carefully read the following terms and conditionsbefore using this software. If you do not agree with the termsof this license, you must remove "Virtual Serial Port Emulator"from your computer.

32 bit FREEWARE LICENSE AGREEMENT

BY DOWNLOADING, INSTALLING OR USING THE "VIRTUAL SERIAL PORTS EMULATOR" (THE "PRODUCT"), THE INDIVIDUAL OR ENTITY LICENSING THE PRODUCT ("LICENSEE") IS CONSENTING TO BE BOUND BY AND IS BECOMING A PARTY TO THIS AGREEMENT. IF LICENSEE DOES NOT AGREE TO ALL OF THE TERMS OF THIS AGREEMENT, THE PRODUCT MUST NOT BE DOWNLOADED, AND LICENSEE MUST NOT INSTALL OR USE THE PRODUCT.

Eterlogic.com exclusively owns source code and all other copyrights referring to the Product.

1. License grant. Eterlogic.com grants Licensee a non-exclusive and non-transferable license to reproduce and use for any purposes the executable code version of the Product, provided any copy must contain all of the original proprietary notices. This license does not entitle Licensee to receive from Eterlogic.com hard-copy documentation, technical support, telephone assistance, or enhancements or updates to the Product. If more than one license agreement was provided for the Product, and the terms vary, the order of precedence of those license agreements is as follows: a signed agreement, a license agreement available for review on the Eterlogic.com website, a printed or electronic agreement that states clearly that it supersedes other agreements, a printed agreement provided with the Product, an electronic agreement provided with the Product.

2. Restrictions. Without Eterlogic.com prior written consent, Licensee may not: (i) modify or create any derivative works (VSPE API is an exception) of the Product or documentation, including customization, translation or localization; (ii) decompile, disassemble, reverse engineer ; (iii) remove or alter any trademark, logo, copyright or other proprietary notices, legends, symbols or labels in the Product.

3. Fees. There is no license fee for the Product. If Licensee wishes to receive the Product on media, there may be a small charge for the media and for shipping and handling. Licensee is responsible for any and all taxes.

4. Proprietary rights. Title, ownership rights, and intellectual property rights in the Product shall remain in Eterlogic.com and/or its suppliers. Licensee acknowledges such ownership and intellectual property rights and will not take any action to jeopardize, limit or interfere in any manner with Eterlogic.com or its suppliers' ownership of or




of 28


rights with respect to the Product. The Product is protected by copyright and other intellectual property laws and by international treaties. Licensee agrees, at its expense, to defend and hold Eterlogic.com and its affiliates harmless from any and all costs, damages and reasonable attorneys' fees resulting from any claim that Licensee's use of the Product has injured or otherwise violated any right of any third party or violates any law.

5. Disclaimer of Warranty. THE PRODUCT IS PROVIDED FREE OF CHARGE, AND, THEREFORE, ON AN "AS IS" BASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE WARRANTIES THAT IT IS FREE OF DEFECTS, VIRUS FREE, ABLE TO OPERATE ON AN UNINTERRUPTED BASIS, MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE OR NON-INFRINGING. THIS DISCLAIMER OF WARRANTY CONSTITUTES AN ESSENTIAL PART OF THIS AGREEMENT. NO USE OF THE PRODUCT IS AUTHORIZED HEREUNDER EXCEPT UNDER THIS DISCLAIMER.

6. Limitation of Liability. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT WILL ETERLOGIC.COM OR ITS AFFILIATES OR SUPPLIERS BE LIABLE FOR ANY INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF OR INABILITY TO USE THE PRODUCT, INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOST PROFITS, LOSS OF GOODWILL, WORK STOPPAGE, COMPUTER FAILURE OR MALFUNCTION, OR ANY AND ALL OTHER COMMERCIAL DAMAGES OR LOSSES, EVEN IF ADVISED OF THE POSSIBILITY THEREOF, AND REGARDLESS OF THE LEGAL OR EQUITABLE THEORY (CONTRACT, TORT OR OTHERWISE) UPON WHICH THE CLAIM IS BASED. IN ANY CASE, ETERLOGIC.COM COLLECTIVE LIABILITY UNDER ANY PROVISION OF THIS AGREEMENT SHALL NOT EXCEED IN THE AGGREGATE THE SUM OF THE FEES LICENSEE PAID FOR THIS LICENSE (IF ANY). SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR LIMITATION OF INCIDENTAL, CONSEQUENTIAL OR SPECIAL DAMAGES, SO THIS EXCLUSION AND LIMITATION MAY NOT APPLY TO YOU.

7. High risk activities. The Product is not fault-tolerant and is not designed, manufactured or intended for use or resale as on-line control equipment in hazardous environments requiring fail-safe performance, such as in the operation of nuclear facilities, aircraft navigation or communication systems, air traffic control, direct life support machines, or weapons systems, in which the failure of the Product could lead directly to death, personal injury, or severe physical or environmental damage ("High Risk Activities"). Accordingly, Eterlogic.com and its suppliers specifically disclaim any express or implied warranty of fitness for High Risk Activities. Licensee agrees that Eterlogic.com and its suppliers will not be liable for any claims or damages arising from the use of the Product in such applications.

8. Termination. Eterlogic.com may terminate this Agreement at any time, for any reason or no reason. Eterlogic.com may also terminate this Agreement if Licensee breaches any of its terms and conditions. Upon termination, Licensee shall destroy all copies of the Product.


Version history

Version 0.923 (March, 2009)

� Updated VSPE API, C++ sample, documentation � Updated VSPE_API PythonBindings � Added: VSPE_ComServer.dll - COM interface � WixInteractor: removed console � VSPE_API: Activation requirement added � VSPE_API: No additional files required in application folder when using COM interface.

� VSPE_API: commercially licensed applications can work simultaneously � Distribution package contains FREE 32 bit VSPE API key � Fixed bug: splitter freezing � 64 bit: VSPE can be started for testing purposes without activation key � TcpClient, TcpServer, Redirector, UdpManager: checking for errors when reading from the source port

Version 0.911 (February, 2009)

� Fixed uninstaller bug in Vista

Version 0.910 (January 28, 2009)

� Feature added: Windows Vista 64 bit support (64 bit license required)

Version 0.875 (December 31, 2008)

� Feature added: Bridge device

Version 0.871 (November 25, 2008)

� Feature added: VSPE API � Feature added: VSPE API C/C++ sample � Feature added: VSPE API Python bindings and sample � Fixed bug: ReadIntervalTimeout=MAXDWORD, ReadTotalTimeoutMultiplier=MAXDWORD, ReadTotalTimeoutConstant=(0;MAXDWORD) � Fixed bug: advanced tab in VSPE settings dialog did not work at all � Code refactoring

Version 0.866 (September 30, 2008)

� Pair device can be used with modem drivers (unlike Connector) � Fixed Python scripting bug on program exit � Fixed bug: driver start failure on XP64 when previous version is installed � Fixed bug: ReadTotalTimeoutMultiplier is now ignored if -1 � (In progress) Data flow control


� Fixed major bug (Connector and Pair): read buffer synchronization issues � Fixed critical bug: ReadTotalTimeoutConstant timer fails � Improved Splitter device processing � Added compatibility with NSSM (service manager) � UdpManager: added error message if listening to port failed � Added Simple UdpManager (hidden by default)


of 28



� Fixed bug: Redirector and TcpClient crash on exit � Improved Updater parser


� Added custom ReadIntervalTimeout in the serial port settings dialog � Added UdpManager device � VSPE can be started without kernel driver (only user-mode devices can be created) � Devices configuration can be modified after creation � Logging into file � Start/stop emulation buttons � TCP keep-alive control (optional, disabled by default) � Added simple Python script system for TcpClient device � Fixed bug on 64 bit OS: WOW64 file system redirection � Fixed bug on XP 64: Waiting dialog hanging


� Kernel driver bug fixed: ReadFile with TotalTimeout != 0 � Kerner driver bug fixed: ReadTotalTimeoutConstant � Device reinitialization command � Socket manager: polling timeout changed from 500 ms to 100 ms � TcpClient: read data timeouts

Version 0.80 (July 29, 2008)

� Feature added: initial modem registers state in the Splitter device settings � Modem registers mapping in the Serial Redirector device � TcpClient/TcpServer: Changing RTS/DTR state depending on connection status is optional � Some small kernel driver bugs fixed

Version 0.78 (July 25, 2008)

� Feature added: user mode device - Serial Redirector � DTR for TcpServer and TcpClient depends on connection status � Information page for TcpServer � EV_CTS, EV_DSR events � Bug fixed: TcpServer, TcpClient disconnect detection � Bug fixed: hanging up when ReadIntervalTimeout is zero � Small GUI improvements

Version 0.77 (July 21, 2008)

� Standard pinout for Pair and Connector devices � RTS for TcpServer and TcpClient depends on connection status � Modem registers information for kernel devices (Connector and Pair) � Preferences dialog (General tab)

Version 0.76 (July 15, 2008)

� Bug fixed: Pair device: exclusive access only � Bug fixed: Read errors in some applications � Feature added: Baud rate emulation for Connector and Pair devices (Optional) � Additional driver checks at program startup � Kernel driver location and type changed (SERVICE_SYSTEM_START)

Version 0.75 (July 10, 2008)

� Bug fixed: some apps hanged on close

Version 0.74 (June 24, 2008)

� Feature added: TcpServer device receives data from network clients � Fixed some bugs

Version 0.73 (June 21, 2008)

� Feature added: information panel � Performed some code optimization

Version 0.72 (June 10, 2008)

� Feature added: working without administrator privileges � Emulation issue: ReadIntervalTimeout

Version 0.71 (May 30, 2008)

� Fixed 2 nasty emulation bugs

Version 0.7 (May 29, 2008)

� Windows Vista compatibility � Command line support � Documentation update

Version 0.6 (May 26, 2008)

� Feature added: TcpClient device

of 28


Version 0.5 (May 22, 2008)

� Registered vspe shell extension � Improved user interface

Version 0.4 (May 21, 2008)

� Feature added: TcpServer device � Feature added: loading / saving configuration � Improved user interface � Code refactoring

Version 0.3 (May 13, 2008)

� Feature added: x86_64 platform support � Fixed some emulation bugs � Improved user interface

Version 0.2 (May 5, 2008)

� Feature added: virtual pair � Fixed emulation bugs (thanks to Dmitry Fomin for his detailed error reports) � Fixed problems with deleting virtual devices.

Version 0.1 (April 13, 2008)

� Feature added: virtual connector � Feature added: virtual data splitter


Frequently asked questions

I create virtual port COM10 but it is not visible to my application.

It is the operating system issue. COM ports with numbers from 1 to 9 can be opened without any problems. To open device with number greater than 9 you need to use "\\.\" prefix.

� COM1 : valid name � COM10 : invalid name � \\.\COM10 : valid name � \\.\COM1 : valid name

I create connector device to emulate modem, but modem does not work correctly.

This can be related to the modem driver. Try to use Pair device.


Credits

Staff

� Developer: Volodymyr Ter

Portions of this software are copyrighted by:

� Navigation Services VS LTD




of 28


VSPE

Documents

Transcript of VSPE