Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
272 lines (200 loc) · 6.04 KB

CONTRIBUTING.md

File metadata and controls

272 lines (200 loc) · 6.04 KB

Contributing to APS2MQTT

Thank you for your interest in contributing to APS2MQTT! 🎉

📋 Table of Contents

🤝 Code of Conduct

This project follows a simple code of conduct:

  • Be respectful and inclusive
  • Focus on constructive feedback
  • Help others when you can

🛠️ How Can I Contribute?

Reporting Bugs

Before creating bug reports, please check existing issues. When creating a bug report, include:

  • Clear title and description
  • Steps to reproduce the behavior
  • Expected vs actual behavior
  • Environment details (OS, Docker version, ECU model)
  • Logs (with DEBUG=True if possible)

Suggesting Enhancements

Enhancement suggestions are welcome! Please include:

  • Clear use case - Why is this needed?
  • Proposed solution - How would it work?
  • Alternatives considered
  • Impact - Who benefits?

Pull Requests

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes
  4. Run tests (python3 test_refactoring.py)
  5. Commit with clear messages
  6. Push to your branch
  7. Open a Pull Request

🚀 Development Setup

Prerequisites

  • Python 3.8+
  • Docker (optional, for testing)
  • APSystems ECU for real testing (or use mock data)

Local Setup

# Clone repository
git clone https://github.com/fligneul/aps2mqtt.git
cd aps2mqtt

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

# Install dependencies
pip install -r requirements.txt

# Install in development mode
pip install -e .

Configuration for Development

Create a config.yaml or .env file:

ecu:
  APS_ECU_IP: '192.168.1.42'
  APS_ECU_TIMEZONE: 'Europe/Paris'

mqtt:
  MQTT_BROKER_HOST: 'localhost'
  MQTT_BROKER_PORT: 1883

Running Locally

# With config file
python3 -m aps2mqtt -c config.yaml

# With environment variables
export APS_ECU_IP=192.168.1.42
export MQTT_BROKER_HOST=localhost
python3 -m aps2mqtt

🏗️ Architecture Overview

The project follows a modular architecture:

aps2mqtt/
├── models.py          # Data models (ECUData, InverterData)
├── constants.py       # Configuration constants
├── parser.py          # Data parsing logic
├── ha_discovery.py    # Home Assistant Discovery generation
├── mqtt_handler.py    # MQTT interface
├── config.py          # Configuration management
├── main.py            # Main application loop
└── apsystems/
    ├── ECU.py         # ECU communication
    └── APSystemsSocket.py  # Socket protocol

Key Components

Models (models.py):

  • InverterData: Represents inverter data with type hints
  • ECUData: Represents ECU data with aggregated inverter info
  • HAEntity: Home Assistant entity configuration

Parser (parser.py):

  • DataParser: Converts ECUData to MQTT topics
  • Handles online/offline states
  • Calculates aggregate statistics

HA Discovery (ha_discovery.py):

  • HADiscoveryGenerator: Creates HA MQTT Discovery configs
  • Reads entity definitions from models.csv
  • Generates proper device classes and units

MQTT Handler (mqtt_handler.py):

  • MQTTHandler: Manages MQTT connection and publishing
  • Handles reconnection logic
  • Publishes both data and discovery topics

Data Flow

ECU Device
    ↓
APSystemsSocket (raw data)
    ↓
ECU.update() → ECUData object
    ↓
DataParser → MQTT topics dict
    ↓
MQTTHandler → Publish to broker
    ↓
Home Assistant (auto-discovery)

🧪 Testing

Unit Tests

# Run refactoring tests
python3 test_refactoring.py

# Run multi-inverter tests
python3 test_multiple_inverters.py

Manual Testing

# Enable debug mode
export DEBUG=True
python3 -m aps2mqtt -c config.yaml

# Monitor MQTT topics
mosquitto_sub -h localhost -t 'aps/#' -v

Docker Testing

# Build image
docker build -t aps2mqtt:test .

# Run with test config
docker run --rm \
  -e APS_ECU_IP=192.168.1.42 \
  -e MQTT_BROKER_HOST=192.168.1.50 \
  -e DEBUG=True \
  aps2mqtt:test

📝 Submitting Changes

Commit Messages

Follow conventional commits format:

type(scope): subject

body (optional)

footer (optional)

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • refactor: Code refactoring
  • test: Adding tests
  • chore: Maintenance tasks

Examples:

feat(parser): add support for QS1A inverters
fix(mqtt): handle connection timeout gracefully
docs(readme): update installation instructions
refactor(models): improve type hints coverage

Code Style

  • Follow PEP 8 style guide
  • Use type hints where possible
  • Add docstrings for public methods
  • Keep functions focused and small
  • Add comments for complex logic

Documentation

When adding features, update:

  • README.md (if user-facing)
  • INSTALL.md (if changes configuration)
  • ENTITIES.md (if new entities)
  • Code docstrings
  • Type hints

🔍 Review Process

Pull requests are reviewed for:

  1. Functionality - Does it work as intended?
  2. Code Quality - Is it maintainable?
  3. Tests - Are changes tested?
  4. Documentation - Is it documented?
  5. Compatibility - Does it break existing setups?

📚 Resources

🆘 Getting Help

📄 License

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

Thank you for contributing to APS2MQTT! 🌟