# 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

```bash
# 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
```bash
# 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:
```bash
# 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

```bash
# 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:
   ```bash
   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:**
```bash
# 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:**
```python
# 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`:
```python
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
```bash
# 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
```bash
# 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