Skip to main content
Kofax

Kofax SignDoc Virtual Serial SignPad (VSSP)

Date of Article: January 2018

Technical Insight: Kofax SignDoc Virtual Serial SignPad (VSSP) - Deprecated

This Knowledge Base Article explains the deprecated Technology called Kofax SignDoc Virtual Serial SignPad which can be used to leverage SignPads in a remote environment.
For a more recent remote environment Technology called Kofax SignDoc Virtual Channel (VC) which is to be prefered see this Knowledge Base Article.


Table of Contents

Step 1: Installation/Preparation on Remote Client

Installing Virtual Serial SignPad for ICA / Citrix and RDP on Windows (here: Windows 7 - x64 and STU-530)
Connecting via RDP
Connecting via ICA / Citrix
Installing Virtual Serial SignPad for ICA / Citrix and RDP on Linux (here: Ubuntu 17.04 - i386)
Connecting via RDP (here: rdesktop)
Connecting via ICA / Citrix

Step 2: Installation/Preparation on Citrix / Remote Desktop Server

Troubleshooting
Test Serial redirection of SignPad using SerialTest
Tracing via DbgView on Windows
Checking for SignPad on Linux
Tracing on Linux

Step 1: Installation/Preparation on Remote Client

Virtual Serial SignPad is a technology, which allows to have a dedicated path of communication between a remote client with a SignPad attached to it via USB, and a server, using either Citrix or Terminal Server.
Communication is established by using a virtual COM Port while the SignPad is connected to the client via USB.
Currently 32-bit and 64-bit versions of Windows are supported as well as 32-bit Versions of Linux.
A sample setup could look as below:



Please refer to the "Legacy - Virtual Serial SignPad" section in the Technical Specifications document for a list of supported SignPads.
If the link to the document above is not working please use the general Kofax Products website.
From there navigate to "Kofax SignDoc" -> "Documentation:" section -> Kofax SignDoc x.x.x Product Documentation (compressed) -> KofaxSignDocTechnicalSpecifications PDF document at bottom of article
At the moment the following SignPads are supported for Kofax Virtual Serial SignPad: WACOM STU-300, STU-430,
STU-500, STU-520, STU-530

Installing Virtual Serial SignPad for ICA / Citrix and RDP on Windows (here: Windows 7 - x64 and STU-530)

Extract the Virtual Serial SignPad package from the shipment to a folder of your choice e.g. C:\temp
Connect the SignPad that should be used together with Virtual Serial SignPad.
Open up a command prompt with administrative permissions in the amd64 or x86 folder according to the Bitness of your operating system.

Intalling the STU-520 and STU-530 bulk transfer driver

In case of using a STU-520 or STU-530 SignPad, install the Wacom driver for bulk transfer which will speed up the transfer of background images:

VirtualSerialSignPad.exe install ..\signtab.inf STU-530



In case of the STU-520 SignPad use this particular one as the equivilant parameter:


VirtualSerialSignPad.exe install ..\signtab.inf STU-520A

Installing the Virtual Serial SignPad driver

To install the driver on the next available COM Port use the below command, again from the folder according to the Bitness of your operating system:

VirtualSerialSignPad install VirtualSerialSignPad.inf




After a succesful installation the Windows Device Manager will show the driver as device in the "Ports (COM & LPT)" section:



An additional check can be performed via the below command:

VirtualSerialSignPad.exe list




In case that a specific COM Port (between COM3 and COM23) should be used please use the parameter port=COM# as per this example:



To enable communication, it is required to set the security level to off.
Check for the current status of the security level with the below command:

VirtualSerialSignPad.exe security list




To switch the security level from "on" to "off" run the below command:

VirtualSerialSignPad.exe security off




N.B.: The disabling of the security level has to be done for every SignPad on each separate USB Port that it is attached to on the client computer.

Installing the Windows Service

Windows 7 by default does not allow non-interactive processes (such as the process hosting VirtualSerialSignPad.dll) read data from HID devices.
The Virtual Serial SignPad driver automatically enables access for non-interactive processes by using the SOFTPRO Virtual Serial SignPad Service (VirtualSerialSignPadService.exe).
To install the service, copy VirtualSerialSignPadService.exe to some directory on your hard drive where it will be available when the system starts.
Then, run (1):

  VirtualSerialSignPadService -install

using the new absolute pathname of VirtualSerialSignPadService.exe.
To start the service, run (2):

  VirtualSerialSignPadService -start

The service is now registered to start automatically upon system start as a Windows services (3):




Connecting via RDP

Before connecting via mstsc please make sure to enable for Ports to be used in the remote session:



Connect to the Terminal Server Host and run the change port command to ensure that the port is present in the client session (here: COM5):



Connecting via ICA / Citrix

Citrix Online Plugin (at least version 12.1) has a bug which interferes with VirtualSerialSignPad (and, to a lesser degree due to their lower speed, real serial devices):
wfica32.exe uses the same buffer for (concurrent) overlapped reading from and writing to the serial device.

To work around that bug, type this command in a Command Prompt with administrative privileges:

  VirtualSerialSignPad ica_skip COUNT

where COUNT is the number of IOCTL_SERIAL_GET_COMMSTATUS calls that will pretend that no data is ready for reading after writing.
The default value is 0.  Small values will cause corruption of data sent by the SignPad, large values will slow down communication.  5 seems to be a good compromise.



After connecting to the Citrix Host the net use command can be run to ensure that the port is present in the client session (here: COM5):






Uninstalling the Virtual Serial SignPad driver

To remove the driver, run this command with administrative privileges:

  VirtualSerialSignPad remove




Uninstalling the Windows Service

To remove the service, 
run this command with administrative privileges:

  VirtualSerialSignPadService -stop
  VirtualSerialSignPadService -uninstall





Installing Virtual Serial SignPad for ICA / Citrix and RDP on Linux (here: Ubuntu 17.04 - i386)

N.B.: Please be aware that Virtual Serial SignPad is only available for 32-bit Linux.

To install and start the VirtualSerialSignPad daemon, run

  install-VirtualSerialSignPad.sh install dev=/dev/ttyS# start

using the desired name of the serial device instead of "/dev/ttyS#".



If you omit "start", you will have to start the daemon by yourself:

  /etc/init.d/VirtualSerialSignPad start

If you omit "dev=/dev/ttyS#" and "start", you will have to configure the
desired name of the serial device in /etc/VirtualSerialSignPad.cfg, then start the daemon.

With a connected SignPad a similar output to below should be observed when running the command service VirtualSerialSignpad status:



Connecting via RDP (here: rdesktop)

To use the SignPad in a RDP environment the Serial Device needs to be mapped to a COM port in the RDP session with a connection string similar to this:

rdesktop -u YourUserName -p YourPassword -r comport:COM5=/dev/ttyS32 YourRDPServerIP

After successfuly establishing the RDP session an initial check with the change port command can be done to see whether the COM Port is present:



In addition the command sp_wspchk -getuid can be run to see whether the SignPad can be found:



Connecting via ICA / Citrix

To use the SignPad in a Citrix environment the Serial Device needs to be mapped to a COM port in the Citrix session via en entry in the module.ini file (typical path: /opt/Citrix/ICAClient/config).
The following two lines have to be added in the [WFClient] section of the module.ini file:

LastComPortNum=5
ComPort5=/dev/ttyS32

Where:

- ComPort# relates to the number of the Com Port that is assigned to the Serial Device in the Citrix session
- /dev/ttyS# is the number of the Serial Device that VSSP runs on




After successfuly establishing the RDP session an initial check with the net use command can be done to see whether the COM Port is present.

In addition the command sp_wspchk -getuid can be run to see whether the SignPad can be found.


Uninstalling the Virtual Serial SignPad driver

To uninstall the VirtualSerialSignPad daemon, type

  install-VirtualSerialSignPad.sh uninstall



Step 2: Installation/Preparation on Citrix / Remote Desktop Server

As a prerequiste, Kofax SignDoc Device Support has to be installed on the Server side.


N.B.: In an environment where other Kofax E-Signature products (e.g. SignDoc Desktop) are installed already:
Please make sure to check the PATH environment variable before and after the installation and make sure, that all the paths
relating to the SignDoc products are still present in the environment variable. In case that a path has been deleted, please re-set it.


SignDoc Device Support comes with a sample Tablet.ini file ("c:\Program Files (x86)\SignDoc Device Support\samples\Tablet.ini.sample")
This sample file has to be renamed into Tablet.ini and copied to a folder that is included in the PATH environment variable (e.g. C:\Program Files (x86)\SignDoc Device Support\Win32 and others).
For the SignPad to be recognized correctly the Tablet.ini file has to be configured with the below parameters:

-------------------------------------

FIRSTWT = SP_WspDrv

[WSIGNPAD]
PadPorts = 5


-------------------------------------

Where "5" is reflecting the number of the COM Port that VSSP is mapped to in the Citrix or RDP session.


Additional information and parameters of the Tablet.ini file can be found in the SignWare documentation file "pg_PadInstallation.html"

To verify whether a connected SignPad can be found, this command can be used (on Client and Server side): sp_wspchk -getuid
The tool sp_wspchk.exe is part of the Kofax SignDoc Device Support setup.
A successful output looks similar to this (here: Citrix XenApp Desktop session):




Troubleshooting

Make use of this section if issues are observed during installation or usage of Virtual Serial Signpad.

Test Serial redirection of SignPad using SerialTest

The shipment of VirtualSerialSignPad contains the test utility SerialTest for Windows and Linux.
SerialTest can be run on the client and server side as per examples below with live vectors of pen strokes being displayed:


SerialTest Windows




SerialTest Linux



Tracing via DbgView on Windows

To set the trace level, type the below command on a command line with administrative privileges.
Use DbgView to view the output. Virtual Serial SignPad output will be visible when enabling Capture -> Capture Global Win 32 in DbgView.

VirtualSerialSignPad trace off

No traces are written.



VirtualSerialSignPad trace errors

Traces are only written in error situations.



VirtualSerialSignPad trace log


Traces of general actions are logged



VirtualSerialSignPad trace debug

Traces of all actions with highest detail are logged.






Checking for SignPad on Linux

After connecting a SignPad on Linux the dmesg command can show whether the SignPad connected successfuly:



Tracing on Linux

To set the trace level, add this line to /etc/VirtualSerialSignPad.cfg:

  trace_level=N

where N is 1 (errors only), 3 (additional information), or 5 (debugging).  The default value is 1.

To retrieve (live) log information use this command: journalctl -t VirtualSerialSignPad -f


Applies to