SuperCom - Serial Communication Library

Easy Handling

SuperCom is a universal communication library. Using only few functions you already get a complete serial communication program within few lines. The following short program clearly shows this for serial communications:

C/C++ 

  char *Msg = "Hello World";

  ComInit(COM_2);

  ComSetState(COM_2, 57600, 8, 1, 'N', SIGNAL_CTS);

  RS_TXPacket(COM_2, Msg, strlen(Msg), &Result);

  ComReset(COM_2);
  C/C++    C#    Delphi    Visual Basic

The function ComInit configures the interface. ComSetState initializes the serial interface "COM2" with the new transmission parameters and flow control. The function RS_TXPacket transmits the data packet Msg through the serial interface and ComReset closes all action on the serial interface and restores the previous state of the interface.

The next small sample shows an elegant solution to a common problem: What serial ports are available in the system (installed and not used).

Available Serial Ports 

    WORD wPortCount=0;
    WORD wPortReady=0;
    BYTE i;

    printf("scaning hardware...");

    for (i=COM_1; i<MAX_COM; i++)
    {
        switch (ComPortPresent(i))
        {
        case PORT_AVAILABLE_READY: wPortReady++;
             // port is not used by any application

        case PORT_AVAILABLE_BUSY: wPortCount++;
             // port is used by any application
            break;

        case PORT_UNAVAILABLE:
             // hardware is not installed
             break;
        }
    }
     
Hint: see also ComPortPresentEx

Event Driven

An application using SuperCom can be event driven. Events are reported for: received or transmitted data, modem status, line errors, modem dialup status, file transmit status, plugging or unplugging serial PnP devices (serial comm port insertion/removal), TCP/IP network failures.

The enhanced event reporting mechanism in SuperCom also enables you to receive events on any defined character (e.g. STX, ACK, NAK, EOF).

Type and amount of the events is also related to the used SuperCom software e.g. a SuperCom supporting only serial communications will not report TCP/IP network events.

Event function receiving communications events
C/C++ 
       // optional event function
   DWORD COMMAPI OnComm (Com, SComEvent)
   {
       if (SComEvent & EV_TXCACHE_EMPTY)
          // ...

       if (SComEvent & EV_RXCHAR)
          // ...

       if (SComEvent & EV_RI)
          // ...

       if (SComEvent & EV_TRIGGER)
          // ...

         :
         :
      return 0;
   }
      :
      :
     // init  ...
   ComInit(Com);

     // activate event reporting ...
   ComGetSetEventProc(Com, OnComm);
  C/C++    C#    Delphi    Visual Basic

Connecting

Establishing connections through a Modem, TAPI, TCP/IP or ISDN is taken care by the common connect functions. The SuperCom functions can establish a connection (dialup) or waiting on an incoming call (server) and execute (on request) completely in background.

The SuperCom functions can trigger events during a connection attempt and provide the application with status information. So, even it executes in background the application stays in touch with the happening.

Modem Connection, OnConnect - InfoProc
C/C++ 
       // optional event function
   int OnConnect(Com, Action, TimeLeft, Data)
   {
      if (Action==acCONNECT_INFO)
      {
         // Received periodically, while in progress
      }
      if (Action==acCONNECT_OK)
      {
         // Connected !
      }
      if (Action==acCONNECT_FAILED)
      {
         // A connection attempt failed
      }
      if (Action==acCONNECT_USERBREAK)
      {
         // User interrupted
      }

      return infContinue;
   }

      :
      :
     // init  ...
   ComInit(Com);

     // now connect ...
   Res = RS_ConnectEx(Com, SEC_60, , DialStr, OnConnect);
  C/C++    C#    Delphi    Visual Basic

Seting up a connection can run completely in background. The application receives events about the progress.

Comparing this sample made for a serial Modem with the one for TCP/IP or ISDN shows how effective it is to have a portable API!

File Transfer Protocols

SuperCom provides reliable and high speed file transfer protocols. These protocols are widely used and supported by many third party applications (e.g. ZMODEM, YMODEM/BATCH, YMODEM, YMODEM-G, XMODEM-1K, XMODEM, XMODEM/CRC, KERMIT, Extended XMODEM and ASCII).

One of the most powerful among these protocols is ZMODEM that includes important features like "crash recovery", 32bit CRC, "batch file transfer", File Options, ZMODEM/8k block option and the powerful ADONTEC extension ZMODEM/32k (ZMODEM/64k shipped on request). The SuperCom ZMODEM implementation also includes support for slow communication channels and high latency connections (e.g. Satellite lines).

The KERMIT protocol and the Extended XMODEM are also offering a lot of interesting options.

Autodownload
is a file transfer protocol feature that enables the automated receive of a file transmitted from a remote host machine. Autodownloading is actually supported with the ZMODEM, KERMIT and Extended XMODEM protocol.

A file transfer is very easy started by one function. The protocol then triggers events to inform about status and other usefull protocol information. Events are received by a so called *. The OnFile function is optional but very handy in many situation e.g. to receive progress information, to cancel a file transfer. A protocol like ZMODEM or YMODEM/BATCH can receive many files within on session. The OnFile will provide such information.

File Transfer, OnFile - InfoProc
C/C++ Sample 
       // optional event function
   int COMMAPI OnFile(Com, Action, DataCount, FileData)
   {
      int Res=infCONTINUE;

      if (Action==acSYN)
      {
        // Synchronization
      }
      if (Action==acRXING)
      {
        // A block of data received
      }
      if (Action==acTXING)
      {
       // A block of data transmitted
      }
      if (Action==acTXFIN)
      {
       // File successfully transmitted
      }
      :
      return Res;
   }
      :
    // Transmit a file ...
   RS_TXFile_ZMODEM(Com, FName, , OnFile);
  C/C++    C#    Delphi    Visual Basic

With the SuperCom library each protocol can run on any established connection concurrently and in background. Queues of files to transfer are also possible to create and monitor (file-server etc.).

The following samples are using the ActiveX API like class "TSCom" of the SuperCom .NET Class Library. It is the same API used for serial connections, TCP/IP and ISDN.

Establish a serial modem connection and file transfer
C# Sample 

        using ADONTEC.Comm;  // see C# source in SComClass.cs
           :                 // VB Net references the class DLL
           :
        public class MYSCOM : TSCom
        {
            public MYSCOM(int CommId, Form frm)
                : base(CommId, frm) // pass the window handle to TSCom
            {

            }
            protected override void OnComm(OnCommEventArgs e) [OnComm +-]

            protected override void OnConnect(OnConnectEventArgs e) [OnConnect +-]

            protected override void OnFile(OnFileEventArgs e) [OnFile +-]

            protected override void OnDataPacket(OnDataPacketEventArgs e) [OnDataPacket +-]


        } //MYSCOM

        SCom = new MYSCOM(Com, frm1);

         // Set some comm parameters
        SCom.ComType  = ComType.COMTYPE_RS232; // *) serial, TAPI, TCP/IP, ISDN
        SCom.Settings = "115200,N,8,1";
                // or
        SCom.BaudRate = 115200;
        SCom.DataBits = 8;
        SCom.StopBits = StopBits.One;
        SCom.Parity = Parity.None;

        SCom.Handshaking = Handshaking.SCOMM_HANDSHAKE_CTS;

        SCom.PortOpen = true;  // Ready to start action...
         :
             // need some trigger to report when received ?
        SCom.Trigger = SuperCom.StringToByteArray("Username");
        SCom.TriggerAction = TriggerAction.SCOMM_TRIGGER_ADD;
        SCom.Trigger = SuperCom.StringToByteArray("Password");
        SCom.TriggerAction = TriggerAction.SCOMM_TRIGGER_ADD;

              // now connect to a modem server ..
        SCom.ConnectAddress="1234 5678 99"; // phone number
        SCom.Connect = true;
         :
              // transmit a file
        SCom.FileName = "sales.doc";
        SCom.Protocol = Protocol.PROTOCOL_ZMODEM;
        SCom.FileTransmit = true;
         :
* One point to select the desired communication type!
The same class can be used for console applications as well.

The above sample gives a brief outline on how to use the ActiveX API like class "TSCom" of the SuperCom .NET Class Library.

 

Now, once we have a working sample as the above how much would it take to switch over to a TCP/IP client ?

Switching ComType from Serial to TCP/IP
C# Sample 

In the above sample we've done serial communications. Now we need to send files
to a TCP/IP server. We can create a new class or reuse the one we had in
the previous sample for serial communications.
         :
      SCom.PortOpen = false; // close that one...
      SCom.CommPort = ClientCom;  // switch comm index, if needed...
      SCom.ComType  = ComType.COMTYPE_WINSOCK_CLIENT; // *) serial, TAPI, TCP/IP, ISDN
      SCom.PortOpen = true; // Ready to take actions ...
         :
              // now connect to a TCP/IP server ..
      SCom.ConnectAddress = "www.weburl.com:9000";
      SCom.Connect = true;
         :
              // transmit a file
      SCom.FileName = "sales.doc";
      SCom.Protocol = Protocol.PROTOCOL_ZMODEM;
      SCom.FileTransmit = true;
         :
* one point to select the desired communication type!

Obviously, the SuperCom API not only increases productivity but the code developed once can be reused easily (e.g. from the SuperCom ActiveX, MSComm or PDQComm to SuperCom for NET) and most of the time without changes.

The following sample is using the ActiveX API like class "TSCom" of the SuperCom .NET Class Library within a console application.

Establish a serial file transfer (Tx, Rx)
C# console sample 

using ADONTEC.Comm;  // see C# source in SComClass.cs
                     // VB Net references the class DLL

namespace CSharpTxRxFileConsole
{
   class Program
   {
      public class MYSCOM : TSCom
      {
         public MYSCOM(int CommId) : base(CommId)
         {
         }

         // Optional but handy event functions
         protected override void OnComm(OnCommEventArgs e) [OnComm +-]

         protected override void OnFile(OnFileEventArgs e) [OnFile +-]


      }  // MYSCOM


      static void Main(string[] args)
      {
         Console.WriteLine(" CSharpTxRxFileConsole " + Environment.NewLine);

         MYSCOM SCom = new MYSCOM( SuperCom.COM_1); // create instance

         // Set some comm parameters
         SCom.ComType = ComType.COMTYPE_RS232; // *) serial, TAPI, TCP/IP, ISDN
         SCom.Settings = "115200,N,8,1";
         SCom.Handshaking = Handshaking.SCOMM_HANDSHAKE_NONE;

         Console.WriteLine("Opening port/channel" + Environment.NewLine);
         SCom.PortOpen = true; // // Ready to start action...

         if (SCom.PortOpen == false)
         {
            Console.WriteLine(" failed to open port/channel." + Environment.NewLine);
            SCom = null;
            return;
         }

         // OK so far we own an open port/channel now prepare environment e.g. DownLoadDir
         SCom.FileDownLoadDir = @"c:\adtmp";

           // Any Trigger to add for automated receive of files ?
         SCom.TriggerAction = TriggerAction.SCOMM_TRIGGER_ADD_ZMODEM;
         SCom.TriggerAction = TriggerAction.SCOMM_TRIGGER_ADD_KERMIT;


           // prepare for file transmission
         SCom.Protocol = Protocol.PROTOCOL_ZMODEM;
         SCom.FileName = "c:\\sales*2012.txt";

         Console.WriteLine("Starting transmition of " + SCom.FileName + Environment.NewLine);

         SCom.FileTransmit = true;  // send now

              :
              :

         // Lets assume we want also to receive file(s)
         // While we do a simple busy wait here SuperCom may receive files in background
         ConsoleKeyInfo cki;
         do
         {
             Console.WriteLine(".. now waiting to receive file(s). ");
             Console.WriteLine("Start Sender or press 'E' key to end .. " + Environment.NewLine);
             cki = System.Console.ReadKey();
         } while (cki.Key != ConsoleKey.E);

         :
         :

         Console.WriteLine(Environment.NewLine + "Closing the port...");

         SCom.PortOpen = false; // close port/channel, free communication index

         Console.WriteLine(" .. done." + Environment.NewLine);

         :
      }

   }
}
* One point to select the desired communication type!.

 

C++ Sample using high-level class CSuperCom

A small sample that connects and transmits a file. As one can easily see there is no difference between calls if Serial, ISDN or TCP/IP.

C++ Sample 
//-------------------------------------------------------------------
// SuperCom sample from C++ project Connect / TXFile
//
// Console connect sample using CSuperCom class v7.3 and later
//
// Copyright (c) 1991,2012 by ADONTEC Ltd.
//-------------------------------------------------------------------

#if defined(_OS_NT_)
#define STRICT
#include 
#endif

#include 
#include 

#include "supercom.hpp" // CSuperCom

#if defined(__OS_LINUX__)

#else
     // Enable TCP/IP or ISDN, disable both for serial
//#define __USE_TCPIP__
//#define __ISDN__
#endif


int bPgmEnd = FALSE;


//-------------------------------------------------------------------
// Class CCMyCOM
//-------------------------------------------------------------------
class CMyCOM : public CSuperCom {

    private:

    public:
    CMyCOM(LPCTSTR pszConfigString, HANDLE hWnd=0);
    ~CMyCOM(void);

      // optional event functions
    int OnComm(DWORD SComEvent);
    int OnConnect(WORD Action, DWORD TimeLeft);
    int OnFile(WORD Action, DWORD Data, PFDATA FileData);
};

CMyCOM::CMyCOM(LPCTSTR pszConfigString, HANDLE hWnd)
      :CSuperCom(pszConfigString, hWnd)
{
}
CMyCOM::~CMyCOM(void)
{
}

  // Optional Event functions called from SuperCom in background
int CMyCOM::OnComm(DWORD SComEvent)[OnComm +-]

int CMyCOM::OnConnect(WORD Action, DWORD TimeLeft)[OnConnect +-]

int CMyCOM::OnFile(WORD Action, DWORD Data, PFDATA pFileData)[OnFile +-]




#if defined(__USE_TCPIP__)
  #define SET_CONFIG  "SET_IP"=adontec.com:80;"
#elif defined (__ISDN__)
  #define SET_CONFIG  SET_OWNEXTENSION"=900020;"SET_CONNECTADDRESS"=222333344444;"
                    SET_CONNECTTIMEOUT"=10;"
#else   // Serial
    // standard serial port
  #define SET_CONFIG  "Serial=COM1;BaudRate=9600;"
    // or connect through a modem and also trace data
  #define SET_CONFIG  "Serial=COM18;BaudRate=115200;
                    ConnectAddress=222333344444;
                    TRACE=C:\\sc_trace.txt;"
#endif

int main(int argc, char** argv)
{
    printf("\nSuperCom Connect sample\nEstablishing connection\n[" );

    CMyCOM *ThisCOM = new CMyCOM(SET_CONFIG); // create instance

    ThisCOM->Connect(TRUE); // now open channel and try to connect

    printf("]");

    if (ThisCOM->ComValid() == FALSE)
        printf("\nFailed to open channel!\n");
    else if (ThisCOM->Connected() == FALSE)
        printf("\nFailed to connect!\n");
    else // port opened, connected, now perform ...
    {
        int nErrorCode;
        char szFileName[SC_MAXPATH]="sales.dat";
        printf("\nConnected .. starting transmitting %s\n[", szFileName);

        ThisCOM->RS_TXFile (PROTOCOL_ZMODEM, szFileName, &nErrorCode);

        if (nErrorCode)
            printf("\n Err=%d", nErrorCode);

        printf("]\nDone.");
    }

    printf("\nPress ENTER to end.\n");
    getchar();
    return 0;
}

 

Special Applications

RS-485 Multidrop

Besides supporting RS-232 and RS-422 serial communication, SuperCom also support the RS-485 data communication.

RS-485 connects two or more stations on a two wire half-duplex bus system (network). That is bi-directional, half-duplex, multi-drop serial data communication over a single pair of cable. Each station can only transmit or receive data at a time (half-duplex). The so called "direction" is used to switch from transmit to receiving mode and vice versa. A timed switch of the "direction" is essential to avoid loss in data.

SuperCom handles the RS-485 serial port transparently and offers a very low-latency switch of "direction" (more...). A four wire full-duplex connection may also be used.
::: The testing samples showed that SuperCom can switch several times within 1 ms.

9-Bit serial data

9-Bit serial communication (9-Bit framing) is mainly used to identify address byte within messages running on a RS-485 multidrop network but also on standard RS-232 connections. 9-Bit frames are usually not supported by the standard PC UART but simulated by the SuperCom software. Very fast response timing (low latency) by the software is essential to accomplish reliable 9-bit data communication. SuperCom does provide a very realiable solution here to be used with high level languages.
Many Samples (e.g. C/C++, C#, Delphi) also included that demonstrate this operating mode.

For example, transmitting a data packet using 9-bit addressing e.g.:

        TXPacket9BitCond(Com, cData, nDataCount, SEC0_1);

Intelligent Functions

SuperCom includes additional intelligent functions that solve lengthly or complex operations thus avoiding delaying or blocking of your application (e.g. Data Filtering, Data Monitoring, Data Trigger, Data Packets, File Transmission Queue). The result is a rock-solid solution developed much faster than with regular tools. More samples here.

 

More info on SuperCom Library, price list and order form.

Home    Back
Modified at:

Info about ADONTEC
It Simply Works!