Home Assistant Automated Puppet 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 Structure

This is a Home Assistant add-on repository containing **Automated Puppet** (v2.0.0), a scheduler-based architecture that runs continuous screenshot jobs.

Core Components

Working with This Codebase

Development Setup

1. **Configure development environment**:

```bash

cd puppet/ha-puppet

cp options-dev.json.sample options-dev.json

cp screenshots-example.json screenshots-dev.json

```

2. **Edit `options-dev.json`**:

- Set `home_assistant_url` to your Home Assistant instance

- Add a long-lived access token from Home Assistant

- Configure `chromium_executable` path for your system (defaults to Google Chrome on macOS)

3. **Configure screenshots in `screenshots-dev.json`**:

- Each screenshot needs: `name`, `path`, `viewport`, `interval`

- Optional: `format`, `eink`, `invert`, `zoom`, `rotate`, `lang`, `theme`, `dark`, `wait`

- See `screenshots-example.json` for examples

4. **Install and run**:

```bash

npm ci

node scheduler.js

```

Screenshots will be saved to `puppet/ha-puppet/output/`

Building Docker Image

From repository root:

```bash

docker build -t puppet -f puppet/Dockerfile .

```

Run container:

```bash

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

```

Key Architecture Patterns

**Environment Detection**:

Code detects dev vs production mode:

```javascript

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

```

This adjusts wait times, URLs, browser args, and output paths.

**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 {

// browser operations

} finally {

this.busy = false;

}

```

This prevents concurrent page manipulations.

**Scheduler Lifecycle**:

Screenshot Processing Pipeline

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

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

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

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

5. File saved to `/config/www/screenshots/<name>/latest.<format>`

E-ink Optimization

For e-ink displays, the service provides:

Home Assistant Integration Details

**Authentication**:

**Page Readiness Detection**:

Waits for DOM elements in sequence:

1. `home-assistant` element

2. `home-assistant-main` shadow root

3. `partial-panel-resolver` element

4. Panel element (e.g., `hui-panel-view`)

5. `_loading` property becomes false

**Navigation Optimization**:

Uses Home Assistant's `location-changed` event instead of full page reload for faster same-domain navigation.

**Wait Times**:

Performance Tuning

Optimized for low-end devices (e.g., Home Assistant Green):

Puppeteer args include `--enable-low-end-device-mode` when running as add-on (see `screenshot.js:16-52`).

File Organization

Each screenshot gets a dedicated folder:

```

/config/www/screenshots/<name>/latest.<format>

```

Accessible via Home Assistant at:

```

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

```

History mode (timestamped copies) is currently disabled.

Making Changes

Adding Features

Testing Changes

1. Update `options-dev.json` and `screenshots-dev.json` as needed

2. Run locally: `node puppet/ha-puppet/scheduler.js`

3. Check output in `puppet/ha-puppet/output/`

4. Test in Docker container before deploying to Home Assistant

Versioning

Dependencies

Core runtime dependencies:

Container dependencies:

Migration Notes (v2.0.0)

If working with older versions:

Common Tasks

Add New Screenshot Configuration

Edit `screenshots-dev.json` or `/config/screenshots.json`:

```json

{

"name": "unique-name",

"path": "/lovelace/0",

"viewport": {"width": 800, "height": 480},

"interval": 300,

"format": "png",

"eink": true

}

```

Debug Browser Issues

Set environment variable for Puppeteer debugging:

```bash

DEBUG=puppeteer:* node scheduler.js

```

Optimize for Different Hardware

Adjust Puppeteer args in `screenshot.js` based on your target device's capabilities.

Access Screenshots from Home Assistant

Use URLs like:

```

http://homeassistant.local:8123/local/screenshots/<name>/latest.png

```

Important Constraints