adminandClaude Opus 5
266684bed7
Rebuilt the guide as something usable on site rather than a document to read at a desk: strict order of operations, DO / VERIFY / IF NOT blocks per step, pass-fail gates in a table, a printable sign-off sheet, and troubleshooting keyed by symptom rather than by subsystem. Includes real screenshots of the add-on's own Web UI - captured by running it against stub data - showing the healthy state and the misconfigured one side by side, because telling those apart at a glance is the single most useful skill on site. Plus the ESPHome step from a live builder. The text lives only in docs/build_guide.py, which renders the HTML and drives headless Chrome to produce the PDF. One source: a Markdown copy would inevitably drift from the PDF someone is holding in a cellar. Pagination is enforced, not hoped for. Each section must render under the A4 printable height (1039 px at 96 dpi) or Chrome silently spills it onto a second page and the page numbers stop matching the step numbers. Measured every section rather than eyeballing it: the Web UI reference page was 1170 px and is now 1017 px, and the PDF comes out at exactly one page per section. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016NckgXecasQb2eSsPYNSW6
42 lines
1.6 KiB
Markdown
42 lines
1.6 KiB
Markdown
# Field Guide
|
|
|
|
The guide technicians carry is the PDF:
|
|
|
|
**`docs/GoodWe-RS485-Field-Guide.pdf`** — 10 pages, A4, print it double-sided.
|
|
|
|
It covers, in the order the work is done: pre-visit checks, hardware, firmware,
|
|
add-on install and configuration, how to read the Web UI, the six commissioning
|
|
gates, the e-stop (and the statement a site without one must sign), proving a
|
|
maintenance cycle, handover with a sign-off sheet, and troubleshooting.
|
|
|
|
## Editing it
|
|
|
|
The text lives in `docs/build_guide.py` — deliberately one source, so a Markdown
|
|
copy cannot drift from the PDF someone is holding in a cellar.
|
|
|
|
```bash
|
|
python3 docs/build_guide.py # regenerates field-guide.html and the PDF
|
|
```
|
|
|
|
Requires Chrome or Chromium (used headless for print-to-PDF). Screenshots live
|
|
in `docs/img/` and are base64-embedded, so `field-guide.html` is standalone.
|
|
|
|
⚠️ **Every section must stay under the A4 printable height** (1039 px at 96 dpi
|
|
with the configured margins). Chrome silently spills an over-long section onto a
|
|
second page, and the pagination stops matching the step numbers. After editing,
|
|
open `field-guide.html` and check:
|
|
|
|
```js
|
|
document.querySelectorAll('.page').forEach(el =>
|
|
console.log(el.getBoundingClientRect().height)) // each must be < 1039
|
|
```
|
|
|
|
The PDF should always come out at exactly **one page per section**.
|
|
|
|
## Regenerating the screenshots
|
|
|
|
`docs/img/ui-running.png` and `ui-notready.png` are real captures of the add-on's
|
|
own Web UI, taken by running it against stub data. If the UI changes, retake them
|
|
— a field guide showing a screen that no longer exists is worse than one with no
|
|
screenshots at all.
|