|
| 1 | +# Battery Notes - AI Coding Instructions |
| 2 | + |
| 3 | +## Project Overview |
| 4 | +Battery Notes is a Home Assistant custom integration that tracks battery information for IoT devices. It uses a **sub-entry architecture** where a single config entry can manage multiple battery devices via ConfigSubentry objects. |
| 5 | + |
| 6 | +## Architecture & Core Components |
| 7 | + |
| 8 | +### Config Entry Structure (Critical) |
| 9 | +- **Main Config Entry**: Domain-level configuration (`BatteryNotesConfigEntry`) |
| 10 | +- **Sub-entries**: Individual device configurations (`ConfigSubentry`) stored in `config_entry.runtime_data.subentries` |
| 11 | +- **Coordinators**: Each sub-entry has its own `BatteryNotesSubentryCoordinator` in `config_entry.runtime_data.subentry_coordinators[subentry_id]` |
| 12 | + |
| 13 | +**Key Pattern**: Always iterate through `subentry_coordinators.values()` not the main coordinator when looking for devices. |
| 14 | + |
| 15 | +### Entity Inheritance Structure |
| 16 | +- `BatteryNotesEntity` (base class in `entity.py`) - handles device association and common setup |
| 17 | +- Sensor classes inherit from both `BatteryNotesEntity` and HA sensor classes |
| 18 | +- Example: `class BatteryNotesTypeSensor(BatteryNotesEntity, RestoreSensor)` |
| 19 | + |
| 20 | +### Device Discovery & Library |
| 21 | +- `library/library.json`: 10K+ device definitions with battery types |
| 22 | +- `discovery.py`: Auto-discovers devices and creates config entries |
| 23 | +- Device matching: `manufacturer` + `model` (+ optional `hw_version`) |
| 24 | + |
| 25 | +## Key File Responsibilities |
| 26 | + |
| 27 | +### Core Files |
| 28 | +- `__init__.py`: Config entry setup, sub-entry management, platform loading |
| 29 | +- `coordinator.py`: Data coordination, battery level tracking, event firing |
| 30 | +- `config_flow.py`: UI configuration flows for manual device addition |
| 31 | +- `services.py`: Battery replacement service handlers |
| 32 | +- `entity.py`: Base entity class with device association logic |
| 33 | + |
| 34 | +### Platform Files |
| 35 | +- `sensor.py`: Battery type, battery+, and last replaced sensors |
| 36 | +- `binary_sensor.py`: Battery low binary sensors |
| 37 | +- `button.py`: Battery replaced action buttons |
| 38 | + |
| 39 | +### Supporting Files |
| 40 | +- `library.py`: Device library management and updates |
| 41 | +- `discovery.py`: Automatic device discovery from library |
| 42 | +- `const.py`: All constants, service schemas, event names |
| 43 | +- `store.py`: Persistent storage for user data |
| 44 | + |
| 45 | +## Development Workflow |
| 46 | + |
| 47 | +### Local Development |
| 48 | +```bash |
| 49 | +# Start HA development server on port 8123 |
| 50 | +./scripts/develop |
| 51 | + |
| 52 | +# Lint code |
| 53 | +./scripts/lint |
| 54 | + |
| 55 | +# Check types (if mypy installed) |
| 56 | +mypy custom_components/battery_notes/ --check-untyped-defs |
| 57 | +``` |
| 58 | + |
| 59 | +### File Structure Conventions |
| 60 | +- Put constants in `const.py` with proper categorization |
| 61 | +- Use dataclasses for configuration objects |
| 62 | +- Service schemas defined in `const.py`, handlers in `services.py` |
| 63 | +- All entities extend `BatteryNotesEntity` base class |
| 64 | + |
| 65 | +## Critical Patterns |
| 66 | + |
| 67 | +### Sub-entry Iteration Pattern |
| 68 | +```python |
| 69 | +# CORRECT - iterate through sub-entry coordinators |
| 70 | +for config_entry in hass.config_entries.async_loaded_entries(DOMAIN): |
| 71 | + if not config_entry.runtime_data.subentry_coordinators: |
| 72 | + continue |
| 73 | + for coordinator in config_entry.runtime_data.subentry_coordinators.values(): |
| 74 | + if coordinator.device_id == target_device_id: |
| 75 | + # Process device |
| 76 | +``` |
| 77 | + |
| 78 | +### Entity Registration Pattern |
| 79 | +```python |
| 80 | +# Use unique_id from coordinator + description suffix |
| 81 | +self._attr_unique_id = f"{coordinator.device_id}_{description.unique_id_suffix}" |
| 82 | + |
| 83 | +# Handle entity naming based on device association |
| 84 | +if coordinator.source_entity_id and not coordinator.device_id: |
| 85 | + self._attr_translation_placeholders = {"device_name": coordinator.device_name + " "} |
| 86 | +``` |
| 87 | + |
| 88 | +### Service Implementation Pattern |
| 89 | +```python |
| 90 | +# Always validate device exists before processing |
| 91 | +device_found = False |
| 92 | +for coordinator in subentry_coordinators.values(): |
| 93 | + if coordinator.device_id == device_id: |
| 94 | + device_found = True |
| 95 | + # Process service call |
| 96 | + break |
| 97 | + |
| 98 | +if not device_found: |
| 99 | + _LOGGER.error("Device %s not configured in Battery Notes", device_id) |
| 100 | + return None |
| 101 | +``` |
| 102 | + |
| 103 | +## Testing & Validation |
| 104 | + |
| 105 | +### Type Checking |
| 106 | +- Project uses mypy with `--check-untyped-defs` |
| 107 | +- All major classes use type hints |
| 108 | +- ConfigEntry typing: `BatteryNotesConfigEntry = ConfigEntry[BatteryNotesData]` |
| 109 | + |
| 110 | +### Linting |
| 111 | +- Uses `ruff` for code formatting and linting |
| 112 | +- Config in `pyproject.toml` |
| 113 | +- Run `./scripts/lint` before commits |
| 114 | + |
| 115 | +## Integration Points |
| 116 | + |
| 117 | +### Home Assistant APIs |
| 118 | +- Device Registry: Link entities to HA devices |
| 119 | +- Entity Registry: Manage entity lifecycle |
| 120 | +- Event Bus: Fire battery events (`EVENT_BATTERY_THRESHOLD`, `EVENT_BATTERY_REPLACED`) |
| 121 | +- Config Flow: Handle UI configuration |
| 122 | + |
| 123 | +### External Dependencies |
| 124 | +- Library updates from `https://battery-notes-data.codechimp.org/library.json` |
| 125 | +- Version checking with `awesomeversion` |
| 126 | +- Data validation with `voluptuous` |
| 127 | + |
| 128 | +## Common Tasks |
| 129 | + |
| 130 | +### Adding New Entity Types |
| 131 | +1. Create entity description in appropriate platform file |
| 132 | +2. Extend `BatteryNotesEntity` base class |
| 133 | +3. Add to platform's `async_setup_entry` function |
| 134 | +4. Register constants in `const.py` |
| 135 | + |
| 136 | +### Adding New Services |
| 137 | +1. Define schema in `const.py` |
| 138 | +2. Implement handler in `services.py` using sub-entry iteration pattern |
| 139 | +3. Register in `__init__.py` `async_setup_entry` |
| 140 | +4. Add service definition to `services.yaml` |
0 commit comments