trmnl-paper-screen

trmnl-paper-screen

Overview

Responsible for pushing existing markup to LaraPaper via POST /api/screens . After the actual send succeeds, retrieve the current rendered image (path see references/api-screens.md), review whether the display is normal and whether it is suitable for e-paper; if there are problems, pass the problem list back to trmnl-paper-blade for the next round of fixes.

Workflow

1. Confirm whether the markup is ready

   • No → first use trmnl-paper-blade to generate, then come back here
   • Yes → continue

2. Collect parameters(all four are required):

   Parameter	Description	Example
   base URL	LaraPaper instance address, must include scheme	https://larapaper.example.com
   mac_address	Device MAC, the server will automatically convert it to uppercase	AA:BB:CC:DD:EE:FF
   device API key	Device-level API key (not APP_KEY）	abc123...
   markup	The Blade / HTML content to push	<x-trmnl::screen>...</x-trmnl::screen>

1. Default dry-run: preview the complete request body (credentials redacted), only actually POST when the user explicitly requests it; if you need to view the raw credentials, only dry-run can add --show-secrets。
2. Prefer using the script: run from the repository root python3 skills/trmnl-paper-screen/scripts/push_screen.py ..., to avoid hand-written JSON escaping errors; if the current directory is already inside the skill, you can use python3 scripts/push_screen.py ...。
3. Read the rendering result after the actual send: use --send --current-screen, or call the current screen interface after the send succeeds (path see references/api-screens.md）。
4. Download the image when visual review is needed: use --download-image <path> to download image_url locally, then check whether the display is normal and aesthetically pleasing;--download-image will implicitly trigger current_screen read.
5. If there are problems, follow the fix loop: organize the problem list → hand back to trmnl-paper-blade to modify the markup → validate_markup.py validate → re-push and re-check.

Post-push review loop

Only enter this loop when the user explicitly requestsactual send; dry-run does not do image review.

1. POST /api/screens push markup
2. Retrieve the current rendered image image_url(path see references/api-screens.md）
3. Download the image and do manual/multimodal review (review criteria see references/review-checklist.md）
4. Return to trmnl-paper-blade to fix according to the problem type
5. Re-validate, push, and re-check

By default, fix the 1-3 most obvious problems first, to avoid changing too much at once and causing regressions. If obvious trade-offs still remain after two rounds, then explain to the user and confirm the direction.

If the target instance does asynchronous rendering or extra caching, the retrieved image may briefly be the previous version; in this case, just wait a moment and retry, and do not mistakenly judge the new draft as invalid.

Rules

• Do not forge base URL、mac_address、device API key
• Only use POST /api/screens
• The path to retrieve the rendering result is see references/api-screens.md
• The request header is fixed as id + access-token
• body is fixed as {"image":{"content":"...","file_name":"..."}}
• file_name optional, default screen.blade.markup
• By default, display the markup and the request body separately
• Only actually send when the user explicitly requests it
• POST /api/screens does not return image_url；image_url comes from the subsequent current screen interface
• Only when the user explicitly requests actual send, execute the "push → fetch image → review → optimize" loop
• APP_KEY is not the credential for this skill
• LaraPaper will perform content on Blade::render(), so you can directly send <x-trmnl::...> syntax, provided that the target instance has installed trmnl-blade

Image review standards

See references/review-checklist.md. When reviewing, first check "normality", then "aesthetics", and finally refer to "common correction actions" to return to trmnl-paper-blade for correction.

Error handling

HTTP status code	Meaning	Handling method
200	Success, returns {"message":"success"}	—
404	MAC or API key does not match	Check whether the MAC casing and API key are correct
422	Request body validation failed (missing image.content）	Check whether the JSON structure conforms to the specification
500	Server-side rendering failed (Blade syntax error, etc.)	Check whether the markup is valid
Connection failed	base URL unreachable	Check the URL scheme and network
Failed to retrieve rendered image	Unable to read the current screen	Check access-token, instance reachability, and whether the send was actually completed
image_url missing or image download failed	Unable to perform post-push review	First confirm that the current LaraPaper screen has been generated, then retry

Pre-send checks

• base URL with scheme (http:// or https://, by default prefer https://）
• mac_address and device API key come from user input; do not forge them yourself
• First perform a dry-run to verify whether the endpoint, headers, and body structure are correct
• In the dry-run output, credentials remain masked; only when the user explicitly requests it, --send
• If the user requests an actual send, after sending retrieve image_url again for a visual recheck (for the image retrieval path, see references/api-screens.md）
• If it fails, return the HTTP status code or script error, then give the minimal fix suggestion

and trmnl-paper-blade boundaries

	trmnl-paper-blade	trmnl-paper-screen
Responsibility	Generate markup	Push markup
Input	Content description / data	Completed markup
Output	Blade template code	API request or execution result
Validation	Component syntax, structural rules	Request format, credentials

Pipeline connection

trmnl-paper-blade The markup generated by

• File：--markup-file <path>(recommended, to avoid escaping issues)
• Standard input：--markup-stdin, suitable for pipeline chaining

Handoff format

The following YAML is the authoritative handoff format shared by trmnl-paper-screen and trmnl-paper-blade .

If issues need to be sent back to trmnl-paper-bladeafter pushing, use the following minimal field format for each issue:

- issue: 文案在标题栏溢出
  location: x-trmnl::title-bar title 属性
  suggested_fix: 缩短标题文案，或加 data-clamp="1"

issue describes the issue symptoms,location locates the component or attribute,suggested_fix gives the minimal modification direction.

Reference materials

• Verified request format and image retrieval steps: read references/api-screens.md
• Post-push visual review standards: read references/review-checklist.md

Available scripts

• scripts/push_screen.py — construct or send a LaraPaper screen update request (dry-run by default), and after sending can retrieve current_screen and download the rendered image

Output conventions

By default, output in the following order:

1. endpoint：POST /api/screens
2. Request headers (credentials redacted)
3. Request body (markup displayed separately)
4. If the user requests actual sending, then provide the sending result
5. If the user requests a post-send review, then provide image_url, review conclusions, and correction suggestions