Windows Standard

Serial Communications

for eVC

Programmer's Manual


(WSC_4eVC)


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


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 Features
1.2 Example Code Segment
1.3 Documentation Set
1.4 Installation
1.5 Uninstalling
1.6 Ordering
1.7 Updates
2 Library Overview
2.1 Dynamic Link Libraries
2.2 Static Linking
2.3 Compiling Programs
2.4 Emulation
3 Example Programs
3.1 WSCVER (WSC Version)
3.2 SIMPLE
3.3 MESSAGE
3.4 DEVICE
3.5 MODEM
3.6 XMS and XMR
3.7 YMS and YMR
4 Revision History

1 Introduction

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

The WSC/CE component library uses a simple interface to communicate with any device connected to a serial port. WSC4eVC includes several eMbedded Visual C++ (eVC) example programs demonstrating serial communication functions.

The Windows/CE Standard Serial Communications Library (WSC/CE) includes 33 functions, modem control , and XMODEM and YMODEM protocols. WSC4eVC will work with all Pocket PC (PPC) platforms supported by Microsoft eMbedded Visual C++ v3.0 (eVC3) and eMbedded Visual C++ v4.0 (eV4). The eVC comm library can also be used with Bluetooth serial. The library can also be used 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 WSC/CE DLL (WSC32.DLL) can be used from any language capable of calling the Windows/CE API. MarshallSoft provides separate products for Windows 95/98/ME and NT/2000/XP. Evaluation versions for these may be downloaded from our web site at

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

When comparing the Windows/CE Standard Serial Communications Library component library against our competition, note that:

  1. WSC4eVC is a standard Windows DLL (NOT an OCX or ActiveX control) and is much smaller than a comparable OCX or ActiveX control.
  2. WSC4eVC does NOT depend on ActiveX or similar "support" libraries. Makes calls to Windows/CE API functions only.
  3. WSC4eVC is fully thread safe.
  4. The WSC4eVC functions can be called from applications not capable of using controls.
  5. The same DLL can be used both eVC and eVB programs.

Our goal is to provide a robust serial communication component library that you and your customers can depend upon. A fully functional evaluation version is available. Contact us if you have any questions.


1.1 Features

Some of the many features of the Windows/CE Standard Serial Communications Library for eVC component library are as follows:

A good selection of  eVC++ example programs with full source code are included.  Refer to Section 6  for more details on each of the example programs.

     [PROGRAM]    [DESCRIPTION]
     WSCVER     : Program that displays the WSC version number and build.
     SIMPLE     : A simple terminal program (uses timer).
     MESSAGE    : A simple terminal program (uses Windows message loop).
     DEVICE     : Sends a user command to a serial device.
     MODEM      : Same as SIMPLE but controls flow control, modem lines, etc.
     XMS , XMR  : XMODEM send/receive programs.
     YMS , YMR  : YMODEM send/receive programs.


1.2 Example Code Segment

 
     // pass keycode (0 for evaluation version) to WSC
     SioKeyCode(0);
     // open the port
     Code = SioReset(Port, 1024, 1024);
     if(Code<0)
       {// SioReset fails
        wsprintf((LPWSTR)Temp,L"Cannot open COM%1d: Error %d",1+Port,Code);
        MsgBox((LPWSTR)&Temp);
       }
     else
       {// open opened successfully
        wsprintf((LPWSTR)Temp,(LPWSTR)L"COM%1d opened @ %d",1+Port,BaudRate);
        MsgBox((LPWSTR)&Temp);
        // set baud rate (default is 19200)
        SioBaud(Port,BaudRate);
        // set DTR & RTS
        SioDTR(Port,'S');
        SioRTS(Port,'S');
        // set hardware (RTC/CTS) flow control
        Code = SioFlow(Port, 'H');
        // set parity, stop bits & data bits (default is 8N1)
        SioParms(Port, WSC_NoParity, WSC_OneStopBit, WSC_WordLength8);
        // transmit "AT" followed by a carriage return
        Code = SioPuts(Port, "AT\r", 3);
        // close port
        SioDone(Port);
       }

1.3 Documentation Set

Documentation is located in the /APPS subdirectory where WSC4EVC is installed and also can be accessed online from the Windows/CE Standard Serial Communications Library for eVC product page at:

http://www.marshallsoft.com/evc-serial-comm-pocketpc.htm

Documentation consists of four manuals. This is the first manual (WSC_4eVC) in the set.

Each manual comes in three formats:

The WSC_4eVC Programmer's Manual is the language specific eMbedded Visual C++ manual and provides information needed to compile your programs in an eVC++ environment.

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

The WSC/CE 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.


1.4 Installation

  1. Unzip WSC4eVC34.ZIP (or WSC4eVC.ZIP for registered users) using WINZIP or PKZIP for Windows.

  2. Run the installation program SETUP.EXE which will install all WSC4eVC files to your desktop computer.

The SETUP program creates a directory (default WSC4eVC) on the desktop machine with the following sub-directories (folders).

     DOCS : All documentation.
     APPS : All example code.
     COPY : DLL's to be copied to the PPC WINDOWS directory.
     PPC_2002_ARM   : ARM/PPC version of WSC32.DLL and XYM32.DLL
                      ARM/PPC version of WSC32.LIB and XYM32.LIB
     PPC_2002_X86   : X86/PPC emulator version of WSC32.DLL and XYM32.DLL
                      X86/PPC emulator version of WSC32.LIB and XYM32.LIB
     PPC_2003_ARMV4 : ARMV4/PPC version of WSC32.DLL and XYM32.DLL
                      ARMV4/PPC version of WSC32.LIB and XYM32.LIB
     PPC_2003_EMU   : PPC emulator version of WSC32.DLL and XYM32.DLL
                      PPC emulator version of WSC32.LIB and XYM32.LIB

NOTE: The COPY directory contains the version of WSC32.DLL and XYM32.DLL chosen when SETUP is run.

After SETUP completes, the DLL's in the COPY directory (folder) must be copied to your Win/CE machine's \WINDOWS directory (folder) using ActiveSync. ActiveSync can be downloaded from Microsoft at

http://www.microsoft.com/windowsmobile/downloads/default.mspx

Microsoft Embedded Tools v3 or v4 must be installed on your desktop in order to compile the example programs. Download from Microsoft at:

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

1.5 Uninstalling

Uninstalling WSC4eVC is very easy. WSC4eVC does not modify the registry. First, delete the WSC4eVC project directory created when installing WSC4eVC. Second, delete WSC32.DLL and XYM32.DLL your Win/CE machine's \WINDOWS directory (folder) using ActiveSync.

1.6 Ordering

WSC4eVC can be registered for $115 (or $195 with source code). Refer to Section 1.6, "Ordering" in the WSC/CE User's Manual (WSC_eUSR) for details on ordering or purchase a developer license online at

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

1.7 Updates

An update for WSC4eVC may be purchased for $30 (for email delivery) if ordered within one year of the original purchase (or previous update). After one year, WSC4eVC can be updated for $55. See Section 1.6, "Ordering" in the WSC/CE User's Manual (WSC_eUSR) for details.

Note that the registered DLL's do not expire.

2 Library Overview

2.1 Dynamic Link Libraries

WSC4eVC is implemented as a Win/CE dynamic link library (DLL). A DLL is characterized by the fact that it need not be loaded until required by an application program and that only one copy of the DLL is necessary regardless of the number of application programs that use it. Contrast this to the traditional static library which is bound to each and every application that uses it at link time.

2.2 Static Linking

Registered users (who have ordered WSC4eVC with source code) can easily compile WSC32.CPP into their application, so that the WSC32.DLL is not needed.

In the WSC/CE prototype file wsc.h, change

     #ifdef WSC_IMPLEMENTATION
     #define WSCDLLEXPORT _declspec(dllexport)
     #else
     #define WSCDLLEXPORT _declspec(dllimport)
     #endif

to
   
     #define WSCDLLEXPORT
   

2.3 Compiling Programs

Microsoft Embedded Tools v3 or V4 must be installed on your desktop computer in order to compile the example programs.

  1. Start Microsoft Embedded Tools Visual C++.

  2. Click "Tools/Configure Platform Manager", then click "POCKET PC 2003 " or "POCKET PC 2002". Click OK,

  3. Click "File/Open Workspace" menu item in Microsoft Embedded Tools to open the eVC project files (*.vcp) in the APPS directory (folder) (i.e., \wsc4evb\apps). Expand Files of Type: and click Projects: [.vcp, dsp]. Open file. eMbedded Tools V3 projects end in v3.vcp and eMbedded Tools V4 projects end in v4.vcp.

  4. From the main menu, click "Project / Settings...". When the "Project Settings" window is displayed, click "Link" .

  5. Add WSC32.LIB to "Object/library modules:" if not already there (which it should be for all example programs).

  6. For any project that uses the XMODE/YMODEM module (such as the XMS, XMR, YMS, and YMR example programs), also add XYM32.LIB to "Object/library modules:" if not already there.

  7. From the main menu, choose "Build", then choose "Rebuild All" .

  8. After compiling the program, copy it to a pocket pc (PPC) machine using ActiveSync where it can be executed. You can copy the program executable to any PPC directory that you choose.

2.4 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 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 Example Programs

All example program compile using Microsoft's Embedded Tools v3 (eVC3) or Embedded Tools v4 (eVC4). eVC3 project files end with "V3.vcp" while eVC4 project files end with "V4.vcp".

3.1 WSCVER

The first example program is the WSCVER ("WSC Version") program which displays the WSC library version number. Its purpose is display the WSC/CE version, build, and registration string as well as to verify that WSC32.DLL is being found and loaded by Windows/CE.


3.2 SIMPLE

SIMPLE is a very simple communications program using WSC4eVC. Everything typed on the keyboard is sent to the serial port, and everything incoming from the serial port is displayed on the screen.

Test SIMPLE by connecting the PPC to a RS232 serial device or another computer using the serial port or Bluetooth (virtual) serial port.

3.3 MESSAGE

MESSAGE is a very simple communications program using WSC4eVC. Everything typed on the keyboard is sent to the serial port, and everything incoming from the serial port is displayed on the screen.

MESSAGE is the same program as SIMPLE except that it uses Windows messages in the Windows message loop rather than a timer to check for incoming serial data.

3.4 DEVICE

The DEVICE program is designed for talking to an arbitrary serial device. Use this program as a guide when communicating with serial devices other than modems and other computers.

3.5 MODEM

The MODEM program uses WSC/CE functions to set flow control (hardware, software, or none), DTR line (set or clear), RTS line (set or clear), display the transmit & receive queue sizes, detect a break signal, and detect changes in DSR and CTS. Various line errors can be checked such as parity error, framing error, data overrun, receive queue overflow, and transmit buffer full.

3.6 XMS and XMR

XMS (XMODEM Send) and XMR (XMODEM Receive) are programs that send and receive files using the XMODEM protocol. The default for the local directory is \My Documents.

3.7 YMS and YMR

YMS (YMODEM Send) and YMR (YMODEM Receive) are programs that send and receive files using the YMODEM protocol. The default for the local directory is \My Documents.


4 Revision History

Version 3.3: July 21, 2003

Version 3.4: May 8, 2005