COBS Example

This example demonstrates the COBS (Consistent Overhead Byte Stuffing) component with comprehensive tests and real-world usage scenarios.

What This Example Tests

The example runs four main test suites:

Single Packet Test: Basic encoding/decoding of individual packets with span-based API
Streaming Encoder Test: Batching multiple packets for transmission with buffer management
Streaming Decoder Test: Processing fragmented incoming data streams with debugging support
Edge Cases Test: Empty packets, all zeros, no zeros, and maximum block size

Detailed Test Coverage

Single Packet Test (Tests 1-12)

Tests 1-6: Basic encoding/decoding with various data patterns (zeros at different positions, no zeros, all zeros, empty packets, single bytes)
Tests 7-8: Buffer-based encoding/decoding using std::span API for embedded systems
Tests 9-10: Buffer size validation - ensures functions return 0 when buffers are too small
Tests 11-12: Static API usage - demonstrates max_encoded_size() and max_decoded_size() for buffer allocation

Streaming Encoder Test (Tests 1-5)

Test 1: Multiple packets with move semantics for efficient memory usage
Test 2: Empty encoder behavior
Test 3: Buffer-based extract_data() for direct buffer output
Test 4: Single packet encoding
Test 5: clear() method for buffer management

Streaming Decoder Test (Tests 1-6)

Test 1: Multiple packets with move semantics for efficient processing
Test 2: Empty decoder behavior
Test 3: Single packet decoding
Test 4: Incomplete packet handling (fragmented data)
Test 5: remaining_data() access for debugging and buffer inspection
Test 6: clear() method for buffer management

Edge Cases Test (Tests 1-4)

Test 1: Maximum block size (254 non-zero bytes) - tests COBS overhead limits
Test 2: Alternating zeros and non-zeros - tests complex encoding patterns
Test 3: Consecutive zeros - tests zero handling edge cases
Test 4: Large packet (1000 bytes) - tests performance with realistic packet sizes

Test Scenario: 48-byte Packets

The example uses 48-byte packets to simulate a realistic communication protocol:

Packet size: 48 bytes (includes zeros to test COBS encoding)
Chunk size: 100 bytes for encoder, 80 bytes for decoder (simulates bus limitations)
Multiple packets: Tests batching and fragmentation handling

Build and Flash

Build the project and flash it to the board, then run monitor tool to view serial output:

idf.py -p PORT flash monitor

(Replace PORT with the name of the serial port to use.)

Monitor Commands

Exit monitor: Type Ctrl-]
Reset board: Type Ctrl+R

Expected Output

The example will output:

Verification results (PASS/FAIL) for all 27 test cases
Buffer size information and validation results
Static API usage demonstrations with size calculations
Buffer-based encoding/decoding test results
Streaming encoder/decoder functionality tests
Edge case handling verification
Summary of all test results

I (305) main_task: Calling app_main()
[COBS Example/I][0.042]: Starting COBS example!
[COBS Example/I][0.042]: COBS Encoder/Decoder Example
[COBS Example/I][0.048]: ============================
[COBS Example/I][0.053]:
=== Single Packet Test ===
[COBS Example/I][0.059]: Test 1: Packet with zeros at positions 0, 28, 43
[COBS Example/I][0.066]: Test 1: PASS - Zeros at various positions
[COBS Example/I][0.073]: Test 2: Packet with no zeros (1-48)
[COBS Example/I][0.079]: Test 2: PASS - No zeros
[COBS Example/I][0.084]: Test 3: Packet with all zeros
[COBS Example/I][0.090]: Test 3: PASS - All zeros
[COBS Example/I][0.095]: Test 4: Empty packet
[COBS Example/I][0.100]: Test 4: PASS - Empty packet
[COBS Example/I][0.105]: Test 5: Single byte packet (0x42)
[COBS Example/I][0.111]: Test 5: PASS - Single byte
[COBS Example/I][0.117]: Test 6: Single zero byte
[COBS Example/I][0.122]: Test 6: PASS - Single zero byte
[COBS Example/I][0.128]: Test 7: Buffer-based encoding
[COBS Example/I][0.133]: Test 7: PASS - Buffer-based encoding
[COBS Example/I][0.140]: Test 8: Buffer-based decoding
[COBS Example/I][0.145]: Test 8: PASS - Buffer-based decoding
[COBS Example/I][0.151]: Test 9: Buffer size validation - encoding with too small buffer
[COBS Example/I][0.160]: Test 9: PASS - Buffer size validation (encoding)
[COBS Example/I][0.167]: Test 10: Buffer size validation - decoding with too small buffer
[COBS Example/I][0.176]: Test 10: PASS - Buffer size validation (decoding)
[COBS Example/I][0.183]: Test 11: Static API usage - max_encoded_size
[COBS Example/I][0.190]: Test 11: PASS - Static API max_encoded_size (required: 9, written: 9)
[COBS Example/I][0.199]: Test 12: Static API usage - max_decoded_size
[COBS Example/I][0.207]: Test 12: PASS - Static API max_decoded_size (required: 8, written: 7, original: 7)
[COBS Example/I][0.217]:
=== Streaming Encoder Test ===
[COBS Example/I][0.223]: Test 1: PASS - Multiple packets with move semantics
[COBS Example/I][0.230]: Test 2: PASS - Empty encoder
[COBS Example/I][0.236]: Test 3: PASS - Buffer-based extract_data
[COBS Example/I][0.242]: Test 3: PASS - Single packet
[COBS Example/I][0.248]: Test 5: clear() method
[COBS Example/I][0.253]: Test 5: PASS - clear() method
[COBS Example/I][0.259]:
=== Streaming Decoder Test ===
[COBS Example/I][0.265]: Test 1: PASS - Multiple packets with move semantics
[COBS Example/I][0.272]: Test 2: PASS - Empty decoder
[COBS Example/I][0.278]: Test 3: PASS - Single packet
[COBS Example/I][0.283]: Test 4: PASS - Incomplete packet
[COBS Example/I][0.289]: Test 5: remaining_data() access
[COBS Example/I][0.295]: Test 5: PASS - remaining_data() access
[COBS Example/I][0.301]: Test 6: clear() method
[COBS Example/I][0.306]: Test 6: PASS - clear() method
[COBS Example/I][0.312]:
=== Edge Cases Test ===
[COBS Example/I][0.317]: Test 1: PASS - Maximum block size (254 bytes)
[COBS Example/I][0.324]: Test 2: PASS - Alternating zeros and non-zeros
[COBS Example/I][0.331]: Test 3: PASS - Consecutive zeros
[COBS Example/I][0.338]: Test 4: PASS - Large packet (1000 bytes)
[COBS Example/I][0.344]: ============================
[COBS Example/I][0.349]: COBS example complete!
[COBS Example/I][0.354]: All tests completed successfully!

Key Features Demonstrated

Span-based API: Zero-copy operations using std::span for efficient data handling
Buffer-based encoding/decoding: Direct buffer operations for embedded systems with limited memory
Buffer size calculation: Static API methods for compile-time buffer size estimation
Buffer validation: Comprehensive buffer size checking and overflow protection
Efficient batching: Multiple packets combined into transmission chunks with move semantics
Fragmentation handling: Incoming data processed in arbitrary chunks with debugging support
Error handling: Invalid packets are skipped gracefully with proper error reporting
Edge case robustness: Handles empty packets, all zeros, large packets, and complex patterns
Thread-safe streaming: Streaming classes with internal locking for multi-threaded environments
Memory management: RAII-based memory management with clear() methods for buffer control