Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
286 lines (208 loc) · 8.47 KB

CONTRIBUTING.md

File metadata and controls

286 lines (208 loc) · 8.47 KB

Contributing to Claude SDR Control

Thank you for your interest in contributing to Claude SDR Control! This project represents a 28-year dream of combining AI with software-defined radio, and we welcome contributions that help make it even better.

Table of Contents

Getting Started

Before contributing, please:

  1. Read the README.md to understand the project architecture
  2. Check existing Issues to see if your idea is already being discussed
  3. Review the app-specific documentation in claude-sdr-control/apps/ directories
  4. Consider starting with "good first issue" labeled items

Development Environment Setup

Prerequisites

  • Python 3.10 or higher
  • Git for version control
  • Modern web browser for testing the dashboard
  • HackRF One and/or PortaPack H2 (recommended but not required for basic development)

Installation

  1. Fork and clone the repository:

    git clone https://github.com/yourusername/sdr.git
cd sdr/

  2. Create a virtual environment:

    python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# or
.venv\Scripts\activate     # Windows

  3. Install dependencies:

    pip install -r requirements.txt

  4. Set up environment variables:

    cp config.example.env .env
# Edit .env with your hardware configuration

  5. Test the installation:

    cd claude-sdr-control/
python sdr_web_server.py

    Open http://localhost:5051 in your browser to verify the dashboard loads.

REPLAY Mode for Development

Don't have SDR hardware? No problem! The system includes a REPLAY mode that uses cached data for development and testing:

  • ADS-B tracking works with pre-recorded aircraft data
  • All dashboards and web interfaces are fully functional
  • Perfect for UI/UX improvements and web development
  • No hardware required for most contributions

Hardware Requirements

For Full Testing

  • HackRF One — Software-defined radio transceiver
  • PortaPack H2 — Portable SDR platform (optional but recommended)
  • Appropriate antennas for your target frequencies

Development Without Hardware

  • REPLAY mode works without any SDR hardware
  • Mock data is available for most radio applications
  • Web interface development can be done entirely offline

How to Contribute

Areas We Need Help

  1. New Radio Applications — Add support for additional protocols
  2. UI/UX Improvements — Enhance the web dashboards
  3. Documentation — Improve user guides and API docs
  4. Signal Processing — Optimize IQ decoders and DSP algorithms
  5. Testing — Help test with different hardware configurations
  6. Mobile Responsiveness — Improve mobile web experience

App-Specific Contributions

Each radio application has its own development documentation:

  • claude-sdr-control/apps/adsb/ — ADS-B aircraft tracking
  • claude-sdr-control/apps/fm-radio/ — FM broadcast radio
  • claude-sdr-control/apps/rds/ — RDS data decoding
  • claude-sdr-control/apps/recon/ — Frequency scanning
  • And more...

Check the TODO.md and ROADMAP.md files in these directories for specific tasks.

Reporting Bugs

When reporting bugs, please include:

Required Information

  • Operating System (Windows 10, macOS 14, Ubuntu 22.04, etc.)
  • Python Version (python --version)
  • Hardware (HackRF One, PortaPack H2, antenna setup)
  • Data Source Mode (REPLAY, SERIAL, or GATEWAY)

Bug Report Template

Use our Bug Report Template when creating issues. Include:

  1. Expected behavior vs actual behavior
  2. Steps to reproduce the issue
  3. Error messages or logs (if any)
  4. Screenshots (for UI issues)
  5. Hardware configuration (if hardware-related)

Logs and Debugging

Helpful log locations:

  • Web server: Console output from sdr_web_server.py
  • HackRF Gateway: claude-sdr-control/sdr-gateway/src/gateway.log
  • Serial Gateway: serial-gateway/gateway.log

Submitting Pull Requests

Before You Start

  1. Create an issue to discuss major changes
  2. Fork the repository and create a feature branch
  3. Test your changes thoroughly
  4. Update documentation if needed

Pull Request Process

  1. Create a feature branch:

    git checkout -b feature/your-feature-name

  2. Make your changes and commit:

    git add .
git commit -m "Add: brief description of your changes"

  3. Test thoroughly:

    • Run existing tests: pytest
    • Test web interface functionality
    • Verify REPLAY mode works (if applicable)

  4. Push and create PR:

    git push origin feature/your-feature-name

  5. Fill out the PR template with:

    • Description of changes
    • Testing performed
    • Screenshots (for UI changes)
    • Breaking changes (if any)

PR Guidelines

  • Keep PRs focused — One feature or fix per PR
  • Write clear commit messages — Use conventional commit format when possible
  • Update tests — Add tests for new functionality
  • Update documentation — Keep README.md and app docs current
  • Test on multiple platforms — If possible, test on different OS/hardware

Code Style

Python Code Style

We follow PEP 8 with some project-specific conventions:

  • Line length: 100 characters (not 80)
  • Import order: Standard library, third-party, local imports
  • Type hints: Use where helpful, but not required everywhere
  • Docstrings: Use for public functions and classes

File Organization

  • One class per file for major components
  • Group related functions in utility modules
  • Keep app-specific code in claude-sdr-control/apps/[app-name]/
  • Web assets go in static/ directory

Naming Conventions

  • Variables and functions: snake_case
  • Classes: PascalCase
  • Constants: UPPER_SNAKE_CASE
  • Files: snake_case.py
  • Directories: kebab-case

HTML/CSS/JavaScript

  • HTML: Semantic markup, accessible structure
  • CSS: BEM methodology for class names when possible
  • JavaScript: Modern ES6+ syntax, avoid jQuery
  • Responsive: Mobile-first design approach

Project Structure

Understanding the codebase:

sdr/
├── claude-sdr-control/           # Main application
│   ├── src/claude_sdr/
│   │   ├── decoders/            # IQ signal processing
│   │   ├── parsers/             # Data format parsers
│   │   └── controllers/         # Hardware control
│   ├── static/                  # Web dashboards
│   ├── apps/                    # Per-app documentation
│   └── sdr_web_server.py        # Main FastAPI server
├── serial-gateway/              # PortaPack serial interface
├── screenshots/                 # Documentation images
└── requirements.txt             # Python dependencies

Adding New Radio Applications

  1. Create decoder in src/claude_sdr/decoders/
  2. Create parser in src/claude_sdr/parsers/
  3. Add web dashboard in static/
  4. Create app documentation in apps/[app-name]/
  5. Update main server routing

Testing

Automated Tests

Run the test suite:

pytest

Manual Testing

Essential manual tests:

  1. Web dashboard loads at http://localhost:5051
  2. REPLAY mode works for development testing
  3. WebSocket connections establish correctly
  4. App-specific dashboards display data properly

Hardware Testing

If you have SDR hardware:

  1. Serial Gateway connects to PortaPack
  2. HackRF Gateway streams IQ data
  3. Frequency tuning works correctly
  4. Signal decoders produce expected output

License

By contributing, you agree that your contributions will be licensed under the MIT License. See the LICENSE file for details.

Questions?

  • Documentation issues: Check claude-sdr-control/apps/ directories
  • Technical questions: Create a GitHub issue
  • General discussion: Use GitHub Discussions (when enabled)

Thank you for helping make Claude SDR Control even better! 🎯📡