Application Note:

TSP100 Virtual Serial

Port Emulator

Rev. 1.1
The company names and product names that appear in this manual are generally trademarks or registered
trademarks of each company.

Copyright © 2011 Star Micronics Co., Ltd.

 Table of Contents

1. Introduction.......................................................................................................1

2. Supported Products and Environments..........................................................1

3. Supported Programming Environments.........................................................1

4. futurePRNT Utility Settings..............................................................................2

5. List of Supported APIs.........................................................................................3

5.1 Win32 API....................................................................................................................................... 3
5.2 .NET Framework............................................................................................................................ 4

6. Limitations and Considerations.........................................................................5

7. Flow of Data Processing......................................................................................6

7.1 ESC/POS Mode.................................................................................................................................. 6
7.2. Star Line Mode................................................................................................................................. 7

8. Sample Programs................................................................................................9

9. References............................................................................................................9

10. Release History..................................................................................................9

 Star Virtual Serial Port Emulator SDK Manual

1. Introduction
Star Micronics' Virtual Serial Port Emulator (VPE) allows users running older POS Software only supporting
serial communication to enjoy the benefits of using a TSP100 Printer with a modern USB or Ethernet
interface. This solution brings the convenience of these faster communication methods without requiring
any change to the POS Application in use. Additionally, this feature provides support for Star Micronics'
ETB Status Command in Star Line Mode.

This document explains VPE functionality and provides methodology for software developers wishing to
implement such a solution into their applications.

2. Supported Products and Environments

TSP100 futurePRNT Ver5.1.0

■ Printer
Supported Printers: TSP100ECO (USB) * Stop printing: Disable under F/W ver.2.0 or later
TSP100U (USB)
TSP100PUSB (Powered USB)
TSP100GT (USB) * Stop printing: Disable under F/W ver.2.0 or later
TSP100LAN (Ethernet) * only ESC/POS Mode
Supported Emulations: ESC/POS Mode
Star Line Mode

■ Host PC
Supported OS: Microsoft Windows 7 (32-bit/64-bit)
Microsoft Windows Vista Service Pack 2 or later (32-bit/64-bit)
Microsoft Windows XP Service Pack 3 (32-bit)

3. Supported Programming Environments

- Win32API :C
- .NET Framework 2.0 or later : C#

Sample programs are available for both of the above environments. Reference Section 8 (Sample
Programs).

-1-
 Star Virtual Serial Port Emulator SDK Manual

4. futurePRNT Utility Settings

Prerequisite: Prior to making the changes listed in this section, a Virtual Serial Port must be created
in the futurePRNT Configuration Utility in either ESC/POS or Star Line Mode. Refer to
the TSP100 Software Manual for directions on creating the virtual serial port.

Note: The following information applies ONLY to the TSP100GT(F/W ver.2.0 or later) and
TSP100ECO(F/W ver.2.0 or later) in Star Line Mode.

Depending on the firmware version, the futurePRNT Utility might result in an error when attempting to
use the VPE. To remedy this, follow these directions:

1. Click "Stop Printing" and then the "OK" button.

2. Click on the "General Settings" tab and locate the "Automatic Retry" dropdown box.

3. Set Automatic Retry to "Disabled" and click on "Apply Changes" at the bottom.

The default setting of each model is as follows:

· TSP100GT : Disabled
· TSP100ECO : Enabled
· TSP100U : Enabled

-2-
 Star Virtual Serial Port Emulator SDK Manual

5. List of Supported APIs

The VPE supports the following APIs:

5.1 Win32 API

 : Supported
 : Supported (Limitation)
× : No Support

Category Win32 API Status Notes

CreateFile 
WriteFile  If an error occurs while data is being sent, the VPE sets the
fourth parameter (written bytes amount) to 0; in comparison,
Universal a physical serial port would set this parameter to the total
WriteFileEx  amount of bytes sent.
API
ReadFile 
ReadFileEx 
CloseHandle 
BuildCommDCB 
BuildCommDCBAndTimeouts 
ClearCommBreak × This always returns TRUE, even though it is not supported.
Physical errors (framing, parity, etc.) are not caused by the
ClearCommError  virtual port.
CommConfigDialog 
EscapeCommFunction × This always returns TRUE, even though it is not supported.
GetCommConfig 
GetCommMask 
GetCommModemStatus 
GetCommProperties 
GetCommState 
GetCommTimeouts 
Serial Port GetDefaultCommConfig 
Control API PurgeComm 
SetCommBreak × This always returns TRUE, even though it is not supported.
SetCommConfig 
SetCommMask 
VPE does not support the following settings:
- Software flow control
SetCommState  - Data bits without 8-bits data
- Special characters
The VPE and actual serial port handle this function differently.
SetCommTimeouts  To learn more, reference the PDF named "Timeout Status
Differences".
SetDefaultCommConfig 
SetupComm 
TransmitCommChar × This always returns TRUE, even though it is not supported.
WaitCommEvent  Supports EV_CTS, EV_DSR, EV_RXCHAR and EV_TXEMPTY.

Above: Supported functions of Win32 API

-3-
 Star Virtual Serial Port Emulator SDK Manual

5.2 .NET Framework

Supported Class: System.IO.Ports.SerialPort
 : Supported
 : Supported (Limitation)
× : No Support

Category .NET Framework Status Notes

BaudRate 
BreakState × This always returns TRUE, even though it is not supported.
BytesToRead 
BytesToWrite 
CtsHolding 
DataBits  Must be fixed 8-bits data.
DiscardNull × This always returns TRUE, even though it is not supported.
DsrHolding 
DtrEnable 
TSP100LAN Only: It will take 80 seconds for the application to
Handshake  recover from an error if this method is called when the printer is
powered off.
Properties IsOpen 
NewLine 
Parity 
ParityReplace  A parity error is not caused by the virtual port.
PortName 
ReadBufferSize 
ReadTimeout 
ReceivedBytesThreshold 
RtsEnable 
StopBits 
WriteBufferSize 
WriteTimeout 
Close 
DiscardInBuffer 
DiscardOutBuffer 
Dispose 
GetPortNames 
Open 
Read 
Methods
ReadByte 
ReadChar 
ReadExisting 
ReadLine 
ReadTo 
Write 
WriteLine 
DataReceived 
Events Disposed 
ErrorReceived  Physical errors are not caused by the virtual port.
PinChanged 

Above: Supported Status of .NET Framework

-4-
 Star Virtual Serial Port Emulator SDK Manual

6. Limitations and Considerations

- If an error occurs while sending a print job, the data will be lost. Retry sending the print job from the
application.

- Send all data as one document, not by bytes or lines. Sending data in pieces can result in slower print
speed.

- ESC/POS Mode: The application is unable to check if the print job was finished.

- The VPE and actual serial port handle this function differently. To learn more, reference the PDF named
"Timeout Status Differences".

-5-
 Star Virtual Serial Port Emulator SDK Manual

7. Flow of Data Processing

7.1 ESC/POS Mode

It is advisable to confirm if the printer's status is set to online before and after sending a print job in ESC/
POS Mode.
For details of printer status, refer to the "ESC/POS Mode Command Specification" manual available on the
Star Micronics website.

act Printing Process

Start
act Status and Data Transmission Process

Start
Open Port

Get printer status

Read data sent
from the file

Printer status [Error]

[No Error]

Send data
Send data to
the Printer

Keep the process until

the print job is completed
Result [Fail]

[Success] Get printer status

Reprint [YES]

Printer status
[NO] [Error]

[No Error]

Close Port

Printing Printing
Finish Success Failure

-6-
 Star Virtual Serial Port Emulator SDK Manual

7.2. Star Line Mode

In Star Line Mode, it is possible to confirm if a print job was completed by using the ETB Status Command.
For details of both printer status and the ETB command, refer to the "Star Line Mode Command
Specification" manual on the Star Micronics website.
* If using the TSP100GT or TSP100ECO, choose "Stop Printing" in the VPE Utility; refer to Section 4 of this
document for more information.

[Procedure]

(1) Create and enable a Virtual Serial Port.

(2) Send the status request command via the VPE to ensure the printer is online. Additionally, check the
ETB counter.

(3) Add ETB(0x17) to the end of any print data and then send the print job via the VPE.

(4) Send the status request command via the VPE. Then, confirm the status. Repeat this step until the
status is changed to one of the following:
[1]: Success; ETB counter increases by 1, [2]: Printer Error, [3]: Time-out after results [1] and [2] (*1)

(5) The following chart explains the status information returned by steps 2 and 4 of this procedure:

Printer Status Action

ETB Counter Increased by 1 Data was successfully printed

ETB Counter Increased by 1 + Hardware Error Occurred Data was successfully printed even though a printer
error occurred. Identify the hardware error (ex: Paper
Low) and avoid it when sending the next print job

ETB Counter Not Increased + Hardware Error Occurred Data failed to print. Ensure the printer is online and
resend the print job.

Time-out after results [1] and [2] (*1) Data failed to print. Ensure the printer is online and
resend the print job. This could occur if the printer
recovers immediately from error status (*2)
Above: Explanation of status returned by the printer

(*1) Time-out periods will vary depending on size and type of print data sent. The Star Micronics sample
program is set 5 seconds.
Ensure the time is set to a longer value than just finishing the print job; consider the amount of time
necessary to cut paper or pop a cash drawer.

(*2) This situation could occur when the printer detects an error and recovers it immediately while
simutaneously getting status (Step 4).
A time-out happens in this situation because the printer clears all remaining data sent to it, including the
ETB command which is added at the end of print job. The printer then returns to its online status and the
process continues until the ETB counter increases. Since the ETB counter doesn't increase, the printer times
out waiting for it to do so.
In the sample program, the repetition interval is set 500 miliseconds to get status. Change the value
depending on the application's requirements.

-7-
 Star Virtual Serial Port Emulator SDK Manual

act Printing Process act Status and Data Transmission Process

Start Start

Open Port
Get printer status

Read data sent Printer status [Error]

from the file
[No Error]
Note:
Add ETB command Send data to the printer
to the end of the data

Add ETB command to

the end of the data

Get printer status

Send data

ETB counter [No change]

[Change]
Result Printer status
[Fail]

[Error]
[Success]
[No Error]
Reprint
[YES]
Timeout [NO]
[NO]
[YES]

Close Port

Printing Printing
Finish Success Failure

-8-
 Star Virtual Serial Port Emulator SDK Manual

8. Sample Programs
The sample programs* mentioned in Section 7, “Flow of Data Processing”, are stored in the following
location:
Note: “D:\” is the drive letter of CD-ROM

[ESC/POS Mode]
D:\Windows\SDK\VirtualSerialPort\TSP100_VPE_ESC_POS_Sample_20110308.zip

[Star Line Mode]

D:\Windows\SDK\VirtualSerialPort\TSP100_VPE_StarLineMode_Sample_20110308.zip

* These samples were written in Microsoft Visual Studio 2005.

9. References
These links are for reference only and are subject to change without notice:

[MSDN Library] Serial Port Class

http://msdn.microsoft.com/en-us/library/system.io.ports.serialport.aspx

10. Release History

Rev. No. Date Contents
Rev. 1.0 Mar. 2011 Document Created
Rev. 1.1 May. 2011 Updated the List of Supported APIs due to new version release

-9-
SPECIAL PRODUCTS DIVISION OVERSEAS SUBSIDIARY COMPANIES
STAR MICRONICS CO., LTD. STAR MICRONICS AMERICA, INC.
536 Nanatsushinya, Shimizu-ku, Shizuoka, 1150 King Georges Post Road, Edison, NJ 08837-3729 U.S.A.
424-0066 Japan Tel: (int+1)-732-623-5555, Fax: (int+1)-732-623-5590
Tel: (int+81)-54-347-0112, Fax: (int+81)-54-347-0409
STAR MICRONICS EUROPE LTD.
Please access the following URL Star House, Peregrine Business Park, Gomm Road,
http://www.star-m.jp/eng/dl/dl02.htm High Wycombe, Bucks, HP13 7DL, U.K.
for the latest revision of the manual. Tel: (int+44)-1494-471111, Fax: (int+44)-1494-473333

Star VPE SDK Rev. 1.1 2011.5.27

sm00071EN