Skip to content

jtenniswood/espcontrol / .agents/skills/flash-displays

flash-displays

Verified

Flash EspControl display firmware from this repository using ESPHome. Use when the user invokes /flash-displays with no extra display name, or asks to flash, reflash, update, or upload firmware to all known displays in sequence, or to a specific display such as 7inch, 7-inch P4, 10inch, 10-inch V1, 10-inch V2, 10-inch V3, P4-86, 4.3-inch P4, 4-inch P4, or S3, over an explicitly supplied OTA target or USB.

FileKindSize
SKILL.mdskill md11.2 KB
agents/openai.yamlconfig413 B
---
name: flash-displays
description: Flash EspControl display firmware from this repository using ESPHome. Use when the user invokes /flash-displays with no extra display name, or asks to flash, reflash, update, or upload firmware to all known displays in sequence, or to a specific display such as 7inch, 7-inch P4, 10inch, 10-inch V1, 10-inch V2, 10-inch V3, P4-86, 4.3-inch P4, 4-inch P4, or S3, over an explicitly supplied OTA target or USB.
---

# Flash Displays

## Overview

Use the local development ESPHome configs in the active repository worktree to flash the known EspControl displays. If the user invokes `/flash-displays` with no additional display name or target, assume they mean all displays. Flash one requested display, or flash all displays in the fixed order below. Use OTA with the default hard-coded target unless the user provides a different target; use USB only when the user explicitly asks for USB.

## Device Map

| Request names | ESPHome config directory | Default OTA target |
|---|---|---|
| `7inch`, `7-inch`, `7inch P4`, `7-inch P4`, `7inch V2`, `7-inch V2`, `JC1060P470`, `JC1060P470 V2` | `devices/guition-esp32-p4-jc1060p470-v2` | `192.168.6.102` |
| `7inch V1`, `7-inch V1`, `JC1060P470 V1` | `devices/guition-esp32-p4-jc1060p470` | Ask for the target |
| `10inch`, `10-inch`, `10inch P4`, `10-inch P4`, `10inch V3`, `10-inch V3`, `JC8012P4A1`, `JC8012P4A1 V3` | `devices/guition-esp32-p4-jc8012p4a1-v3` | `192.168.6.103` |
| `10inch V1`, `10-inch V1`, `JC8012P4A1 V1` | `devices/guition-esp32-p4-jc8012p4a1` | Ask for the target |
| `10inch V2`, `10-inch V2`, `JC8012P4A1 V2` | `devices/guition-esp32-p4-jc8012p4a1-v2` | Ask for the target |
| `4inch P4`, `4-inch P4`, `P4-86`, `86 Panel`, `Waveshare P4-86`, `esp32-p4-86` | `devices/esp32-p4-86` | `192.168.6.104` |
| `4.3inch P4`, `4.3-inch P4`, `P4 4.3inch`, `P4 4.3-inch`, `JC4880P443` | `devices/guition-esp32-p4-jc4880p443` | `192.168.6.101` |
| `S3`, `4inch S3`, `4-inch S3`, `4848S040` | `devices/guition-esp32-s3-4848s040` | `192.168.6.105` |

Treat the 7-inch panel at `192.168.6.102`, and an ambiguous or default `7inch` request, as V2 hardware. Always flash that panel with the V2 `JC1060P470` configuration in `devices/guition-esp32-p4-jc1060p470-v2`. Use the V1 directory only when the user explicitly requests that version; ask for a different OTA target or USB when one is not supplied.

Treat the 10-inch panel at `192.168.6.103`, and an ambiguous or default `10inch` request, as V3 hardware. Always flash that panel with the V3 `JC8012P4A1` configuration in `devices/guition-esp32-p4-jc8012p4a1-v3`. Use the V1 or V2 directories only when the user explicitly requests that version; ask for a different OTA target or USB when one is not supplied.

All screens can also be flashed over USB when explicitly requested. Use the selected screen's config directory and the local serial target, normally `/dev/cu.usbmodem201301`.

If the user says only `4inch` or `4-inch`, ask whether they mean the 4-inch P4 screen or the S3 screen.

For `/flash-displays` with no extra target, or for `all`, flash in this sequence by default over OTA using the default targets above:

1. 7-inch P4 V2.
2. 10-inch P4 V3.
3. 4-inch P4 / P4-86.
4. 4.3-inch P4.
5. S3.

## YAML Selection

Use `dev.yaml` by default. If the user names another YAML file, use that file instead.

- If the user explicitly says `dev`, `dev file`, or `dev.yaml`, use `dev.yaml` instead.
- If the user gives a bare filename such as `esphome.yaml`, resolve it inside the selected display's config directory.
- If the user gives a repo-relative path such as `devices/guition-esp32-p4-jc8012p4a1/esphome.yaml`, resolve it from the repository root.
- For the 7-inch panel at `192.168.6.102`, or an ambiguous/default 7-inch request, require the selected YAML to resolve inside `devices/guition-esp32-p4-jc1060p470-v2`, which is the V2 configuration. Allow the V1 directory only when the user explicitly requests V1 and supplies a different OTA target or explicitly requests USB; otherwise stop and clarify instead of flashing it.
- For the 10-inch panel at `192.168.6.103`, or an ambiguous/default 10-inch request, require the selected YAML to resolve inside `devices/guition-esp32-p4-jc8012p4a1-v3`, which is the V3 configuration. Allow the V1 or V2 directories only when the user explicitly requests that version and supplies a different OTA target or explicitly requests USB; otherwise stop and clarify instead of flashing it.
- Only use YAML files inside this repository. If the selected file does not exist, ask for the correct file instead of guessing.
- Use the required local secrets file described below. Do not create secret values or print, modify, copy, or commit the file contents.

## Secrets File

All development YAML files require a local `secrets.yaml` containing `wifi_ssid` and `wifi_password`. Always use this existing local file as the only secrets source:

```text
${ESPCONTROL_SECRETS:-<main-checkout>/secrets.yaml}
```

Resolve the active and main checkout paths dynamically before using secrets or
device configs. The `ESPCONTROL_SECRETS` override is optional:

```bash
REPO_ROOT="$(git rev-parse --show-toplevel)"
COMMON_GIT_DIR="$(git -C "$REPO_ROOT" rev-parse --path-format=absolute --git-common-dir)"
MAIN_CHECKOUT="$(dirname "$COMMON_GIT_DIR")"
SECRETS_SOURCE="${ESPCONTROL_SECRETS:-$MAIN_CHECKOUT/secrets.yaml}"
```

Before flashing each selected display:

1. Confirm the source exists with `test -f "$SECRETS_SOURCE"`. If it is missing, stop and tell the user; do not create or guess secret values.
2. Run the following from the selected display's config directory. This creates the ignored local symlink only when `secrets.yaml` is absent, and verifies that any existing file or symlink resolves to the required source:

   ```bash
   if [ ! -e secrets.yaml ] && [ ! -L secrets.yaml ]; then
     ln -s "$SECRETS_SOURCE" secrets.yaml
   fi
   test "$(realpath secrets.yaml)" = "$(realpath "$SECRETS_SOURCE")"
   ```

3. If verification fails, stop and explain that the selected display already has a different `secrets.yaml`; do not replace it without the user's approval.

Never display the secrets file, include its contents in command output, or add it to Git. The per-device `.gitignore` files exclude `secrets.yaml`.

## Workflow

1. Confirm the repository state:
   - Run `git status --short --branch`.
   - Flash the currently selected worktree and branch. Do not switch branches or pull another branch as part of flashing.
   - If the worktree is dirty, do not revert or commit unrelated changes. Tell the user the flash will use the current local checkout as-is.
2. Resolve the requested display names from the device map. If the user invoked `/flash-displays` without naming a display, resolve it as `all`. If the request is ambiguous, ask one short clarification.
3. Resolve the YAML file from the user's request. If none is provided, use `dev.yaml`.
4. Prepare and verify the required local `secrets.yaml` symlink in each selected display's config directory by following the Secrets File section. Do not print or commit the secrets.
5. Resolve OTA targets from an explicit user-supplied target first, then from the device's default hard-coded target. If a needed OTA target is missing, ask for that target or ask whether to use USB.
6. If the user says `USB`, `over USB`, `use USB`, `local`, or similar, use USB for the selected display instead of OTA.
   - For a single display, use that display's config directory and the USB target.
   - For `all over USB`, flash the displays in the normal all-display sequence, but ask the user to connect the correct display before each USB flash if the connected device is not clearly identifiable.
7. For OTA targets, check reachability first with `ping -c 2 -W 1000 <target>`.
8. For USB flashing:
   - List ports with `ls -1 /dev/cu.*`.
   - Prefer `/dev/cu.usbmodem201301` when present.
   - If that port is missing and exactly one obvious `/dev/cu.usbmodem*` port exists, use it.
   - If no clear USB modem port exists, ask the user to connect the display or choose the port.
9. Flash each selected display with the command below, running displays sequentially. Do not run multiple flashes in parallel.
10. After each OTA flash, ping the target again. A first ping may fail during reboot; retry once after a short delay before reporting a problem.
11. Do not commit or push for flashing alone. Commit/push only if this skill or other source files were intentionally changed as part of the user request.

## Commands

Use the project wrapper so a flash always uses the ESPHome version pinned by
`.github/esphome.env`. It stops before compiling if the installed executable is
older or newer than the release version. The wrapper also builds from the local
repository checkout. It also rejects a `run` or `upload` to the known 7-inch V2
target `192.168.6.102` unless the YAML is inside
`devices/guition-esp32-p4-jc1060p470-v2`:

```bash
python3 scripts/local_esphome.py <yaml-file> run --device <target> --no-logs
```

Resolve the active repository root with `git rev-parse --show-toplevel`, then
run from each appropriate config directory under that root. These examples
work from any linked worktree:

```bash
# 7-inch P4 V2 over OTA
cd "$REPO_ROOT/devices/guition-esp32-p4-jc1060p470-v2"
python3 ../../scripts/local_esphome.py dev.yaml run --device 192.168.6.102 --no-logs

# 7-inch P4 V2 over USB, only when explicitly requested
cd "$REPO_ROOT/devices/guition-esp32-p4-jc1060p470-v2"
python3 ../../scripts/local_esphome.py dev.yaml run --device /dev/cu.usbmodem201301 --no-logs

# 10-inch P4 V3 over OTA
cd "$REPO_ROOT/devices/guition-esp32-p4-jc8012p4a1-v3"
python3 ../../scripts/local_esphome.py dev.yaml run --device 192.168.6.103 --no-logs

# 10-inch P4 V3 over USB, only when explicitly requested
cd "$REPO_ROOT/devices/guition-esp32-p4-jc8012p4a1-v3"
python3 ../../scripts/local_esphome.py dev.yaml run --device /dev/cu.usbmodem201301 --no-logs

# 4-inch P4 / P4-86 over OTA
cd "$REPO_ROOT/devices/esp32-p4-86"
python3 ../../scripts/local_esphome.py dev.yaml run --device 192.168.6.104 --no-logs

# 4-inch P4 / P4-86 over USB, only when explicitly requested
cd "$REPO_ROOT/devices/esp32-p4-86"
python3 ../../scripts/local_esphome.py dev.yaml run --device /dev/cu.usbmodem201301 --no-logs

# 4.3-inch P4 over OTA
cd "$REPO_ROOT/devices/guition-esp32-p4-jc4880p443"
python3 ../../scripts/local_esphome.py dev.yaml run --device 192.168.6.101 --no-logs

# 4.3-inch P4 over USB, only when explicitly requested
cd "$REPO_ROOT/devices/guition-esp32-p4-jc4880p443"
python3 ../../scripts/local_esphome.py dev.yaml run --device /dev/cu.usbmodem201301 --no-logs

# S3 over OTA
cd "$REPO_ROOT/devices/guition-esp32-s3-4848s040"
python3 ../../scripts/local_esphome.py dev.yaml run --device 192.168.6.105 --no-logs

# S3 over USB, only when explicitly requested
cd "$REPO_ROOT/devices/guition-esp32-s3-4848s040"
python3 ../../scripts/local_esphome.py dev.yaml run --device /dev/cu.usbmodem201301 --no-logs

```

## Reporting

Keep user updates concise:

- Say which display is currently compiling/uploading.
- Mention known ESPHome warnings only if they affect the result; framework, platform, GPIO19/GPIO20, and MIPI narrowing warnings are normally non-blocking.
- Final response: list each requested display as flashed successfully, or clearly identify the display that failed and the blocking symptom.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall