A Home Assistant custom integration for managing your crops. Track sowing dates, quantities, and species for each plant, view upcoming events in the HA calendar, and automatically enrich entries with AI-generated images.
Each crop becomes a sensor entity (with name, quantity, sowing date, species, and a picture) and all crops are aggregated in a calendar entity so you can visualise your planting schedule from the HA dashboard.
- In Home Assistant, open HACS → Integrations.
- Click the three-dot menu in the top-right corner and choose Custom repositories.
- Add this repository URL with category Integration.
- Find the Crop Planner card and click Install.
- Restart Home Assistant.
- Copy the
custom_components/cropdirectory into your HAcustom_components/folder. - Restart Home Assistant.
Go to Settings → Devices & Services → Add Integration and search for Crop Planner.
Call the crop.create_crop service (from Developer Tools → Services or an automation):
| Field | Required | Description |
|---|---|---|
name |
Yes | Display name (e.g. Tomate de colgar) |
quantity |
Yes | Number of plants (1–50) |
sowing_date |
No | ISO date string, e.g. 2024-04-15 |
species |
No | Species name (stored as an attribute) |
| Entity | Platform | Description |
|---|---|---|
sensor.crop_<name> |
sensor |
One per crop — state is ok, attributes contain all crop data |
calendar.crop_planner |
calendar |
Aggregated calendar with sowing dates |
Open the repo in VS Code and choose Reopen in Container. The container:
- Installs all dependencies via
script/setup+script/bootstrap - Forwards port 8123 for the HA web UI
- Enables async debug mode (
PYTHONASYNCIODEBUG=1)
Requirements: Python 3.13.2+, Home Assistant installed in a virtual environment.
# (First time) create and activate the virtual environment
python3 -m venv .venv
source .venv/bin/activate
# Install dev dependencies
pip install -r requirements.txt
# (First time) initialise the config directory
hass --config config --script ensure_config
# Start Home Assistant with the integration loaded
script/developOn subsequent sessions, just activate the existing venv before running any commands:
source .venv/bin/activateThe script/develop command sets PYTHONPATH so HA picks up custom_components/crop from the repo root and starts with --debug. The HA web UI is available at http://localhost:8123.
Tests use pytest-homeassistant-custom-component.
# (First time) install test dependencies
pip install -r requirements_test.txt
# Run all tests
pytest
# Run a specific file
pytest tests/test_init.py
# Run with verbose output
pytest -v# Start HA dev server
script/develop
# Run tests
pytest
# Lint changed Python files (Ruff + Pylint, relative to upstream/dev)
script/lint
# Check code formatting
script/check_format
script/lintcompares againstupstream/dev. Add the upstream remote if needed:git remote add upstream https://github.com/coopnex/crop-planner.git
The formatter is Ruff (configured in .ruff.toml). Format on save is enabled in the dev container.
Pull requests are welcome. Please follow these steps:
- Fork the repo and create a branch from
main. - Make your changes and ensure
script/lintpasses. - Test manually with
script/develop. - Open a pull request.
Bug reports and feature requests go to GitHub Issues.
All contributions are licensed under the MIT License.
- Todo-list platform — expose crops as HA to-do items for checklist-style management
- Harvest date tracking — add expected harvest date based on species grow time
- Crop status lifecycle — model states beyond
ok(e.g. germinating, growing, harvested, failed) - Translations (i18n) — add
strings.jsonand translation files for multi-language support, mainly for catalan and spanish - Delete / archive service — service call to remove or archive a crop entry
- Notification automations — blueprint for sowing-date reminders and harvest alerts
- UI card — custom Lovelace card for a visual garden overview