Beeminder Home Assistant Integration Development

Develop and maintain the Beeminder custom integration for Home Assistant that creates sensors to track goal progress.

What This Skill Does

This skill helps you work with a Home Assistant custom component that integrates Beeminder goal tracking. The integration fetches data from the Beeminder API and creates sensor entities in Home Assistant to monitor goal progress, targets, and derailment status.

Architecture Overview

Core Components

1. **Data Coordinator** (`__init__.py`):

- `BeeminderDataUpdateCoordinator` fetches data from Beeminder API every 5 minutes

- Manages shared state for all sensors to minimize API calls

- Uses Home Assistant's `DataUpdateCoordinator` pattern

2. **Sensor Implementation** (`sensor.py`):

- Creates three sensors per Beeminder goal:

- Current value sensor (cumulative value)

- Goal value sensor (dynamic target)

- Days until derailment sensor (urgency tracking)

- Exposes comprehensive goal data as attributes (pledge, tags, goal type, urgency, last 100 datapoints)

3. **Configuration**:

- YAML configuration via `configuration.yaml` (primary method)

- UI configuration via config flow (basic implementation)

Key Integration Patterns

Step-by-Step Instructions

1. Set Up Development Environment

Install Home Assistant for local development:

```bash

pip install homeassistant

```

2. Run Home Assistant with Custom Component

Start Home Assistant pointing to your config directory:

```bash

hass -c /path/to/config/dir

```

3. Monitor Integration Logs

Check logs for integration errors and debugging output:

```bash

tail -f /path/to/config/dir/home-assistant.log

```

4. Understand Beeminder API Usage

The integration uses these Beeminder API endpoints:

- `/goals.json` - Fetch all goals

- `/goals/{slug}/datapoints.json?count=100&sort=daystamp` - Fetch goal datapoints

5. Follow Home Assistant Development Patterns

When modifying the integration code:

6. Example Automations

Create automations using the sensor data:

**Alert when goal is derailing today:**

```yaml

automation:

- alias: "Beeminder Derailment Alert"

trigger:

- platform: numeric_state

entity_id: sensor.beeminder_*_days_until_derailment

below: 1

action:

- service: notify.notify

data_template:

title: "Beeminder Alert!"

message: "Goal {{ trigger.to_state.attributes.title }} is derailing today!"

```

**Dashboard card for goals due today:**

```yaml

type: entity-filter

entities:

- sensor.beeminder_*_days_until_derailment

state_filter:

- operator: '<'

value: 1

card:

type: entities

title: Goals Due Today

```

Important Constraints

Development Tips