docs: add comprehensive CONTRIBUTING.md for GhostArmyIntel collaboration
Created detailed contributor guide including: **Join Process:** - Step-by-step onboarding (accept invite → clone → setup → contribute) - Current contributors: leetcrypt (admin), Ringmast4r (invited) - GhostArmyIntel organization integration options **Collaboration Workflows:** - Option 1: Transfer repo to GhostArmyIntel organization (recommended) - Option 2: Fork to organization (independent development) - Option 3: Direct collaborator access (current setup) **Development Guide:** - Codebase structure walkthrough - Git workflow (feature branches, PRs, commit conventions) - Testing procedures (unit tests, benchmarks) - Priority tasks from REAL_CAPTURE_ANALYSIS.md **Quick Start Tasks:** - Add missing protocols (Acurite 02077M, GE Doorbell, Holtek HT12X) - Implement decoded .sub file support (Priority 1 - fixes 45% failures) - Improve real signal robustness (packet segmentation, noise tolerance) **GhostArmyIntel Integration:** - Links to related projects (wardriving-converter, WiGLE-Vault, OUI-Master-Database) - Organization transfer instructions - Fork workflow for org-owned development Designed to onboard Ringmast4r and GhostArmyIntel team members with complete context on project status, architecture, and contribution paths. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
leetcrypt
+429
@@ -0,0 +1,429 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user