--- title: "Serial (_Serial class)" canonical: "https://docs.cuesystem.com/space/CVCHELP/522289153/Serial%20(_Serial%20class)" format: markdown --- > Macro (toc) --- # ClearReceiveBuffer This function removes received data from a receive buffer.  #### Syntax  ```visualbasic Function ClearReceiveBuffer() ``` #### Example  ```visualbasic S1.ClearReceiveBuffer() ``` # Receive This function receives data from the channel’s receive buffer. At first *receiveddata* variable is cleared. The function terminates if the timeout expired or *maxbytestoreceive* bytes were received. It returns **True** if any data is received. It returns **False** if no data is received within the timeout limit or some error occurs. If some data is received, data is moved from the channel’s receive buffer to *receiveddata*. If no data is received, the *receiveddata* remains empty.  #### Syntax  ```visualbasic Function Receive(  ByRef receiveddata As ByteString,  Optional timeout As Time := :10.0,  Optional maxbytestoreceive As Long := 0)  As Boolean ``` #### Parameters  receiveddata  [ByteString](/wiki/spaces/CVCHELP/pages/495058958/Data+types#ByteString) It is a variable where received data is placed to.  timeout  [Time](/wiki/spaces/CVCHELP/pages/495058958/Data+types#Time) Optional, defaults to 10 seconds. It is the receive timeout.  maxbytestoreceive  [Long](/wiki/spaces/CVCHELP/pages/495058958/Data+types#Long) Optional, defaults to 0. It is the maximum number of received bytes stored in the parameter data. If maxsize is equal to 0 or greater than a declared length of the data string, the maxbytestoreceive is set to the declared length.  #### Return value  [Boolean](/wiki/spaces/CVCHELP/pages/495058958/Data+types#Boolean)   **True** if any data is received.   **False** if no data is received within the timeout limit or some error occurs. A function GetLastError returns the error number that occurred while executing the command. The following errors may occur: [92](/wiki/spaces/CVCHELP/pages/510525445/Command+errors#92).  #### Example  ```visualbasic Var RecvData As ByteString[100]  S1.Send(&S"SomeRequest")  // wait for an answer  If S1.Receive(RecvData) = True Then  // process answer  End If ``` # ReceiveAppend This function receives any data from the channel’s receive buffer. Compared to the function Receive the received data is appended to the end of the current *receivebuffer *content. It means the *receivebuffer *is not cleared. Appended data is removed from the channel’s receive buffer. The maximum length of the data read is limited by several empty bytes in *receivebuffer* (declared length minus actual length at the moment function starts). The function terminates if the timeout expired or any number of bytes was received. It returns **True** if any data is received. It returns **False** if no data is received within the timeout limit or some error occurs. If no data is received, the *receivebuffer *is not modified.  This function is helpful if you need to append any data from the channel, parse it in the same buffer and continue receiving. The command can save one buffer variable.  #### Syntax  ```visualbasic Function ReceiveAppend(  ByRef receivebuffer As ByteString,  Optional timeout As Time := :10.0)  As Boolean ``` #### Parameters  receivebuffer  [ByteString](/wiki/spaces/CVCHELP/pages/495058958/Data+types#ByteString) It is a variable where received data is appended.  timeout  [Time](/wiki/spaces/CVCHELP/pages/495058958/Data+types#Time) Optional, receive timeout.  #### Return value* * [Boolean](/wiki/spaces/CVCHELP/pages/495058958/Data+types#Boolean)   ***True*** if any data is received.   ***False*** if no data is received within the timeout limit or some error occurs. A function GetLastError returns the error number that occurred while executing the command. The following errors may occur: [92](/wiki/spaces/CVCHELP/pages/510525445/Command+errors#92), [145](/wiki/spaces/CVCHELP/pages/510525445/Command+errors#145).   # ReceiveFPacket This function receives the body of a data packet containing the body and footer. Footer is a constant data pattern that terminates the data packet. The body contains a payload of a data packet with variable length.  Data packet FPacket = Body + Footer.  The function clears the parameter *receivedbody* at first and then it stores received data to it. Then it moves data from the channel’s receive buffer to *receivedbody* and simultaneously checks data for the footer. If the footer is found it is removed from the *receivedbody*, the function returns **True** and the *receivedbody* contains just the body (payload). If the *receivedbody* is completely filled and the footer is not found or the footer did not follow, then the function returns **False** and all received data remains in *receivedbody*. If the whole data packet is not received within the timeout, then the function returns **False** and all received data remains in *receivedbody*.  #### Syntax  ```visualbasic Function ReceiveFPacket(  ByRef receivedbody As ByteString,  footer As ByteString,  Optional timeout As Time := :10.0)  As Boolean ``` #### Parameters  receivedbody  [ByteString](/wiki/spaces/CVCHELP/pages/495058958/Data+types#ByteString) It is a variable where received data is placed to.  footer  [ByteString](/wiki/spaces/CVCHELP/pages/495058958/Data+types#ByteString) It is a non-empty data pattern that terminates a data packet.  timeout  [Time](/wiki/spaces/CVCHELP/pages/495058958/Data+types#Time) Optional, defaults to 10 seconds. It is the receive timeout.  #### Return value  [Boolean](/wiki/spaces/CVCHELP/pages/495058958/Data+types#Boolean)   ***True*** if the complete footer is received before timeout.  ***False*** if the footer is not received within the timeout limit or some error occurs. A function GetLastError returns the error number that occurred while executing the command. The following errors may occur: [92](/wiki/spaces/CVCHELP/pages/510525445/Command+errors#92), [153](/wiki/spaces/CVCHELP/pages/510525445/Command+errors#153), [154](/wiki/spaces/CVCHELP/pages/510525445/Command+errors#154).  #### Example  This example describes how to receive a line of bytes terminated by CR LF (&S"\0D\0A").  ```visualbasic Private Var OneLine As ByteString[1024]  If S1.ReceiveFPacket(OneLine,&S"\0D\0A") Then    // line received, parse variable OneLine  Else   Select GetLastError()   Case 92 // error handling  Case 154 // error handling  End Select   End If ``` # **ReceiveHFPacket**  This function receives the body of a data packet containing a header, body, and footer. The header and Footer are constant data patterns that start and terminate data packet. The body contains a payload of a data packet with variable length.  Data packet HFPacket = Header + Body + Footer.  The function clears the parameter *receivedbody* at first and waits for the header. All data preceding the header including the header itself are removed from the channel’s receive buffer. If the header is found then all data following the header is moved from the channel’s receive buffer to *receivedbody* and simultaneously checks data for the footer. If the footer is found it is removed from the *receivedbody*, the function returns **True** and the *receivedbody* contains just the body (payload). If the *receivedbody* is completely filled and the footer is not found or the footer did not follow, then the function returns **False** and all received data remains in *receivedbody*. If the whole data packet is not received within the timeout, then the function returns **False** and all received data remains in *receivedbody*.  #### Syntax  ```visualbasic Function ReceiveHFPacket(  ByRef receivedbody As ByteString,  header As ByteString,  footer As ByteString,  Optional timeout As Time := :10.0)  As Boolean ``` #### Parameters  receivedbody  [ByteString](/wiki/spaces/CVCHELP/pages/495058958/Data+types#ByteString) It is a variable where received data is placed to.  header  [ByteString](/wiki/spaces/CVCHELP/pages/495058958/Data+types#ByteString) It is a non-empty data pattern that starts a data packet.  footer  [ByteString](/wiki/spaces/CVCHELP/pages/495058958/Data+types#ByteString) It is a non-empty data pattern that terminates a data packet.  timeout  [Time](/wiki/spaces/CVCHELP/pages/495058958/Data+types#Time) Optional, defaults to 10 seconds. It is the receive timeout.  #### Return value  [Boolean](/wiki/spaces/CVCHELP/pages/495058958/Data+types#Boolean)   ***True*** if header and footer were received before timeout.  ***False*** if header and footer are not received within the timeout limit or some error occurs. A function GetLastError returns the error number that occurred while executing the command. The following errors may occur: [92](/wiki/spaces/CVCHELP/pages/510525445/Command+errors#92), [153](/wiki/spaces/CVCHELP/pages/510525445/Command+errors#153), [154.](/wiki/spaces/CVCHELP/pages/510525445/Command+errors#154)  #### Example  This example describes how to receive a packet started by STX (&S"\02") and terminated by ETX (&S"\03").  ```visualbasic Private Var Data As ByteString[1024]  If S1.ReceiveHFPacket(Data,&S"\02",&S"\03") Then    // data received, parse Data  Else   Select GetLastError()   Case 92 // error handling  Case 154 // error handling  End Select   End If ``` # ReceiveHLPacket This function receives the body of a data packet containing a header and body with a known length. The header is a constant data pattern that starts the data packet. The body contains a payload of a data packet with a known length.  Data packet HLPacket = Header + Body with known length.  The function clears the parameter *receivedbody* at first and waits for the header. All data preceding the header including the header itself are removed from the channel’s receive buffer. If the header is found then the *bodylength* of bytes following the header is moved from the channel’s receive buffer to *receivedbody*. If the *bodylength* number of bytes was received, the function returns **True** and *receivedbody* contains just the body (payload). If the whole data packet is not received within the timeout, then the function returns **False** and all received data remains in *receivedbody*. If the *receivedbody* is full and *bodylength* is not reached, then the function returns **False** and all received data remains in *receivedbody*.  #### Syntax  ```visualbasic Function ReceiveHLPacket(  ByRef receivedbody As ByteString,  header As ByteString,  bodylength As Long,  Optional timeout As Time := :10.0)  As Boolean ``` #### Parameters  receivedbody  [ByteString](/wiki/spaces/CVCHELP/pages/495058958/Data+types#ByteString) It is a variable where received data is placed to.  header  [ByteString](/wiki/spaces/CVCHELP/pages/495058958/Data+types#ByteString) It is a non-empty data pattern that starts a data packet.  bodylength  [Long](/wiki/spaces/CVCHELP/pages/495058958/Data+types#Long) It is the length of the body. It must be greater than 0.  timeout  [Time](/wiki/spaces/CVCHELP/pages/495058958/Data+types#Time) Optional, defaults to 10 seconds. It is the receive timeout.  #### Return value* * [Boolean](/wiki/spaces/CVCHELP/pages/495058958/Data+types#Boolean)   ***True*** if header and data with *bodylength* were received before timeout.   ***False*** if header or data with *bodylength* are not received within the timeout limit or some error occurs. A function GetLastError returns the error number that occurred while executing the command. The following errors may occur: [92](/wiki/spaces/CVCHELP/pages/510525445/Command+errors#92), [153](/wiki/spaces/CVCHELP/pages/510525445/Command+errors#153), [154.](/wiki/spaces/CVCHELP/pages/510525445/Command+errors#154)  #### Example  This example describes how to receive a packet started by &S"*" with a body length of 5 bytes.  ```visualbasic Private Var Data As ByteString[5]  Private Var BodyLength As Long := 5  If S1.ReceiveHLPacket(Data,&S"*", BodyLength) Then    // data received, parse Data  Else   Select GetLastError()   Case 92 // error handling  Case 154 // error handling  End Select   End If ``` # ReceiveSyncFrame This function waits for data pattern defined by parameter *syncframe*.  The function returns **True** if the *syncframe* is received before timeout. If *timeout* exceeds without receiving *syncframe*, the function returns **False**.  #### Syntax  ```visualbasic Function ReceiveSyncFrame(  syncframe As ByteString,  Optional timeout As Time := :10.0)  As Boolean ``` #### Parameters  syncframe  [ByteString](/wiki/spaces/CVCHELP/pages/495058958/Data+types#ByteString) It is a non-empty data pattern.  timeout  [Time](/wiki/spaces/CVCHELP/pages/495058958/Data+types#Time) Optional, defaults to 10 seconds. It is the receive timeout.  #### Return value  [Boolean](/wiki/spaces/CVCHELP/pages/495058958/Data+types#Boolean)   ***True*** if *syncframe* was received before timeout.   ***False*** if timeout exceeds without receiving *syncframe* or some error occurs. A function GetLastError returns the error number that occurred while executing the command. The following errors may occur: [92](/wiki/spaces/CVCHELP/pages/510525445/Command+errors#92), [153](/wiki/spaces/CVCHELP/pages/510525445/Command+errors#153).  #### Example  This example describes how to receive data from &S"@POWERON" and &S"@POWEROFF".  ```visualbasic Private Var Data As ByteString[8]  If S1.ReceiveSyncFrame(&S"@",:2.0) Then   // sync frame @ is received  If S1.Receive(Data,8,:0.05) Then  Select Data  Case &S"POWERON" // power is on  Case &S"POWEROFF" // power is off  End Select  End If  Else   // error handling  End If ``` # Send The function sends data to the channel. It returns **True** on success or **False** if a *datatosend* is not accessible.  #### Syntax  ```visualbasic Function Send(datatosend As ByteString) As Boolean ``` #### Parameters  datatosend  [ByteString](/wiki/spaces/CVCHELP/pages/495058958/Data+types#ByteString) It is the data to be sent.  #### Return value* * [Boolean](/wiki/spaces/CVCHELP/pages/495058958/Data+types#Boolean)  ***True*** on success  ***False*** if *datatosend* is not accessible.  #### Example  ```visualbasic Var RecvData As ByteString[100]  S1.Send(&S"SomeRequest")  // wait for an answer  If S1.Receive(RecvData) = True Then  // process answer  End If ``` # SetSerialParameters The function sets the communication parameters of the serial channel.  #### Syntax  ```visualbasic Function SetSerialParameters(  mode As Byte,  bitspersecond As Long,  databits As Byte,  parity As Byte,  stopbits As Byte,  flowcontrol As Byte,  ParamArray)  As Boolean ``` #### Parameters  mode  [Byte](/wiki/spaces/CVCHELP/pages/495058958/Data+types#Byte) It is the mode of the channel. Predefined constants for parameter mode are as follows:  | | | | | --- | --- | --- | | Name | Value | Description | | _SERIAL_MODE_RS232 | 0 | Channel is in RS232 mode. | | _SERIAL_MODE_RS422 | 1 | Channel is in RS422 mode. | | _SERIAL_MODE_RS485 | 2 | Channel is in RS485 mode. | bitspersecond  [Long](/wiki/spaces/CVCHELP/pages/495058958/Data+types#Long) It is the baud rate from 300 to 115200.  databits  [Byte](/wiki/spaces/CVCHELP/pages/495058958/Data+types#Byte) It is the number of data bits from 5 to 8.  parity  [Byte](/wiki/spaces/CVCHELP/pages/495058958/Data+types#Byte) It is the type of parity. Predefined constants for parameter parity are as follows:  | | | | | --- | --- | --- | | Name | Value | Description | | _SERIAL_PARITY_NO | 0 | No parity. | | _SERIAL_PARITY_ODD | 1 | Odd parity. | | _SERIAL_PARITY_EVEN | 2 | Even parity. | stopbits  [Byte](/wiki/spaces/CVCHELP/pages/495058958/Data+types#Byte) It is the number of stop bits. Predefined constants for parameter stopbits are as follows:  | | | | | --- | --- | --- | | Name | Value | Description | | _SERIAL_STOPBITS_ONE | 0 | One stop bit. | | _SERIAL_STOPBITS_ONEANDHALF | 1 | One and one half stop bits. | | _SERIAL_STOPBITS_TWO | 2 | Two stop bits. | flowcontrol  [Byte](/wiki/spaces/CVCHELP/pages/495058958/Data+types#Byte) It is the type of the control. Predefined constants for parameter flowcontrol are as follows:  | | | | | --- | --- | --- | | Name | Value | Description | | _SERIAL_FLOWCONTROL_NONE | 0 | No handshake. | | _SERIAL_FLOWCONTROL_RTSCTS | 1 | Hardware flow control RTS/CTS. | | _SERIAL_FLOWCONTROL_XONXOFF | 2 | Software flow control by XON and XOFF bytes. The XON and XOFF can be optionally specified in the next parameter ParamArray. | | _SERIAL_FLOWCONTROL_ACK | 3 | Specifies the delay time between bytes and a control byte ACK is sent byte ACK is sent by a receiveis sentnext byte is sent immediately without a delay. They must be specified in the next parameter ParamArray. | | _SERIAL_FLOWCONTROL_DELAY | 4 | Specifies the delay time between bytes. It must be specified in the next parameter ParamArray. | ParamArray  [ParamArray](https://cue.atlassian.net/wiki/spaces/CVCHELP/pages/509149361) They are parameters of the flow. The number and types of these parameters depend on previous parameter flowcontrol if _SERIAL_FLOWCONTROL_XONXOFF or _SERIAL_FLOWCONTROL_ACK or _SERIAL_FLOWCONTROL_DELAY is used.  - _SERIAL_FLOWCONTROL_XONXOFF is used as the flowcontrol: XONbyte  [Byte](/wiki/spaces/CVCHELP/pages/495058958/Data+types#Byte) It is the XON byte.  XOFFbyte  [Byte](/wiki/spaces/CVCHELP/pages/495058958/Data+types#Byte) It is the XOFF byte.  - _SERIAL_FLOWCONTROL_ACK is used as the flowcontrol: timedelay  [Time](/wiki/spaces/CVCHELP/pages/495058958/Data+types#Time) It is the delay time between bytes and a control byte ACK.  controlbyte  [Byte](/wiki/spaces/CVCHELP/pages/495058958/Data+types#Byte) It is the control byte ACK.  - _SERIAL_FLOWCONTROL_DELAY is used as the flowcontrol: timedelay  [Time](/wiki/spaces/CVCHELP/pages/495058958/Data+types#Time) It is the delay time between bytes.  #### Return value  [Boolean](/wiki/spaces/CVCHELP/pages/495058958/Data+types#Boolean)   **True** on success  **False** if some error occurs. A function GetLastError returns the error number that occurred while executing the command. The following errors may occur: [40](/wiki/spaces/CVCHELP/pages/510525445/Command+errors#40), [41](/wiki/spaces/CVCHELP/pages/510525445/Command+errors#41), [42.](/wiki/spaces/CVCHELP/pages/510525445/Command+errors#42)  #### Examples  Channel S1 is in RS232 mode, 9600 bits per second, 8 data bits, no parity, one stop bit, and no handshake.  ```visualbasic S1.SetSerialParameters(  _SERIAL_MODE_RS232,  9600,  8,  _SERIAL_PARITY_NO,  _SERIAL_STOPBITS_ONE,  _SERIAL_FLOWCONTROL_NONE) ``` Channel S3 is in RS422 mode, 9600 bits per second, 8 data bits, no parity, one stop bit, and no handshake.  ```visualbasic S3.SetSerialParameters(  _SERIAL_MODE_RS422,  9600,  8,  _SERIAL_PARITY_NO,  _SERIAL_STOPBITS_ONE,  _SERIAL_FLOWCONTROL_NONE) ``` Channel S3 is in RS485 mode, 9600 bits per second, 8 data bits, no parity, one stop bit, and no handshake.  ```visualbasic S3.SetSerialParameters(  _SERIAL_MODE_RS485,  9600,  8,  _SERIAL_PARITY_NO,  _SERIAL_STOPBITS_ONE,  _SERIAL_FLOWCONTROL_NONE) ``` Channel S1 is in RS232 mode, 9600 bits per second, 8 data bits, no parity, one stop bit, hardware flow control RTS/CTS.  ```visualbasic S1.SetSerialParameters(  _SERIAL_MODE_RS232,  9600,  8,  _SERIAL_PARITY_NO,  _SERIAL_STOPBITS_ONE,  _SERIAL_FLOWCONTROL_RTSCTS) ``` Channel S1 is in RS232 mode, 9600 bits per second, 8 data bits, no parity, one stop bit, software flow control by XON and XOFF.  ```visualbasic S1.SetSerialParameters(  _SERIAL_MODE_RS232,  9600,  8,  _SERIAL_PARITY_NO,  _SERIAL_STOPBITS_ONE,  _SERIAL_FLOWCONTROL_XONXOFF) ``` Channel S1 is in RS232 mode, 9600 bits per second, 8 data bits, no parity, one stop bit, software flow control by XON and XOFF. XON=&h12 and XOFF=&h14 (instead of standard values XON=&h11 and XOFF=&h13).  ```visualbasic S1.SetSerialParameters(  _SERIAL_MODE_RS232,  9600,  8,  _SERIAL_PARITY_NO,  _SERIAL_STOPBITS_ONE,  _SERIAL_FLOWCONTROL_XONXOFF,  &h12,  &h14) ``` Channel S1 is in RS232 mode, 9600 bits per second, 8 data bits, no parity, one stop bit, specifies the delay time between bytes and a control byte ACK. The time delay is 0.5 second, ACK byte is &h63.  ```visualbasic S1.SetSerialParameters(  _SERIAL_MODE_RS232,  9600,  8,  _SERIAL_PARITY_NO,  _SERIAL_STOPBITS_ONE,  _SERIAL_FLOWCONTROL_ACK,  :.5,  &h63) ``` Channel S1 is in RS232 mode, 9600 bits per second, 8 data bits, no parity, one stop bit, specifies the delay time between bytes. The time delay is 1 second.  ```visualbasic S1.SetSerialParameters(  _SERIAL_MODE_RS232,  9600,  8,  _SERIAL_PARITY_NO,  _SERIAL_STOPBITS_ONE,  _SERIAL_FLOWCONTROL_DELAY,  :1) ``` # WaitForData This function waits for any data on the channel. The function doesn’t receive any data, which means the content of the channel’s receive buffer is not changed. If the channel’s receive buffer is not empty the function returns **True** immediately. If the channel’s receive buffer is empty and some data are received before *timeout*, the function returns **True**. The function returns **False** if no data is received before *timeout*.  This function is necessary if you need to receive and process any asynchronous data.  #### Syntax  ```visualbasic Function WaitForData(  Optional timeout As Time := :10.0)  As Boolean ``` #### Parameters  timeout  [Time](/wiki/spaces/CVCHELP/pages/495058958/Data+types#Time) Optional, defaults to 10 seconds. It is the receive timeout.  #### Return value  [Boolean](/wiki/spaces/CVCHELP/pages/495058958/Data+types#Boolean)   ***True*** if the channel is not empty or if some data are received before timeout.  ***False*** if timeout exceeds without any incoming data. A function GetLastError returns the error number that occurred while executing the command. The following errors may occur: [92](/wiki/spaces/CVCHELP/pages/510525445/Command+errors#92).