# Background

renogy-ble is a library written in Python. Its purpose is to connect to Renogy devices over Bluetooth low energy and send and receive modbus commands. renogy-ble then parses the responses and returns usable data. The primary intent is for renogy-ble to be utilized/wrapped/consumed by renogy-ha, a custom integration for Home Assistant; however, renogy-ble may be used by any 3rd party and must remain independent of Home Assistant.

# Documentation

- Use Markdown for all documentation.
- Place documentation in the `docs/` directory.

# Code Style

- Add comments to code when it may be unclear what the code does or how it functions.
- Comments should be full sentences and end with a period.
- Maintainable and understandable code is preferred over complex code.

# Python

- Use uv to manage Python and all Python packages.
- Use 'uv add [package_name]' instead of 'uv pip install [package_name]'.

# Testing

- Use pytest for Python testing.
- Ensure all code is formatted and linted with Ruff.

# Files

- Do not create binary files, such as Lambda zip files.
- Do not modify CHANGELOG.md. This is handled by CI.

# Commits

- Use conventional commits for all changes
  - Prefix all commit messages with fix:; feat:; build:; chore:; ci:; docs:; style:; refactor:; perf:; or test: as appropriate.

# Before Checking In Code

- Fix all code formatting and quality issues in the entire codebase.
- Ensure all new code is covered by appropriate unit tests.

## Python

Fix all Python formatting and linting issues.

### Steps:

1. **Format with ruff**: `uv run ruff format .`
2. **Lint with ruff**: `uv run ruff check . --output-format=github`
3. **Type check with ty**: `uv run ty check . --output-format=github`
4. **Run unit tests**: `uv run pytest tests`
5. **Repeat 1-4 until all steps pass on a single run**

## General Process:

1. Run automated formatters first.
2. Fix remaining linting issues manually.
3. Resolve type checking errors.
4. Verify all tests pass with no errors.
5. Review changes before committing.

## Common Issues:

- Import order conflicts between tools
- Line length violations
- Unused imports/variables
- Type annotation requirements
- Missing return types
- Inconsistent quotes/semicolons

## Issue Tracking

This repo uses `bd` (Beads) for active task tracking.

- Run `bd ready` before starting work.
- Use `bd prime` when you need the current Beads workflow context.
- Track BLE, protocol, parsing, and transport work here.
- Keep Home Assistant integration work in `renogy-ha`.
- For cross-repo work, create the coordinating issue in `renogy-ha` and link the local implementation issue here with a dependency.
- When you want `renogy-ha` to hydrate the latest `renogy-ble` issues, run `bd export -o .beads/issues.jsonl` here, then run `bd repo sync` in `renogy-ha`. This is required for multi-repo hydration with `bd 0.60.0`.
- Do not use markdown TODO lists for active work.

## External Contributors

External contributors may submit normal PRs without using Beads.

- Maintainers use Beads for planning and coordination.
- If you are not using Beads, ignore Beads-specific task-tracking steps and follow the normal repo instructions for code, tests, and PR quality.
- Do not modify tracked Beads configuration unless your change is specifically about the Beads workflow.
- Do not commit runtime Beads artifacts such as `.beads/issues.jsonl`.
