cSerialPort Events Reference

📋 Events List

Event	Description	Trigger Condition
DataReceived	Data received	New data in input buffer (requires StartMonitoring)
FrameReceived	Frame received	Triggered for each complete frame when framing is enabled (FrameInterval>0)
ErrorOccurred	Communication error	Line error detected
PinChanged	Signal line change	Any CTS/DSR/RING/RLSD change
TxEmpty	Transmit buffer empty	Transmission completed
BreakDetected	Break detected	Break signal received
RingDetected	Ring detected	Ring signal received

---

📥 DataReceived Event

Description

Triggered when new data is in the input buffer. Requires StartMonitoring to be called first.

Syntax

Private Sub object_DataReceived(ByVal BytesCount As Long)

Parameters

Parameter	Type	Description
BytesCount	Long	Number of bytes in the input buffer

Usage Example

Private WithEvents m_Port As cSerialPort

Private Sub m_Port_DataReceived(ByVal BytesCount As Long)
    Dim s As String
    s = m_Port.ReadExisting()
    Debug.Print "Received " & BytesCount & " bytes: " & s
End Sub

Notes

• Must call StartMonitoring before this event can be triggered
• Read data as quickly as possible in the event handler to avoid buffer overflow
• Do not perform time-consuming operations in the event handler, as this may affect subsequent data reception

---

🧩 FrameReceived Event

Description

Triggered when framing mode is enabled (FrameInterval > 0) for each complete frame received. This is the core event for solving the "device continuous transmission causing packet concatenation" problem.

For detailed framing principles and solution selection, see Framing Protocol Guide.

Syntax

Private Sub object_FrameReceived(FrameData() As Byte)

Parameters

Parameter	Type	Description
FrameData	Byte array	Raw byte data of this frame

Enabling

' Enable framing: 30ms no new data = one frame ends
m_Port.FrameInterval = 30
m_Port.StartMonitoring 20   ' Polling interval recommended <= FrameInterval/2

Usage Example

Private WithEvents m_Port As cSerialPort

Private Sub Form_Load()
    Set m_Port = New cSerialPort
    m_Port.PortName = "COM3"
    m_Port.Config.BaudRate = br9600
    If m_Port.OpenPort() Then
        m_Port.FrameInterval = 30
        m_Port.StartMonitoring 20
    End If
End Sub

Private Sub m_Port_FrameReceived(FrameData() As Byte)
    Dim s As String
    s = StrConv(FrameData, vbUnicode)
    Debug.Print "Received frame (" & UBound(FrameData) + 1 & " bytes): " & s
End Sub

Notes

• Must set FrameInterval > 0 to trigger; when set to 0, the DataReceived path is still used
• When FrameInterval=0, DataReceived triggers normally; the two are mutually exclusive
• StopMonitoring / ClosePort automatically flushes remaining frames in the buffer, so the last frame is not lost
• Combined with cSerialFrameParser, "protocol framing" can be achieved (precise splitting by delimiter/start-end markers/length field)

---

⚠️ ErrorOccurred Event

Description

Triggered when a communication error is detected.

Syntax

Private Sub object_ErrorOccurred(ByVal ErrorCode As Long, ByVal ErrorMsg As String)

Parameters

Parameter	Type	Description
ErrorCode	Long	Communication error code (CE_ constant combination)
ErrorMsg	String	Error description

Error Codes

Constant	Value	Description
CE_RXOVER	&H1	Receive buffer overflow
CE_OVERRUN	&H2	Character overrun
CE_RXPARITY	&H4	Parity error
CE_FRAME	&H8	Frame error
CE_BREAK	&H10	Break detected
CE_TXFULL	&H100	Transmit buffer full

Usage Example

Private Sub m_Port_ErrorOccurred(ByVal ErrorCode As Long, ByVal ErrorMsg As String)
    Debug.Print "Communication error [" & ErrorCode & "]: " & ErrorMsg

    Select Case ErrorCode
        Case CE_RXOVER
            ' Receive buffer overflow, clear buffer
            m_Port.PurgeRx
        Case CE_RXPARITY
            ' Parity error, log
            LogError "Parity error"
        Case CE_FRAME
            ' Frame error, check baud rate configuration
            LogError "Frame error, check baud rate"
    End Select
End Sub

---

📊 PinChanged Event

Description

Triggered when any CTS/DSR/RING/RLSD signal line changes.

Syntax

Private Sub object_PinChanged(ByVal Events As Long)

Parameters

Parameter	Type	Description
Events	Long	Event mask (EV_CTS/EV_DSR/EV_RLSD/EV_RING combination)

Usage Example

Private Sub m_Port_PinChanged(ByVal Events As Long)
    If (Events And EV_CTS) Then
        Debug.Print "CTS changed: " & m_Port.CtsHolding
    End If
    If (Events And EV_DSR) Then
        Debug.Print "DSR changed: " & m_Port.DsrHolding
    End If
    If (Events And EV_RLSD) Then
        Debug.Print "CD changed: " & m_Port.CdHolding
    End If
End Sub

Note: The PinChanged event only triggers in WaitForEvent synchronous mode. Asynchronous monitoring mode (StartMonitoring) does not currently monitor signal line changes.

---

📤 TxEmpty Event

Description

Triggered when the transmit buffer is empty.

Private Sub m_Port_TxEmpty()
    Debug.Print "Transmission completed"
End Sub

Only triggers in WaitForEvent synchronous mode.

---

⚡ BreakDetected Event

Description

Triggered when a Break signal is detected.

Private Sub m_Port_BreakDetected()
    Debug.Print "Break signal received"
End Sub

Only triggers in WaitForEvent synchronous mode.

---

🔔 RingDetected Event

Description

Triggered when a ring signal is detected.

Private Sub m_Port_RingDetected()
    Debug.Print "Ring detected"
End Sub

Only triggers in WaitForEvent synchronous mode.

---

Event Trigger Mode Comparison

Asynchronous Monitoring Mode (StartMonitoring)

Event	Triggers	Description
DataReceived	✅	Polling detected data in buffer
ErrorOccurred	✅	Polling detected communication error
PinChanged	❌	Does not monitor signal line changes
TxEmpty	❌	Does not monitor transmission completion
BreakDetected	❌	Does not monitor Break
RingDetected	❌	Does not monitor ring

Synchronous Wait Mode (WaitForEvent)

Event	Triggers	Description
DataReceived	✅	Received EV_RXCHAR event
ErrorOccurred	✅	Received EV_ERR event
PinChanged	✅	Received EV_CTS/EV_DSR/EV_RLSD event
TxEmpty	✅	Received EV_TXEMPTY event
BreakDetected	✅	Received EV_BREAK event
RingDetected	✅	Received EV_RING event

⚠️: WaitForEvent blocks the calling thread, not recommended for UI thread use.

---

Last Updated: 2026-07-05