alexokita

Ribbit Radio

Version Status C++ JavaScript WebAssembly Emscripten Web Audio API PWA

A WebAssembly-based digital radio communication application supporting real-time messaging over audio signals. Ribbit uses advanced DSP (Digital Signal Processing) algorithms to encode/decode messages into audio waveforms suitable for transmission via radio, speakers, or any audio medium.

Current Project Status

Version: 0.1.2 (Development) Status: Production-ready core functionality with active development on advanced features

✅ Completed Features

🚧 In Progress / Planned Features

Project Structure

.
├── build.bat              # Windows build script (auto-installs Emscripten)
├── run_tests.bat          # Windows test server launcher
├── run_tests.sh           # Linux/Mac test server launcher
├── README.md              # This file
├── Docs/                  # Comprehensive documentation
│   ├── codec.md             # Codec & Message Architecture
│   ├── quick_start.md       # Quick Start Guide
│   ├── ribbit_wasm.md       # WASM Implementation Details
│   └── ...
├── web/                   # Web assets served to clients
│   ├── index.html         # Main application (v0.1.2)
│   ├── messageCodec.html  # Visual message encoder/decoder
│   ├── headerCodec.html   # Header field codec
│   ├── wasm_tests.html    # Test suite interface
│   ├── decoder_tests.html # Live microphone testing & WAV generator
│   ├── settings-page.html # Settings interface
│   ├── ribbit.webmanifest # PWA manifest
│   ├── sw.js              # Service worker (offline support)
│   ├── scripts/           # JavaScript modules
│   │   ├── ribbit.js      # Emscripten WASM wrapper
│   │   ├── ribbit.wasm    # Compiled WebAssembly binary (~103KB)
│   │   ├── ribbit-wasm.js # Friendly WASM API wrapper
│   │   ├── index.js        # Main application logic
│   │   ├── message_format.js # Message format handler
│   │   ├── messageCodec.js # Message encoding/decoding API
│   │   ├── decoder_tests.js # Live testing implementation
│   │   ├── wasm_tests.js   # Test suite
│   │   ├── wav.js          # WAV file utilities
│   │   └── ...
│   ├── styles/            # CSS stylesheets
│   ├── assets/            # Icons and images
│   └── test/              # Test files
│       ├── test-e2e/      # End-to-end tests (Playwright)
│       └── setup.js       # Test configuration
└── src/                   # C++ source code
    └── ribbit/
        ├── src/
        │   ├── ribbit.cc           # Main WASM bindings
        │   ├── message_format.cc   # Message packing/unpacking
        │   ├── decode.cc           # Decoder implementation
        │   └── dsp/                # Digital Signal Processing library
        │       ├── encoder.hh     # Signal encoder
        │       ├── decoder.hh     # Signal decoder
        │       ├── polar_*.hh     # Polar codes (error correction)
        │       └── ... (60+ DSP headers)
        └── include/
            └── message_format.hh  # Message format definitions

Building

Prerequisites

Quick Build (Windows)

  1. Open Command Prompt or PowerShell
  2. Navigate to the project directory

  3. Run the build script:

    .\build.bat

The script will:

Manual Emscripten Setup

If you prefer manual setup or are not using Windows, follow these steps:

  1. Clone Emscripten SDK:

    git clone https://github.com/emscripten-core/emsdk.git
cd emsdk

  2. Install and activate latest version:

    ./emsdk install latest
./emsdk activate latest

  3. Set up environment variables:

    
# On Windows (PowerShell)
.\emsdk_env.ps1

# On Windows (Command Prompt)
.\emsdk_env.bat

# On Linux/macOS
source ./emsdk_env.sh

  4. Verify installation:

    emcc --version

  5. Manual compilation:

    emcc src/ribbit/src/ribbit.cc src/ribbit/src/message_format.cc -o web/scripts/ribbit.js ^
    -s WASM=1 ^
    -s EXPORTED_RUNTIME_METHODS=['ccall','cwrap','stringToUTF8','UTF8ToString','lengthBytesUTF8'] ^
    -s EXPORTED_FUNCTIONS=['_malloc','_free','_createEncoder','_destroyEncoder','_createDecoder','_destroyDecoder','_feed_pointer','_feed_length','_message_pointer','_message_length','_signal_pointer','_signal_length','_payload_pointer','_payload_length','_feedDecoder','_digestFeed','_initEncoder','_readEncoder','_pack_contest_message','_unpack_contest_message'] ^
    -I src/ribbit/include ^
    -std=c++17 ^
    -O3 ^
    -s ALLOW_MEMORY_GROWTH=1 ^
    -s INITIAL_MEMORY=16MB ^
    -s MAXIMUM_MEMORY=64MB ^
    -s STACK_SIZE=1MB ^
    -s MODULARIZE=1 ^
    -s EXPORT_ES6=0 ^
    -s ENVIRONMENT=web ^
    -s FILESYSTEM=0 ^
    -s ASSERTIONS=0 ^
    -s MALLOC=emmalloc ^
    -msimd128 ^
    --closure 0 ^
    -flto

    Note: The build includes both ribbit.cc and message_format.cc to support dual-mode messaging. The EXPORTED_RUNTIME_METHODS includes string conversion functions required for message format handling.

Build Optimization Features

The build script uses the following optimizations:

Setup and running locally

  1. Serve the app (WASM requires a real origin; file:// will not work):
    • Windows: run_tests.bat
    • Linux/Mac: ./run_tests.sh
    • Or from repo root: python3 -m http.server 8000 and open http://localhost:8000/web/ (HTTPS needed for microphone: use the scripts or https://localhost:8443 if configured).

  2. Main app: web/index.html — chat, encode/decode, settings. Use Settings → Application → Install App to add to home screen for offline use.

  3. WASM and tests:
  4. Decoder and encoder:
  5. Message format and header codec:

Development

Developer-Friendly WASM API

Ribbit now includes a modern, promise-based WASM API that makes integration simple:

// Import the friendly API
import { RibbitWASM } from './scripts/ribbit-wasm.js';

// One-line initialization
const ribbit = await RibbitWASM.load();

// Encode a message
const audioBuffer = await ribbit.encodeMessage("Hello World!", {
    callsign: "W1AW",
    gridsquare: "FN31pr",
    name: "John"
});

// Decode audio
const decoded = await ribbit.decodeAudio(audioBuffer);
console.log("Received:", decoded.text);

// Cleanup when done
ribbit.destroy();

Key Features:

See Docs/README_WASM_API.md for complete API documentation.

Testing

A comprehensive test suite is available to verify encoder/decoder functionality, including automated tests, live microphone testing, WAV file generation for cross-device validation, and end-to-end browser testing.

Quick Start

Windows:

run_tests.bat

Linux/Mac:

./run_tests.sh

Then open your browser to:

Test Features

Automated Testing:

Live Testing (decoder_tests.html):

End-to-End Testing:

Documentation:

🎨 Visual Tools & Demos

1. Visual Message Codec

URL: http://localhost:8000/web/messageCodec.html ⭐

Interactive encoder/decoder that shows:

2. Message Format Demo (WASM Verification)

URL: http://localhost:8000/web/message_format_demo.html 🐸

A complete end-to-end demo of the Ribbit message format using the actual WebAssembly binary.

3. Decoder Tests & Live Testing

URL: https://localhost:8443/decoder_tests.html 🎤

Complete testing environment with:

[!NOTE] All tools require a local HTTP server to run (due to WASM security restrictions). Run: python3 -m http.server 8000 or use the provided test scripts.

Quick Start: Docs/quick_start.md Details: Docs/codec.md

Message Formats

Ribbit now supports dual-mode messaging:

Chat Mode (Type 1) 💬

Contest Mode (Type 2) 🏆

Example Savings: “Hello from Ribbit!” is 37% smaller in Contest mode (52 → 33 bytes)

Full Details: Docs/ribbit_wasm.md

Transmit / Receive Architecture (Protocol Layering)

Ribbit’s transmit/receive (Tx/Rx) path maps onto the classic OSI “networking burrito.” Understanding which layer each part lives in keeps responsibilities clear: the physical signal, the channel-access rules, and the message contents are engineered separately.

In short: the PHY decides what the signal is, the MAC decides when it is allowed on the air, and the framing/application layers decide what the message contains. The Tx/Rx component this project engineers for channel access is squarely a Layer 2 MAC, with the ~2.35 s composite burst as its authoritative Layer 1 timing constraint.

Transmit / Receive Process

This walks the end-to-end Tx/Rx cycle in the same layering vocabulary used above. Every timing decision is a Layer 2 MAC concern operating over a fixed Layer 1 PHY whose authoritative constant is the ~2.35 s composite burst. Because the burst is longer than a slot, a transmission legitimately spans a slot boundary — the defining constraint the MAC schedules around.

1. Slot timing (MAC). Channel time is divided into fixed 2-second GPS-aligned slots (aligned to even UTC seconds so all operators share the same grid). The composite burst is ~2.35 s, so it does not fit inside one slot — it starts in one slot and runs into the next. This is intended: the slot is the contention grid, not a hard transmission budget. Competing operators keep deferring (carrier sense, below) until the in-flight burst ends.

2. Carrier sense (MAC). Before keying up, an operator waits a randomized listen window of 50–400 ms and listens for an occupied channel (CSMA/CA). If the channel is busy — including a burst still in flight from the previous slot — the operator defers and applies backoff. If the channel is clear when its listen window elapses, the operator wins the slot and keys up. Real-world asymmetry (differing PWR/Gain between stations) and hidden nodes mean carrier sense is not perfect; backoff and the silence reset (below) recover from the resulting collisions.

3. Transmission (PHY). The winning operator transmits the composite burst: a 300 Hz VOX wake-up tone (200 ms) to open squelch, a 100 ms silence gap, then the Ribbit waveform (2.048 s / 16384 samples at 8 kHz) — ≈ 2.35 s total on-air occupation. The PHY owns modulation and error-correction coding; the MAC treats this duration as an immovable constraint.

4. Reception with acknowledgment. A receiving station runs the reverse PHY path (demodulate → error-correct → decode) and then closes the loop at the framing/application layer:

  1. Decode the incoming burst into a message frame.
  2. Record the Message ID from the frame (see the ACK arrays in message_format.hh).
  3. Piggyback the ACK — the recorded Message ID is carried in the ACK array of the receiver’s next outbound burst, so acknowledgments cost no extra airtime.
  4. Confirm — when the original sender decodes a burst containing its Message ID, the contact is confirmed (QSO complete).

Audit findings and resolutions

The timing audit (see Docs/contest_queue_timing_audit.md) compared the contest queue simulator’s constants against this authoritative model. Each recorded mismatch and its resolution:

Constant Was (simulator) Authoritative model Resolution
TX time default 3.0 s 2.35 s composite burst Default set to the composite burst (2.35 s)
Slot / timing window 10.0 s 2.0 s GPS slot Slot fixed at 2 s, aligned to the GPS grid
Slot ≥ tx coupling slot forced ≥ tx time slot (2 s) < burst (2.35 s) allowed Coupling removed; a burst may span a slot boundary
Listen window (slot − tx)/txFrames frame basis random uniform 50–400 ms Replaced with a 50–400 ms carrier-sense window
Backoff reschedule, no growth binary exponential, max exp 4 (≤ 16 slots) Binary exponential backoff capped at 16 slots
Aging / promotion none promote after > 3 attempts Attempt-count aging rule added (see below)
Silence threshold 3 slots 3 slots Already matched — no change needed

Strengthened fairness

To guarantee no operator is starved during a busy contest, the MAC’s scheduler adds an attempt-count aging rule:

Together these bound the worst-case wait. For a peak of N concurrent contenders:

Bounded_Wait(N) = 14 + 2N  slots      (= 28 + 4N seconds at a 2 s slot)

The 14-slot term is the worst-case pre-promotion backoff ramp-up (2 + 4 + 8 slots); the 2N term reflects each of the other N − 1 operators transmitting at most once (one burst + listen window ≈ 2 slots) before the aged message is served. The guarantee is verified by simulation — see the Fairness-Bound Verification results in the audit document.

Timing values at a glance

These values are consistent across the updated simulator, the authoritative model, and this write-up:

Parameter Value
GPS slot 2 s (aligned to even UTC seconds)
Composite burst ~2.35 s (200 ms VOX + 100 ms silence + 2.048 s waveform)
Carrier-sense listen window 50–400 ms
Max backoff ≤ 16 slots (binary exponential, max exponent 4)
Silence reset 3 consecutive silent slots

Known Issues & Bugs

🐛 Confirmed Bugs

  1. Service Worker Cache Versioning
    • Location: web/sw.js
    • Issue: Cache version 'ribbit-cache-v1' is hardcoded and may not invalidate old caches
    • Impact: Users may see stale versions after updates
    • Status: Should implement cache versioning strategy
    • Severity: Low (affects updates)
  2. Audio Context State Management
    • Location: web/scripts/index.js - RibbitApp class
    • Issue: Audio context suspension/resumption could be more robust
    • Impact: Occasional audio playback issues on mobile browsers
    • Status: Improved with user interaction handlers, but edge cases may exist
    • Severity: Low (rare edge cases)

⚠️ Potential Issues

  1. Audio Buffer Size Mismatch
    • Web Audio API provides power-of-2 buffer sizes (e.g., 2048), decoder expects 160-sample chunks
    • Current implementation handles this with overflow buffer in digestFeedOptimized()
    • Recommendation: Add unit tests for various buffer sizes
  2. Concurrent Encode/Decode
    • No explicit locking mechanism if encoder and decoder run simultaneously
    • Current implementation suspends listening during transmission
    • Recommendation: Add state checks or queue system for edge cases
  3. Large Message Handling
    • Messages near 256-byte limit may not be validated early enough
    • Recommendation: Add pre-encoding length validation
  4. IndexedDB Error Handling
    • Some edge cases in database initialization may not be fully handled
    • Recommendation: Add more comprehensive error recovery

Optimization Opportunities

🚀 Performance Optimizations

  1. Web Workers for Audio Processing (High Priority)
    • Move audio processing to Web Worker to prevent UI blocking
    • Expected Impact: Smoother UI, better real-time performance
    • Complexity: Medium
    • Files to Modify: web/scripts/index.js, create web/scripts/audio-worker.js
  2. Lazy WASM Loading (Medium Priority)
    • Load WASM module only when needed, not on page load
    • Expected Impact: Faster initial page load, reduced memory usage
    • Complexity: Low
    • Files to Modify: web/scripts/index.js
    • Note: Already partially implemented with RibbitWASM.load()
  3. Message Queuing/Batching (Medium Priority)
    • Queue multiple messages for batch processing
    • Expected Impact: Better throughput for rapid message sending
    • Complexity: Medium
    • Files to Modify: web/scripts/index.js, web/scripts/messages.js
  4. Optimize Bit Manipulation (Low Priority)
    • Current bit manipulation in message_format.cc uses loops
    • Could use SIMD operations or lookup tables for common operations
    • Expected Impact: 10-20% faster encoding/decoding
    • Complexity: High
    • Files to Modify: src/ribbit/src/message_format.cc
  5. Memory Pooling (Low Priority)
    • Reuse buffers instead of allocating/deallocating for each message
    • Expected Impact: Reduced GC pressure, faster message processing
    • Complexity: Medium
    • Files to Modify: web/scripts/ribbit-wasm.js, src/ribbit/src/ribbit.cc
    • Note: Partially implemented in digestFeedOptimized()

💾 Memory Optimizations

  1. Reduce Static Buffer Sizes (If possible)
    • Current buffers: FEED_LENGTH=2048, SIGNAL_LENGTH=16384, PAYLOAD_LENGTH=256
    • Evaluate if sizes can be reduced without affecting functionality
    • Expected Impact: Lower memory footprint
    • Complexity: Medium (requires performance testing)
  2. Cleanup Unused WASM Memory
    • Explicitly free temporary buffers after use
    • Expected Impact: Lower peak memory usage
    • Complexity: Low
    • Files to Modify: web/scripts/ribbit-wasm.js
    • Status: Already implemented in RibbitWASM class

📦 Bundle Size Optimizations

  1. WASM Size Reduction
    • Current WASM: ~103KB
    • Investigate removing unused DSP functions if not needed
    • Expected Impact: Smaller download, faster loading
    • Complexity: High (requires careful dependency analysis)
  2. Code Splitting
    • Separate contest mode codec into separate module
    • Expected Impact: Faster initial load if contest mode not needed
    • Complexity: Medium

🔧 Code Quality Improvements

  1. TypeScript Migration (Long-term)
    • Add type safety to JavaScript codebase
    • Expected Impact: Fewer runtime errors, better IDE support
    • Complexity: High
    • Note: TypeScript definitions already exist for WASM API (ribbit-wasm.d.ts)
  2. Unit Test Coverage
    • Increase test coverage beyond integration tests
    • Add tests for edge cases, error conditions
    • Expected Impact: Higher code reliability
    • Complexity: Medium
    • Status: Test infrastructure in place with Jest and Playwright
  3. Error Recovery
    • Add automatic retry for failed decode operations
    • Expected Impact: Better resilience to noisy signals
    • Complexity: Medium
    • Status: Smart debouncing already implemented

Next Steps & Roadmap

Immediate (Next Sprint)

  1. Enhanced Error Handling
    • Improve decode error messages with more context
    • Add retry logic for transient failures
    • Better validation feedback in UI
  2. Contest Mode UI Integration
    • Add mode selector to main application
    • Integrate contest mode encoding/decoding in index.js
    • Add UI for contest mode message fields (timestamp, flags, etc.)
  3. Performance Monitoring
    • Add real-time performance metrics display
    • Track encoding/decoding times
    • Monitor memory usage patterns

Short-term (Next Month)

  1. ACK Array Implementation
    • Design ACK array structure (room for 20+ ACKs)
    • Implement packing/unpacking logic
    • Add UI for ACK management
  2. Statistics Dashboard
    • Message counts, success rates
    • Encoding/decoding performance metrics
    • Bandwidth usage statistics
    • Signal quality indicators
  3. Web Workers for Audio
    • Offload audio processing to Web Worker
    • Improve UI responsiveness
    • Better handling of concurrent operations
  4. Enhanced Testing
    • Expand E2E test coverage
    • Add performance regression tests
    • Cross-browser automated testing

Long-term (Next Quarter)

  1. ADIF/Cabrillo Logging
    • Export contact logs in standard formats
    • Import from existing log files
    • Integration with popular logging software
  2. QSO Mode
    • Automatic contact logging
    • Duplicate detection
    • Contest logging features
    • Real-time QSO tracking
  3. Performance Monitoring
    • Real-time performance metrics
    • Bottleneck identification
    • Performance profiling tools
    • Automated performance testing
  4. Advanced Features
    • Message compression
    • Multiple modulation schemes
    • Adaptive data rates
    • Optional encryption layer

Contact Logging

Saving and exporting contacts:

AI Agent & Developer Guidance

This project has specific constraints to ensure offline reliability and portability. Please read the AgentGuidance before writing code.

Contributing

When reporting bugs or implementing optimizations:

  1. Bug Reports: Include reproduction steps, expected vs actual behavior, browser/OS info
  2. Optimizations: Include performance benchmarks before/after, explain trade-offs
  3. Code Changes: Follow existing code style, add tests for new features
  4. Documentation: Update relevant docs when adding features

Resources & Documentation

Deployment (GitHub Pages)

This repo is the live GitHub Pages site at https://badkangaroo.github.io/. Pushing to the release branch (or a v* release tag) publishes the repository so both app pages and docs stay reachable: