MarshallSoft

Windows Standard

Serial Communications

for Windows / CE

Users Manual


(WSC_eUSR)


Version 3.4


May 8, 2005



This software is provided as-is.
There are no warranties, expressed or implied.



Copyright (C) 2005
All rights reserved



MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815 USA


Voice : 1-256-881-4630

FAX : 1-256-880-0925

email : info@marshallsoft.com

web : www.marshallsoft.com


MARSHALLSOFT is a registered trademark of MarshallSoft Computing.

TABLE OF CONTENTS


1 Introduction
1.1 Using Both WSC4eVC and WSC4eVB
1.2 Versions of Win/CE supported
1.2.1 Pocket PC (PPC)
1.2.2 Handheld PC (HPC)
1.3 Documentation Set
1.4 User Support
1.5 Ordering
1.5.1 Source Code
1.5.2 WSC/CE and WSC Discount
1.5.3 Academic Discount
1.5.4 Disk Only
1.5.5 Disk and Printed Manuals
1.6 Updates
1.7 Customer ID
1.8 License File
2 Applications Notes
2.1 Keycode (License Key)
2.2 USB Ports
2.3 Threads
2.4 SioPuts Notes
2.5 Hardware Flow Control & Blocking
2.6 Bluetooth Serial
2.7 Emulation
3 XMODEM and YMODEM (XYM)
3.1 XYM Introduction
3.2 XYM Example Programs
3.3 XYM Function Summary
4 Problems
5 Legal Issues
5.1 Registration
5.2 License
5.3 Warranty
6 Summary
6.1 WSC/CE Function Summary

1 Introduction

The Windows/CE Standard Serial Communications Library (WSC/CE) is a powerful toolkit that allows software developers to quickly develop serial port communications applications for Windows CE and the Mobile-based Pocket PC. The Windows/CE Standard Serial Communications Library (WSC/CE) SDK is a dynamic link library (DLL) that uses the standard Windows/CE API (Application Programmer's Interface).

There are two versions of WSC/CE: the Windows Standard Serial Communications Library for eVC (WSC4eVC) and the Windows Standard Serial Communications Library for eVB (WSC4eVB). Both use the same Windows/CE DLL (WSC32.DLL).

WSC4eVC requires Microsoft Embedded Tools 3 (eVC3) or Microsoft Embedded Tools 4 (eVC4). WSC4eVB requires eMbedded Visual Basic v3.0 (eVB3) since VB is not supported in Embedded Tools 4. Note that eVC3/eVB3 supports Pocket PC 2002 while eVC4 supports Pocket PC 2003.

Both versions of Embedded Tools can be downloaded from the Microsoft Web site at:

http://www.microsoft.com/downloads/search.aspx?displaylang=en&categoryid=8

The WSC/CE Serial Comm library can also be used with Bluetooth serial as well as with the Pocket PC emulator that is provided with Microsoft Embedded Tools . This will allow a programmer to develop serial communication applications without having the physical Windows/CE device.

The latest versions of our serial communications software can be found at:

http://www.marshallsoft.com/serial-communication-library.htm

1.1 Using Both WSC4eVC and WSC4eVB

Programs written in both eVC (eMbedded Visual C++) and eVB (eMbedded Visual Basic) use the same WSC/CE DLL (WSC32.DLL). Therefore, it is necessary to purchase only one of the libraries in order to receive the registered DLL for use by both WSC4eVC and WSC4eVB.

The only differences between WSC4eVC and WSC4eVB are the Programmer's Manual and the example programs.

1.2 Versions of Win/CE Supported

WSC/CE supports Pocket PC 2002 and Pocket PC 2003 versions of Windows/CE.

1.2.1 Pocket PC (PPC)

Both WSC4eVC and WSC4eVB run on Pocket PC (PPC) computers (PPC 2002 and PPC 2003), and use the same Win/CE Pocket PC DLL (WSC32.DLL).

WSC4eVC will work with all Pocket PC platforms supported by Microsoft Embedded Visual C++ v3 (eVC3) and Embedded Visual C++ v4 (eVC4).

WSC4eVB will work with all Pocket PC platforms supported by Microsoft Embedded Visual Basic 3 (eVB3).

Embedded Visual Basic Runtime for Pocket PC 2003 is available from Microsoft to allow VB3 programs to run on Pocket PC 2003 platforms. Search 

     http://msdn.microsoft.com/mobility

for "eMbedded Visual Basic Runtime for Windows Mobile-based Pocket PC 2003", or see

     http://msdn.microsoft.com/mobility/windowsmobile/downloads/evb.aspx

For the latest version of our serial communications software, see

     http://www.marshallsoft.com/serial-communication-library.htm

1.2.2 Handheld PC (HPC)

Handheld PC (HPC) versions of the library LIB and DLL files (WSC32.LIB and WSC32.DLL) are available on request at, although we do not have any HPC example programs.


1.3 Documentation Set

The complete set of documentation consists of four manuals in three formats (MS WORD, ASCII text, and HTML). This is the second manual (WSC_eUSR) in the set.

Each manual comes in three formats:

The WSC_4eVC and the WSC_4eVB Programmer's Manuals are the language specific eMbedded Visual C++ and eMbedded Visual Basic manuals that provide information needed to compile mobile based application programs in an embedded environment 

[NAME]       [DESCRIPTION]
WSC_4eVC    :  WSC/CE Programmer's Manual for eMbedded Visual C++
WSC_4eVB    :  WSC/CE Programmer's Manual for eMbedded Visual Basic

The WSC/CE User's Manual (WSC_eUSR) discusses language independent serial communications programming issues such as modem control, Bluetooth, USB, threads, flow control, emulation, etc . Ordering information is also provided in the manual.

The WSC Reference Manual (WSC_eREF) contains details on each individual WSC/CE function.

The Serial Communications Manual (SERIAL) contains background information on serial port hardware.

Use Microsoft Word or Microsoft WordPad to print the document files. Documentation can be accessed online at:

http://www.marshallsoft.com/support.htm


1.4 User Support

We want you to be successful in developing your applications using WSC/CE! We are committed to providing the best library that we can. If you have any suggestions or comments, please let us know.

If you are having a problem using WSC/CE, refer to Section 4.0 "Problems". If you still cannot resolve your problem, email us at 

     info@marshallsoft.com

To avoid having your email deleted by our spam scanners, begin the SUBJECT of your email with "WSC4eVC" or "WSC4eEVB". Zip up any attachments and send plain ASCII text email only.

You can also reach us at +1-256-881-4630 between 7:00 AM and 7:00 PM CST Monday through Friday. You can also often reach us on Saturday.

The latest versions of our products are available on our web site at 

     http://www.marshallsoft.com

and on our anonymous FTP sites at

     ftp://ftp.marshallsoft.com/pub
     ftp://ftp.marshallsoft.net/pub

Registered users can update to the latest DLL's at

      http://www.marshallsoft.com/oem.htm


1.5 Ordering

A developer license for WSC/CE (WSC4eVC or WSC4eVB) may be purchased for $115 (USD) for email delivery, or $195 (USD) with source code for the DLL.

It is necessary to only register only one of the libraries in order to receive the registered DLL for use by both WSC4eVC and WSC4eVB. See Section 1.1 above.

The fastest and easiest way to order is on our web site at 

     http://www.marshallsoft.com/order.htm

You can also order by completing INVOICE.TXT (contained within the WSC/CE zip file) and emailing (info@marshallsoft.com), mailing (see our address at top), or faxing (+1.256.880.0925) it to us.

Multiple copy discounts (3 or more) and site licenses are available. Please call for details.

We accept American Express, VISA, MasterCard, Discover, checks in US dollars drawn on a US bank, International Postal Money Orders, and purchase orders (POs) within the USA from recognized US schools and companies listed in Dun & Bradstreet.

For credit card orders, be sure to include the account number, the expiration date, the exact name on the credit card, and the complete card billing address (the address to which the credit card bill is mailed - not the bank's address). Please include the Card Verification Code (last 3 numbers printed on the back of Visa, MasterCard and Discover cards, or the 4 numbers of the front of American Express cards.) The cardholder's signature is required on faxed orders.

Print the file INVOICE.TXT if a "Pro Forma" invoice is needed. The registered package includes:

1.5.1 Source Code

There are two ways to order Source Code for WSC/CE.

  1. Source Code can be ordered at the same time as the Developer's License for $155 (for both).

  2. Source Code can be ordered within one year of purchasing a Developer's License for $50. After one year, a Developer's License update ($30 or $55) must be purchased prior to purchasing the source code ($50)

1.5.2 WSC/CE and WSC Discount

Purchase both the Windows/CE embedded and Windows desktop (Windows 95/93/ME/XP/NT/2000) versions of the MarshallSoft Serial Communication Libraries at the same time for $189 (with source $279). Discount will be provided in the order confirmation sent to the customer. This offer is not retroactive.

1.5.3 Academic Discount

We offer an "academic price" of 30% off the normal price for prepaid email orders to faculty and full time students currently enrolled in any accredited high school, college, or university. To qualify for the discount, your school must have a web site and you must have an email address at your school.

When ordering, ask for the "academic discount", or enter "student at" (or "faculty at") and your schools web site address (URL) in the comments field of the order form on our web site order page. Your order will be sent to your email address at your school.

This offer is not retroactive and cannot be used with any other discount. Products bought with academic pricing are for educational purposes only.

The academic discount does not apply to source code.

1.5.3 Disk Only

When ordering WSC/CE, a 3.5" HD disk can be purchased for $5 for delivery to the, US, Canada, and Mexico. For all other destinations, the cost is $8. A CD can be purchased instead for an additional $3.

1.5.4 Disk and Printed Manuals

Printed manuals (see Section 1.1 "Documentation Set") are the same as in the WSC/CE evaluation distribution. Printed manuals can be purchased for $20 for delivery to the US, Canada, and Mexico. For all other destinations, printed manuals are $25. Printed manuals also come with a 3.5" HD disk.

See INVOICE.TXT or http://www.marshallsoft.com/order.htm

1.6 Updates

When you register the WSC/CE Serial Communication SDK you will receive a set of registered DLLs plus a license file (WSCxxxx.LIC) that can be used to update the registered DLL's for a period of one year from purchase. Updates can be downloaded from

http://www.marshallsoft.com/oem.htm

After one year, the developer license must be updated to be able to download updates. The developer license can be updated for $30 if ordered within one year from the original purchase (or previous update). After one year, licenses can be updated for $55. Source code can be updated for $25 in addition to the license update.

Note that the registered DLL's do not expire.

1.7 Customer ID

The Customer ID is the 4 or 5 digits following the product name (WSC) in the license file. For example, customer 1234 will receive license file WSC1234.LIC. Provide the Customer ID in the email Subject when contacting us for technical support (WSC4C 1234).

1.8 License File

When a developer license is purchased, the developer will receive a license file named WSCxxxx.LIC, where "xxxx" is the 4 or 5 digit customer ID. The license file is an encrypted binary file used for updating WSC as explained in section 1.6 "Updates". The license file is required in order to create (or update) the registered DLL's.

2 Application Notes

2.1 Keycode (License Key)

When you register WSC/CE, you will receive a new set of DLL's and a key code for your DLL's. Pass this keycode as the second argument to SioKeyCode. The keycode will be found in the file named "KEYCODE". The registered keycode is a 9 or 10 digit number. It is not your Customer ID. The keycode for the evaluation (shareware) version is 0.

2.2 USB Ports

WSC/CE will work with USB ports which have a "USB / Serial Port" converter installed.

The Win/CE driver that comes with the "USB / Serial Port" converter will create a virtual RS232 serial port, and handle the conversion between RS232 serial data and USB data.

2.3 Threads

The Windows/CE Serial Communications Library (WSC/CE) is thread safe. Note that calling 

     SioEvent(Port, EV_RXCHAR)
   
will block the thread in which SioEvent is called.  The blocking can be stopped by calling (from another thread)

    SioSetInteger(Port, 'S', 1)         [eVC]
    SioSetInteger(Port, ASC("S"), 1)    [eVB]

2.4 SioPuts Notes

The SioPuts function can operate in two ways: (1) "wait for completion" and (2) "immediate return".

In the first (default) way ("wait for completion"), SioPuts will not return to the caller until the entire contents of the buffer (passed to SioPuts) has been accepted by the UART

In the second way ("immediate return"), the contents of the buffer (passed to SioPuts) is queued in the transmit (TX) buffer within Windows, after which SioPuts returns. This means that SioPuts will return immediately, before any data is passed to the UART for transmission. This allows the calling program code to continue processing at the same time that the serial data is being transmitted.

In all cases, the value returned by SioPuts must be checked by the caller to determine the number of bytes actually accepted.

To enable the second method of operation (immediate return) for SioPuts , call SioInteger as follows before calling SioPuts. 

     SioSetInteger(Port, WSC_WAIT_ON_PUTS, 1)

2.5 Hardware Flow Control & Blocking

If hardware flow control is set, and CTS is 0, your application will block until CTS is raised by the serial device (modem, etc.). To prevent blocking because there is no modem connected, do this:

  1. Call SioReset and check the return code.
  2. Set DTR
  3. If DSR is 0, then you are NOT connected to a modem.
  4. If CTS is 0, then the modem has NOT enabled hardware flow control.
  5. If DSR & CTS are both not 0, set hardware flow control.

Another way to avoid blocking is to put the serial code in a Win32 thread. The thread may block but your invoking code will not.

2.6 Bluetooth Serial

Bluetooth is a short range radio that can be used to connect two Bluetooth enabled devices. Both Windows Standard Serial Communications Library for eVC (WSC4eVC) and the Windows Standard Serial Communications Library for eVB (WSC4eVB) SDK can be used with Bluetooth serial ports.

A PPC (Pocket PC) program using WSC/CE can communicate with any other Bluetooth enabled device such as PPC's, HPC's, desktop / laptop PC's, GPS receivers, Smartphone, etc.

Bluetooth makes use of two virtual serial ports: one named "inbound" and the other named "outbound". For example, iPAQ 3970 uses COM7 for inbound and COM8 for outbound, while the iPAQ 4355 uses COM8 for inbound and COM6 for outbound.

To discover which ports your machine is using, select the Bluetooth Manager, turn the Bluetooth radio on, and then choose the "Serial Port" entry. The Bluetooth port assignments cannot be changed.

The inbound port is for accepting "inbound" serial connections, and the outbound port is for initiating "outbound" serial connections. The only difference between inbound and outbound is which device initiates the serial connection over Bluetooth. Use the outbound port to initiate the connection and the inbound port to accept the connection from some other device. Once the Bluetooth connection is established, the one port is used for normal serial communications in both directions.

Some Bluetooth devices require that they be configured as "paired devices". For these devices, follow the directions for the particular device.

For more information on Bluetooth, see http://www.bluetooth.com

2.7 Emulation

Example programs can also be compiled with the Pocket PC emulator that is provided with Microsoft Embedded Tools. This will allow a programmer to develop serial communication applications without having the physical Windows/CE device.

The following information, which is the same that is provided in the WSC/CE Programmer's Manual, describes how to run the SimpleV4 example program on the PPC 2003 emulator, and assumes that you have installed WSC4eVC into the default directory C:\WSC4eVC

  1. Run CopyDLLeVC.exe, choosing the PPC 2003 emulator version (EMU). This will copy the PPC 2003 emulator DLL's to the COPY directory and the corresponding LIB's to the APPS directory.

  2. Start eVC4 (Microsoft Embedded Tools 4).

  3. Choose "Tools/Configure Platform Manager", then choose "POCKET PC 2003 Emulator", then click "Properties...". Expand Startup Server then click Emulator Startup Server. Click Configure button for the emulator startup server to open the Emulation Configuration Settings dialog box. Expand Serial Port 1 and click to the port wanted (COM1 to COM3). Click Apply. Finally, push "OK" three times to return to eVC4.

  4. From the menu bar, choose "File/Open Workspace". Set "Files of type:" to "Projects".

  5. Load the eVC project SimpleV4.vcp. Check that "POCKET PC 2003", "Win32 (WCE emulator) Release", and "Pocket PC 2003 Emulator" are displayed.

  6. Click "Build/Rebuild All". Simple.cpp will be compiled to SimpleV4.exe and then uploaded to the emulator. Be sure that you are linking with the emulator version of WSC32.LIB.

  7. Copy WSC32.DLL from the COPY directory to the same directory as SimpleV4.exe. For example: 
     COPY C:\WSC4eVC\COPY\wsc32.dll APPS\emulatorRel

  1. Once the "Pocket PC 2003" emulator pops up, click "Emulator/File Sharing...". Enable "Share this folder:" then enter the full path name of the folder that contains (both) SimpleV4.exe and WSC32.DLL. For example, 
     C:\WSC4eVC\APPS\emulatorRel

  1. Click "Tools/Remote File Viewer". Then choose "Pocket PC 2003 Emulator" and "File/Export File" to upload WSC32.DLL to the emulator.

  2. Click "Build/Execute SimpleV4.exe" to start execution.

For more information on using the emulator, search for "Moving Files to and from the Emulator" at 

     http://msdn.microsoft.com

3 XMODEM and YMODEM

3.1 XYM Introduction

The XMODEM and YMODEM functions are implemented as DLL's (Dynamic Link Libraries), in XYM32.DLL, and are state driven like the Modem I/O functions described in the previous section.

Files can be sent and received using XMODEM, XMODEM/CRC, XMODEM/1K, and YMODEM. The basic procedure used to run XMODEM and YMODEM is as follows:

  1. Call xyAcquire() immediately after calling SioReset().
  2. To receive a file, call xyStartRx(), then call xyDriver() repeatedly until XY_IDLE is returned.
  3. To send a file, call xyStartTx(), then call xyDriver() repeatedly until XY_IDLE is returned.
  4. Call xyRelease() immediately before calling SioDone().

Refer to XMODEM.TXT for more information on the internal operation of the XMODEM protocol, and to YMODEM.TXT for more information on the internal operation of the YMODEM protocol.

3.2 XYM Example Programs

There are four XMODEM and YMODEM example programs. Example programs are found in the APPS directory, which is created when running SETUP.

3.3 XYM Function Summary

Refer to the WSC/CE Reference Manual (WSC_eREF) for more information on individual XY Modem functions (XYM32.DLL).

http://www.marshallsoft.com/WSC_eREF.htm


4 Problems

  1. If you cannot get your application to run properly, first compile and run the terminal emulator program SIMPLE provided on your distribution disk. Test SIMPLE by connecting two computers with a null modem cable or by commanding a Hayes AT command set compatible modem.

  2. If your application does not run but SIMPLE runs correctly, then you have most likely made a programming mistake in your application. MarshallSoft Computing cannot debug your application, especially over the telephone! However, consider each of the following when searching for an error in your application.

  3. Are the receive and transmit buffers large enough? Use a buffer size that is twice the size of the largest expected block.

  4. Have you selected too high a baud rate? Win/CE can multitask many tasks at once. You may have to lower your baud rate.

  5. Did SioReset return a zero value? If not, then the port is not open.

  6. Did you send the proper initialization string to your modem? Did you set DTR and RTS? (you should).

  7. Are you sure you have selected the correct CPU for your Win/CE machine? Also verify that you are compiling for PPC 2002 or PPC 2003.

  8. If you are using the registered version of WSC/CE and you are still getting the evaluation screen, make sure you have deleted all copies of the WSC/CE evaluation DLL's in the Windows search path.

  9. Verify that you are linking your application with the correct version of WSC32.LIB (or XYM32.LIB). For example, if you are compiling for the eVC4 emulator (PPC 2003), you must link with the corresponding PPC 2003 emulator version of WSC32.LIB.

  10. Verify that you are using either Embedded Tools v3.0 for PPC 2002 programs or Embedded Tools v4.0 for PPC 2003 programs. Also note that project files for Embedded Tools v3.0 end with "V3.vcp" while project files for Embedded Tools v4.0 end with "V4.vcp".

We recommend the following steps if you believe that you have discovered a bug in the library:

  1. Create the smallest, simplest test program possible that demonstrates the problem.
  2. Document your exact machine configuration and what error the test program demonstrates.
  3. Email us the example source.

If the problem is an error in the library and can be solved with an easy work-around, we will publish the work-around. If the problem requires a modification to the library, we will make the change and make the modified library available to our customers without charge.


5 Legal Issues

5.1 Registration

See Section 1.5 "Ordering" for information on ordering.

5.2 License

MarshallSoft Computing, Inc. grants the registered user of WSC the right to use one copy of the WSC DLL's on a single computer in the development of any software product. The user may not use the library on more than one computer at the same time.

The "student" registered DLL's may not be distributed under any circumstances, nor may they be used for any commercial purpose.

The "professional" registered DLL's may be distributed (without royalty) in object form only, as part of the user's compiled application. The registered DLL's may NOT be distributed as part of any software development system (compiler or interpreter) without our express written permission. The source code for the library (WSC32.CPP and XYM32.CPP) is copyrighted by MarshallSoft Computing and may not be released in whole or in part.

5.3 Warranty

MARSHALLSOFT COMPUTING, INC. DISCLAIMS ALL WARRANTIES RELATING TO THIS SOFTWARE, WHETHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, AND ALL SUCH WARRANTIES ARE EXPRESSLY AND SPECIFICALLY DISCLAIMED. NEITHER MARSHALLSOFT COMPUTING, INC. NOR ANYONE ELSE WHO HAS BEEN INVOLVED IN THE CREATION, PRODUCTION, OR DELIVERY OF THIS SOFTWARE SHALL BE LIABLE FOR ANY INDIRECT, CONSEQUENTIAL, OR INCIDENTAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE SUCH SOFTWARE EVEN IF MARSHALLSOFT COMPUTING, INC. HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES OR CLAIMS. IN NO EVENT SHALL MARSHALLSOFT COMPUTING, INC.'S LIABILITY FOR ANY SUCH DAMAGES EVER EXCEED THE PRICE PAID FOR THE LICENSE TO USE THE SOFTWARE, REGARDLESS OF THE FORM OF THE CLAIM. THE PERSON USING THE SOFTWARE BEARS ALL RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE.

Some states do not allow the exclusion of the limit of liability for consequential or incidental damages, so the above limitation may not apply to you.

This agreement shall be governed by the laws of the State of Alabama and shall inure to the benefit of MarshallSoft Computing, Inc. and any successors, administrators, heirs and assigns. Any action or proceeding brought by either party against the other arising out of or related to this agreement shall be brought only in a STATE or FEDERAL COURT of competent jurisdiction located in Madison County, Alabama. The parties hereby consent to in personam jurisdiction of said courts.

6 Summary

6.1 WSC Function Summary

Refer to the WSC/CE Reference Manual (WSC_eREF) for detailed information on the WSC/CE functions. A one line summary of each function follows.

There are 33 functions in the WSC/CE library.