Home Assistant Automated Puppet Development

You are assisting with development of the **Automated Puppet** Home Assistant add-on - a Puppeteer-based scheduled screenshot service that automatically captures Home Assistant dashboards and saves them to disk, optimized for e-ink displays and other screen types.

This is a fork of the original Puppet add-on, refactored from an HTTP server to a scheduled background process.

Project Architecture

Core Components

**Scheduler System** (`scheduler.js`):

**Browser Management** (`screenshot.js`):

**File Manager** (`file-manager.js`):

**BMP Encoding** (`bmp.js`):

**Configuration** (`const.js`):

**Error Handling** (`error.js`):

Screenshot Processing Pipeline

1. Puppeteer captures PNG at viewport dimensions + 56px header height

2. Sharp processes image (rotate, e-ink color reduction, format conversion)

3. Custom BMP encoding for e-ink displays when needed

4. Header cropped from final output (HEADER_HEIGHT = 56px)

E-ink Optimization

Home Assistant Integration

Development Workflow

Local Development Setup

1. Copy `puppet/ha-puppet/options-dev.json.sample` to `puppet/ha-puppet/options-dev.json`

2. Configure Home Assistant URL and long-lived access token

3. Set `chromium_executable` path for your system (defaults to Google Chrome on macOS)

4. Copy `puppet/ha-puppet/screenshots-example.json` to `puppet/ha-puppet/screenshots-dev.json`

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

6. Install dependencies: `cd puppet/ha-puppet && npm ci`

7. Run scheduler: `node puppet/ha-puppet/scheduler.js`

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

Docker Build (from repository root)

```bash

Build image

docker build -t puppet -f puppet/Dockerfile .

Run container

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

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

Refer to `screenshots-example.json` for full configuration schema.

Code Patterns and Conventions

Environment Detection

```javascript

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

```

Used throughout to adjust behavior (wait times, URLs, browser args, output paths) between development and production environments.

Busy Flag Pattern

The `Browser` class uses `this.busy` to serialize operations:

```javascript

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

this.busy = true;

try {

// Perform work

} finally {

this.busy = false;

}

```

This prevents concurrent page manipulations that could cause race conditions.

Scheduler Job Management

Each screenshot configuration becomes a scheduled job with an independent `setInterval` timer stored in the `jobs` Map.

Performance Considerations

Key Dependencies

Version Management

Architecture Changes in v2.0.0

Home Assistant Add-on Configuration

**Required Options** (`config.yaml`):

**Optional Options**:

**Watchdog**: Enable in Home Assistant supervisor to auto-restart on browser launch failures

Development Guidelines

When working on this project:

1. **Maintain compatibility** between development and production modes using environment detection

2. **Respect the busy flag pattern** when adding browser operations

3. **Test with low-end devices** in mind - optimize for Home Assistant Green performance profile

4. **Preserve e-ink optimization** features when modifying image processing pipeline

5. **Keep scheduler jobs independent** - each screenshot should run on its own interval without blocking others

6. **Handle errors gracefully** - use custom error types and ensure browser cleanup on failures

7. **Document configuration changes** in both code and example JSON files

8. **Test Docker builds** before committing changes that affect the Dockerfile or dependencies