Contributing

Thank you for your interest in contributing to ESPectre! This document provides guidelines and information for contributors.

Table of Contents

Code of Conduct

This project follows the Contributor Covenant Code of Conduct. By participating, you agree to uphold this code. Please report unacceptable behavior to contact@espectre.dev.

First-Time Contributors

New to open source? Welcome! Here's how to get started:

  1. Check past contributions for inspiration
  2. Read through this guide before submitting your first PR
  3. Don't hesitate to ask questions in the issue comments

We appreciate all contributions, no matter how small!

Ways to Contribute

Type Description Skill Level
Bug Reports Report issues with clear reproduction steps Beginner
Documentation Improve guides, fix typos, add examples Beginner
Data Collection Contribute labeled CSI datasets Beginner
Code Review Review Pull Requests Intermediate
Bug Fixes Fix reported issues Intermediate
New Features Implement roadmap items Advanced
Algorithm R&D Develop new detection algorithms Advanced

Development Setup

Prerequisites

  • Python 3.12 (recommended)
  • ESP32 device (S3/C6 recommended)
  • Home Assistant (optional, for testing ESPHome integration)

Environment Setup

# Clone the repository
git clone https://github.com/francescopace/espectre.git
cd espectre

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

# Install dependencies
pip install -r micro-espectre/requirements.txt

Running Tests

# C++ tests (ESPHome component)
cd test && pio test

# Python tests (Micro-ESPectre)
cd micro-espectre && pytest tests/ -v

# With coverage (run from micro-espectre/)
cd micro-espectre && pytest tests/ -v --cov=src --cov-report=term-missing

Code Contributions

Branching Model

ESPectre uses a simple branching model:

  • develop: Active development branch. All PRs should target this branch.
  • main: Stable release branch. Merges from develop when releasing.

Workflow

  1. Fork the repository on GitHub
  2. Clone your fork locally
  3. Create a branch from develop: bash git checkout develop git pull origin develop git checkout -b feature/your-feature-name
  4. Make changes with tests and documentation
  5. Run tests to ensure nothing is broken
  6. Commit with clear messages (see Commit Guidelines)
  7. Push to your fork
  8. Open a Pull Request to the develop branch

Commit Guidelines

Use clear, descriptive commit messages:

<type>: <short description>

<optional body with more details>

Types: - feat: New feature - fix: Bug fix - docs: Documentation only - test: Adding or updating tests - refactor: Code refactoring (no functional change) - perf: Performance improvement - chore: Maintenance tasks

Examples:

feat: add low-pass filter for noise reduction
fix: correct calibration for edge cases
docs: update TUNING.md with filter examples
test: add unit tests for Hampel filter

DCO Sign-off (required)

This repository enforces the Developer Certificate of Origin (DCO) in CI. Every commit in a pull request must include a valid Signed-off-by trailer.

Use:

git commit -s -m "type: short description"

For existing commits, add the sign-off and force-push your branch:

git commit --amend -s
git push --force-with-lease

Code Style

C++ (ESPHome Component)

  • Follow ESPHome component conventions
  • Use ESP-IDF framework (not Arduino)
  • Use ESP_LOGD, ESP_LOGI, ESP_LOGW, ESP_LOGE for logging
  • All code and comments in English

File Header:

/*
 * ESPectre - [Component Name]
 * 
 * [Brief description]
 * 
 * Author: [your name] <[your email]>
 * License: GPLv3
 */

Python (Micro-ESPectre)

  • MicroPython compatible (no asyncio, limited stdlib)
  • Memory-efficient (ESP32 constraints)
  • Use config.py for constants
  • All code and comments in English

File Header:

"""
Micro-ESPectre - [Module Name]

[Brief description]

Author: [your name] <[your email]>
License: GPLv3
"""

Pull Request Guidelines

  • Target branch: Always develop (not main)
  • Title: Clear, descriptive title
  • Description: Explain what and why
  • Tests: Include tests for new functionality
  • Documentation: Update relevant docs
  • Single focus: One feature/fix per PR

Quality Standards

Requirement Target
Test coverage >80% for core modules
CI passing All checks must pass
Documentation Features require docs
Code review At least one approval

Data Contributions

Help build a diverse CSI dataset for ML training! Your contributions will improve gesture recognition and HAR models for everyone.

How to Contribute Data

  1. Collect data following ML_DATA_COLLECTION.md
  2. Ensure quality:
  3. At least 10 samples per label
  4. 30+ seconds per sample
  5. Quiet room for baseline recordings
  6. Document your setup:
  7. ESP32 model (S3, C6, etc.)
  8. Distance from router
  9. Room type (living room, office, etc.)
  10. Any notable characteristics
  11. Submit via Pull Request:
  12. Add your data to micro-espectre/data/<label>/
  13. Include a brief description in the PR

Priority Gestures

We're particularly looking for these gestures useful for smart home automation:

Priority Gesture Description Use Case
🔴 High swipe_left / swipe_right Hand swipe in air Change scene, adjust brightness
🔴 High push / pull Push away / pull toward Turn on/off, open/close
🔴 High circle_cw / circle_ccw Circular hand motion Dimmer, thermostat
🟡 Medium clap Hand clap Toggle lights
🟡 Medium sit_down / stand_up Sitting/standing TV mode, energy saving
🟡 Medium fall Person falling Elderly safety alert
🟢 Low idle No movement Baseline (always needed)

Data Privacy

  • CSI data is anonymous - contains only radio channel characteristics
  • No personal information, images, or audio
  • You retain ownership of your contributions
  • All contributions will be credited

Documentation

Good documentation is essential! Here's how you can help:

Types of Documentation

Type Location Description
README README.md Project overview, quick start
Setup Guide SETUP.md Installation and configuration
Tuning Guide TUNING.md Parameter optimization
Algorithms micro-espectre/ALGORITHMS.md Scientific documentation
API Docs Code comments Function/class documentation

Documentation Guidelines

  • Write in clear, simple English
  • Include code examples where helpful
  • Keep formatting consistent with existing docs
  • Test any commands or code snippets you include

Reporting Issues

Before Reporting

  1. Search existing issues to avoid duplicates
  2. Check the FAQ in README.md
  3. Try the latest version from develop branch

Bug Reports

Include: - Description: Clear description of the bug - Steps to reproduce: Numbered steps - Expected behavior: What should happen - Actual behavior: What actually happens - Environment: - ESP32 model (S3, C6, etc.) - ESPectre version - Home Assistant version (if applicable) - Relevant configuration

Feature Requests

Include: - Use case: Why is this feature needed? - Proposed solution: How might it work? - Alternatives: Other approaches considered

Community

Getting Help

  • GitHub Issues: Bug reports and feature requests
  • GitHub Discussions: Questions and design discussions

Stay Updated

  • Watch the repository for updates
  • Star if you find it useful
  • Share with others who might benefit

Recognition

All contributors are recognized in: - Pull Request acknowledgments - Release notes for significant contributions - Data contributors credited in dataset documentation

License

By contributing to ESPectre, you agree that your contributions are licensed under the GPLv3 license.

All contributions must also be certified under the Developer Certificate of Origin (DCO) by adding the Signed-off-by trailer to each commit. This certifies that you have the right to submit the contribution under the project license.

See LICENSE for details.