esp32-bluetooth-relay/CONTRIBUTING.md

Contributing to ESP32 Bluetooth Relay Controller

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

Table of Contents

• Code of Conduct
• How Can I Contribute?
• Reporting Bugs
• Suggesting Features
• Development Setup
• Pull Request Process
• Coding Standards
• Testing Guidelines

Code of Conduct

Our Pledge

We are committed to providing a welcoming and inclusive environment for everyone. We expect all contributors to:

• Be respectful and considerate
• Welcome diverse perspectives and experiences
• Accept constructive criticism gracefully
• Focus on what's best for the community
• Show empathy towards other community members

Unacceptable Behavior

• Harassment, discrimination, or derogatory comments
• Trolling, insulting comments, or personal attacks
• Publishing private information without permission
• Any conduct that could be considered inappropriate in a professional setting

How Can I Contribute?

Reporting Bugs

Before creating a bug report:

1. Check existing issues to avoid duplicates
2. Test with the latest version to ensure the bug still exists
3. Gather information about your setup and the bug

Bug Report Template

**Description:**
A clear description of the bug

**Steps to Reproduce:**
1. Step 1
2. Step 2
3. Step 3

**Expected Behavior:**
What you expected to happen

**Actual Behavior:**
What actually happened

**Environment:**
- ESP32 Board: [e.g., ESP32-DevKitC V4]
- Relay Module: [e.g., 8-Channel 5V Active LOW]
- Arduino IDE Version: [e.g., 2.3.2]
- Operating System: [e.g., Windows 11]
- Bluetooth Device: [e.g., Android 14]

**Additional Context:**
- Serial monitor output
- Photos of wiring
- Any other relevant information

Suggesting Features

Feature requests are welcome! Before submitting:

1. Check if it's already requested in existing issues
2. Explain the use case - why is this feature needed?
3. Provide examples of how it would work
4. Consider alternatives you've thought about

Feature Request Template

**Feature Description:**
A clear description of the feature

**Use Case:**
Why is this feature needed? What problem does it solve?

**Proposed Solution:**
How you think this feature should work

**Alternatives Considered:**
Other solutions you've thought about

**Additional Context:**
Mockups, diagrams, or examples

Development Setup

Prerequisites

• Arduino IDE 2.0+ or PlatformIO
• ESP32 board support installed
• Git for version control
• An ESP32 board and relay module for testing

Setting Up Development Environment

1. Fork the repository

   # Click "Fork" on the repository page
   

2. Clone your fork

   git clone https://gitea.hideawaygaming.com.au/[your-username]/esp32-bluetooth-relay.git
   cd esp32-bluetooth-relay
   

3. Create a branch

   git checkout -b feature/your-feature-name
   # or
   git checkout -b bugfix/your-bugfix-name
   

4. Set up hardware

   • Connect ESP32 and relay module as per documentation
   • Test with existing firmware before making changes

Testing Your Changes

1. Compile the code

   # Arduino IDE: Sketch > Verify/Compile
   # PlatformIO: pio run
   

2. Upload to ESP32

   # Arduino IDE: Sketch > Upload
   # PlatformIO: pio run --target upload
   

3. Test functionality

   • Test all modified features
   • Verify existing features still work
   • Test edge cases

4. Check serial output

   • Monitor for errors or warnings
   • Verify debug messages are helpful

Pull Request Process

Before Submitting

• Code compiles without errors
• All features tested on actual hardware
• Documentation updated (README, comments, etc.)
• CHANGELOG.md updated with your changes
• Code follows project coding standards
• Commit messages are clear and descriptive

Submitting a Pull Request

1. Push to your fork

   git push origin feature/your-feature-name
   

2. Create Pull Request

   • Go to the original repository
   • Click "New Pull Request"
   • Select your fork and branch
   • Fill out the PR template

3. PR Description Template

   ## Description
   Brief description of changes
   
   ## Type of Change
   - [ ] Bug fix
   - [ ] New feature
   - [ ] Documentation update
   - [ ] Performance improvement
   - [ ] Code refactoring
   
   ## Testing
   How has this been tested?
   
   ## Checklist
   - [ ] Code compiles without errors
   - [ ] Tested on actual hardware
   - [ ] Documentation updated
   - [ ] CHANGELOG.md updated
   - [ ] Follows coding standards
   
   ## Screenshots/Videos
   If applicable, add screenshots or videos
   

Review Process

1. Maintainers will review your PR
2. Address any requested changes
3. Once approved, your PR will be merged
4. Your contribution will be credited in CHANGELOG

Coding Standards

C++ Style Guidelines

// Use clear, descriptive variable names
int relayCount = 8;  // Good
int rc = 8;          // Avoid

// Constants in UPPER_CASE
const int MAX_RELAYS = 8;

// Functions in camelCase
void sendCommand(String command) {
    // Implementation
}

// Classes in PascalCase
class RelayController {
    // Implementation
};

// Add comments for complex logic
// Calculate average response time over last 10 readings
float averageResponseTime = calculateAverage(readings, 10);

Code Organization

/*
 * File Header: Brief description of file purpose
 * Author information (optional)
 * License reference
 */

// 1. Include statements
#include "BluetoothSerial.h"

// 2. Define constants
#define MAX_BUFFER_SIZE 256

// 3. Global variables (minimize these)
BluetoothSerial SerialBT;

// 4. Function declarations
void setupRelays();
void processCommand(String cmd);

// 5. Setup function
void setup() {
    setupRelays();
}

// 6. Loop function
void loop() {
    // Main logic
}

// 7. Helper functions
void setupRelays() {
    // Implementation
}

Documentation Standards

/**
 * @brief Controls a single relay
 * 
 * @param relayIndex Index of the relay (0-7)
 * @param state Desired state (true=ON, false=OFF)
 * @return bool Success status
 */
bool setRelay(int relayIndex, bool state) {
    // Validate input
    if (relayIndex < 0 || relayIndex >= 8) {
        return false;
    }
    
    // Set relay state
    // (relays are active LOW)
    digitalWrite(relayPins[relayIndex], state ? LOW : HIGH);
    
    return true;
}

Git Commit Messages

type(scope): brief description

Longer explanation if needed

Fixes #issue_number

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Code style changes (formatting, no logic change)
• refactor: Code refactoring
• test: Adding or updating tests
• chore: Maintenance tasks

Examples:

feat(relay): add relay interlock functionality

Prevents multiple relays from being active simultaneously
when interlock mode is enabled.

Fixes #42

---

docs(readme): update wiring diagram for ESP32-C3

Added pin mapping for newer ESP32-C3 boards

---

fix(bluetooth): resolve connection timeout issue

Increased timeout from 5s to 10s to handle slower devices

Fixes #28

Testing Guidelines

Hardware Testing

Required tests before PR:

• Compile test (no errors/warnings)
• Upload test (successful upload)
• Basic functionality (all commands work)
• All 8 relays tested individually
• Bluetooth connection stability
• Power cycle test (state persistence)
• Long-running test (24+ hours)

Test Checklist

## Test Report

**Hardware:**
- ESP32 Board: [model]
- Relay Module: [model]
- Power Supply: [specs]

**Test Results:**
- [ ] All relays switch correctly
- [ ] Bluetooth pairs successfully
- [ ] Commands processed correctly
- [ ] States persist after reboot
- [ ] No memory leaks observed
- [ ] Serial output is correct
- [ ] Runs stable for 24+ hours

**Issues Found:**
- [List any issues]

**Additional Notes:**
- [Any observations]

Documentation Contributions

Documentation improvements are always welcome!

Documentation Types

• Code comments: Explain complex logic
• README updates: Keep instructions current
• Troubleshooting: Add solutions to common issues
• Examples: Add more use cases
• Diagrams: Visual aids for wiring/setup
• Translations: Documentation in other languages

Writing Style

• Use clear, simple language
• Include examples where helpful
• Add screenshots/diagrams when appropriate
• Test all instructions on fresh setup
• Proofread for grammar and clarity

Recognition

Contributors will be:

• Listed in CHANGELOG.md for their contributions
• Credited in release notes
• Mentioned in the repository's contributors section

Questions?

• Open an issue with the "question" label
• Check existing issues and discussions
• Review documentation thoroughly first

License

By contributing, you agree that your contributions will be licensed under the same MIT License that covers this project.

---

Thank you for contributing to ESP32 Bluetooth Relay Controller!

Your contributions help make this project better for everyone in the maker and IoT community.