giglez/CONTRIBUTING.md

Contributing to GigLez - IoT RF Device Mapping Platform

Welcome! We're building a Wigle-style platform for Sub-GHz RF device mapping. This guide will help you join the project and start contributing.

---

🏛️ Project Overview

GigLez is an open-source crowdsourced platform for mapping IoT RF devices (300-928 MHz). Think "Wigle.net for garage doors, weather stations, and doorbells."

Key Features:

• 6-component RF signature matching engine
• 299 protocol database (RTL_433 imported)
• GPS validation & privacy features
• Real-world benchmarking infrastructure
• Support for Flipper Zero, RTL-SDR, HackRF captures

Current Status:

• ✅ Core identification engine complete
• ✅ 56 unit tests passing
• ⚠️ 33% synthetic accuracy, 0% real-world (documented gap analysis)
• 📊 Benchmarking & calibration in progress

---

👥 Current Contributors

Core Team

• leetcrypt - Repository owner, core developer (admin access)
• Ringmast4r - Invited collaborator (write access) - Pending acceptance

Organizations

• GhostArmyIntel - Organization for wardriving & RF intelligence projects
  • Projects: wardriving-converter, WiGLE-Vault, OUI-Master-Database

---

🚀 How to Join the Project

Step 1: Accept Your Invitation

If you've been invited as a collaborator:

1. Check your email for invitation from GitHub
2. Or visit: https://github.com/notifications
3. Accept the invitation to join leetcrypt/giglez
4. You'll receive write access (push, pull, create branches/PRs)

Pending Invitations:

• Ringmast4r (invited 2026-02-16)

Step 2: Clone the Repository

# Clone the repo
git clone https://github.com/leetcrypt/giglez.git
cd giglez

# Verify you have access
git remote -v

Step 3: Set Up Your Environment

Option A: Python Virtual Environment

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies (if requirements.txt exists)
pip install -r requirements.txt

# Run tests to verify setup
python -m pytest tests/ -v

Option B: Development with Existing Tools

If you already have Python 3.10+ and pytest:

# Just run the tests
cd /path/to/giglez
python -m pytest tests/ -v

Step 4: Understand the Codebase

Key Directories:

giglez/
├── src/
│   ├── matcher/           # RF device identification engine
│   │   ├── device_identifier.py      # Unified API (iteration 6/6)
│   │   ├── pattern_decoder.py        # Multi-factor scoring
│   │   ├── timing_analyzer.py        # Pulse timing extraction
│   │   ├── preamble_detector.py      # Sync pattern detection
│   │   ├── frequency_fingerprint.py  # ISM band classification
│   │   ├── statistical_classifier.py # Bayesian scoring
│   │   └── protocol_database.py      # 299 protocol signatures
│   ├── parser/
│   │   └── sub_parser.py             # Flipper .sub file parser
│   └── gps/
│       └── validator.py              # GPS validation & privacy
├── tests/
│   ├── unit/                         # 56 unit tests
│   ├── benchmark/                    # Synthetic signal testing
│   └── real_captures/                # Real Flipper Zero files
├── scripts/
│   ├── benchmark.py                  # Accuracy benchmarking
│   └── benchmark_real.py             # Real-world testing
└── docs/
    ├── REAL_CAPTURE_ANALYSIS.md      # 0% accuracy gap analysis
    └── WARDRIVER_ONBOARDING.md       # RF community survey

Read First:

1. CLAUDE.md - Project status & architecture
2. docs/REAL_CAPTURE_ANALYSIS.md - Critical findings on real-world performance
3. docs/WARDRIVER_ONBOARDING.md - Data format requirements

Step 5: Make Your First Contribution

Quick Start Tasks (Good First Issues)

1. Add Missing Protocols (Priority 2 fix - 27% of failures)

• Add Acurite 02077M to protocol database
• Add GE Doorbell 19297
• Add Byron DB421E
• Add Holtek HT12X (fan/LED remotes)

2. Test Real Captures

• Download more real .sub files from UberGuidoZ/Flipper
• Run scripts/benchmark_real.py
• Document which protocols work/fail

3. Improve Documentation

• Add examples to CONTRIBUTING.md
• Create protocol database contribution guide
• Document how to add new signal types

4. Fix Decoded .sub File Support (Priority 1 fix - 45% of failures)

• Implement parser for decoded Flipper files
• Extract Protocol, Bit, Key, TE fields
• Match by protocol name + timing element

---

🔄 Git Workflow

Standard Development Workflow

# 1. Create feature branch
git checkout -b feature/your-feature-name

# 2. Make changes and commit
git add .
git commit -m "feat: add Acurite 02077M protocol support"

# 3. Push to GitHub
git push origin feature/your-feature-name

# 4. Create Pull Request on GitHub
# Visit: https://github.com/leetcrypt/giglez/pulls
# Click "New Pull Request"

Commit Message Convention

Follow conventional commits:

feat: add new protocol support for Holtek HT12X
fix: correct timing ratio calculation for Oregon Scientific
docs: update CONTRIBUTING.md with fork workflow
test: add unit tests for decoded .sub file parsing
refactor: optimize preamble detection algorithm

Branch Naming

• feature/protocol-xyz - New protocol additions
• fix/timing-accuracy - Bug fixes
• docs/contributing-guide - Documentation
• test/real-captures - Test improvements

---

🏗️ For GhostArmyIntel Organization

Option 1: Transfer Repository to Organization (Recommended)

Requires: GhostArmyIntel organization admin to accept transfer

Process:

1. Repository owner (leetcrypt) initiates transfer:

   gh api -X POST /repos/leetcrypt/giglez/transfer \
     -f new_owner=GhostArmyIntel
   

2. GhostArmyIntel org admin accepts transfer at: https://github.com/settings/repositories

3. Repository becomes: GhostArmyIntel/giglez

4. leetcrypt is re-added as collaborator

Pros:

• Organization owns the repo
• Professional branding
• Team can manage collaborators
• Fits with wardriving-converter, WiGLE-Vault projects

Cons:

• Requires org admin permission
• URL changes (redirect is automatic)

Option 2: Fork to Organization

Process:

1. GhostArmyIntel member visits: https://github.com/leetcrypt/giglez
2. Click "Fork" button
3. Select "GhostArmyIntel" as owner
4. Fork created at: GhostArmyIntel/giglez

Workflow:

# Clone the fork
git clone https://github.com/GhostArmyIntel/giglez.git
cd giglez

# Add upstream remote (original repo)
git remote add upstream https://github.com/leetcrypt/giglez.git

# Sync with upstream
git fetch upstream
git merge upstream/main

Pros:

• Independent development
• Can create org-specific features
• Proper fork relationship

Cons:

• Two separate repositories
• Need to sync regularly

Option 3: Collaborator Access (Current Setup)

Process:

1. Ringmast4r accepts invitation to leetcrypt/giglez
2. Works directly on shared repository
3. Creates branches and PRs

Pros:

• Simple, immediate access
• Single source of truth

Cons:

• Not under GhostArmyIntel organization

---

📊 Current Priority Tasks

Based on docs/REAL_CAPTURE_ANALYSIS.md:

Priority 1: Decoded .sub File Support (Fixes 45% of failures)

Impact: 5/11 real captures failed because they're decoded, not RAW

Task:

# Implement in src/parser/sub_parser.py
def parse_decoded_sub_file(filepath):
    """Parse decoded Flipper .sub files"""
    # Extract: Protocol, Bit, Key, TE
    # Match by protocol name + timing element
    # Return SignalMetadata with is_decoded=True

Priority 2: Add Missing Protocols (Fixes 27% of failures)

Needed:

• Acurite 02077M (weather station)
• GE Doorbell 19297
• Byron DB421E
• Holtek HT12X (LED/fan remotes)
• LiftMaster (generic 433 MHz)

Task: Add to src/matcher/protocol_database.py:

Protocol(
    name="Acurite 02077M",
    category="weather_sensor",
    frequency=433920000,
    short_pulse_us=1000,
    long_pulse_us=2000,
    # ... etc
)

Priority 3: Improve Real Signal Robustness (Fixes 27% of failures)

Issues:

• Multi-packet transmissions (131 pulses vs 40 bits)
• Signal noise beyond 15% tolerance

Tasks:

• Implement packet segmentation
• Increase jitter tolerance from 15% → 25%
• Add repetition detection

---

🧪 Testing Your Changes

Run All Tests

# All unit tests
pytest tests/ -v

# Specific test file
pytest tests/unit/test_timing_analyzer.py -v

# With coverage
pytest tests/ --cov=src --cov-report=html

Run Benchmarks

# Synthetic signal benchmark
python scripts/benchmark.py

# Real-world captures benchmark
python scripts/benchmark_real.py

Expected Output

REAL-WORLD BENCHMARK SUMMARY
═══════════════════════════════
Total Tests: 11

TOP-K ACCURACY:
  Top-1: 0.0% (0/11)   # Target: improve this!
  Top-3: 0.0% (0/11)

---

📞 Communication & Coordination

GitHub Discussions

Use GitHub Issues for:

• Bug reports
• Feature requests
• Protocol addition proposals
• Questions about implementation

Pull Request Reviews

• Tag @leetcrypt for code review
• Tag @Ringmast4r for wardriving expertise
• Wait for approval before merging

Project Board (Coming Soon)

Track work on GitHub Projects:

• To Do: Priority tasks from REAL_CAPTURE_ANALYSIS.md
• In Progress: Current work
• Done: Completed features

---

🎯 Long-Term Vision

Phase 1 (Current): Core Identification Engine

• ✅ Multi-factor scoring
• ✅ Protocol database (299 protocols)
• ⚠️ Real-world accuracy (in progress)

Phase 2: Web Platform

• Upload interface (drag .sub files + GPS)
• Interactive map (Leaflet.js)
• Device database browser

Phase 3: Community Features

• Manual device ID submission
• Photo uploads
• Voting/verification system
• Leaderboards

Phase 4: Multi-Format Support

• rtl_433 JSON import
• URH .complex files
• GPX track parsing
• Batch upload API

---

📄 License

MIT License - See LICENSE file

---

🤝 Code of Conduct

• Be respectful and professional
• Provide constructive feedback
• Help newcomers learn
• Document your changes
• Test before pushing

---

❓ Questions?

GitHub Issues: https://github.com/leetcrypt/giglez/issues Repository: https://github.com/leetcrypt/giglez

Related GhostArmyIntel Projects:

• wardriving-converter: https://github.com/GhostArmyIntel/wardriving-converter
• WiGLE-Vault: https://github.com/GhostArmyIntel/WiGLE-Vault
• OUI-Master-Database: https://github.com/GhostArmyIntel/OUI-Master-Database

---

"A Ringmast4r project honoring the WWII Ghost Army — blending art, code, and strategy into modern open-source signalcraft."

Last Updated: 2026-02-16