Skip to content

FAQ

Jump to bottom
Chris Purcell edited this page Feb 7, 2026 · 2 revisions

Frequently Asked Questions

Common questions about HA-Dev-Template and Home Assistant integration development.

General Questions

Q: What is this template for?

A: This template provides a complete development environment for creating custom Home Assistant integrations. It includes:

  • Python 3.14.2+ setup with Home Assistant
  • Testing framework (pytest + HA-specific tools)
  • Code quality tools (Ruff, mypy, pre-commit)
  • Example integration following best practices
  • CI/CD pipelines
  • Comprehensive documentation

Q: Do I need to know Home Assistant to use this?

A: Basic familiarity with Home Assistant is recommended. You should understand:

  • How integrations work in HA
  • Basic concepts (entities, devices, services)
  • How to use the HA UI

You don't need deep HA internals knowledge - the template guides you through development patterns.

Q: Can I use this for my first integration?

A: Absolutely! This template is designed for both beginners and experienced developers. Start by studying the example integration, then follow the Getting Started guide.

Q: Is this only for Python developers?

A: Home Assistant integrations are written in Python, so Python knowledge is required. However, if you're new to Python, this template follows modern best practices and can help you learn.

Setup Questions

Q: Which Python version do I need?

A: Python 3.14.2 or higher. Home Assistant 2026.2+ requires Python 3.14.2+.

Check your version:

python --version  # Should show 3.14.x or higher

Q: Can I use Windows for development?

A: Yes! The template works on Windows, macOS, and Linux. Just note:

  • Use Windows Subsystem for Linux (WSL) for best experience
  • Or use native Windows with Python 3.14.2+
  • File paths may differ (use pathlib.Path for cross-platform code)

Q: Do I need a running Home Assistant instance?

A: No! Tests mock Home Assistant, so you don't need HA running for development. However, for manual testing of your integration, you'll want:

  • A test HA instance (dev container, VM, or spare Pi)
  • DO NOT test on your production HA!

Q: Can I develop integrations in VS Code?

A: Yes, VS Code is recommended! This template includes:

  • .vscode/settings.json with Python configuration
  • Integrated debugging support
  • Extensions recommendations (Python, Ruff, mypy)

Development Questions

Q: Do I need to use DataUpdateCoordinator?

A: Yes, for ANY integration that polls data. DataUpdateCoordinator is:

  • Required for Bronze tier
  • Best practice for all polling integrations
  • Handles errors, availability, and prevents redundant polls

Exceptions: Integrations that only provide services or utilities (no data fetching).

Q: Can I use YAML configuration?

A: NO! New integrations must use config flow (UI-based setup). YAML configuration is:

  • Deprecated for new integrations
  • Not allowed in HA Core
  • Required to be config flow for Bronze tier

Q: How do I handle API keys/passwords securely?

A: Store credentials in ConfigEntry.data:

# In config flow
return self.async_create_entry(
    title="My Integration",
    data={CONF_API_KEY: user_input[CONF_API_KEY]},
)

# Access in setup
api_key = entry.data[CONF_API_KEY]

NEVER:

  • Log credentials
  • Store in entity attributes
  • Hardcode in source code

Q: Should I use async or sync?

A: Always use async for I/O operations. Home Assistant is async, and blocking the event loop freezes the entire system.

# ✅ CORRECT
async def get_data(self):
    async with aiohttp.ClientSession() as session:
        async with session.get(url) as resp:
            return await resp.json()

# ❌ WRONG - blocks event loop!
def get_data(self):
    return requests.get(url).json()

Testing Questions

Q: Are tests really required?

A: Yes! Tests are:

  • Required for Bronze tier
  • Required for HACS submission
  • Essential for catching bugs
  • Necessary for Gold tier (90%+ coverage)

Q: How do I test without a real device/API?

A: Use mocks! Tests should NEVER make real API calls:

@pytest.fixture
def mock_api():
    """Mock API client."""
    with patch("custom_components.my_integration.MyApiClient") as mock:
        client = mock.return_value
        client.async_get_data = AsyncMock(return_value={"temp": 20.5})
        yield client

Q: My tests pass locally but fail in CI. Why?

A: Common causes:

  • Different Python versions (CI runs 3.13 and 3.14)
  • Platform-specific code (paths, timezones)
  • Missing dependencies
  • Cached data

Solution: Run tests in clean environment matching CI.

Quality Questions

Q: What quality tier should I target?

A:

  • Minimum: Bronze (functional, tested, linted)
  • Recommended: Silver (reliable error handling, good UX)
  • Ideal: Gold (robust, well-tested, fully typed)
  • Aspirational: Platinum (excellent code, optimal performance)

Start with Bronze, iterate to Silver/Gold.

Q: How do I achieve 90% test coverage (Gold tier)?

A:

  1. Test all config flow steps
  2. Test all error scenarios
  3. Test setup/unload
  4. Test coordinator updates
  5. Test all entity platforms
  6. Test entity availability

Run: pytest --cov=custom_components.my_integration --cov-report=html

Q: Is type checking (mypy) really necessary?

A: For Gold tier, yes. Type hints:

  • Catch bugs at development time
  • Improve IDE autocomplete
  • Document function contracts
  • Required for HA Core contributions

Run: mypy custom_components/my_integration/

Publishing Questions

Q: How do I publish to HACS?

A: See Publishing Guide for full details.

Quick summary:

  1. Meet Bronze tier requirements
  2. Create public GitHub repository
  3. Add hacs.json and LICENSE
  4. Create v1.0.0 release
  5. Submit PR to hacs/default

Q: Do I need to submit to HACS?

A: No, but it's highly recommended! HACS provides:

  • Easy installation for users
  • Automatic updates
  • Larger audience
  • Community trust

Alternative: Users can manually install from your GitHub repo.

Q: Can I submit broken/WIP integrations to HACS?

A: NO! Only submit working, tested integrations. HACS will reject:

  • Broken integrations
  • Missing tests
  • Invalid structure
  • Poor documentation

Q: How do I update my published integration?

A: Simply create a new GitHub release:

# Update manifest.json version
git tag v1.1.0
git push origin v1.1.0

HACS automatically detects new releases. Users get update notifications.

Common Issues

Q: My entities show "Unavailable". How do I fix this?

A: Common causes:

  1. Coordinator update failed (check logs for errors)
  2. Entity availability check too strict
  3. Data structure mismatch
  4. Coordinator not refreshing

See Troubleshooting for solutions.

Q: Config flow doesn't show my error messages. Why?

A: Error key mismatch between code and strings.json:

# config_flow.py
errors["base"] = "cannot_connect"

# strings.json - must match!
{
  "error": {
    "cannot_connect": "Failed to connect"
  }
}

Q: Tests can't import my integration. How do I fix it?

A: This is already fixed in conftest.py, but ensure:

# tests/conftest.py
import sys
from pathlib import Path

sys.path.insert(0, str(Path(__file__).parent.parent))

Best Practices

Q: Should I create one big file or split code into modules?

A:

  • Small integrations: Single file OK
  • Medium integrations: Split into logical modules (coordinator, entities, api)
  • Large integrations: Use package structure with submodules

Example structure:

my_integration/
├── __init__.py
├── coordinator.py
├── config_flow.py
├── const.py
├── api.py
├── sensor.py
├── binary_sensor.py
└── switch.py

Q: How often should coordinator poll data?

A: Depends on use case:

  • Fast-changing data: 10-30 seconds
  • Slow-changing data: 60-300 seconds
  • Infrequent updates: 300+ seconds

Balance:

  • Too frequent: Wastes resources, may hit rate limits
  • Too infrequent: Stale data, poor UX

Q: Should I support YAML configuration for backward compatibility?

A: NO! If you must support legacy users:

  1. Use config flow as primary method
  2. Provide migration path from YAML
  3. Deprecate YAML in docs
  4. Plan removal timeline

New users should only use config flow.

Contributing

Q: How do I contribute to this template?

A:

  1. Fork the repository
  2. Make improvements
  3. Add tests
  4. Create pull request

Ideas for contributions:

  • Additional example integrations (OAuth2, multi-platform)
  • Documentation improvements
  • Bug fixes
  • Additional automation

Q: Can I suggest new features?

A: Yes! Open a Discussion to:

  • Propose new features
  • Suggest improvements
  • Share ideas

Q: I found a bug in the template. What should I do?

A: Open an issue with:

  • Description of the bug
  • Steps to reproduce
  • Expected vs actual behavior
  • Error messages/logs
  • Your environment (OS, Python version)

Resources

Q: Where can I learn more about Home Assistant development?

A:

Q: Are there example integrations to study?

A: Yes!

  • In this template: custom_components/example_integration/
  • HA Core: Browse core integrations
  • Community: Search GitHub for custom integrations

Q: Where do I get help if stuck?

A:

  1. Check Troubleshooting
  2. Search HA Developer Docs
  3. Ask in Discussions
  4. Join HA Discord - #devs_integrations

Still Have Questions?

Can't find your answer?

Related Guides

Clone this wiki locally