[[TOC]]

= CCommSerial =

CCommSerial is a C++ class that is provided to simplify 825 serial communications. CCommSerial is inherited from the CComm base class.

== Constructors ==

{{{
CCommSerial(void)
CCommSerial(int port);
}}}
These constructors just create a CCommSerial object without opening a communications channel.

==== Parameters ====
 * port - serial port number ( 1 = COM1, 2 = COM2 )

==== Remarks ====

For the **825gen2** support is added for USB serial adapters and sending text to USB printers. Offsets for the COM port are defined for these devices: COMM_USB_SERIAL_OFFSET, and COMM_USB_PRINTER_OFFSET.

==== Examples ====

{{{
CCommSerial *pSerial = new CCommSerial();
// Creates a CCommSerial instance that does not have a port specified yet. Method SetPort() must be called before calling Open().
}}}

{{{
CCommSerial *pSerial = new CCommSerial(2);
// Creates a CCommSerial instance that when opened will connect to COM2
}}}

USB to Serial adapter example **825gen2**
{{{
CCommSerial *pSerial = new CCommSerial(COMM_USB_SERIAL_OFFSET);
// Creates a CCommSerial instance that when opened will connect to first USB to serial adapter /dev/ttyUSB0
}}}

USB Printer example **825gen2**
{{{
CCommSerial *pSerial = new CCommSerial(COMM_USB_PRINTER_OFFSET + 1);
// Creates a CCommSerial instance that when opened will connect to second USB printer /dev/usb/lp1
}}}

**NOTE** When "new" is used to instantiate an object be sure to "delete" the memory when the use of the object is complete. Otherwise a memory leak will occur and the 825 may run out of memory.

{{{
  pSerial->Close();
  delete pSerial;
  pSerial = NULL; // Good practice to set pointer to NULL after delete
}}}

==== Example ====

{{{
   if(commTypeSelection == SERIAL)
   {
      int commPort = 2;
      CCommSerial *pSerial = new CCommSerial(commPort);
      pComm = pSerial;
   }
   pComm->Open();

   // Now the app can call pComm->Send to send data without regard for whether it is serial or TCP/IP.

   pComm->AddRcvEvent(CHR_STX, CHR_ETX, CommEventDataMsg, 0, NULL);

}

void StopCommunications(void)
{ 
   if(pComm != NULL)
   {
       pComm->Close();
       delete pComm;
       pComm = NULL;
   }
}

COMM_EVENT(DataMsg)
{
   uint8* buf = pConnection->GetRcvBuffer();
   buf[pConnection->GetRcvPos() - 1] = '\0';

   printf("rcvd [%s]\r\n", buf);

   if(buf[1] == 'T') // Received <STX>T<ETX> return timeval
   {
       time_t tmval;
       time(&tmval);  // Get timeval

       char response[12];
       sprintf(response, "%d\n", tmval);
       // pConnection isn't important in the case of serial port, but if TCP/IP server it is important to send
       // the response to the connection that the message was received from.
       pComm->Send(pConnection, response, strlen(response);
    }


   return 0;
}


}}}

== Member Functions ==

=== !SetPort ===
Sets the communications port to be used when Open() is called.

{{{
void SetPort(int port);
}}}

==== Parameters ====
 * port - the port number

==== Return Value ====

Function does not return any parameters

=== Open ===
Opens the previously specified port.

{{{
int Open(void);
}}}

==== Parameters ====
 * void - no parameters

==== Return Value ====

Returns 1 if successful or 0 if unsuccessful.

==== Remarks ====

==== Example ====

{{{
}}}

=== Close ===
Closes the connection
{{{
int Close(void);
}}}

==== Parameters ====

Function does not accept any parameters

==== Return Value ====
 
Function always returns zero.

==== Remarks ====

For serial ports it may be necessary to provide some delay to allow all of the buffered data to be sent out of the port before closing the port.

==== Example ====

=== !SetParameters ===
Set the baud rate, number of data bits, parity, and number of stop bits for serial ports.
{{{
bool SetParameters(baud_index baud, data_bit_index = data8, parity_index = parityNone, stop_bit_index = stopOne);
}}}

==== Parameters ====
 * baud_index - baud1200, baud2400, baud4800, baud9600, baud19200, baud38400, baud57600, or baud115200
 * data_bit_index - data7 or data8
 * parity_index - parityNone, parityEven, or parityOdd
 * stop_bit_index - stopOne or stopTwo

==== Return Value ====

Returns true if successful, false if not successful.

==== Remarks ====

==== Examples ====

{{{
CCommSerial* pSerial = new CCommSerial(2);
if(pSerial->Open())
{
   pSerial->SetParameters(CCommSerial::baud9600, CCommSerial::data7, CCommSerial::parityEven, CCommSerial::stopOne);
}
}}}

{{{
CCommSerial* pSerial = new CCommSerial(2);
if(pSerial->Open())
{
   pSerial->SetParameters(CCommSerial::baud19200);
}
}}}

=== !IsReady ===
Check the state of the serial CTS input (for serial ports that are equipped with CTS input)
{{{
bool IsReady(void);
}}}
==== Parameters ==== 

Function does not accept any parameters.

==== Return Value ====

Function returns true if CTS is active, false if CTS is inactive.

==== Remarks ====

IsReady() will return false if the CTS line is unconnected. Printers or other devices must be wired correctly for applications to be able to use this function to determine their readiness. '''The main board COM3 is not currently supported by this function.'''

==== Example ====

{{{
CCommSerial *pSerial = new CCommSerial(2);
if(pSerial->Open())
{
   pSerial->SetRTS(true);
   if(pSerial->IsReady() == false)
   {
      DisplayText(0, 0, "Device offline, or disconnected");
   }
}
}}}


=== SetRTS ===
Set the state of the serial RTS output

{{{
bool SetRTS(bool bRTSOn = true);
}}}

==== Parameters ==== 

 * bRTSOn - true to turn on RTS output, false to turn off RTS output

==== Return Value ====

Returns true if successfully set RTS state, false otherwise.

==== Remarks ====

==== Example ====

{{{
CCommSerial* pSerial = new CCommSerial(2);
if(pSerial->Open())
{
   pSerial->SetRTS(true);
}
}}}







== See Also ==

 * [wiki:CComm CComm]
 * [wiki:CCommClient CCommClient]
 * [wiki:CCommServer CCommServer]