Packet Loss Widget: Potential Wraparound Ambiguity Issue

[DashBarkHuss]

Packet Loss Widget: Potential Wraparound Ambiguity Issue

Question

The packet loss widget looks inaccurate to me. I'm wondering if the widget is meant to be a heuristic for packet loss and not a true indicator, or am I misunderstanding the logic and behavior of OpenBCI that makes this actually accurate?

Code Reference

OpenBCI_GUI/OpenBCI_GUI/PacketLossTracker.pde

Line 136 in e23869e

while (sampleIndexArray.get(lastSampleIndexLocation) != currentSampleIndex) {

while (sampleIndexArray.get(lastSampleIndexLocation) != currentSampleIndex) {
    incrementLastSampleIndexLocation();
    numSamplesLost++;

    if (numSamplesLost > sampleIndexArray.size()) {
        // we looped the entire array, the new sample is not part of the current array
        println("WARNING: The sample index " + currentSampleIndex + " is not in the list of possible sample indices.");
        break;
    }
}

if (numSamplesLost > 0) {
    sessionPacketRecord.numLost += numSamplesLost;
    streamPacketRecord.numLost += numSamplesLost;
    currentRecord.numLost += numSamplesLost;

The Issue

To me, the code looks as if it's ignoring the possibility that multiple loops of the sample array have been lost.

Concrete Example (Cyton Daisy)

The sample index array for Cyton Daisy is: [0, 2, 4, ..., 252, 254] (128 values)

Scenario:

• Last sample had packet ID: 2
• Expected next packet ID: 4
• Actual received packet ID: 8

Current logic reports: 2 samples lost (4 and 6)

But this could also be:

• 130 packets lost: (128 × 1 full loop) + 2
• 258 packets lost: (128 × 2 full loops) + 2
• 386 packets lost: (128 × 3 full loops) + 2
• etc.

The Ambiguity

The formula should theoretically be:

Actual packets lost = (Loop size × Number of complete loops) + Difference between indices
Actual packets lost = (128 × X) + 2

Where X is unknowable from the sample index alone.

This also means:

• Going from expected 2 to packet ID 4 doesn't guarantee zero packet loss
• It could be: (128 × 0) + 0 = 0 packets lost ✓
• Or it could be: (128 × 1) + 0 = 128 packets lost
• Or it could be: (128 × 2) + 0 = 256 packets lost
• The code always reports: 0 packets lost

My Question

Am I correct that this is inaccurate? If so, maybe adding this limitation to the documentation would be helpful for users who need precise packet loss counts for data analysis.

If this is actually accurate, I'd love to understand how! I'm trying to figure out how to correctly identify packet loss to help with interpolation, and I thought I would use the GUI logic as an example, but the GUI logic doesn't seem to account for wraparounds to me.

Possible Solutions

If this is indeed a limitation:

GUI Solutions:

1. Document the limitation - Add comments/documentation noting that packet loss counts represent the minimum possible loss, and may underreport in cases of severe data loss exceeding one full cycle of the sample index range.

2. Explore arrival timestamp-based heuristics - Investigate whether packet arrival timestamps could help detect cases where actual packet loss exceeds the reported amount.

Firmware Solutions:

3. Alternative firmware with 3-byte packet ID counter - Replace the 1-byte packet ID (0-255) with a 3-byte counter (0-16,777,215). At 250 Hz, this provides 18.6 hours before wraparound, sufficient for overnight recordings and long-duration experiments. Would require removing or compressing other packet data to maintain packet size.

Thank you for any clarification!