Home Assistant Automated Puppet

A specialized skill for working with the Automated Puppet add-on repository — a Puppeteer-based scheduled screenshot service that automatically captures Home Assistant dashboards and saves them to disk, optimized for e-ink displays.

What This Skill Does

This skill helps you understand, develop, and debug the Automated Puppet add-on. It provides context about the scheduler-based architecture, browser lifecycle management, e-ink optimization techniques, and Home Assistant integration patterns.

Key Architecture Components

Core Modules

When working with this codebase, understand these key files:

Critical Patterns

**Busy Flag Pattern** — Prevents concurrent browser operations:

```javascript

if (this.busy) throw new Error("Browser is busy");

this.busy = true;

try { /* work */ } finally { this.busy = false; }

```

**Environment Detection** — Adjusts behavior between dev and production:

```javascript

const isAddOn = optionsFile === "/data/options.json";

```

**Browser Lifecycle** — Single browser instance shared across all jobs, stays alive for scheduler lifetime (no automatic cleanup)

Development Setup Instructions

Local Development

1. Copy configuration templates:

```bash

cp puppet/ha-puppet/options-dev.json.sample puppet/ha-puppet/options-dev.json

cp puppet/ha-puppet/screenshots-example.json puppet/ha-puppet/screenshots-dev.json

```

2. Configure `options-dev.json` with:

- Home Assistant URL

- Long-lived access token

- `chromium_executable` path (defaults to Google Chrome on macOS)

3. Configure desired screenshots in `screenshots-dev.json`

4. Install dependencies and run:

```bash

cd puppet/ha-puppet && npm ci

node puppet/ha-puppet/scheduler.js

```

5. Screenshots saved to `puppet/ha-puppet/output/`

Docker Build & Run

From repository root:

```bash

docker build -t puppet -f puppet/Dockerfile .

docker run \

-v /path/to/options.json:/data/options.json \

-v /path/to/screenshots.json:/data/screenshots.json \

-v /path/to/www:/config/www \

puppet

```

Screenshot Configuration Schema

Create `screenshots-dev.json` or `/config/screenshots.json` with:

**Required Fields**:

**Optional Fields**:

See `screenshots-example.json` for complete examples.

E-ink Optimization Details

When debugging e-ink output issues:

Home Assistant Integration

Authentication

DOM Waiting Strategy

Waits for element chain:

```

home-assistant → home-assistant-main → partial-panel-resolver → panel

```

Then monitors `_loading` property on panel elements for readiness

File Access

Screenshots accessible at:

```

/local/screenshots/<name>/latest.<format>

```

Performance Considerations

Troubleshooting Guidance

Browser Won't Start

Screenshots Fail to Save

E-ink Output Issues

Authentication Failures

Dependencies

Architecture History

**v2.0.0 Changes** (scheduler-based architecture):

Constraints