From 2be153a103d5c2c994dbeb8a28af961922092f03 Mon Sep 17 00:00:00 2001 From: Matt Edholm Date: Sat, 9 May 2026 11:06:42 -0400 Subject: [PATCH] feat(help): public /help setup-and-troubleshooting page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Anchor for the manual QR baked into the firmware Step 1/2 screen (pictureframe-firmware e089911). One self-contained Twig page, PUBLIC_ACCESS in security.yaml, /help excluded from the SPA catch-all regex so it doesn't get swallowed. Scope is deliberately tight: first-time setup screen by screen, the captive-portal-didn't-open fallback (manual nav to 192.168.4.1 plus the iOS lock-screen-scan caveat), the connection-failed retry path, how to wipe the frame for a new account, photo-not-appearing diagnosis, and what the yellow/red status borders mean. Anything beyond that goes in the SPA proper, not here. No frontend rebuild needed — pure server-rendered Twig + inline CSS. Co-Authored-By: Claude Opus 4.7 (1M context) --- config/packages/security.yaml | 1 + src/Controller/HelpController.php | 20 ++++ src/Controller/SpaController.php | 2 +- templates/help/index.html.twig | 178 ++++++++++++++++++++++++++++++ 4 files changed, 200 insertions(+), 1 deletion(-) create mode 100644 src/Controller/HelpController.php create mode 100644 templates/help/index.html.twig diff --git a/config/packages/security.yaml b/config/packages/security.yaml index 767e988..2befa5f 100644 --- a/config/packages/security.yaml +++ b/config/packages/security.yaml @@ -36,6 +36,7 @@ security: - { path: ^/register, roles: PUBLIC_ACCESS } - { path: ^/setup, roles: PUBLIC_ACCESS } - { path: ^/token, roles: PUBLIC_ACCESS } + - { path: ^/help, roles: PUBLIC_ACCESS } - { path: ^/api/device, roles: PUBLIC_ACCESS } - { path: ^/, roles: ROLE_USER } diff --git a/src/Controller/HelpController.php b/src/Controller/HelpController.php new file mode 100644 index 0000000..d726893 --- /dev/null +++ b/src/Controller/HelpController.php @@ -0,0 +1,20 @@ +render('help/index.html.twig'); + } +} diff --git a/src/Controller/SpaController.php b/src/Controller/SpaController.php index 3bcc0ed..e7104a7 100644 --- a/src/Controller/SpaController.php +++ b/src/Controller/SpaController.php @@ -24,7 +24,7 @@ class SpaController extends AbstractController #[Route( '/{path}', name: 'spa', - requirements: ['path' => '^(?!api|setup|token|login|register|logout|_profiler|_wdt).*'], + requirements: ['path' => '^(?!api|setup|token|help|login|register|logout|_profiler|_wdt).*'], defaults: ['path' => ''], )] public function index(): Response diff --git a/templates/help/index.html.twig b/templates/help/index.html.twig new file mode 100644 index 0000000..3c0d360 --- /dev/null +++ b/templates/help/index.html.twig @@ -0,0 +1,178 @@ + + + + + + Setup help — pictureFrame + + + +
+ +

pictureFrame setup help

+

Trouble joining your frame to the network, or stuck on a screen? Start here.

+ + + +

First-time setup, screen by screen

+ +

Step 1 of 2   Yellow screen, two QR codes

+

This is the WiFi-join screen. Your frame is broadcasting its own temporary network called PictureFrame-XXXX (where XXXX is the last four characters of its hardware ID).

+
    +
  1. Unlock your phone first. iOS will not open the connection page automatically if you scan from the lock screen.
    2. +
  2. Scan the large QR on the right with your phone's camera. Tap "Join PictureFrame-XXXX" when prompted.
    3. +
  3. Your phone should pop up a "Connect to WiFi" page where you enter your home network's name and password.
    4. +
  4. Tap Connect. The frame's screen will refresh (about 20 seconds — be patient, e-ink is slow).
    5. +
+
+ If the connect page didn't pop up: see this section below — there's a manual fallback URL. +
+ +

Step 2 of 2   Green screen, single QR code

+

The frame is now on your home WiFi. This QR points at the website where you'll create an account (or sign in) and link the frame to it.

+
    +
  1. Scan the QR. Your browser opens to a setup page on pictureframe.edholm.me.
    2. +
  2. Create an account or sign in. The frame is linked to whichever account claims it first.
    3. +
  3. Upload your first photo. Within a minute or two the frame will pull it down and display it.
    4. +
+ +

The "Connect to WiFi" page didn't open on my phone

+

This is the most common setup issue, and it's an iOS quirk more than a frame problem. Here's the fix order:

+
    +
  1. Make sure your phone is unlocked before scanning. If you scanned with the lock-screen camera, iOS joins the network but won't open the captive portal page automatically — even after unlocking.
    2. +
  2. Open the "Connect to WiFi" page manually. With your phone connected to the PictureFrame-XXXX network, open Safari (or any browser) and go to http://192.168.4.1. The same form that should have popped up will load there.
    3. +
  3. Forget the network and try again. In your phone's WiFi settings, tap the i next to PictureFrame-XXXX and tap "Forget This Network". Then unlock your phone, scan the yellow Step 1 QR again, and accept the join prompt.
    4. +
  4. Try a different phone or laptop. Any device that can join WiFi and open a browser will work.
    5. +
+ +

The frame says "Connection Failed — try again"

+

You'll see this screen (red header instead of yellow) when the WiFi password you entered didn't work. The QR is the same — your phone might still have the PictureFrame-XXXX network saved.

+
    +
  1. Reconnect your phone to PictureFrame-XXXX (it may have already auto-rejoined).
    2. +
  2. If the connect page doesn't open, navigate to http://192.168.4.1 manually.
    3. +
  3. Re-enter your home network credentials carefully. Double-check the password — the most common cause is a typo or a missed capital letter.
    4. +
+
+ Note: the frame doesn't display network names — when you enter the WiFi name, the frame can't tell you whether the network is reachable until it tries to connect. If you've fat-fingered the SSID name, the failure looks the same as a wrong password. +
+ +

Start over (give the frame to a new account, or wipe it)

+

If you need to re-link the frame to a different account — for example, you're giving it to someone else, or you want to clear the old WiFi credentials — you can reset it.

+

Hold the small button on the back of the frame until the screen starts to flash. Don't worry about timing — just keep holding until you see the display refresh. The frame will wipe its saved network credentials and the photos it had cached, and go back to the yellow Step 1 screen.

+

The new account that scans the green Step 2 QR will be the one the frame is linked to going forward.

+ +

Photos aren't appearing, or aren't changing

+ +

I just uploaded a photo, when will it show up?

+

Frames pull from the server roughly once per configured wake interval (often hourly or every few hours, depending on what you set). If you want the new photo to appear right now, the easiest thing is to unplug the frame and plug it back in — a power cycle forces an immediate sync regardless of the schedule.

+ +

The same photo has been showing for a long time

+

Open pictureframe.edholm.me on your phone, sign in, and check:

+
    +
  • The frame is shown as recently active (last sync timestamp).
    • +
  • Wake times are set to a reasonable schedule — if you set a single daily wake at 9am, that's the only time it will check.
    • +
  • You actually have multiple photos uploaded — a frame with one photo will keep showing that one photo.
    • +
+

If the frame hasn't checked in for more than a day, it's probably not on WiFi — see the next section.

+ +

Coloured border around the photo

+

If the frame can show a photo but something is wrong, it draws a thin coloured border around the image so you can tell at a glance:

+
    +
  • Yellow border   The frame is on WiFi but couldn't reach the server, or the server didn't have a fresh photo. Usually clears itself on the next wake.
    • +
  • Red border   The frame couldn't connect to WiFi at all. Check the router is up. If the network name or password has changed, you'll need to reset the frame (see "Start over" above) and re-enter the new credentials.
    • +
+ + + +
+ +