[{"id":1,"title":"Widgets","pageTitle":"Widgets","text":"This page is a reference for every widget that ships with the system, and a guide to setting each one up. When you finish, you know what each widget shows, what it needs, and how to turn it on for a frame. A widget is one thing a frame can show: the clock, the weather, your calendar, photos, a Home Assistant dashboard, or greeting cards. You choose widgets per frame in the admin. Widget Shows Needs On when a frame is claimed Clock The time and date. Nothing. Yes Weather Current conditions and a forecast. US locations only. A location in Library . The fetcher. Yes, if a location exists Calendar Today's events, and a week view. A calendar in Library . The fetcher. Yes, with no calendars ticked Photos A daily set of photos, also the screensaver. A Nextcloud album or a library album. No Home Assistant Your Home Assistant dashboard. The address of Home Assistant. No Cards Greeting cards from family, as stamps over the photos. Covers and stamps, and a sender link. No","url":"https://calevans.com/picture-frame/docs/widgets/index.html","tags":"","category":""},{"id":2,"title":"Turn widgets on and off","pageTitle":"Widgets","text":"Select Frames , then the frame. Open Widgets in the rail on the left. Switch each widget On or Off . Select Save . Once a widget is on and has settings, it gets its own section in the rail, named after the widget. Settings save from that section, with its own Save button. If a widget is off, its section says \"Weather is off\" (or the widget's name) and links back to Widgets . The widgets list shows the enabled widgets first, in the order you switched them on, then the rest.","url":"https://calevans.com/picture-frame/docs/widgets/index.html#turn-widgets-on-and-off","tags":"","category":""},{"id":3,"title":"Where widgets appear on the frame","pageTitle":"Widgets","text":"There is no drag-to-reorder. The home screen has fixed cells, and each widget has its own: Clock and Weather sit in the top row. Calendar fills the lower row. Photos and Cards sit beside the calendar. Most widgets also add a page to the frame's navigation rail. A touch on the screen while the photos show slides the rail in from the left. It has a button for each page and a Dim button: Widget Page on the frame Weather Weather Calendar Week , shown once a ticked calendar has been fetched Photos Pictures , shown only when there are photos Home Assistant Home Assistant , shown only when an address is saved Cards Mailbox , shown when there are cards Changes you save reach the frame within a minute or two. The frame polls the server about every 20 seconds.","url":"https://calevans.com/picture-frame/docs/widgets/index.html#where-widgets-appear-on-the-frame","tags":"","category":""},{"id":4,"title":"Clock","pageTitle":"Widgets","text":"Shows the time and date in the frame's time zone. It has no settings and is on by default. The time zone is a property of the frame, not of the widget. New frames use America/New_York . Change it in the frame's Schedule section. See Use the admin: Schedule and bedtime .","url":"https://calevans.com/picture-frame/docs/widgets/index.html#clock","tags":"","category":""},{"id":5,"title":"Weather","pageTitle":"Widgets","text":"Shows current conditions, the next 24 hours, and the next 7 days from the US National Weather Service ( api.weather.gov ). Warning Weather works for US locations only . The National Weather Service has no data elsewhere.","url":"https://calevans.com/picture-frame/docs/widgets/index.html#weather","tags":"","category":""},{"id":6,"title":"Set it up","pageTitle":"Widgets","text":"In the admin, select Library , then Add location under Locations . Enter a Name , a Latitude and a Longitude . Leave Stations empty at first. Select Add location . Open the frame, then Widgets , switch Weather on, and select Save . Open the Weather section and pick the Location . If you have no location yet, select New location there. Select Save . By default the server picks the nearest three observation stations. Fill Stations with up to five comma-separated four-character station IDs (for example KJFK ) only if you want specific ones. When you claim a frame, Weather turns itself on and uses your first location (the one with ID 1), if that location exists. Otherwise Weather stays off until you set it up.","url":"https://calevans.com/picture-frame/docs/widgets/index.html#set-it-up","tags":"","category":""},{"id":7,"title":"How it refreshes","pageTitle":"Widgets","text":"The fetcher downloads from the National Weather Service. It needs the cron job from Install the frame server . Data Refreshed about every Current conditions 10 minutes Hourly and daily forecasts 30 minutes The grid point for a location 24 hours, or sooner if you move the location The admin refuses to delete a location that a frame's Weather widget uses.","url":"https://calevans.com/picture-frame/docs/widgets/index.html#how-it-refreshes","tags":"","category":""},{"id":8,"title":"Calendar","pageTitle":"Widgets","text":"Shows today's events on the home screen, and a week view on its Week page. It reads calendars shared as public iCal links, such as Nextcloud.","url":"https://calevans.com/picture-frame/docs/widgets/index.html#calendar","tags":"","category":""},{"id":9,"title":"Set it up","pageTitle":"Widgets","text":"Add the calendar's host to calendar_hosts in config.php . The server downloads only from listed hosts, over HTTPS, with no port and no user name in the address. In the admin, select Library , then Add calendar under Calendars . Enter a Name and the calendar's Share URL . Add a Color like #6cb6ff if you want a colored dot. Select Add calendar . Open the frame, then Widgets , switch Calendar on, and select Save . Open the Calendar section, tick the calendars to show, and select Save . A Nextcloud share link in either form works: https://cloud.example.org/apps/calendar/p/ https://cloud.example.org/remote.php/dav/public-calendars/ The server turns either form into Nextcloud's export address. Any other address is fetched as given, so it must return an iCal file. A calendar with nothing ticked shows no events, and the Week page does not appear. There is no \"show all\" shortcut. The Library table shows each calendar's status: OK , Error with the message from the last attempt, or Not fetched if the fetcher has not run yet. A calendar's pencil button renames it and sets its color. Calendars refresh about every 15 minutes.","url":"https://calevans.com/picture-frame/docs/widgets/index.html#set-it-up-1","tags":"","category":""},{"id":10,"title":"Photos","pageTitle":"Widgets","text":"Shows a daily set of photos on the screensaver and on the Pictures page. It has two sources, a Nextcloud public album and a photo library on your own server, and the library adds family drop links. Settings, in the frame's Photos section: Setting What it does Photos come from Nextcloud link or Photo library . Album link For Nextcloud: the public album link. Album For the library: the album to show. Show each photo for 5 to 3600 seconds. Default 30. New photos daily at The time of day the frame picks its next set. All of it is explained in Photos .","url":"https://calevans.com/picture-frame/docs/widgets/index.html#photos","tags":"","category":""},{"id":11,"title":"Home Assistant","pageTitle":"Widgets","text":"Opens a Home Assistant dashboard on the frame. You set it per frame, and the address and token are stored on your server, not on the page you see.","url":"https://calevans.com/picture-frame/docs/widgets/index.html#home-assistant","tags":"","category":""},{"id":12,"title":"What you need","pageTitle":"Widgets","text":"A running Home Assistant that the frame can reach on your network, or over HTTPS. Optional: the Kiosk Mode add-on from HACS. The URL the frame opens ends in ?kiosk , which hides the Home Assistant header and sidebar when Kiosk Mode is installed. A long-lived access token, or Home Assistant's trusted networks. See Sign-in options .","url":"https://calevans.com/picture-frame/docs/widgets/index.html#what-you-need","tags":"","category":""},{"id":13,"title":"Set it up","pageTitle":"Widgets","text":"In Home Assistant, create a dedicated user for the frame that is not an administrator. Sign in as that user. Open the profile (bottom of the sidebar), then Security , and under Long-lived access tokens create a token. Copy it. Home Assistant shows it once. In the admin, open the frame, then Widgets , switch Home Assistant on, and select Save . Open the Home Assistant section. Enter the Home Assistant address : the address only, no path, for example http://homeassistant.local:8123 . Paste the token into Access token . The admin never shows it again. It shows Token set , and you can replace or remove it. Select Save . Choose the Dashboard once the frame has reported its dashboards. Until then the admin says \"Waiting for the frame to report its dashboards.\" The default is Default (lovelace) . Changing the address removes the saved token, so enter the token again. A token never follows a new host.","url":"https://calevans.com/picture-frame/docs/widgets/index.html#set-it-up-2","tags":"","category":""},{"id":14,"title":"Address rules","pageTitle":"Widgets","text":"Rule Detail Form scheme://host or scheme://host:port . No path, no query, no user name or password. At most 300 characters. https Allowed for any host. http Allowed only for private network addresses ( 10.x.x.x , 172.16.x.x to 172.31.x.x , 192.168.x.x ) and names ending in .local . The admin shows a warning that an http address sends the token and everything else unencrypted on your network. Not allowed localhost , loopback and link-local addresses, IPv6 literals.","url":"https://calevans.com/picture-frame/docs/widgets/index.html#address-rules","tags":"","category":""},{"id":15,"title":"Sign-in options","pageTitle":"Widgets","text":"A long-lived access token is the default. The token is sent only to the frame's own app code, through the frame's authenticated connection. It is never part of the dashboard page and never shown again in the admin. It is stored in the server's database. Use a dedicated non-admin Home Assistant user, so a stolen frame can do no more than that user can. Trusted networks are the alternative. Leave Access token empty, and let Home Assistant trust the frame's address. Without a token, the frame relies on Home Assistant's trusted networks. Not verified The trusted-networks setup was not tested for this page. It lives in Home Assistant's configuration.yaml under homeassistant: and auth_providers: . Follow Home Assistant's own documentation for the trusted_networks provider, give the frame a fixed address with a DHCP reservation, and choose a non-admin user for it. Both options keep the frame limited to one place: the kiosk allows navigation only to the Home Assistant address you saved.","url":"https://calevans.com/picture-frame/docs/widgets/index.html#sign-in-options","tags":"","category":""},{"id":16,"title":"Cards","pageTitle":"Widgets","text":"Cards are greeting cards that people send to a frame from their phones. A relative opens a private link, picks a cover, writes a message, and signs it with a finger or by typing a name. The card arrives on the frame as a postage stamp over the photos. Nobody needs an account.","url":"https://calevans.com/picture-frame/docs/widgets/index.html#cards","tags":"","category":""},{"id":17,"title":"Set it up","pageTitle":"Widgets","text":"Open Card designs and upload covers and stamps. See Card designs . Open the frame, then Widgets , switch Cards on, and select Save . Open the Cards section. Under Sender links , select New sender link . Enter the sender's Name , which is printed on every card their link sends, then select Create link . Select Copy link and send it to that person. It looks like https://frames.example.com/frames/notes/<43 characters> . Warning The link is shown once . The server keeps only a hash of it. If you lose it, make a new one with New link .","url":"https://calevans.com/picture-frame/docs/widgets/index.html#set-it-up-3","tags":"","category":""},{"id":18,"title":"What the relative sees","pageTitle":"Widgets","text":"Opening the link shows a page for sending a card to the frame's recipient (\"Cards for Grandma\"). They: Pick a cover. The covers are grouped by category. Write a message of up to 400 characters and 8 lines. Sign it, by drawing with a finger or by typing a name of up to 40 characters. Select Send card . There is no approval step. A card goes straight to the frame, and the sender link is your control over who can send. This is different from drop link photos , which wait for your approval.","url":"https://calevans.com/picture-frame/docs/widgets/index.html#what-the-relative-sees","tags":"","category":""},{"id":19,"title":"What shows on the frame","pageTitle":"Widgets","text":"A new card appears as a stamp on the photo screensaver. Up to five stamps show, plus a \"+N more\" stamp. Tap a stamp to open the card. Without the Photos widget there is no screensaver for the stamps. Cards then appear only in the Mailbox . Opened cards move to the Mailbox , where they stay for the number of days you set. Cards nobody has opened never expire. The home screen has a Mailbox cell that shows how many new cards there are.","url":"https://calevans.com/picture-frame/docs/widgets/index.html#what-shows-on-the-frame","tags":"","category":""},{"id":20,"title":"Settings per frame","pageTitle":"Widgets","text":"In the frame's Cards section, under Settings : Setting What it does Name on the sender page Senders see \"Cards for Grandma\". Up to 24 characters. Leave empty to use the frame's name. Keep opened cards for 1 to 30 days. Default 30. Categories offered The cover categories senders can choose from: Thinking of you, Birthday, Thank you, Funny, Sweet, Get well, Holidays. Offer at least one.","url":"https://calevans.com/picture-frame/docs/widgets/index.html#settings-per-frame","tags":"","category":""},{"id":21,"title":"Sender links","pageTitle":"Widgets","text":"Each sender gets their own link. The Sender links table shows each one's name, whether it is active or revoked, when it was created, when it was last used, and how many cards it sent. Action What it does Rename Changes the name on future cards. Cards already sent keep the old name. New link Replaces the link. The old link stops working at once. Asks for your password. Revoke Stops the link. Cards already sent stay on the frame. Asks for your password. Restore Un-revokes the link and makes a new link. The old one stays dead. Delete unopened Deletes every card from that sender that has not been opened yet. Opened cards stay. Asks for your password.","url":"https://calevans.com/picture-frame/docs/widgets/index.html#sender-links","tags":"","category":""},{"id":22,"title":"Cards sent","pageTitle":"Widgets","text":"Cards sent lists the cards for this frame. Filter by status ( All , Not opened , Opened ) or by sender. You can delete a card that has not been opened. Show older loads more.","url":"https://calevans.com/picture-frame/docs/widgets/index.html#cards-sent","tags":"","category":""},{"id":23,"title":"Privacy","pageTitle":"Widgets","text":"Messages are private from the admin. You see who sent a card, when, and whether it was opened. You do not see the message, and nobody does in the admin. The message is readable on the frame and by the sender through their own link. The database holds the message in plain text. Anyone who can read var/frames.db can read the cards. Protect the file and its backups. Links are secrets. A sender link is 43 random characters. The server stores only its hash, and shows the link once. Revoking works at once. The old link stops working the moment you revoke or replace it.","url":"https://calevans.com/picture-frame/docs/widgets/index.html#privacy","tags":"","category":""},{"id":24,"title":"Limits","pageTitle":"Widgets","text":"Limit Value Cards one link can send 6 per hour and 20 per day Cards from one phone's address 30 per day Unopened cards from one sender 10 Unopened cards on one frame 30. After that, senders see that the mailbox is full. Message 400 characters, 8 lines Signature text 40 characters","url":"https://calevans.com/picture-frame/docs/widgets/index.html#limits","tags":"","category":""},{"id":25,"title":"Card designs","pageTitle":"Widgets","text":"Card designs in the top bar holds the art for every frame's cards. Covers are the card fronts. Select Upload covers . Choose images. JPEG, PNG or WebP, up to 4 MB, 400 to 4096 pixels on each side. Choose a Category for each cover. Select the add button. It shows the count, for example Add 3 covers . The server crops each cover to 16:10 and shrinks it to 1280x800. Upload it as it is. A cover already in the library is not added again. In the covers grid you can filter by category and by On and Off . Select covers to turn them On or Off , to Set category , or to Delete . Open one for a larger view and its details. Stamps are the small pictures on each card. Each card gets a random stamp from those that are on. Select Upload stamps . Choose images. JPEG, PNG or WebP, up to 4 MB, 100 to 4096 pixels on each side. Select the add button. It shows the count, for example Add 5 stamps . The server crops stamps and shrinks them to 288x366. If no stamp is on, new cards get a plain stamp. A cover or stamp that a sent card uses cannot be deleted. The admin offers to turn it off instead. Back up var/notes/ together with var/frames.db . See Back up the server .","url":"https://calevans.com/picture-frame/docs/widgets/index.html#card-designs","tags":"","category":""},{"id":26,"title":"How widgets are built","pageTitle":"Widgets","text":"Each widget is a folder under web/app/widgets/ with its own settings, data, fetch code, frame code and admin code. Add or remove a folder and the rest of the system does not change. If you remove a widget's folder, frames that had it on stop showing it. To write your own, see Developer documentation: widgets .","url":"https://calevans.com/picture-frame/docs/widgets/index.html#how-widgets-are-built","tags":"","category":""},{"id":27,"title":"Related","pageTitle":"Widgets","text":"Photos Use the admin Install the frame server A guide for the family , for the people who use the frame and send cards Next: Photos .","url":"https://calevans.com/picture-frame/docs/widgets/index.html#related","tags":"","category":""},{"id":28,"title":"Unlock your PF1007L","pageTitle":"Unlock your PF1007L","text":"This guide is for owners of a PF1007L photo frame who can use a Linux shell and PowerShell. When you finish, the frame boots normally but accepts root ADB connections, and you have a verified backup of its storage. No soldering, and you never open the case. Do this guide first. After it, go to Build the kiosk and set up a frame . Provisioning also needs a running server, which you set up with Install the frame server . The server does not depend on this guide, so you can do it before or after.","url":"https://calevans.com/picture-frame/docs/unlock/index.html","tags":"","category":""},{"id":29,"title":"Before you start","pageTitle":"Unlock your PF1007L","text":"Warning This can brick the frame. You write to its storage. Follow the backup step before any write, and check each write the way the guide says. The backup holds the frame's private credentials. The image of the storage includes the vendor's device certificate. Keep backups/ out of Git, and never upload or share it. The repository's .gitignore already ignores it. Root ADB has no password. After this guide, anyone who can reach the frame's network port 5555 has full control. Provisioning shows how to restrict it with ADB_ALLOW . Only the January 2026 firmware was tested. The one-sector ADB method was verified on firmware AEEZO/astar_m86_8723cs:6.0.1/MOB30R/20260113:eng/test-keys . Other firmware may store files in different places. The patch is made from your own backup, so it adapts, but nothing here is verified on other builds. If tools/derive-sector.sh stops with an error, stop and do not guess. Only modify hardware you own.","url":"https://calevans.com/picture-frame/docs/unlock/index.html#before-you-start","tags":"","category":""},{"id":30,"title":"What you need","pageTitle":"Unlock your PF1007L","text":"A PF1007L frame, with its USB-C cable. The frame takes power from USB. Windows 10 or 11 with WSL2 (Ubuntu 22.04 or later). The scripts call powershell.exe and PowerShell disk commands, so this guide does not work on a plain Linux machine without changes. usbipd-win 4 or later on Windows. A microSD card, any size. Its contents survive. The guide changes only bytes 8 KiB to 16 KiB. About 16 GB of free disk space for the backup, and patience. The backup takes about 90 minutes. In this guide, WSL means a shell in your Linux distribution. PowerShell means an Administrator PowerShell on Windows. means the folder holding this repository, written the way Windows sees it. Note The .ps1 scripts write backups\\ next to themselves and read patch\\ there. If your clone lives inside the WSL file system, the Windows path looks like \\\\wsl.localhost\\Ubuntu\\home\\you\\frame . Writing a 15 GB image over that path is slow. Cloning to a Windows drive such as /mnt/d/frame gives both sides the same fast folder. Neither layout has been compared.","url":"https://calevans.com/picture-frame/docs/unlock/index.html#what-you-need","tags":"","category":""},{"id":31,"title":"The map","pageTitle":"Unlock your PF1007L","text":"Nine steps. The backup in step 6 is not optional, and nothing writes to the frame's storage before it. Each step ends with a You are here box. If what you see does not match, stop and use If something goes wrong .","url":"https://calevans.com/picture-frame/docs/unlock/index.html#the-map","tags":"","category":""},{"id":32,"title":"Step 1: Set up your computer","pageTitle":"Unlock your PF1007L","text":"In WSL, install the tools: sudo apt install -y sunxi-tools adb e2fsprogs fdisk Allow your user to talk to the frame in FEL mode (the Allwinner USB recovery mode): echo 'SUBSYSTEM==\"usb\", ATTR{idVendor}==\"1f3a\", ATTR{idProduct}==\"efe8\", MODE=\"0666\"' | sudo tee /etc/udev/rules.d/61-sunxi-fel.rules sudo udevadm control --reload In PowerShell, tell usbipd it may share the frame's two USB identities with WSL automatically: usbipd policy add --effect Allow --operation AutoBind --hardware-id 1f3a:efe8 usbipd policy add --effect Allow --operation AutoBind --hardware-id 1f3a:1001 1f3a:efe8 is FEL mode. 1f3a:1001 is Android with ADB on. In PowerShell, stop Windows from mounting the frame's partitions. First note the current value so you can restore it later: Get-StorageSetting | Select NewDiskPolicy Set-StorageSetting -NewDiskPolicy OfflineAll Write down the value the first command prints. You put it back in When you finish . Copy .env.example to .env in the repository root. You fill in USBIP_BUSID in step 5. Provisioning explains every key. cp .env.example .env You are here Your computer has the tools, the udev rule and the usbipd policy. Windows no longer mounts new disks automatically. Nothing has touched the frame.","url":"https://calevans.com/picture-frame/docs/unlock/index.html#step-1-set-up-your-computer","tags":"","category":""},{"id":33,"title":"Step 2: Build U-Boot","pageTitle":"Unlock your PF1007L","text":"The frame's storage is not visible to your PC while Android runs. You temporarily boot a small program called U-Boot that shows the storage as a USB disk. The repository holds the patch for it but no binaries, so you build them. The build needs an ARM cross-compiler. Install the build tools (Debian or Ubuntu package names): sudo apt install -y gcc-arm-linux-gnueabihf bison flex swig device-tree-compiler \\ python3-pyelftools python3-setuptools libgnutls28-dev uuid-dev git make The python3- packages are U-Boot's own build dependencies. Project code uses no Python. Build it, using a work directory outside the repository: uboot/build.sh ~/frame-uboot-build The script clones U-Boot v2025.01, applies the patch and writes u-boot-sunxi-with-spl.bin and sunxi-spl-ck5.bin into uboot/ . It prints their SHA-256 hashes. The first run needs network access to source.denx.de . See uboot/README.md for what the patch changes. Note The build is not bit-for-bit reproducible. The binaries embed a build timestamp, so two builds from the same source have different hashes. You are here uboot/ holds u-boot-sunxi-with-spl.bin and sunxi-spl-ck5.bin , and the script printed a SHA-256 for each.","url":"https://calevans.com/picture-frame/docs/unlock/index.html#step-2-build-u-boot","tags":"","category":""},{"id":34,"title":"Step 3: Get fel-sdboot.sunxi","pageTitle":"Unlock your PF1007L","text":"fel-sdboot.sunxi is a tiny boot program that puts the frame into FEL mode and keeps it there. It comes from linux-sunxi/sunxi-tools . Its license differs from this repository's, so it is not included. Get the file from the sunxi-tools repository. If the repository does not hold a ready-made copy, build it. The on-device programs are not built by default, and need an ARM bare-metal compiler ( arm-none-eabi-gcc ). Install it the same way as the U-Boot tools in step 2 : git clone https://github.com/linux-sunxi/sunxi-tools ~/sunxi-tools make -C ~/sunxi-tools target-tools CROSS_COMPILE=arm-none-eabi- Not verified This build command was not checked. The linux-sunxi wiki page on sunxi-tools describes fel-sdboot . Copy the file to uboot/fel-sdboot.sunxi . Check its SHA-256: sha256sum uboot/fel-sdboot.sunxi write-sd.ps1 accepts only this hash, the one the procedure was tested with: 19db8994363b1464a1de82e1c90ab63c5a985d1c96b57403d039d69bfff39f14 If your hash differs, the script stops with fel-sdboot.sunxi hash mismatch . A different build of sunxi-tools produces a different file. Check that your file is the real fel-sdboot from the upstream source, then edit $ImageSha at the top of write-sd.ps1 to your hash. Do not skip the check. You are here uboot/fel-sdboot.sunxi exists, and its hash is either the one above or a hash you checked against upstream and wrote into write-sd.ps1 .","url":"https://calevans.com/picture-frame/docs/unlock/index.html#step-3-get-fel-sdbootsunxi","tags":"","category":""},{"id":35,"title":"Step 4: Make the FEL card","pageTitle":"Unlock your PF1007L","text":"The frame's boot ROM looks at the microSD slot before the internal storage. With this card in the slot, pressing RESET puts the frame into FEL mode and keeps it there. Pressing RESET alone also enters FEL, but it times out after a second or two, which is too short for this procedure. Put the microSD card in your PC. In PowerShell, find the card: Get-Disk Note its Number and its exact Size in bytes. Check this twice. The script writes to the disk number you give it. Write the file: powershell -ExecutionPolicy Bypass -File \\write-sd.ps1 -DiskNumber -ExpectSize The script refuses to run unless the disk is a USB disk of exactly that size. It first backs up the card's first 16 MiB to backups\\sd--first-16MiB.bin , writes the file at the 8 KiB offset, and reads it back. You see OK: fel-sdboot.sunxi written at offset 8192 and verified. Put the card in the frame's microSD slot. From now on: RESET with the card in enters FEL mode ( 1f3a:efe8 ). RESET with the card removed boots Android normally. You are here The script printed OK: fel-sdboot.sunxi written at offset 8192 and verified. and the card is in the frame.","url":"https://calevans.com/picture-frame/docs/unlock/index.html#step-4-make-the-fel-card","tags":"","category":""},{"id":36,"title":"Step 5: Show the frame's storage to Windows","pageTitle":"Unlock your PF1007L","text":"Plug the frame's USB-C port directly into your PC, not through a hub. In PowerShell, find the frame's bus ID: usbipd list The frame is 1f3a:efe8 if it is in FEL mode. Press the RESET pinhole with the card in if it is not. Put the bus ID in .env : USBIP_BUSID= A bus ID looks like 1-13 . The script refuses anything else. In WSL, run: scripts/boot-ums.sh Press the frame's RESET button. The script waits up to 30 minutes for FEL mode and attaches the frame to WSL. It runs a first DRAM set-up pass, because the first memory set-up after power-on fails and the second succeeds. Then it loads U-Boot. U-Boot shows the storage as a USB disk named Linux UMS disk 0 . The script ends with eMMC visible to Windows and a table with a disk number and size. Rules for this step: Never attach 1f3a:1010 (U-Boot's disk) with usbipd. The disk drops and does not recover. Never run usbipd attach --auto-attach on this bus ID. Cancel every \"format this disk\" prompt. The partition table mislabels the Android data partition as FAT32. If the disk disappears, U-Boot returns to FEL mode on its own, or its 16 second watchdog resets the frame into FEL mode. Run scripts/boot-ums.sh again. Press RESET only if FEL does not answer. You are here The script printed eMMC visible to Windows and a table with a disk number and a size of 15758000128. Windows shows the disk offline. You have not written anything to it.","url":"https://calevans.com/picture-frame/docs/unlock/index.html#step-5-show-the-frames-storage-to-windows","tags":"","category":""},{"id":37,"title":"Step 6: Back up the storage","pageTitle":"Unlock your PF1007L","text":"Warning Do not go on until the backup is verified. In PowerShell, while the disk is up: powershell -ExecutionPolicy Bypass -File \\backup-emmc.ps1 The script marks the disk read-only, writes backups\\emmc-full.img , then reads the whole disk a second time and compares the SHA-256 of both passes. At about 5.7 MB/s, each pass takes around 45 minutes. It ends with OK: ... verified by two independent reads. and writes backups\\emmc-full.img.sha256 . The script expects a 15,758,000,128 byte disk, the size of the tested unit. If yours differs, pass -ExpectSize . If the second pass is interrupted, run verify-backup.ps1 instead. It compares the image with the disk up to the user-data partition (about 2 GB, 7 minutes). If the disk drops, run it again with -Start from the last progress line: powershell -ExecutionPolicy Bypass -File \\verify-backup.ps1 Then check the system partition read-only in WSL. Expect only the message padding at end of inode bitmap , which is normal for Android images: fdisk -l backups/emmc-full.img Find the start sector of partition 7 ( system ), then: dd if=backups/emmc-full.img of=system.img bs=512 skip= count= e2fsck -fn system.img rm system.img You are here backups\\emmc-full.img and backups\\emmc-full.img.sha256 exist, the script printed OK: ... verified by two independent reads. (or verify-backup.ps1 passed), and e2fsck -fn found nothing but padding at end of inode bitmap . Copy backups/ somewhere private. Do not continue without this.","url":"https://calevans.com/picture-frame/docs/unlock/index.html#step-6-back-up-the-storage","tags":"","category":""},{"id":38,"title":"Step 7: Make the patch from your backup","pageTitle":"Unlock your PF1007L","text":"Android decides whether to turn ADB on from one line in /system/build.prop : persist.sys.usb.config=mass_storage . The patch changes mass_storage to adb , followed by a newline and #padding . The file stays the same length and no file-system structures change. tools/derive-sector.sh finds that one 512-byte sector in your own backup and writes the original and patched copies to patch/ . In WSL, run: tools/derive-sector.sh It reads backups/emmc-full.img by default. Pass another image path as an argument. If the system partition is not number 7, set SYSTEM_PART= . Check the output. You expect something like: bytes changed (expect up to 12): 12 sector , in-sector offset ; wrote patch/sector-{number.txt,orig.bin,adb.bin} If the script prints 'persist.sys.usb.config=mass_storage' not found , the line is already patched or your firmware differs. Stop. Confirm the data partition has no override. A file at /property/persist.sys.usb.config on the data partition would beat build.prop . On the tested firmware, the data partition starts at byte 2,235,564,032 (sector 4,366,336): debugfs -R 'stat /property/persist.sys.usb.config' 'backups/emmc-full.img?offset=2235564032' You expect File not found . The ?offset= form needs e2fsprogs 1.43 or later. On other firmware, take the start of the last partition from fdisk -l . You are here patch/ holds sector-number.txt , sector-orig.bin and sector-adb.bin , and the data partition has no override file.","url":"https://calevans.com/picture-frame/docs/unlock/index.html#step-7-make-the-patch-from-your-backup","tags":"","category":""},{"id":39,"title":"Step 8: Apply the patch","pageTitle":"Unlock your PF1007L","text":"With the storage still showing as a disk, in PowerShell: powershell -ExecutionPolicy Bypass -File \\patch-sector.ps1 The script: refuses to write unless the live sector is identical to patch\\sector-orig.bin , writes the 512-byte sector, reads it back and compares it, marks the disk read-only again. It ends with OK: sector now holds the ADB-enabled build.prop line, verified by readback. If the sector is already patched it says so and does nothing. If your disk is not 15,758,000,128 bytes, pass -ExpectSize . To put the stock sector back later, run the same command with -Restore while U-Boot shows the disk. You are here The script printed OK: sector now holds the ADB-enabled build.prop line, verified by readback. The frame's storage differs from the backup by one sector.","url":"https://calevans.com/picture-frame/docs/unlock/index.html#step-8-apply-the-patch","tags":"","category":""},{"id":40,"title":"Step 9: First boot with ADB","pageTitle":"Unlock your PF1007L","text":"Take the microSD card out of the frame. Press RESET. The frame boots Android as usual, with the stock home app. In PowerShell, find the frame. It now reports 1f3a:1001 : usbipd list usbipd attach --wsl --busid In WSL: adb devices adb shell id You see the frame in adb devices , and adb shell id prints uid=0(root) . ADB asks for no authorization. You are done unlocking. Keep the microSD card. It is your way back into FEL mode. You are here adb shell id prints uid=0(root) . The frame is unlocked. The backup is safe. Next you build the kiosk.","url":"https://calevans.com/picture-frame/docs/unlock/index.html#step-9-first-boot-with-adb","tags":"","category":""},{"id":41,"title":"When you finish","pageTitle":"Unlock your PF1007L","text":"Put Windows back to the disk policy you wrote down in step 1. Use the value the first command printed: Set-StorageSetting -NewDiskPolicy Keep backups/ and patch/ private and backed up. Do not add them to Git. Keep the FEL microSD card. You use it for any later recovery.","url":"https://calevans.com/picture-frame/docs/unlock/index.html#when-you-finish","tags":"","category":""},{"id":42,"title":"If something goes wrong","pageTitle":"Unlock your PF1007L","text":"Frame will not enter FEL mode. Check that the card is in, and that usbipd list shows 1f3a:efe8 . Press RESET again. boot-ums.sh says warm-up SPL did not return . Press RESET to restart FEL, and run the script again. boot-ums.sh says eMMC disk did not appear in Windows . Check that Windows has not set the disk offline for another reason, then run the script again. boot-ums.sh says timeout . It waited 30 minutes without seeing FEL. Check the card, the cable, and that the frame is not plugged into a hub. A write script says it expected exactly one disk. U-Boot's disk is not up, or its size differs from the default. Pass -ExpectSize . patch-sector.ps1 says the sector does not match. Do not force it. Check that patch/ was made from this frame's own backup. Undo the ADB change. Show the disk with scripts/boot-ums.sh , then run patch-sector.ps1 -Restore . The frame will not boot after a write. Follow step 4 of The frame does not boot . It restores your backup. adb devices shows nothing. Run usbipd list , find the frame ( 1f3a:1001 ), and attach it again. More recovery steps, including a frame that does not boot and a lost PIN, are in Troubleshooting and recovery .","url":"https://calevans.com/picture-frame/docs/unlock/index.html#if-something-goes-wrong","tags":"","category":""},{"id":43,"title":"Related","pageTitle":"Unlock your PF1007L","text":"Hardware and requirements Install the frame server U-Boot patch and build Next: Install the frame server , if you have not already. Then Build the kiosk and set up a frame .","url":"https://calevans.com/picture-frame/docs/unlock/index.html#related","tags":"","category":""},{"id":44,"title":"Update the kiosk","pageTitle":"Update the kiosk","text":"This page is for the person who builds and sends new versions of the kiosk app. When you finish, you can put a new kiosk build on a frame, roll it out to the rest, and recover when a build goes wrong, even when the frame is hundreds of miles away. You install the first kiosk on a frame over ADB. After that, the frame can update itself from a release you upload to your server. The server only stores the file and tells each frame which build it should have. The frame decides whether to install it.","url":"https://calevans.com/picture-frame/docs/kiosk-updates/index.html","tags":"","category":""},{"id":45,"title":"The ways to update a frame","pageTitle":"Update the kiosk","text":"Method Use it for Needs Section ADB, first install A frame that has no kiosk yet. USB or network ADB. Provisioning, step 7 ADB, manual update A frame next to you, or one that cannot self-update. ADB, the same keystore. Update over ADB Admin upload The normal way. The admin, a built APK and its .sig . Upload in the admin Shell on the server A server where you have a shell, or for scripting. bin/kiosk-release.php . Add a release from the shell The admin upload and the shell command both store a release. You then choose which frame gets it in the admin.","url":"https://calevans.com/picture-frame/docs/kiosk-updates/index.html#the-ways-to-update-a-frame","tags":"","category":""},{"id":46,"title":"How an update travels","pageTitle":"Update the kiosk","text":"Four things keep this safe to send and safe to get wrong: Two signatures. Android checks the APK certificate. The frame also checks a second, separate signature from an offline ECDSA key that never touches the server. A stolen admin password cannot push a build you did not sign. The frame decides. It refuses downgrades, other packages, mismatched certificates, and files with anything glued in front of the ZIP. Staged rollout. A release is marked Proven only after a frame has downloaded it and reported running it. Only then can you roll it out to everyone. A root watchdog. If a new build never becomes healthy, the frame reinstalls the last one that was, on its own. A crashing build costs roughly 15 minutes.","url":"https://calevans.com/picture-frame/docs/kiosk-updates/index.html#how-an-update-travels","tags":"","category":""},{"id":47,"title":"Two keys, two jobs","pageTitle":"Update the kiosk","text":"APK keystore Release key What it is An RSA key in a Java keystore, default ~/.android/frame-kiosk.keystore An EC P-256 key as a PEM file, default ~/.android/frame-release-key.pem What it signs The kiosk app (the APK) The text : of each build Who checks it Android, when installing an update The kiosk, from the public key baked into the app. The server too, if you set kiosk_release_pubkey . Lose it, and Every frame needs the kiosk uninstalled and installed again Every frame needs one more adb install with a new public key Keep it Backed up, private, off the server Backed up, private, offline , off the server Make both before your first build. The commands are in Provisioning, step 5 , and the .env keys are KEYSTORE , KEYSTORE_PASS , RELEASE_KEY and RELEASE_PUBKEY . The release signature is ECDSA with SHA-256 over the ASCII text : , for example ab12...ef:15 . The .sig file holds the base64 of its DER encoding. To let the server reject bad signatures early, put the public key in config.php : php 'kiosk_release_pubkey' => \"-----BEGIN PUBLIC KEY-----\\n...\\n-----END PUBLIC KEY-----\\n\" , Without it the server stores the signature as given, and only the frame checks it.","url":"https://calevans.com/picture-frame/docs/kiosk-updates/index.html#two-keys-two-jobs","tags":"","category":""},{"id":48,"title":"Build a release","pageTitle":"Update the kiosk","text":"Raise the version code. Every release needs a higher number than the last. Either edit android:versionCode in kiosk/AndroidManifest.xml , or pass it as an option. Build: cd kiosk lando build-kiosk -- --version-code 16 --version-name 16 The build prints: built kiosk/build/frame-kiosk.apk versionCode 16 sha256 <64 hex characters> signature kiosk/build/frame-kiosk.apk.sig (upload with the APK) You now have two files in kiosk/build/ : frame-kiosk.apk and frame-kiosk.apk.sig . Warnings that begin WARNING: mean a release key setting is missing, and the build then cannot self-update. Provisioning, step 6 lists every build option. Optional: check the signature yourself with OpenSSL. This is standard OpenSSL and is not part of the project's scripts: printf '%s' ':16' > msg.txt base64 -d kiosk/build/frame-kiosk.apk.sig > sig.der openssl dgst -sha256 -verify ~/.android/frame-release-pub.pem -signature sig.der msg.txt It prints Verified OK .","url":"https://calevans.com/picture-frame/docs/kiosk-updates/index.html#build-a-release","tags":"","category":""},{"id":49,"title":"Rules for every release","pageTitle":"Update the kiosk","text":"A higher version code than the last. Android and the kiosk both refuse a lower one. To go back, see Roll back by rebuilding . Data compatibility. A rollback keeps the app's saved data. A release must not write preferences or files that the previous release cannot read, or a rollback will crash. Sign it with the same keystore. A different key makes the frame refuse the update ( cert ). Never upload a test build. See Keystore and release key hygiene .","url":"https://calevans.com/picture-frame/docs/kiosk-updates/index.html#rules-for-every-release","tags":"","category":""},{"id":50,"title":"Update over ADB","pageTitle":"Update the kiosk","text":"For a frame next to you, or one that cannot self-update, install a newly built APK over the old one. It must be signed with the same keystore: adb install -r kiosk/build/frame-kiosk.apk Use -s to pick a device. This keeps the app's data and the device owner setting. Use the same command when you change the baked-in release public key, KIOSK_PIN or FRAME_SERVER_URL , because each is built into the app. A frame updated over ADB has no .sig check. Nothing but you and Android is involved.","url":"https://calevans.com/picture-frame/docs/kiosk-updates/index.html#update-over-adb","tags":"","category":""},{"id":51,"title":"Upload in the admin","pageTitle":"Update the kiosk","text":"In the admin, select Library . Under Kiosk app , select Upload release . Choose frame-kiosk.apk as the APK file (up to 16 MiB). Choose frame-kiosk.apk.sig as the Release signature . Add Notes (optional) if you like, up to 500 characters. Select Upload . If you have not entered your password in the last five minutes, the admin asks for it. You see \"Release uploaded\". The table lists the release with its size, who uploaded it, how many frames run it, and whether it is Proven or Not yet proven . The server checks the file before it keeps it: It is a plain ZIP, with nothing hidden before or after the entries (Janus-safe). Its package is com.calevans.frame . Its version code is a number from 1 to 2,100,000,000. If you set kiosk_release_pubkey , the signature verifies. No release with the same file hash or version code already exists. The server does not check the APK's signing certificate. The frame does. Uploaded builds are stored in var/kiosk/ , named by their SHA-256 hash. Back the folder up with var/frames.db . If the upload fails, the box shows the reason. A 413 means a size limit. See Troubleshooting .","url":"https://calevans.com/picture-frame/docs/kiosk-updates/index.html#upload-in-the-admin","tags":"","category":""},{"id":52,"title":"Add a release from the shell","pageTitle":"Update the kiosk","text":"On the server, you can add a release without the admin. Run it as the web user (it refuses root), from the folder that holds app/ : sudo -u www-data php app/bin/kiosk-release.php add frame-kiosk.apk [frame-kiosk.apk.sig] [--notes \"text\"] sudo -u www-data php app/bin/kiosk-release.php list The signature file defaults to .sig . --notes takes up to 500 characters. The web user must be able to read both files. Copy them to a folder it can read first. It makes the same checks as the admin upload, refuses symlinks and files that are not regular files, and stops at 16 MiB. On success it prints version_code , version_name , sha256 and id . Failures go to standard error with the admin's codes: duplicate_sha256 , duplicate_version_code , not_apk and others. The upload is logged as cli: (the SUDO_USER name when you use sudo). list prints one line per release, with tabs between the columns: ID, version code, version name, SHA-256, size, upload time (UTC), uploaded by, and proven or unproven . Choosing which frame gets the release is still done in the admin.","url":"https://calevans.com/picture-frame/docs/kiosk-updates/index.html#add-a-release-from-the-shell","tags":"","category":""},{"id":53,"title":"Choose which frame gets a release","pageTitle":"Update the kiosk","text":"Always target one frame first. Open the frame in the admin, then Details . Find the Kiosk version row. It shows the build the frame runs (\"Build 15\"). In the list, choose the release. Each entry reads like 16 (build 16) . No update cancels. It asks for your password. You see \"Update queued\". The frame installs the release the next time its screen is quiet. The row shows the state: Pill Meaning Up to date The frame runs the target, or newer. Update pending The frame has been offered the release and has not installed it yet. Waiting for a report The frame has not yet said which build it runs. Update failed See Failure states . No rollback watchdog The frame's boot script has no watchdog. See below. A frame with no rollback watchdog can only be sent a release that has already run on another frame. The server refuses with \"this frame has no rollback watchdog, so it can only take a release that already runs on another frame\". Send the first copy to a frame that has the watchdog. Install the boot script on every frame before you use self-update on it.","url":"https://calevans.com/picture-frame/docs/kiosk-updates/index.html#choose-which-frame-gets-a-release","tags":"","category":""},{"id":54,"title":"What the frame checks","pageTitle":"Update the kiosk","text":"The frame installs a release only if all of these hold. Otherwise it holds a failure that the admin shows. The detached release signature verifies against the public key baked into the app. The file's SHA-256 and size match the offer, it is at most 32 MiB, and it is a plain ZIP. It is the kiosk package. Its version code is the offered one and is higher than the installed one. A frame never downgrades itself. Its signing certificates are exactly the installed ones. Nobody is using the frame: the network is up, the PIN panel and Wi-Fi setup are closed, and the screen is dimmed (bedtime or Dim ) or untouched for 30 minutes. The frame checks every 30 seconds. The server lets each frame download a release at most 12 times an hour.","url":"https://calevans.com/picture-frame/docs/kiosk-updates/index.html#what-the-frame-checks","tags":"","category":""},{"id":55,"title":"Staged rollout and proven releases","pageTitle":"Update the kiosk","text":"A release is Proven once a frame has downloaded it in full and then reported running that version or newer. Only a proven release can be rolled out to everyone. Target one frame (above). Wait. Check that its Kiosk version row shows Up to date , and look at the frame's Screen to see the dashboard is fine. In Library , under Kiosk app , the release now says Proven . Select Roll out to all on that release. It asks for your password. The admin says how many frames will update, and how many are already on it or queued. The button is disabled before then, with the hint \"Target one frame first and let it prove this release\". Roll out to all offers the release to every active frame that reports an older build, unless that frame is already pointed at this release or a newer one. When you claim a new frame, the server points it at the newest release that has already run on a frame. If no release has run yet, the frame stays on the build you installed.","url":"https://calevans.com/picture-frame/docs/kiosk-updates/index.html#staged-rollout-and-proven-releases","tags":"","category":""},{"id":56,"title":"The rollback watchdog","pageTitle":"Update the kiosk","text":"The boot script device/frame-fixmac.sh carries the line # frame-watchdog: 1 . The kiosk reports it, and the admin shows No rollback watchdog for frames without it. How it works: The kiosk writes healthy (its version code) after it has been in front for 5 minutes without crashing, or after its first good server answer plus a loaded dashboard. Root copies the installed APK to /data/misc/frame/kiosk-good.apk (root-only) each time healthy equals the installed version. On the first boot with the script, the installed build is copied. If a new version was installed and is still not healthy after about 15 minutes, root reinstalls that copy with pm install -r -d , once. The admin shows Update failed with \"the new build did not start properly and was rolled back\". A crashing build therefore costs you roughly 15 minutes, then the frame is back on the last build that worked. Root reads only the digits of healthy and the to= line of files/update/state from the app's folder, ignores symlinks and anything else, and never writes into the app's folder. The server can therefore at most cause a rollback to the last build that ran healthy on that frame.","url":"https://calevans.com/picture-frame/docs/kiosk-updates/index.html#the-rollback-watchdog","tags":"","category":""},{"id":57,"title":"Failure states","pageTitle":"Update the kiosk","text":"When a frame cannot install a release, the Kiosk version row says Update failed and gives the reason. Reason in the admin What it means What to do the download failed The frame could not fetch the file. Check that the frame is online and var/kiosk/ is readable by the web user. Select Clear and retry . the file was the wrong size The size does not match the offer. Delete the release and upload it again. the file did not match its hash The stored file differs from the offer. Delete the release and upload it again. the file is not a plain APK The ZIP has extra data in it. Rebuild and upload again. the file is for another app The package is not the kiosk. Upload the right APK. the file is not newer than the installed app The version code is not higher. Rebuild with a higher version code. the file's version is not the one offered The APK's version code differs from the release record. Delete the release and upload again. the signing certificate differs from the installed app The build was signed with a different keystore. Rebuild with the original keystore. If the original is lost, see Lost keystore . the release signature did not verify The signature does not match, or the frame has a different public key baked in. Check RELEASE_KEY and RELEASE_PUBKEY . A frame built with another public key needs an adb install -r of a build with the right one. the new build did not start properly and was rolled back The watchdog reinstalled the old build. Find out why the new build failed. Fix it, raise the version code, and release again. the app is not the device owner The kiosk lost its device owner status. Redo Provisioning, step 7 . Android refused the install (status N) Android returned an install error. Read adb logcat on the frame. When you have fixed the cause, select Clear and retry on the Kiosk version row. It asks for your password and says \"Cleared. The frame will try again.\" Until then the frame does not try the same file again. A failure belongs to one file. A new release with a different file is offered afresh.","url":"https://calevans.com/picture-frame/docs/kiosk-updates/index.html#failure-states","tags":"","category":""},{"id":58,"title":"Delete a release","pageTitle":"Update the kiosk","text":"In Library , under Kiosk app , select Delete on the release. It asks for your password, then removes the record and the file. The admin refuses while a frame still targets the release: \"a frame still targets this release; clear its target first\". Set that frame's Kiosk version to No update first.","url":"https://calevans.com/picture-frame/docs/kiosk-updates/index.html#delete-a-release","tags":"","category":""},{"id":59,"title":"Roll back by rebuilding","pageTitle":"Update the kiosk","text":"Android and the kiosk both refuse a lower version code, so you cannot send an old build as it was. To go back, build the old code again with a higher number and release that: git checkout -- kiosk/src kiosk/res cd kiosk && lando build-kiosk -- --version-code 21 --version-name 21-rollback ( KIOSK_VERSION_CODE and KIOSK_VERSION_NAME in the environment work too when you build without Lando.) The new APK has a new SHA-256 and its own signature file. Upload it, target one frame, and roll it out as usual.","url":"https://calevans.com/picture-frame/docs/kiosk-updates/index.html#roll-back-by-rebuilding","tags":"","category":""},{"id":60,"title":"Keystore and release key hygiene","pageTitle":"Update the kiosk","text":"Back up both keys somewhere private. Keep the release key off the server, out of the repository and out of any container image. Do not give either key to the server, to CI, or to anyone else. Never sign a throwaway or test build with the real keys, and never upload one as a release. The only exception is the --test-crash build, used for the watchdog test on your own frame. Lost the release key: every frame needs one more adb install -r of a build with a new public key. Lost the keystore: you cannot update in place. On every frame you must undo device owner, uninstall the kiosk, and start again. See Provisioning .","url":"https://calevans.com/picture-frame/docs/kiosk-updates/index.html#keystore-and-release-key-hygiene","tags":"","category":""},{"id":61,"title":"After a watchdog test","pageTitle":"Update the kiosk","text":"A --test-crash build ( lando build-kiosk -- --test-crash --version-code ) crashes on purpose, but only while root has run setprop debug.frame.testcrash 1 . That property is cleared at reboot. With SELinux off, any app on the frame could set it, so the gate means only that a compromised server alone cannot trigger the crash. The build is signed with your real keys, so retire it as soon as the test is done: Delete that release in the admin. Remove the build: rm -rf kiosk/build , and any copy of the crash APK and its .sig that you saved. Ship a real release with a higher version code to every frame. The crash build is then refused as not_newer everywhere. Do this before any frame leaves your control.","url":"https://calevans.com/picture-frame/docs/kiosk-updates/index.html#after-a-watchdog-test","tags":"","category":""},{"id":62,"title":"What the server logs","pageTitle":"Update the kiosk","text":"Uploads, targets, roll-outs and cleared failures go to the PHP error log, for example: frame admin: kiosk release uploaded user=yourname ip=203.0.113.9 version_code=15 sha256=... frame admin: kiosk target set user=yourname ip=203.0.113.9 frame=1a2b3c4d version_code=15 sha256=... frame admin: kiosk rollout user=yourname ip=203.0.113.9 version_code=15 sha256=... frames=3 frame admin: kiosk failure cleared user=yourname ip=203.0.113.9 frame=1a2b3c4d sha256=... reason=hash Other events: release deleted , target cleared , target set on claim , and upload rejected (with the reason).","url":"https://calevans.com/picture-frame/docs/kiosk-updates/index.html#what-the-server-logs","tags":"","category":""},{"id":63,"title":"Related","pageTitle":"Update the kiosk","text":"Build the kiosk and set up a frame Use the admin Troubleshooting and recovery Security Next: Troubleshooting and recovery .","url":"https://calevans.com/picture-frame/docs/kiosk-updates/index.html#related","tags":"","category":""},{"id":64,"title":"Use the admin","pageTitle":"Use the admin","text":"This page is for the person who runs the server. It covers how to create admin logins, how sign-in and two-step codes work, which actions ask for your password again, and a tour of the admin screens. When you finish, you can sign in safely and find everything you need to run your frames day to day. The admin is a desktop web page at https://frames.example.com/frames/admin/ . It is built for a computer, not a phone.","url":"https://calevans.com/picture-frame/docs/admin/index.html","tags":"","category":""},{"id":65,"title":"Manage admin users","pageTitle":"Use the admin","text":"Admin logins live in the database. You create them from the command line on the server, as the web user. Nobody can sign in until a user exists. sudo -u www-data php /srv/frame/app/bin/user.php [user name] Command What it does add Creates a user. Asks for the password twice. passwd Sets a new password. Signs that user out of every browser. remove Deletes the user. Their sessions stop working. list Prints every user with the date created, the last sign-in time (UTC), and whether two-step sign-in is on. totp-enable Turns on two-step sign-in. See Two-step sign-in . totp-disable Turns two-step sign-in off. Use it if you lose your authenticator. passwd , totp-enable and totp-disable also sign that user out of every browser at once and make that user's trusted-device cookie stop working. Rules: The command refuses to run as root. Run it as the web user, as shown, so the database keeps the right owner. User names are lowercase letters, digits, dot, underscore and hyphen, up to 64 characters, and start with a letter or digit. The sign-in form ignores capital letters and spaces around the name. A password must be at least 12 characters. It cannot match the user name, and it cannot be on the bundled list of commonly used passwords. The limit is 1024 bytes, or 72 bytes if your PHP has no Argon2 support and the server uses bcrypt. The password is read from the terminal with echo off. To pass it without a terminal, pipe one line into the command. Never put a password on the command line. If the database is missing or out of date, the command stops and tells you to run migrate.php first. Passwords are stored as Argon2id hashes.","url":"https://calevans.com/picture-frame/docs/admin/index.html#manage-admin-users","tags":"","category":""},{"id":66,"title":"Two-step sign-in","pageTitle":"Use the admin","text":"A password alone is the only thing between the internet and your frames. Add a one-time code from an authenticator app. It is strongly recommended. Run: sudo -u www-data php /srv/frame/app/bin/user.php totp-enable yourname The command prints a secret: and an otpauth:// link. In your authenticator app, choose to add an account by entering a setup key, and type the secret. The link holds the same secret. At the prompt, enter the six-digit code your app shows. Nothing is saved until the code checks out. If two-step sign-in is already on for that user, run totp-disable first. After that, the sign-in form needs the password and the current code together. A wrong password and a wrong code give the same message, so nobody can tell which was wrong. Details: The codes are standard time-based codes: six digits, a new one every 30 seconds, SHA-1. The app name shown is \"Frames admin\". The server accepts the current code and the ones just before and after it, to allow for clock drift. Your server's clock must be right, so run NTP on it. A code works once. Entering the same code a second time fails. If you lose the authenticator, you recover from the shell, which only you have: sudo -u www-data php /srv/frame/app/bin/user.php totp-disable yourname","url":"https://calevans.com/picture-frame/docs/admin/index.html#two-step-sign-in","tags":"","category":""},{"id":67,"title":"Sign in and out","pageTitle":"Use the admin","text":"Open https://frames.example.com/frames/admin/ . You land on the sign-in page. Enter your User name and Password . If two-step sign-in is on, enter the Authentication code . Leave it empty otherwise. Select Sign in . You land on Frames . To sign out, open the account menu in the top-right corner (it shows your user name) and select Sign out . Messages you might see on the sign-in page: Message Meaning Sign-in failed. Check your details and try again. The user name, password or code is wrong. The message is the same for all three. Too many attempts. Try again later. A lockout is active. The page expired. Try again. The form's token or the request's origin did not check out. See Troubleshooting . That request was not understood. The browser sent the form in an unexpected format. Reload the page.","url":"https://calevans.com/picture-frame/docs/admin/index.html#sign-in-and-out","tags":"","category":""},{"id":68,"title":"Sessions and timeouts","pageTitle":"Use the admin","text":"What Limit Idle time before you are signed out 30 minutes without a request Longest session 12 hours after you sign in The session ID changes About every 15 minutes, with a short overlap so open requests do not fail The sign-in form stays valid 15 minutes When a session ends, the admin shows a Signed out box with a Sign in button. Unsaved edits on that page are lost. A password change, a two-step change, or removing the user ends that user's sessions at once.","url":"https://calevans.com/picture-frame/docs/admin/index.html#sessions-and-timeouts","tags":"","category":""},{"id":69,"title":"Trusted device","pageTitle":"Use the admin","text":"When you sign in successfully, your browser keeps a trusted-device cookie for 90 days. It does exactly one thing: it lifts the per-user lockout described below for that browser. It never skips the password or the code. The cookie stops working when that user's password changes, two-step sign-in is turned on or off, or the user is removed. The key that signs these cookies is var/device.key , created the first time someone signs in. Deleting it invalidates every trusted-device cookie and changes nothing else.","url":"https://calevans.com/picture-frame/docs/admin/index.html#trusted-device","tags":"","category":""},{"id":70,"title":"Confirming a risky action","pageTitle":"Use the admin","text":"Some actions ask for your password (and your code, if two-step is on) again, unless you entered it in the last five minutes. Signing in counts. When it asks, the Confirm it's you box appears with Password and Authentication code fields and a Confirm button. After you confirm, the action goes ahead. If you select Cancel , the admin says \"Not confirmed. Nothing was changed.\" These actions ask: Area Actions Frames Revoke a frame. Restore a revoked frame. Delete a frame. Dismiss unclaimed frames. Set a frame's PIN. Reset a frame's PIN to the factory PIN. Kiosk app Upload a release. Edit a release's notes. Delete a release. Choose the release a frame should install ( Kiosk version ). Roll out to all . Clear and retry after a failed update. Photos Delete an album. Delete photos, including Reject . Revoke or restore a drop link. Make a new link ( New link ). Delete a drop link. Delete their photos . Cards Revoke or restore a sender link. Make a new link. Delete a sender link. Delete unopened cards from a sender.","url":"https://calevans.com/picture-frame/docs/admin/index.html#confirming-a-risky-action","tags":"","category":""},{"id":71,"title":"Lockouts","pageTitle":"Use the admin","text":"The sign-in page counts failed attempts. Every attempt counts, including ones with a wrong code. Limit What happens 10 failed sign-ins from one address in 15 minutes That address is locked out for the rest of the window. 20 failed sign-ins for one user name in an hour That user name is locked out, except for a browser that signed in as that user before and still holds its trusted-device cookie. While a lockout is active, a correct password is refused too. Wait it out. The sign-in page says \"Too many attempts. Try again later.\" Re-confirming your password inside the admin uses the per-address limit only, so someone guessing at your user name cannot stop you from confirming an action. If a proxy hides client addresses, everyone shares one address and a few failures lock the page for all. Set client_ip_header and trusted_proxies . See Install the frame server .","url":"https://calevans.com/picture-frame/docs/admin/index.html#lockouts","tags":"","category":""},{"id":72,"title":"What the server logs","pageTitle":"Use the admin","text":"Sign-ins and failures go to the PHP error log, one line each, without passwords: frame admin: login ok user=yourname ip=203.0.113.9 frame admin: login failed user=yourname ip=203.0.113.9 frame admin: login throttled ip=203.0.113.9 frame admin: login rejected origin ip=203.0.113.9 frame admin: login rejected token ip=203.0.113.9 frame admin: logout user=yourname frame admin: reauth failed user=yourname ip=203.0.113.9 frame admin: reauth throttled ip=203.0.113.9 Kiosk release changes, such as uploads and roll-outs, are logged the same way. See Update the kiosk . You can point fail2ban at the login failed , login throttled , login rejected and reauth failed lines. Not verified A fail2ban filter for these lines was not tested. A starting point for filter.d/frame-admin.conf is failregex = frame admin: (login (failed|throttled|rejected \\w+)|reauth (failed|throttled)).* ip= . Check it against your log before you rely on it.","url":"https://calevans.com/picture-frame/docs/admin/index.html#what-the-server-logs","tags":"","category":""},{"id":73,"title":"A tour of the admin","pageTitle":"Use the admin","text":"The top bar has the Frames admin name, four links, and your account menu. Link What it holds Frames Your frames, and the Claim a frame button. Library Locations, calendars, and the kiosk app releases. Photos Your photo library: albums, uploads, drop links. See Photos . Card designs Covers and stamps for Cards. See Widgets: Cards . Every page uses a hash address, such as #/photos or #/frame//widgets , so you can bookmark any screen.","url":"https://calevans.com/picture-frame/docs/admin/index.html#a-tour-of-the-admin","tags":"","category":""},{"id":74,"title":"Frames","pageTitle":"Use the admin","text":"Frames shows one tile per claimed frame. Each tile has the last screenshot, the frame's name, and a status: Online , Offline (with when it was last seen), Never connected , or Revoked . A Weak Wi-Fi badge shows when the signal is below -75 dBm. An Update available badge shows when another frame runs a newer kiosk. The page refreshes every minute.","url":"https://calevans.com/picture-frame/docs/admin/index.html#frames","tags":"","category":""},{"id":75,"title":"Claim a frame","pageTitle":"Use the admin","text":"A new frame shows a six-digit pairing code on its screen. A banner on Frames says \"A frame is waiting to be claimed.\" with Claim it and Dismiss buttons. Select Claim a frame . Enter the six-digit code from the frame's screen in Code . The box finds the frame as soon as you type six digits. You can also select Find frame . Check the frame ID the admin shows. Confirm it is the one in front of you. Enter a Name for the frame. It is shown in the admin and nowhere else. Select Claim frame . You see \"Claimed. Turn on the widgets you want.\" The admin opens the frame's Widgets section. The code is valid for 24 hours. After five wrong codes in 10 minutes, the admin stops accepting codes for a while. The message is \"That code was wrong or has expired.\" When you claim a frame, the server also: turns on the Clock and Calendar widgets, and Weather if a location already exists, picks a time for the daily photo set, between 04:00 and 06:00 in the frame's time zone, and points the frame at the newest kiosk release that has already run on a frame, if there is one. See Update the kiosk . Dismiss deletes unclaimed frames. It asks you to confirm your password. Any that are still powered on enroll again.","url":"https://calevans.com/picture-frame/docs/admin/index.html#claim-a-frame","tags":"","category":""},{"id":76,"title":"The frame page","pageTitle":"Use the admin","text":"Select a tile to open a frame. The header shows the frame's name (use the pencil button to rename it) and its status. The More menu has Revoke (or Restore ) and Delete . Revoke stops a frame working at once. You can restore it later. Restore brings a revoked frame back. Delete removes the frame and its settings. If the frame is still powered on, it enrolls again as unclaimed. The dialog offers Revoke instead . All three ask for your password again. A rail on the left lists the frame's sections: Screen , Schedule , Widgets , one section per widget that has settings (shown while the widget is on), Security and Details . A dot next to a section means unsaved changes there. Each section saves on its own. A bar at the bottom shows \"Unsaved changes\" with Discard and Save . If you try to leave with unsaved changes, the admin asks \"Discard unsaved changes?\"","url":"https://calevans.com/picture-frame/docs/admin/index.html#the-frame-page","tags":"","category":""},{"id":77,"title":"Live view","pageTitle":"Use the admin","text":"Screen shows what the frame is showing. Select Refresh to ask the frame for a new screenshot. The frame picks up the request on its next check-in. This usually takes a few seconds, and the admin waits up to 45 seconds. After 25 seconds it says \"Taking longer than usual.\" You can ask again 10 seconds after the last request. If the screen was off, the picture is a \"Screen off\" placeholder and the caption says when it turned off and when it comes back. If the frame is offline, the admin says \"Offline, so no live view.\" and offers Check again . Frames running an older kiosk say \"This frame's software is too old for live view.\" Only the latest screenshot of each frame is kept, as a JPEG of up to 600 KiB.","url":"https://calevans.com/picture-frame/docs/admin/index.html#live-view","tags":"","category":""},{"id":78,"title":"Schedule and bedtime","pageTitle":"Use the admin","text":"Schedule controls when the screen turns fully off how long the frame waits before it starts the screensaver, and which time zone the frame uses. Turn on Turn the screen off overnight . Set Bedtime and Wake time . Type a time into each, or drag the moon and sun handles on the 24-hour bar. With the keyboard, the arrow keys move a handle by 5 minutes and Page Up and Page Down move it by an hour. Select Save . Time zone. New frames start with America/New_York . Bedtime, wake time, the daily photo pick time and the clock all use the frame's time zone. To change it, type in Time zone to search the list, for example America/Chicago , or select Use this computer's zone . Select Save . The frame picks it up on its next check-in, within a minute. Rules: Bedtime and wake time must differ. The 24-hour bar keeps its two handles at least 15 minutes apart. Dragging snaps to 15 minutes, or 5 minutes while you hold Shift. When the switch is off, the bar says \"Screen stays on all day.\" A line under the bar says how long the screen is off and on, and whether it is on or off right now. The schedule is saved on the frame, so it works when the frame is offline. At bedtime the backlight goes fully off, not just dim. A tap wakes it.","url":"https://calevans.com/picture-frame/docs/admin/index.html#schedule-and-bedtime","tags":"","category":""},{"id":79,"title":"Screensaver","pageTitle":"Use the admin","text":"On the same page, Start screensaver after sets how long the frame waits without a touch before it starts the photo screensaver. The choices are 30 seconds, 1, 2, 5, 10, 15 and 30 minutes, and 1 hour. The default is 2 minutes. If the frame has no photos, it returns to the home screen instead. The photos come from the frame's daily set. See Photos .","url":"https://calevans.com/picture-frame/docs/admin/index.html#screensaver","tags":"","category":""},{"id":80,"title":"Widgets","pageTitle":"Use the admin","text":"Widgets has an On and Off switch for each widget. Turn switches on or off and select Save . Settings for each widget appear in their own section once it is on. See Widgets .","url":"https://calevans.com/picture-frame/docs/admin/index.html#widgets","tags":"","category":""},{"id":81,"title":"Security","pageTitle":"Use the admin","text":"Security sets the frame's PIN, the one the frame asks for after you hold the top-left corner for 10 seconds. The panel says whether the frame uses a custom PIN or the factory PIN, which is the KIOSK_PIN baked into the build. Enter the New PIN , 4 to 8 digits. Use the eye button to see what you typed. Select Set PIN . It asks for your password. Reset to factory PIN clears the custom PIN. The frame picks up the change on its next check-in.","url":"https://calevans.com/picture-frame/docs/admin/index.html#security","tags":"","category":""},{"id":82,"title":"Details","pageTitle":"Use the admin","text":"Details is a read-only summary: the Wi-Fi network and signal, the local and public IP, the MAC address, when it last checked in, the versions it runs, its uptime, its short ID, its time zone and when it enrolled. The Kiosk version row is where you send it a new kiosk. See Update the kiosk .","url":"https://calevans.com/picture-frame/docs/admin/index.html#details","tags":"","category":""},{"id":83,"title":"Library","pageTitle":"Use the admin","text":"Library holds three lists. Locations. Weather needs at least one. Select Add location , then fill in: Field What to enter Name A label, up to 64 characters. Names are unique. Latitude -90 to 90. Longitude -180 to 180. Stations (optional) Up to five comma-separated four-character station IDs, such as KJFK . Leave Stations empty at first. The pencil edits a location and Delete removes it. The admin refuses to delete a location a frame's Weather widget uses. Calendars. Select Add calendar and enter: Field What to enter Name A label, up to 64 characters. Share URL The calendar's public iCal link. Its host must be in calendar_hosts . Color (optional) A color like #6cb6ff . The table shows each calendar's host and a status: OK , Error (with the message), or Not fetched . Rename and Delete are on each row. The admin refuses to delete a calendar a frame uses. Kiosk app. The list of kiosk releases, with Upload release . See Update the kiosk .","url":"https://calevans.com/picture-frame/docs/admin/index.html#library","tags":"","category":""},{"id":84,"title":"Photos and Card designs","pageTitle":"Use the admin","text":"These pages are covered where the feature is explained: Photos : Photos . Card designs : Widgets: Cards .","url":"https://calevans.com/picture-frame/docs/admin/index.html#photos-and-card-designs","tags":"","category":""},{"id":85,"title":"Related","pageTitle":"Use the admin","text":"Install the frame server Widgets Photos Update the kiosk Security Next: Build the kiosk and set up a frame .","url":"https://calevans.com/picture-frame/docs/admin/index.html#related","tags":"","category":""},{"id":86,"title":"Build the kiosk and set up a frame","pageTitle":"Build the kiosk and set up a frame","text":"This guide is for people whose PF1007L already has root ADB (see Unlock your PF1007L ) and whose server is running (see Install the frame server ). When you finish, the frame boots to your logo, then shows your dashboard full screen, and you have claimed it in the admin. You do the setup once per frame. You build the kiosk app once per change.","url":"https://calevans.com/picture-frame/docs/provisioning/index.html","tags":"","category":""},{"id":87,"title":"Before you start","pageTitle":"Build the kiosk and set up a frame","text":"Warning Keep the signing keystore forever. Updates to the kiosk install only if they are signed with the same key. If you lose the keystore, you must uninstall the kiosk (undo device owner first) on every frame and start again. Warning Make the release key before your first build. The key that approves self-updates is baked into the app, so a build made without it cannot self-update. See Step 5 . Root ADB has no password. Anyone who can reach port 5555 on the frame controls it. Set ADB_ALLOW in step 1. Every write is yours to confirm. scripts/provision.sh prints what it will do and waits for y before the first write. Read it. Use the tested firmware. Package names and file paths below come from the January 2026 firmware ( AEEZO/astar_m86_8723cs:6.0.1/MOB30R/20260113 ). Check each one on other builds. You need on your computer: adb , Docker and Lando for the included kiosk build (or a JDK and the Android build tools, see below), openssl , unzip and php . Run everything in a WSL shell, in the repository root.","url":"https://calevans.com/picture-frame/docs/provisioning/index.html#before-you-start","tags":"","category":""},{"id":88,"title":"Step 1: Fill in .env","pageTitle":"Build the kiosk and set up a frame","text":"Copy .env.example to .env in the repository root if you have not already: cp .env.example .env chmod 600 .env .env holds your keystore password, so keep it private. Git ignores it. The file is KEY=value , one per line. These rules come from the strict reader in scripts/lib/env.sh : Blank lines and lines that start with # are allowed. Anything else must be KEY=value for a known key. A value may be wrapped in one pair of single or double quotes. The quotes are removed. There is no variable expansion, no backticks and no escapes. A line with an unknown key stops the script with unknown key . A line with a Windows line ending stops it with control characters (CRLF line endings?) . KEYSTORE , RELEASE_KEY and RELEASE_PUBKEY may start with ~/ . Key Read by Needed What it does FRAME_SERVER_URL kiosk/build.sh Always, for a build The address of your server. It must be HTTPS, end with a slash, and match frames_url in the server's config.php . Example: https://frames.example.com/frames/ . KIOSK_PIN kiosk/build.sh Always, for a build The factory PIN for the frame's on-screen panel, 4 to 8 digits. Only a salted hash goes into the app. You can set a different PIN per frame in the admin later. KEYSTORE kiosk/build.sh Optional Path to the signing keystore. Default: ~/.android/frame-kiosk.keystore . Keep it under your home folder: Lando sees only that. KEYSTORE_PASS kiosk/build.sh Always, for a build Password for the keystore and its key (both use the same one). Choose your own. RELEASE_PUBKEY kiosk/build.sh For self-update Path to the public half of your release key. It is built into the app. Without it, the app refuses every self-update. RELEASE_KEY kiosk/build.sh For self-update Path to the private half of your release key. The build uses it to write a .sig file next to the APK. Without it, no .sig is written. OWNER_NAME kiosk/build.sh Optional Name shown on the pairing screen, in \"Read this code to ...\". ADB_ALLOW scripts/provision.sh boot-script For the boot script IPv4 addresses or CIDR ranges that may reach ADB over Wi-Fi, separated by commas or spaces. Example: 192.0.2.20,198.51.100.0/28 . Empty means no limit. NTP_SERVER scripts/provision.sh time For time The time server the frame uses before it has a clock. Example: pool.ntp.org . Letters, digits, dots and hyphens only. TZ scripts/provision.sh time For time The frame's time zone. Example: America/New_York . USBIP_BUSID scripts/boot-ums.sh Unlocking only The USB/IP bus ID of the port the frame is plugged into. Not needed here. ADB_ALLOW takes effect only when the boot script is installed (step 9). Include the address of the computer you use for ADB. USB ADB is never limited, so you can always recover over the cable. Here is a filled-in example: FRAME_SERVER_URL=https://frames.example.com/frames/ KIOSK_PIN=4821 KEYSTORE=~/.android/frame-kiosk.keystore KEYSTORE_PASS=a-long-password-of-your-own RELEASE_KEY=~/.android/frame-release-key.pem RELEASE_PUBKEY=~/.android/frame-release-pub.pem OWNER_NAME=Alex ADB_ALLOW=192.0.2.20,198.51.100.0/28 NTP_SERVER=pool.ntp.org TZ=America/New_York Note TZ in .env sets the time zone of the Android system on the frame. The time zone the admin uses for the schedule and photo pick time is a separate setting: Time zone in the frame's Schedule section. See Use the admin .","url":"https://calevans.com/picture-frame/docs/provisioning/index.html#step-1-fill-in-env","tags":"","category":""},{"id":89,"title":"Step 2: Get the files you provide","pageTitle":"Build the kiosk and set up a frame","text":"The repository does not carry third-party binaries. Download these: File Why Where to get it WebView 106 APK (arm, 32-bit) The frame's stock WebView 44 is too old for modern pages. 106 is the newest that runs on Android 6. The LineageOS prebuilt WebView for ARM: LineageOS/android_external_chromium-webview_prebuilt_arm . The version tested is 106.0.5249.126 , from the prebuilt commit 4b0ae494a7dd , with SHA-256 e2edc1f89ec1608b169da9e7ffc037190b70c7825f0be29694f4cae719980580 . Check the hash, whatever source you use. A launcher APK (optional) A second home app for maintenance. Nothing in this guide needs it, and the kiosk has no way to open it. Skip it and use ADB. Any launcher that runs on Android 6. The author tested Rootless Pixel Launcher ( amirz.rootless.nexuslauncher ) and does not provide a download. ISRG Root X1 certificate Android 6.0.1 does not trust Let's Encrypt. Without this, a Let's Encrypt site fails to load on the frame. letsencrypt.org/certs/isrgrootx1.pem Put the files in a folder outside the repository, for example ~/frame-files/ . Check the WebView hash: sha256sum ~/frame-files/webview.apk The WebView prebuilts and the Let's Encrypt root keep their own licenses.","url":"https://calevans.com/picture-frame/docs/provisioning/index.html#step-2-get-the-files-you-provide","tags":"","category":""},{"id":90,"title":"Step 3: Connect to the frame","pageTitle":"Build the kiosk and set up a frame","text":"Plug the frame into your computer and attach it to WSL ( usbipd attach --wsl --busid from PowerShell, as in the unlock guide). Then in WSL: adb devices adb shell id You expect uid=0(root) . All steps below work over USB ADB. After the kiosk is installed and the frame is on Wi-Fi (step 11), you can connect over the network instead: adb connect 192.0.2.50:5555 If both USB and network connections are open, add -s to adb and to scripts/provision.sh .","url":"https://calevans.com/picture-frame/docs/provisioning/index.html#step-3-connect-to-the-frame","tags":"","category":""},{"id":91,"title":"Step 4: Prepare the system partition","pageTitle":"Build the kiosk and set up a frame","text":"Wrap every /system change in a read-write remount and a read-only remount, and keep a .bak of any file you replace.","url":"https://calevans.com/picture-frame/docs/provisioning/index.html#step-4-prepare-the-system-partition","tags":"","category":""},{"id":92,"title":"Turn on ADB over Wi-Fi","pageTitle":"Build the kiosk and set up a frame","text":"adb shell 'mount -o remount,rw /system cp -p /system/build.prop /system/build.prop.bak echo service.adb.tcp.port=5555 >> /system/build.prop mount -o remount,ro /system'","url":"https://calevans.com/picture-frame/docs/provisioning/index.html#turn-on-adb-over-wi-fi","tags":"","category":""},{"id":93,"title":"Disable the vendor apps","pageTitle":"Build the kiosk and set up a frame","text":"com.yhk.qeota is the over-the-air updater. Do it first, and never press \"Check for updates\" in the stock app: an update could overwrite /system and undo your work. com.DeviceTest and com.android.gl2jni are factory leftovers. for p in com.yhk.qeota com.DeviceTest com.android.gl2jni; do adb shell \"am force-stop $p; pm disable $p; pm hide $p\" done Do not disable the stock home app, com.efercro.os.aimor , yet. Step 7 does it, after the kiosk is installed.","url":"https://calevans.com/picture-frame/docs/provisioning/index.html#disable-the-vendor-apps","tags":"","category":""},{"id":94,"title":"Install WebView 106","pageTitle":"Build the kiosk and set up a frame","text":"Android 6 does not unpack native libraries for apps in /system , and WebView 106 stores them compressed. So you unpack them on your computer and push them. mkdir -p ~/frame-files/webview-libs unzip -j ~/frame-files/webview.apk 'lib/armeabi-v7a/*.so' -d ~/frame-files/webview-libs adb push ~/frame-files/webview.apk /data/local/tmp/webview.apk adb push ~/frame-files/webview-libs /data/local/tmp/webview-libs adb shell 'mount -o remount,rw /system cp -p /system/app/webview/webview.apk /system/app/webview/webview.apk.bak cp /data/local/tmp/webview.apk /system/app/webview/webview.apk chmod 644 /system/app/webview/webview.apk rm -rf /system/app/webview/oat mkdir -p /system/app/webview/lib/arm cp /data/local/tmp/webview-libs/*.so /system/app/webview/lib/arm/ chmod 755 /system/app/webview/lib /system/app/webview/lib/arm chmod 644 /system/app/webview/lib/arm/* chown -R root:root /system/app/webview/lib mount -o remount,ro /system rm -r /data/local/tmp/webview.apk /data/local/tmp/webview-libs'","url":"https://calevans.com/picture-frame/docs/provisioning/index.html#install-webview-106","tags":"","category":""},{"id":95,"title":"Trust the Let's Encrypt root","pageTitle":"Build the kiosk and set up a frame","text":"Android looks up certificates by a hash of the subject, so the file name matters. Compute it: openssl x509 -inform PEM -subject_hash_old -noout -in ~/frame-files/isrgrootx1.pem It prints 6187b673 . Copy the certificate to that name with .0 on the end and install it: cp ~/frame-files/isrgrootx1.pem ~/frame-files/6187b673.0 adb push ~/frame-files/6187b673.0 /data/local/tmp/ adb shell 'mount -o remount,rw /system cp /data/local/tmp/6187b673.0 /system/etc/security/cacerts/ chmod 644 /system/etc/security/cacerts/6187b673.0 mount -o remount,ro /system rm /data/local/tmp/6187b673.0' If your server uses a certificate from another authority that Android 6 does not trust, install that root the same way, with the name from its own hash.","url":"https://calevans.com/picture-frame/docs/provisioning/index.html#trust-the-lets-encrypt-root","tags":"","category":""},{"id":96,"title":"Restart and check","pageTitle":"Build the kiosk and set up a frame","text":"adb reboot adb wait-for-device adb shell dumpsys package com.android.webview | grep versionName You expect versionName=106.0.5249.126 . Reconnect with adb disconnect and adb connect if you use ADB over the network: the old session shows \"device offline\" after a reboot. Keep a record Write down each change you make to a frame, with its undo. The .bak files above are the undo for build.prop and WebView.","url":"https://calevans.com/picture-frame/docs/provisioning/index.html#restart-and-check","tags":"","category":""},{"id":97,"title":"Step 5: Create your keys","pageTitle":"Build the kiosk and set up a frame","text":"Two keys, kept apart. You make both once, on your own computer, before your first build. Key What it is What it protects APK keystore An RSA key in a Java keystore. Signs the kiosk app. Android accepts an app update only if it is signed with the same key as the installed app. Release key An offline ECDSA P-256 key. Signs each release's SHA-256 and version code. A stolen server or admin login cannot push a build you did not sign. Update the kiosk explains how they work together.","url":"https://calevans.com/picture-frame/docs/provisioning/index.html#step-5-create-your-keys","tags":"","category":""},{"id":98,"title":"The APK keystore","pageTitle":"Build the kiosk and set up a frame","text":"If the keystore is missing, the build creates it with keytool on first use. To create it yourself first (same result), run this with your own password, which must equal KEYSTORE_PASS : mkdir -p ~/.android keytool -genkeypair -keystore ~/.android/frame-kiosk.keystore -alias frame \\ -keyalg RSA -keysize 2048 -validity 10000 -dname \"CN=Frame Kiosk\" keytool asks for the password. Use it for both the keystore and the key. Then: Back up the keystore file somewhere private. It is the only thing that lets you update the kiosk in place. Set it to chmod 600 , and keep it out of the repository.","url":"https://calevans.com/picture-frame/docs/provisioning/index.html#the-apk-keystore","tags":"","category":""},{"id":99,"title":"The release key","pageTitle":"Build the kiosk and set up a frame","text":"The private key must be an unencrypted PKCS#8 PEM, which is what openssl genpkey writes: openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out ~/.android/frame-release-key.pem openssl pkey -in ~/.android/frame-release-key.pem -pubout -out ~/.android/frame-release-pub.pem chmod 600 ~/.android/frame-release-key.pem Then set RELEASE_KEY and RELEASE_PUBKEY in .env to those two paths. The public key is baked into every build. If RELEASE_PUBKEY is missing, that build refuses every self-update. It fails closed and reports release_sig . If RELEASE_KEY is missing, no signature file is written. Either way the build itself works. If the two keys are not a pair, the build stops with RELEASE_KEY and RELEASE_PUBKEY are not a pair. To let the server check signatures too, put the contents of the public key file in config.php as kiosk_release_pubkey . It is optional. Keep the private key offline. Back it up somewhere private. Never put it on the server, in the repository, or in a container image. Losing it means one more adb install per frame with a new public key.","url":"https://calevans.com/picture-frame/docs/provisioning/index.html#the-release-key","tags":"","category":""},{"id":100,"title":"Step 6: Build the kiosk","pageTitle":"Build the kiosk and set up a frame","text":"Start the build container. The first run downloads and installs the tools: cd kiosk lando start Build: lando build-kiosk The script reads .env in the repository root, then: writes the server address, your owner name and the PIN hash into the app, creates the signing keystore at KEYSTORE if it does not exist, builds, aligns and signs kiosk/build/frame-kiosk.apk (with both the v1 and v2 signature schemes), if RELEASE_KEY is set, signs the build's SHA-256 and version code and writes kiosk/build/frame-kiosk.apk.sig . It prints built kiosk/build/frame-kiosk.apk , then the versionCode and sha256 . A line starting WARNING: means a release key setting is missing. That is fine for a first install, but set the release key before you rely on self-update .","url":"https://calevans.com/picture-frame/docs/provisioning/index.html#step-6-build-the-kiosk","tags":"","category":""},{"id":101,"title":"Build options","pageTitle":"Build the kiosk and set up a frame","text":"Lando does not pass your shell's environment through, so give options as arguments after -- : lando build-kiosk -- --version-code 15 --version-name 15 Option Environment variable What it does --version-code N KIOSK_VERSION_CODE The Android versionCode . A whole number from 1 to 2,100,000,000, no leading zero. Without it the build uses the value in kiosk/AndroidManifest.xml . Every release needs a higher number than the one before. --version-name S KIOSK_VERSION_NAME The label shown in the admin. Letters, digits, . , _ and - , up to 64 characters. Default: the version code. --test-crash KIOSK_TEST_CRASH=1 A build that crashes on purpose, for testing the rollback watchdog on your own frame. Never upload it as a real release. See Update the kiosk . The environment variables work only when you build without Lando.","url":"https://calevans.com/picture-frame/docs/provisioning/index.html#build-options","tags":"","category":""},{"id":102,"title":"Build without Lando","pageTitle":"Build the kiosk and set up a frame","text":"The build also works on a machine that has the tools. They are the Ubuntu packages the Lando container installs: sudo apt-get install --no-install-recommends aapt android-sdk-platform-23 apksigner dalvik-exchange zipalign openjdk-17-jdk-headless bash kiosk/build.sh --version-code 15 The native route was not tested for this page.","url":"https://calevans.com/picture-frame/docs/provisioning/index.html#build-without-lando","tags":"","category":""},{"id":103,"title":"Step 7: Install the kiosk and set device owner","pageTitle":"Build the kiosk and set up a frame","text":"scripts/provision.sh kiosk kiosk/build/frame-kiosk.apk Use -s before kiosk to pick a device, for example scripts/provision.sh -s 192.0.2.50:5555 kiosk ... . The script checks that the frame answers as root, then shows what it will do, and waits for y : adb install -r the APK, stop, disable and hide the stock home app, so the kiosk is the only home screen, make the kiosk the device owner , which turns on lock-task mode and blocks factory reset, safe boot and new users. If the kiosk is already the owner, it skips this. It stops with an error if there is more than one user or any account. To clear an account, run adb shell dumpsys account . It names the account type and the app that owns it. Remove the account in that app, or disable that app and reboot (Android drops accounts whose app is gone), then run the script again. It does not reboot the frame. Reboot it yourself, then check: adb reboot adb shell dumpsys device_policy | grep -A2 'Device Owner' adb shell dumpsys activity activities | grep -i locktask You expect the kiosk package and mLockTaskModeState=LOCKED . To update later, run adb install -r with a newly built APK signed with the same keystore, or from the admin . Uninstalling needs Undo device owner first. If the Wi-Fi picker shows no networks, Android 6 may be hiding scan results because location is off. The kiosk normally turns it on. If not: adb shell settings put secure location_providers_allowed +network","url":"https://calevans.com/picture-frame/docs/provisioning/index.html#step-7-install-the-kiosk-and-set-device-owner","tags":"","category":""},{"id":104,"title":"Step 8: Set the clock source","pageTitle":"Build the kiosk and set up a frame","text":"The frame has no battery-backed clock. Tell it which time server and time zone to use: scripts/provision.sh time It needs NTP_SERVER and TZ in .env . After confirmation it runs settings put global ntp_server and sets persist.sys.timezone , then prints both values back.","url":"https://calevans.com/picture-frame/docs/provisioning/index.html#step-8-set-the-clock-source","tags":"","category":""},{"id":105,"title":"Step 9: Install the boot script","pageTitle":"Build the kiosk and set up a frame","text":"The boot script is device/frame-fixmac.sh . It runs as root on every boot. Install it after the kiosk, because it hands the backlight to the kiosk's user ID.","url":"https://calevans.com/picture-frame/docs/provisioning/index.html#step-9-install-the-boot-script","tags":"","category":""},{"id":106,"title":"Optional: keep a specific MAC address","pageTitle":"Build the kiosk and set up a frame","text":"The Wi-Fi chip has no MAC address of its own, so the script gives each frame a fixed one: on first run it generates a random locally administered address and stores it in /data/misc/frame/mac . To use a particular address instead (for an existing DHCP reservation), set it before you install the script: adb shell 'mkdir -p /data/misc/frame; chmod 700 /data/misc/frame echo > /data/misc/frame/mac chmod 600 /data/misc/frame/mac' A factory reset deletes the file. Reserve the frame's address in your DHCP server either way.","url":"https://calevans.com/picture-frame/docs/provisioning/index.html#optional-keep-a-specific-mac-address","tags":"","category":""},{"id":107,"title":"Install the script","pageTitle":"Build the kiosk and set up a frame","text":"scripts/provision.sh boot-script The command stops early if ADB_ALLOW holds anything other than IPv4 addresses and ranges, or if the frame has no timeout command (the rollback watchdog needs it). After confirmation it: writes /system/etc/frame.conf with the kiosk package and your ADB_ALLOW , keeps any older script as /system/bin/frame-fixmac.sh.v , installs device/frame-fixmac.sh as /system/bin/frame-fixmac.sh (0755 root:shell, so the kiosk can read its watchdog marker), backs up install-recovery.sh as .bak and adds one line: exec /system/bin/sh /system/bin/frame-fixmac.sh . Android runs that file as root at every boot. The line must be exec , because Android kills background children, checks the installed script against the repository copy. It ends with \"Installed and verified.\" The script takes effect after a reboot. Run it again after you change ADB_ALLOW . To undo it, restore the old frame-fixmac.sh.v and remove /system/etc/frame.conf .","url":"https://calevans.com/picture-frame/docs/provisioning/index.html#install-the-script","tags":"","category":""},{"id":108,"title":"What the boot script does","pageTitle":"Build the kiosk and set up a frame","text":"Watch it work with adb logcat -d -s frame-fixmac . Feature What it does Pins the Wi-Fi MAC The Wi-Fi driver ignores a configured address and picks a random one on every load. The script sets the stored one, checks every second for the first two minutes, then every 10 seconds. Android restarts Wi-Fi once during boot, so the log shows two corrections and two short Wi-Fi drops. Hands the backlight to the kiosk It gives the kiosk's user ID ownership of /sys/class/disp/disp/attr/lcdbl on every boot. Without it, the Dim button only lowers brightness to 1 percent, under a black screen, instead of turning the backlight off. Check with adb shell stat -c %u /data/data/com.calevans.frame . The log line is lcdbl -> uid N . If you uninstall and reinstall the kiosk (not install -r ), it gets a new user ID. Reboot afterwards. Restores the clock After a power cut the frame starts in 1969. The script saves the time to /data/misc/frame/clock (every minute for the first two minutes after boot, then about every 10 minutes). If the frame starts with a clock before 2024, it sets the saved time, so HTTPS works before NTP answers. With no saved time, it restarts the kiosk once NTP has set the year. Look for clock restored in the log. Limits ADB over Wi-Fi With ADB_ALLOW set, it builds an iptables chain that lets only those IPv4 addresses reach TCP port 5555 and drops the rest, including all of IPv6. Android's network service clears the rule when it starts, so the script puts it back whenever it goes missing. USB ADB is never filtered. With ADB_ALLOW empty, the list is off. Fails closed on a bad entry If one ADB_ALLOW entry is not a valid IPv4 address or range, the script allows nobody over Wi-Fi (only the frame itself), logs bad ADB_ALLOW entry , and you must use USB ADB to fix it. Recovers from the Home chooser Every 30 seconds, it checks whether Android is showing the \"Complete action using\" chooser (which appears if the default home app is lost) and starts the kiosk if so. Rolls back a bad kiosk update The watchdog. See Update the kiosk . It needs timeout and dd from the frame's toolbox. Note The clock restore step is unverified on the tested firmware: the exact date syntax is assumed.","url":"https://calevans.com/picture-frame/docs/provisioning/index.html#what-the-boot-script-does","tags":"","category":""},{"id":109,"title":"Step 10: Make the boot logo and animation (optional)","pageTitle":"Build the kiosk and set up a frame","text":"Start from a 1280x800 PNG. Back up the stock files first: adb pull /system/media/bootanimation.zip stock-bootanimation.zip adb pull /bootloader/bootlogo.bmp stock-bootlogo.bmp","url":"https://calevans.com/picture-frame/docs/provisioning/index.html#step-10-make-the-boot-logo-and-animation-optional","tags":"","category":""},{"id":110,"title":"Animation","pageTitle":"Build the kiosk and set up a frame","text":"Android shows the animation while it starts: php tools/make-bootanimation.php my-logo-1280x800.png bootanimation.zip adb push bootanimation.zip /data/local/tmp/ adb shell 'mount -o remount,rw /system cp /data/local/tmp/bootanimation.zip /system/media/bootanimation.zip chmod 644 /system/media/bootanimation.zip chown root:root /system/media/bootanimation.zip mount -o remount,ro /system rm /data/local/tmp/bootanimation.zip' The script writes an uncompressed zip, which Android's player requires. It shows one image until the frame has booted.","url":"https://calevans.com/picture-frame/docs/provisioning/index.html#animation","tags":"","category":""},{"id":111,"title":"Logo","pageTitle":"Build the kiosk and set up a frame","text":"The bootloader shows the logo before Android starts. The panel is 800x1280 and used rotated, so rotate the image first. With ImageMagick on your own computer: convert my-logo-1280x800.png -resize 1280x800^ -gravity center -extent 1280x800 -rotate 90 -type TrueColor -alpha off BMP3:bootlogo.bmp The result is an 800x1280, 24-bit BMP of 3,072,054 bytes. Copy it over /bootloader/bootlogo.bmp on the small FAT partition mounted at /bootloader : adb push bootlogo.bmp /data/local/tmp/ adb shell 'cp /data/local/tmp/bootlogo.bmp /bootloader/bootlogo.bmp; rm /data/local/tmp/bootlogo.bmp' If /bootloader is read-only, remount it read-write first. This was not needed or checked. Do not leave a System Volume Information folder there if you ever mounted that partition on Windows: delete it. To go back, push your saved stock-bootanimation.zip and stock-bootlogo.bmp the same way.","url":"https://calevans.com/picture-frame/docs/provisioning/index.html#logo","tags":"","category":""},{"id":112,"title":"Step 11: Connect to Wi-Fi and claim the frame","pageTitle":"Build the kiosk and set up a frame","text":"Reboot the frame: adb reboot . The kiosk opens its Wi-Fi picker on its own when the frame has no saved network and stays offline for 30 seconds. Select your network and enter the password. Other network... lets you type a hidden network's name. When the frame reaches your server, it shows a six-digit pairing code (\"Read this code to ...\", using OWNER_NAME ). In the admin at https://frames.example.com/frames/admin/ , sign in and select Claim a frame . Enter the six-digit code, select Find frame , enter a name for the frame, then select Claim frame . You see \"Claimed. Turn on the widgets you want.\" The code is valid for 24 hours. See Use the admin for the details. Open the frame in the admin and turn on the widgets you want under Widgets . The frame loads its display within a minute. Widgets covers each one. To give the frame its own PIN, open the frame, go to Security , enter a New PIN and select Set PIN . Without one, the frame uses the KIOSK_PIN from the build. Reset to factory PIN goes back to it. To connect over the network from now on, find the frame's address in your router and run adb connect 192.0.2.50:5555 .","url":"https://calevans.com/picture-frame/docs/provisioning/index.html#step-11-connect-to-wi-fi-and-claim-the-frame","tags":"","category":""},{"id":113,"title":"Updates after you claim","pageTitle":"Build the kiosk and set up a frame","text":"When you claim a frame, the server points it at the newest release that has already run on a frame, and the frame moves itself to that release when its screen is quiet. If no release has run on a frame yet (a brand-new install), the frame stays on the build you installed. See Update the kiosk .","url":"https://calevans.com/picture-frame/docs/provisioning/index.html#updates-after-you-claim","tags":"","category":""},{"id":114,"title":"The maintenance panel","pageTitle":"Build the kiosk and set up a frame","text":"The kiosk has no on-screen exit by design. A hidden panel offers the few things you need on site. Hold one finger in the top-left corner of the screen (the first 120x120 pixels) for 10 seconds. A PIN pad opens. The hold works while the screen is dark. Enter the PIN. An info panel opens with the frame ID, app version, state, last server contact, network details and uptime. The panel offers Wi-Fi , Reload and Back , and nothing else. After five wrong PINs in a row the pad locks for 5 minutes. Each further five wrong PINs lengthens the lock: 30 minutes, 2 hours, then 8 hours. A reboot during a lock restarts the lock from the beginning.","url":"https://calevans.com/picture-frame/docs/provisioning/index.html#the-maintenance-panel","tags":"","category":""},{"id":115,"title":"What the kiosk does","pageTitle":"Build the kiosk and set up a frame","text":"For reference, so nothing surprises you: It is the home app. It runs full screen, stays on, and stays landscape. It shows \"Setting the clock...\" until the year is set, and a \"Can't reach ...\" screen with the network name, address and frame ID while offline. It opens the Wi-Fi picker by itself, with no PIN, when it has no saved network and has been offline for 30 seconds after boot, or when saved networks have not connected for five minutes. It closes the picker again if the old network returns while nobody is touching it. Dim (the moon on the dashboard) turns the backlight fully off. The next tap wakes it and does not reach the page. The 10 second top-left hold works while dark. It follows the frame's bedtime and wake schedule from the admin, in the frame's time zone, and saves it so it works offline. It keeps the day's photos in its own storage, so they keep showing when the network or the photo host is down.","url":"https://calevans.com/picture-frame/docs/provisioning/index.html#what-the-kiosk-does","tags":"","category":""},{"id":116,"title":"Undo device owner","pageTitle":"Build the kiosk and set up a frame","text":"dpm remove-active-admin refuses to remove a device owner on Android 6, and there is no screen for it. The kiosk has a hidden receiver that only root can call: adb shell am broadcast -n com.calevans.frame/.AdbReceiver -a com.calevans.frame.action.RELEASE_DEVICE_OWNER The result line says device owner released . After that, adb shell pm uninstall com.calevans.frame works. If the app is broken and cannot receive the broadcast, delete the policy files as root and reboot. This is untested. Restrictions the owner set may remain in /data/system/users/0.xml , so check adb shell dumpsys user afterwards: adb shell rm /data/system/device_owner.xml /data/system/device_policies.xml","url":"https://calevans.com/picture-frame/docs/provisioning/index.html#undo-device-owner","tags":"","category":""},{"id":117,"title":"Give a frame away","pageTitle":"Build the kiosk and set up a frame","text":"The kiosk has your server's address built in. Handing over the hardware does not hand over independence. Choose what the new owner gets: The frame stays on your server. Claim it for them in your admin. They never need ADB. The new owner runs their own server. They need their own kiosk build, signed with their own keystore. Android will not replace your build with theirs, so first undo device owner and uninstall the kiosk, then they run this guide from step 5 . USB ADB is always open for this. Either way, before you hand it over: In your admin, revoke the frame ( More , then Revoke ) or delete it, so your server stops serving it. Remove your saved Wi-Fi networks. This ends ADB over Wi-Fi, so USB ADB must still work: adb shell am broadcast -n com.calevans.frame/.AdbReceiver -a com.calevans.frame.action.FORGET_WIFI The result line says removed N of N saved networks . Within about a minute the kiosk opens its Wi-Fi picker, which is what the new owner sees. Power the frame off with adb shell reboot -p . If Wi-Fi is off, the broadcast says so. Run adb shell svc wifi enable , wait a few seconds, and try again.","url":"https://calevans.com/picture-frame/docs/provisioning/index.html#give-a-frame-away","tags":"","category":""},{"id":118,"title":"Related","pageTitle":"Build the kiosk and set up a frame","text":"Unlock your PF1007L Install the frame server Update the kiosk Troubleshooting and recovery , including common ADB gotchas Next: Widgets .","url":"https://calevans.com/picture-frame/docs/provisioning/index.html#related","tags":"","category":""},{"id":119,"title":"Hardware and requirements","pageTitle":"Hardware and requirements","text":"This page is for anyone deciding whether to start. It says which frame this project supports, what the frame is, and everything you need to gather before you begin. When you finish reading, you know whether your frame qualifies and what to have on hand.","url":"https://calevans.com/picture-frame/docs/hardware/index.html","tags":"","category":""},{"id":120,"title":"Supported frame","pageTitle":"Hardware and requirements","text":"The project supports one frame model: the PF1007L . Property Value Model PF1007L Screen 10.1 inch, 1280 x 800 landscape. The panel itself is 800 x 1280 and used rotated. Processor Allwinner A33 Operating system Android 6.0.1 Storage eMMC. The tested unit is 15,758,000,128 bytes. Power USB-C. The same cable carries data to your PC. Case You never open it. You never solder.","url":"https://calevans.com/picture-frame/docs/hardware/index.html#supported-frame","tags":"","category":""},{"id":121,"title":"Firmware that was tested","pageTitle":"Hardware and requirements","text":"The unlock was verified on one firmware build only: AEEZO/astar_m86_8723cs:6.0.1/MOB30R/20260113:eng/test-keys That is a January 2026 build. Other builds may store files in different places. The unlock procedure builds its patch from a backup of your own frame, so it adapts to small differences. Nothing is verified on other builds. The tools stop with an error when they do not recognize what they find. If one stops, stop too and work out why before you go on. Do not guess. After the unlock, you can read your own build with adb shell getprop ro.build.fingerprint . This is a standard Android property. It was not checked as part of writing this page.","url":"https://calevans.com/picture-frame/docs/hardware/index.html#firmware-that-was-tested","tags":"","category":""},{"id":122,"title":"Brand names","pageTitle":"Hardware and requirements","text":"The PF1007L is sold under more than one name. Names seen so far include Humblestead and AiMOR . The stock home app on the frame is the AiMOR launcher ( com.efercro.os.aimor ), which the kiosk setup later disables. If you are unsure your frame is a PF1007L, the unlock guards against a mismatch. The scripts that write to the frame accept only a USB disk of the expected size, and the patch step refuses to write unless the sector on the frame is exactly the one it expects.","url":"https://calevans.com/picture-frame/docs/hardware/index.html#brand-names","tags":"","category":""},{"id":123,"title":"Where to buy","pageTitle":"Hardware and requirements","text":"The frames this project was built and tested on came from this Amazon listing, bought in October 2026: Digital Picture Frame 10.1 inch, 32GB, 1280 x 800 IPS touchscreen, Wi-Fi, AiMOR app This is a plain link: the project earns nothing from it. Listings change, and a seller can ship a different board or firmware under the same page, so check the frame when it arrives, before you start: The label on the back says PF1007L , and the FCC ID is 2AW9M-PF1007 . The stock app is AiMOR . The screen is 1280 x 800 and the frame runs Android 6. If any of these differ, stop: the unlock may not fit your frame. See Firmware that was tested and Other frames .","url":"https://calevans.com/picture-frame/docs/hardware/index.html#where-to-buy","tags":"","category":""},{"id":124,"title":"What changes on the frame","pageTitle":"Hardware and requirements","text":"Understand these before you begin: You give up vendor support. The vendor's over-the-air updater is disabled and the vendor app is replaced. There is no going back to a warranty claim. The frame becomes a kiosk. It runs one app, full screen, with no status bar, no navigation bar and no on-screen exit. Root ADB has no password. After the unlock, anyone who can reach port 5555 on the frame controls it. The boot script can limit that to addresses you list. See Provisioning, step 9 . The frame talks to your server only. It does not contact the manufacturer once the vendor updater is disabled.","url":"https://calevans.com/picture-frame/docs/hardware/index.html#what-changes-on-the-frame","tags":"","category":""},{"id":125,"title":"For the unlock","pageTitle":"Hardware and requirements","text":"You need Used for A PF1007L and its USB-C cable The frame itself. A Windows 10 or 11 PC with WSL2 (Ubuntu 22.04 or later) The unlock scripts call powershell.exe and PowerShell disk commands, so they do not run on a plain Linux machine without changes. usbipd-win 4 or later Passing the frame's USB connection into WSL. A microSD card, any size Booting the frame into its USB recovery mode (FEL). Its contents survive. The guide changes only bytes 8 KiB to 16 KiB. About 16 GB of free disk space The verified backup of the frame's storage. About 90 minutes of waiting The backup alone takes that long. A PowerShell and a WSL shell, both open You switch between them. These Linux packages are installed during the unlock: sunxi-tools , adb , e2fsprogs , fdisk , and an ARM cross-compiler with other U-Boot build tools (listed in the guide).","url":"https://calevans.com/picture-frame/docs/hardware/index.html#for-the-unlock","tags":"","category":""},{"id":126,"title":"For the server","pageTitle":"Hardware and requirements","text":"You need Used for A Linux host with Apache 2.4 The server runs on any Linux host. A host name with a valid HTTPS certificate The kiosk refuses plain HTTP, and the admin refuses to run without an https:// address. PHP 8.5 with pdo_sqlite , curl , mbstring , gd , dom , xmlreader , xmlwriter , zlib The server code. See Install the frame server for optional extensions. Composer One library, sabre/vobject , which reads calendars. A cron user and the web server's user Running the fetcher and the web app. sudo rights Creating folders and running commands as the web user. Optional: bubblewrap , libheif-examples , libheif-plugin-libde265 , prlimit , nice The local photo library. See Photos .","url":"https://calevans.com/picture-frame/docs/hardware/index.html#for-the-server","tags":"","category":""},{"id":127,"title":"For the kiosk","pageTitle":"Hardware and requirements","text":"You need Used for Docker and Lando Building the kiosk app with the included Lando setup (or install the JDK and Android build tools yourself). adb , openssl , unzip , php Provisioning and release signing. A WebView APK, a Let's Encrypt root certificate, and optionally a launcher Files you download yourself. See Provisioning, step 2 .","url":"https://calevans.com/picture-frame/docs/hardware/index.html#for-the-kiosk","tags":"","category":""},{"id":128,"title":"Other things worth having","pageTitle":"Hardware and requirements","text":"A DHCP reservation for the frame in your router. The boot script gives the frame a fixed Wi-Fi MAC address so a reservation holds. A Nextcloud or Home Assistant , if you want to use those widgets. Neither is required. Somewhere private to keep two keys. The kiosk signing keystore and the release key must be backed up and kept off the server. See Update the kiosk .","url":"https://calevans.com/picture-frame/docs/hardware/index.html#other-things-worth-having","tags":"","category":""},{"id":129,"title":"Know before you start","pageTitle":"Hardware and requirements","text":"Weather is US-only. It comes from the US National Weather Service. You need a terminal. You run shell and PowerShell commands, build an Android app, run a PHP site on Apache with a real HTTPS certificate, and add a cron job. The backup is private. It holds the vendor's device certificate. Keep backups/ out of Git and never share it. Never redistribute vendor firmware or dumps. This repository ships none.","url":"https://calevans.com/picture-frame/docs/hardware/index.html#know-before-you-start","tags":"","category":""},{"id":130,"title":"Other frames","pageTitle":"Hardware and requirements","text":"This project is built for the PF1007L. The U-Boot patch is specific to this board, the kiosk is written for Android 6 on this screen, and the unlock was checked on one firmware build. None of it has been tested on other frames, and you should not expect it to work on them. If you have a different frame, wesbos/photo-frame-dashboard covers other models. It inspired this project. No code or text is copied from it. Next: Unlock your PF1007L .","url":"https://calevans.com/picture-frame/docs/hardware/index.html#other-frames","tags":"","category":""},{"id":131,"title":"Photos","pageTitle":"Photos","text":"This page is for the person who decides which photos a frame shows. It covers all three ways to get photos onto a frame, how the frame picks each day's set, and how the server protects itself when it opens pictures that strangers send. When you finish, a frame is showing photos from the source you chose.","url":"https://calevans.com/picture-frame/docs/photos/index.html","tags":"","category":""},{"id":132,"title":"Choose a method","pageTitle":"Photos","text":"A frame's Photos widget has one source at a time. Pick one: Method 1: Nextcloud album Method 2: photo library Method 3: family drop links Where photos live Your Nextcloud Your frame server Your frame server, in a library album Who adds photos Anyone who can add to the Nextcloud album You, from your computer Relatives, from their phones, with your approval Extra server software None GD, and ideally a sandbox. HEIC support needs libheif. The same as method 2 Needs the fetcher Yes No No Setup effort A few minutes An album and a decoder check Method 2, plus a link per person Methods 2 and 3 share the library. Drop links add photos to a library album, so you need method 2 first. You can use methods 1 and 2 on different frames. You can also switch a frame between them. The frame keeps the Nextcloud link while it points at the library, and finds it again when you switch back.","url":"https://calevans.com/picture-frame/docs/photos/index.html#choose-a-method","tags":"","category":""},{"id":133,"title":"How a frame picks its photos","pageTitle":"Photos","text":"The frame shows a daily set . Understanding the rules explains why a new photo may not show up straight away. 50 photos a day. If the album has 50 photos or fewer, the frame shows all of them every day. The newest first. Up to 25 of the set are the newest photos added in the last 30 days. No repeats until the album is used up. The rest are chosen at random from photos this frame has not shown in the current pass through the album. When none are left, a new pass begins. Approved photos only. Photos waiting for your approval never reach a frame. Once a day. The set is fixed until the next pick time. Photos you add after the pick can appear in the next day's set. Pick time. Each frame gets its own time between 04:00 and 06:00 in its time zone, chosen so no two frames pick at the same moment. You can change it with New photos daily at . If another frame already uses that exact minute, the admin says \"Another frame uses this exact time. Move it a minute earlier or later.\" Kept on the frame. The frame downloads each photo (up to 4 MB each) and stores it. They keep showing when the network or the photo host is down. The frame skips downloads while it has less than 200 MB free. Where they show. On the screensaver, which starts after the idle time you set under Schedule , and on the Pictures page. In the admin, the frame's Photos section shows the day's picks as a contact sheet: New today and Carried over , with the time of the next pick. Setting a different source or album for a frame starts a new pass and a new pick.","url":"https://calevans.com/picture-frame/docs/photos/index.html#how-a-frame-picks-its-photos","tags":"","category":""},{"id":134,"title":"Method 1: A Nextcloud public album","pageTitle":"Photos","text":"The Photos widget shows a public Nextcloud Photos album. The fetcher on your server keeps a list of the album's photos. The frame loads the images from Nextcloud itself.","url":"https://calevans.com/picture-frame/docs/photos/index.html#method-1-a-nextcloud-public-album","tags":"","category":""},{"id":135,"title":"What you need","pageTitle":"Photos","text":"A Nextcloud with the Photos app. The Nextcloud host in photo_hosts in config.php , for example 'cloud.example.org' . See Install the frame server . The fetcher cron job running. See Install the frame server . A Nextcloud that the frame can reach. The frame loads previews straight from the Nextcloud host, so it must be reachable from the frame's network.","url":"https://calevans.com/picture-frame/docs/photos/index.html#what-you-need","tags":"","category":""},{"id":136,"title":"Set it up","pageTitle":"Photos","text":"In Nextcloud, share the album with a public link and copy the link. It looks like https://cloud.example.org/apps/photos/public/ . A link with /index.php/apps/photos/public/ also works. In the admin, open the frame, then Widgets , switch Photos on, and select Save . Open the Photos section. Under Photos come from , choose Nextcloud link . Paste the link into Album link . Check New photos daily at , and Show each photo for . Select Save . Under Album link the admin shows a status: the number of photos once the fetcher has run, Not fetched yet until then, or an error message. The link is stored on the server and never shown again. The field shows \"A link is saved. Paste a new one to replace it.\" Use Remove link to delete it, or Keep link to cancel the removal.","url":"https://calevans.com/picture-frame/docs/photos/index.html#set-it-up","tags":"","category":""},{"id":137,"title":"What it uses","pageTitle":"Photos","text":"The fetcher lists the album over WebDAV and refreshes the list about every 15 minutes. It keeps up to 2000 photos from an album. It sees JPEG, PNG, and HEIC or HEIF files. Other file types in the album are ignored. The frame loads 1280x800 previews from Nextcloud. The photos' \"newest\" order uses when the server first saw each photo in the album.","url":"https://calevans.com/picture-frame/docs/photos/index.html#what-it-uses","tags":"","category":""},{"id":138,"title":"Method 2: The photo library","pageTitle":"Photos","text":"The photo library keeps photos on your server instead of on Nextcloud. You make albums , add photos from your computer, and point a frame at an album. The server keeps only frame-sized copies. Each photo is shrunk to fit 1280x800 (never enlarged), its metadata (location, camera, date) is removed, and a 320x200 thumbnail is made. The original is not kept. You can skip the library if you use Nextcloud only. It is off until its host requirements are met, and nothing else on the server depends on it.","url":"https://calevans.com/picture-frame/docs/photos/index.html#method-2-the-photo-library","tags":"","category":""},{"id":139,"title":"What the server needs","pageTitle":"Photos","text":"Image decoding is the risky part of any upload feature. The server decodes in a separate, limited process, and refuses anything but JPEG, PNG, WebP and HEIC. It needs: PHP's GD extension for the command-line PHP, with JPEG, PNG and WebP support (package php8.5-gd ; a plain php-gd can pull in another PHP version's GD). Check: php -n -d extension=gd -r 'print_r(gd_info());' It must show JPEG Support , PNG Support and WebP Support as 1 . For iPhone (HEIC) photos: libheif's command-line converter and its HEVC decoder: sudo apt install libheif-examples libheif-plugin-libde265 heif-dec --version || heif-convert --version heif-convert , the older name of the same tool, also works. Ubuntu 24.04 (libheif 1.17) ships only heif-convert . Without them everything else still works and HEIC uploads are refused. prlimit (package util-linux ) and nice (package coreutils ). Both are on most Linux servers. A PHP command-line binary. The worker runs php , not the web server's PHP. The server looks for the one running this command, then /usr/bin/php8.5 , /usr/bin/php , /usr/local/bin/php . If yours is elsewhere, set 'php_binary' . See Limits and config keys . A sandbox, unless you choose to run without one. See Sandbox modes . Minimum versions of the libraries that read untrusted images. Older ones have known memory-safety bugs a hostile image can reach. Debian and Ubuntu fix them under the old version number, so a lower number can still be patched. Keep security updates on. Library Minimum libheif 1.17.6 (Ubuntu 24.04 ships it in main) libde265 A version with the current security fixes. Keep updates on. libwebp 1.3.2 libjpeg, libpng (inside PHP's GD) Current distribution security updates. If php_binary or heif_dec points outside /usr , its installation prefix (the directory two levels up, for example /opt/php for /opt/php/bin/php ) is bound read-only into the bubblewrap sandbox. That prefix must not contain secrets. bin/migrate.php checks all of this. See Troubleshooting .","url":"https://calevans.com/picture-frame/docs/photos/index.html#what-the-server-needs","tags":"","category":""},{"id":140,"title":"Why no ImageMagick","pageTitle":"Photos","text":"The library does not use ImageMagick or php-imagick . On Ubuntu 24.04, ImageMagick and php-imagick sit in the universe repository, and universe gets security updates only with Ubuntu Pro. The decoders the library uses instead ( libheif , libde265 , libwebp , GD) come from main , which gets free security updates. Check where a package lives with apt-cache policy libheif-examples . The line for your release says main or universe . If nothing else on the host needs ImageMagick, sudo apt remove --simulate php8.5-imagick shows what you could remove.","url":"https://calevans.com/picture-frame/docs/photos/index.html#why-no-imagemagick","tags":"","category":""},{"id":141,"title":"How the decoder works","pageTitle":"Photos","text":"Every upload goes through the same pipeline, from the admin or from a drop link: The server decides the file type from the first bytes, not from the file name. SVG, AVIF and similar are refused. JPEG, PNG and WebP are decoded by PHP's GD in a separate process with no network. With a sandbox on, it sees only system libraries and its scratch folder. It runs under prlimit (1 GiB of address space, 60 CPU seconds, 32 open files), nice , and a wall-clock kill after 45 seconds. Image sizes are read from the file headers first. Anything over 12,000 pixels on a side or 64 megapixels is refused before decoding. HEIC takes three steps in the same sandbox: a header check, heif-dec converting to a PNG in the scratch folder (it applies the photo's rotation itself), and GD reading that PNG. Each decoder step is killed after 45 seconds. A whole HEIC upload (header check, conversion and resize) shares one 60-second deadline. The photo's EXIF orientation is applied to JPEGs. Photos are always saved as plain sRGB baseline JPEGs with no metadata. Color profiles are not converted. A Display P3 photo (iPhone) is shown as sRGB and looks slightly less saturated. CMYK JPEGs are refused ( unsupported_color : export as sRGB), and so are animated WebPs ( unsupported_animation ). Cut-off JPEG files are refused.","url":"https://calevans.com/picture-frame/docs/photos/index.html#how-the-decoder-works","tags":"","category":""},{"id":142,"title":"Sandbox modes","pageTitle":"Photos","text":"The decoder runs a program on files that strangers can send. The sandbox limits the damage if that program has a bug. You choose the mode with the sandbox option under widgets > photos in config.php . There are four modes. Mode Setting Use it when bubblewrap 'sandbox' => 'bwrap' (the default) bwrap works on your server. It is the simplest strong option. Dedicated user 'sandbox' => 'user' bwrap does not work, for example on Ubuntu 24.04. Recommended there. Automatic 'sandbox' => 'auto' You want bwrap when it works and no sandbox otherwise. The migration prints a NOTE when it falls back. Not for drop links. None 'sandbox' => 'none' You are the only one who uploads, and you accept the risk. Not for drop links. With a mode that is required ( bwrap or user ) and not working, uploads are refused with sandbox_unavailable . They are never run unprotected. Frames keep showing photos already stored.","url":"https://calevans.com/picture-frame/docs/photos/index.html#sandbox-modes","tags":"","category":""},{"id":143,"title":"Sandbox mode bwrap: bubblewrap","pageTitle":"Photos","text":"bwrap is the default. Install it: sudo apt install bubblewrap The image worker then runs in its own namespaces with no network. It sees only system libraries, its own code and one scratch folder. It cannot see config.php , frames.db or sessions.","url":"https://calevans.com/picture-frame/docs/photos/index.html#sandbox-mode-bwrap-bubblewrap","tags":"","category":""},{"id":144,"title":"When bwrap works","pageTitle":"Photos","text":"It works where the kernel lets unprivileged programs create user namespaces. Most Debian and Ubuntu 22.04 servers allow it.","url":"https://calevans.com/picture-frame/docs/photos/index.html#when-bwrap-works","tags":"","category":""},{"id":145,"title":"When Ubuntu 24.04 blocks it","pageTitle":"Photos","text":"Ubuntu 24.04 turns unprivileged user namespaces off for programs without an AppArmor profile ( kernel.apparmor_restrict_unprivileged_userns=1 ). bwrap then fails with setting up uid map: Permission denied . To tell whether this is your problem: Run the migration and read the output: sudo -u www-data php /srv/frame/app/bin/migrate.php A line like WARNING (photos): photo uploads are off: the bubblewrap sandbox is required ... but cannot run here means bwrap is not usable. Check the kernel setting: sysctl kernel.apparmor_restrict_unprivileged_userns = 1 means the restriction is on. The setting does not exist on older kernels. Look in the PHP error log for frame photos: worker failed . The line includes the first 300 characters of the error, which would hold uid map . Instead of loosening the system for every program, use the dedicated-user mode on Ubuntu 24.04. The result of the bwrap self-test is remembered for 10 minutes if it fails and an hour if it works. After you fix something, delete /srv/frame/var/photos/.sandbox-state and .probe-ok to check again at once.","url":"https://calevans.com/picture-frame/docs/photos/index.html#when-ubuntu-2404-blocks-it","tags":"","category":""},{"id":146,"title":"Sandbox mode user: a dedicated decoder account","pageTitle":"Photos","text":"Instead of namespaces, run the decoder as a separate, powerless Unix user. Set 'sandbox' => 'user' under widgets > photos in config.php , and do the one-time setup below as root ( sudo -i ). What the setup creates: A system user framephoto (no login shell, no home, not in the web user's group) and a group photowork that the web user joins. The group is used for one thing only: the per-upload work folder (mode 2770) and the uploaded file (0640) under var/photos/tmp/ . A root-owned script, /usr/local/bin/frame-photo-run (copied from app/widgets/photos/bin/ ), which is the only thing the web user may run as framephoto . It accepts nothing but a time limit (1 to 45 seconds) and paths inside one per-upload folder (32 hex characters under var/photos/tmp/ ). It runs the PHP worker or the HEIC converter with fixed programs, under prlimit and timeout -k 2 -s KILL . One call runs at a time (a lock file, /etc/frame-photo-run.lock ). When it ends, or is stopped, it kills every process still owned by framephoto , so a hijacked decoder cannot leave a daemon behind. Where PHP, the worker and var/ are comes from /etc/frame-photo-run.conf (root-owned KEY=/path lines; parsed, never run as shell). A sudoers rule with no wildcards: www-data ALL=(framephoto) NOPASSWD: /usr/local/bin/frame-photo-run . ACLs: framephoto may walk through var/ and var/photos/ (execute only: it cannot list or read them), and the photowork group may walk through var/photos/tmp/ . It may read only the photo widget's own files in the app ( app/widgets/photos/ ), through an ACL (plus a default ACL for files a later deploy adds), so your deploy permissions stay unchanged. It cannot read config.php , frames.db , sessions, stored photos or other uploads in progress. A firewall rule that rejects every connection made by framephoto (IPv4 and IPv6, loopback included), kept across reboots. The script never installs or removes a firewall manager . With ufw active, the rule goes into ufw's own before.rules and before6.rules (before its loopback accept) and ufw is reloaded. If netfilter-persistent is already installed, it saves the iptables rule. Otherwise a small systemd unit ( frame-photo-firewall.service ) inserts it at boot. The server tests this: its self-test makes the decoder user try to connect to a port the web side listens on, and anything but a refusal turns uploads off. If any part is missing, uploads are refused ( sandbox_unavailable ) rather than run unprotected, and bin/migrate.php says what failed. Change the paths in the first lines of the script if yours differ. You can run the script again safely. sh #!/bin/sh # Run as root (sudo -i). Safe to run again. Paths are the only thing to adjust. set -eu APP=/srv/frame/app VAR=/srv/frame/var PHP=/usr/bin/php8. 5 HEIF=/usr/bin/heif-dec # /usr/bin/heif-convert on Ubuntu 24.04 (libheif 1.17 has no heif-dec) WEB=www-data # 1. packages: sudo, ACL tools, util-linux (flock, runuser), iptables, and the HEIC converter. This never installs or removes a firewall manager. export DEBIAN_FRONTEND=noninteractive apt-get install -y sudo acl util-linux iptables libheif-examples libheif-plugin-libde265 # 2. the decoder user and the shared group (the web user joins the group; the decoder user is not in the web user's group) getent group photowork >/dev/null || groupadd --system photowork id framephoto >/dev/null 2 >& 1 || useradd --system --no-create-home --home-dir /nonexistent --shell /usr/sbin/nologin --gid photowork framephoto id -nG \"$WEB\" | tr ' ' '\\n' | grep -qx photowork || usermod -aG photowork \"$WEB\" # 3. the wrapper (root-owned, so the web user cannot change what runs as framephoto), its config and its lock file install -o root -g root -m 0755 \"$APP/widgets/photos/bin/frame-photo-run\" /usr/local/bin/frame-photo-run cat > /etc/frame-photo-run.conf < /etc/frame-photo-run.lock chown root:root /etc/frame-photo-run.lock chmod 0644 /etc/frame-photo-run.lock # 4. sudoers: exactly one command, nothing else (checked with visudo before it is installed) tmp=$(mktemp) cat > \"$tmp\" < 'auto' uses bwrap when it works and falls back to no sandbox when it does not. The migration prints a NOTE when it falls back. The admin album page also says \"Image processing runs without the extra sandbox.\" The same advice as none applies when it falls back.","url":"https://calevans.com/picture-frame/docs/photos/index.html#sandbox-mode-auto","tags":"","category":""},{"id":148,"title":"Sandbox mode none","pageTitle":"Photos","text":"'sandbox' => 'none' is an explicit opt-out. The worker runs without a sandbox. The migration prints: NOTE (photos): widgets.photos.sandbox is 'none': the image worker runs without the bubblewrap sandbox (resource limits still apply) What stays: the prlimit limits, nice , the 45-second kill, the header checks and size caps, PHP's open_basedir , and a PHP configuration for the worker that turns off exec , proc_open , network functions and other dangerous functions. What goes: the wall around the process. If a hostile image exploited a bug in GD or libheif, the exploit would run as the web user, which can read config.php and frames.db . Use none only when you alone upload photos, from your own computer, and you do not use drop links. Do not use it when strangers or relatives can send photos.","url":"https://calevans.com/picture-frame/docs/photos/index.html#sandbox-mode-none","tags":"","category":""},{"id":149,"title":"Limits and config keys","pageTitle":"Photos","text":"All keys go under widgets > photos in config.php . The integer limits are all positive whole numbers. Key Default What it limits library_bytes 5 GiB All stored photos together. album_photos 5000 Photos in one album, including those waiting for approval. upload_bytes 30 MiB One photo. Keep the .htaccess LimitRequestBody (31457280) in step. pending_album 500 Photos waiting for approval, per album. pending_bytes 512 MiB Photos waiting for approval, all albums together. min_free_bytes 1 GiB Uploads are refused when the disk has less free. The decoder may also spill 1.2 GiB while it works. drop_per_hour 100 Photos one drop link can send per hour. drop_per_day 300 Photos one drop link can send per day. drop_ip_per_day 500 Photos one visitor address can send per day, across links. php_binary Found automatically The only PHP used for the worker. Must be named php , php8 or php8.5 . A configured path is the only one used, with no fallback. heif_dec Found automatically The only HEIC converter. Must be named heif-dec or heif-convert . sandbox 'bwrap' 'bwrap' , 'user' , 'auto' or 'none' . See Sandbox modes . An unknown key stops the server with widgets.photos: unknown option . A value that is not a positive whole number stops it with widgets.photos. must be a positive integer . php 'widgets' => [ 'photos' => [ 'library_bytes' => 5 * 1024 ** 3 , 'album_photos' => 5000 , 'upload_bytes' => 30 * 1024 * 1024 , 'pending_album' => 500 , 'pending_bytes' => 512 * 1024 * 1024 , 'min_free_bytes' => 1024 ** 3 , 'drop_per_hour' => 100 , 'drop_per_day' => 300 , 'drop_ip_per_day' => 500 , // 'php_binary' => '/usr/bin/php8.5', // 'sandbox' => 'bwrap', // 'heif_dec' => '/usr/bin/heif-dec', ], ], If you raise upload_bytes , raise LimitRequestBody in both .htaccess exceptions and post_max_size to match. See Install the frame server .","url":"https://calevans.com/picture-frame/docs/photos/index.html#limits-and-config-keys","tags":"","category":""},{"id":150,"title":"Where photos are stored","pageTitle":"Photos","text":"var/photos/ files/ab/abcdef….jpg frame-sized photo, named by its content hash files/ab/abcdef….thumb.jpg thumbnail tmp/ work area for uploads; leftovers older than an hour are removed during uploads Photos are named by the hash of their bytes. The same picture in two albums is stored once. var/photos/ must be on the same server and not under the web root. The app refuses to start the library if var_dir is inside the document root. Photos are served only through the app, after a check that the requester is the right frame or a signed-in admin. Back it up together with var/frames.db . Without the files the albums show blank photos. See Back up the server .","url":"https://calevans.com/picture-frame/docs/photos/index.html#where-photos-are-stored","tags":"","category":""},{"id":151,"title":"Make an album and add photos","pageTitle":"Photos","text":"In the admin, select Photos in the top bar. Select New album . Enter a Name , up to 60 characters, such as \"Family\". Select Create album . The album opens. It has these sections: Waiting for approval (only when something waits), Add photos , Photos , and Drop links . At the top are All albums , Rename and Delete album .","url":"https://calevans.com/picture-frame/docs/photos/index.html#make-an-album-and-add-photos","tags":"","category":""},{"id":152,"title":"Add photos in bulk","pageTitle":"Photos","text":"Add photos takes files, folders, and ZIP files. Photos you add yourself are approved at once. Drag photos, folders or ZIP files onto the box, or select Choose photos or ZIPs or Choose a folder . Look over the list. Remove anything with the x button. Select Upload (it shows the count, for example Upload 40 photos ). While it runs, each row shows progress. Cancel stops after the current photo. Retry failed retries photos that failed in a way that may pass on a second try. Clear list empties the list. The summary line reads \"12 added, 3 duplicates, 0 failed\". Details: Accepted: JPEG, PNG, WebP and HEIC, up to 30 MiB each (the upload_bytes limit). Photos upload one at a time, in order. The list holds up to 10,000 photos. Hidden files and folders (names starting with a dot, and __MACOSX ) are skipped, and so is anything that is not a photo. Folders are read in full, including sub-folders, down to 25 levels. ZIP files are opened in your browser. The browser unpacks one photo at a time as its turn to upload comes, so memory use stays at one photo. ZIP limits, set in the browser: Limit Value Files in one ZIP 5000 Photos inside one ZIP, all together 2 GB Size one file may unpack to, compared with its packed size At most 200 times larger ZIP64 archives Not supported. Unzip on your computer and add the folder. Archives split across several parts Not supported Password-protected files Skipped Compressed ZIPs Need a browser with DecompressionStream : Chrome, Edge, Firefox, or Safari 16.4 or newer If a photo upload stops with a message, the rows that were not tried stay in the list.","url":"https://calevans.com/picture-frame/docs/photos/index.html#add-photos-in-bulk","tags":"","category":""},{"id":153,"title":"Duplicates","pageTitle":"Photos","text":"A photo already in the same album is recognized and skipped: the row says \"Already in this album\". The server compares the file's bytes and also the processed picture, so a re-saved copy of the same photo is caught too. The same photo can exist in two different albums.","url":"https://calevans.com/picture-frame/docs/photos/index.html#duplicates","tags":"","category":""},{"id":154,"title":"What the rows can say","pageTitle":"Photos","text":"Row says What it means and what to do Too large (max 30 MB) The file is bigger than upload_bytes . Shrink it, or raise the limit. Not a JPEG, PNG, WebP or HEIC photo The file type is not accepted. CMYK images aren't supported - save as RGB JPEG Export the photo as sRGB. Animated images aren't supported Use a still image. iPhone HEIC photos aren't supported on this server yet heif-dec is missing or not working. See Troubleshooting . Photo processing is unavailable on the server The decoder or sandbox check failed. Uploads stop. See Troubleshooting . This album is full The album reached album_photos . Uploads stop. The server is out of space The library reached library_bytes , or the disk has less than min_free_bytes free. Uploads stop. The server is busy. Try again in a moment. Another upload holds the lock. The admin retries three times on its own. Can't reach the server Check your connection. Uploads stop.","url":"https://calevans.com/picture-frame/docs/photos/index.html#what-the-rows-can-say","tags":"","category":""},{"id":155,"title":"Review and delete","pageTitle":"Photos","text":"The Photos grid shows thumbnails, 48 at a time. Show more loads the next page. Select a photo to see it larger, with its size, when it was added and who added it. To delete photos: Tick the photos, or Select all shown . Select Delete . Confirm. It asks for your password. The admin sends large selections in batches of 500. Deleting cannot be undone. Frames that are showing a deleted photo drop it within a few minutes. To delete an album, select Delete album and confirm. This removes the album, all its photos, and its drop links. The admin refuses while a frame still uses the album: point that frame at something else first.","url":"https://calevans.com/picture-frame/docs/photos/index.html#review-and-delete","tags":"","category":""},{"id":156,"title":"Point a frame at the album","pageTitle":"Photos","text":"Open the frame, then Widgets , switch Photos on, and select Save . Open the Photos section. Under Photos come from , choose Photo library . Choose the Album . The list shows the photo count. Check New photos daily at , and Show each photo for . Select Save .","url":"https://calevans.com/picture-frame/docs/photos/index.html#point-a-frame-at-the-album","tags":"","category":""},{"id":157,"title":"Method 3: Family drop links","pageTitle":"Photos","text":"A drop link lets a relative add photos to one album from their phone, with no account. Their photos wait for your approval. They cannot see anything in the album. You need method 2 working first: the library, an album, and a sandbox you trust.","url":"https://calevans.com/picture-frame/docs/photos/index.html#method-3-family-drop-links","tags":"","category":""},{"id":158,"title":"Create a link","pageTitle":"Photos","text":"In the admin, select Photos , then open the album. In Drop links , select New drop link . Enter a Name , up to 40 characters, for the person it is for, such as \"Aunt Sue\". The admin shows it in your list, and the page they open greets them with it (\"Hi, Aunt Sue.\"), so use a name they would recognize. Select Create link . In the box that opens, select Copy link and send it to that person. The link looks like https://frames.example.com/frames/drop/<43 characters> . Warning The link is shown once . The server keeps only a hash. If you lose it, make a new link. Treat links as secrets. They also appear in your web server's access log. Rotate or delete logs on a short schedule.","url":"https://calevans.com/picture-frame/docs/photos/index.html#create-a-link","tags":"","category":""},{"id":159,"title":"What relatives see","pageTitle":"Photos","text":"The link opens a page titled \"Send photos to the frame\" with their name (\"Hi, Aunt Sue.\"). It says: \"Your photos will appear on the frame after they're approved.\" They tap Choose photos , pick photos from their phone, and the page sends them one by one. It shows how many more photos they can send right now. It gives them nothing else: no album, no other photos, no gallery. If the link has expired, been revoked, or been replaced, the page says \"This link isn't working anymore. Ask for a new one.\" Your name is owner_name from config.php .","url":"https://calevans.com/picture-frame/docs/photos/index.html#what-relatives-see","tags":"","category":""},{"id":160,"title":"Approve what arrives","pageTitle":"Photos","text":"Photos from a link wait in Waiting for approval , at the top of the album. Nothing waiting ever reaches a frame. In the album list, a Waiting column shows \"N to approve\". Open the album. In Waiting for approval , tick the photos. Each shows who sent it. Select Approve to add them to the album, or Reject to delete them.","url":"https://calevans.com/picture-frame/docs/photos/index.html#approve-what-arrives","tags":"","category":""},{"id":161,"title":"Manage links","pageTitle":"Photos","text":"The Drop links table shows each link's name, status ( Active , Revoked or Expired ), expiry, when it was last used, and how many photos it sent (with how many are waiting). Action What it does Rename Changes the name. Extend Adds 90 days to the expiry, up to one year from today. New link Replaces the link. The old address stops working at once. Shows the new one once. Asks for your password. Revoke Turns the link off at once. Photos already sent stay in the album. Asks for your password. Restore Turns a revoked link back on. The same address works again. Asks for your password. Delete their photos Deletes every photo that link sent, waiting and approved. Cannot be undone. Asks for your password. Delete link Removes the link. Photos it sent stay in the album. Asks for your password. Links expire after 90 days. A link that expires shows Expired and stops working. Use Extend to renew it.","url":"https://calevans.com/picture-frame/docs/photos/index.html#manage-links","tags":"","category":""},{"id":162,"title":"Quotas","pageTitle":"Photos","text":"Limit Default If a relative hits it Photos per link per hour 100 ( drop_per_hour ) The page waits and retries, then says \"You've sent a lot of photos. Please wait a while, then tap Try again.\" Photos per link per day 300 ( drop_per_day ) The same. Photos per visitor address per day 500 ( drop_ip_per_day ) The same. Photos waiting in one album 500 ( pending_album ) \"The frame can't take photos right now. Please try again later.\" Waiting photos, all albums 512 MiB ( pending_bytes ) The same. Size of one photo 30 MiB ( upload_bytes ) \"Too big (the limit is 30 MB).\" Clear a full pending queue by approving or rejecting photos.","url":"https://calevans.com/picture-frame/docs/photos/index.html#quotas","tags":"","category":""},{"id":163,"title":"Logs","pageTitle":"Photos","text":"The application logs one frame photos: ingest ... line per upload: album, size, type and result. It never writes a link. The only IP address it writes is the rate-limit key.","url":"https://calevans.com/picture-frame/docs/photos/index.html#logs","tags":"","category":""},{"id":164,"title":"Troubleshooting","pageTitle":"Photos","text":"bin/migrate.php checks the photo library and prints a WARNING (photos) line for each problem and a NOTE (photos) line for information. They never stop the migration. Run it as the web user: sudo -u www-data php /srv/frame/app/bin/migrate.php The migration runs the same self-test the admin uses. It decodes small test photos through the real worker, including a HEIC through heif-dec . While the self-test fails, the admin shows a banner in the album, \"Photo uploads are off. The server's image decoder isn't working, so new photos can't be added.\", and turns uploads off. Frames keep showing photos already stored. Line What it means What to do photo uploads are off: prlimit and nice (util-linux and coreutils) must be installed One of the two programs is missing. Install util-linux and coreutils . photo uploads are off: widgets.photos.php_binary is '...', which is not an executable file named php, php8 or php8.5 (there is no fallback) The configured PHP path is wrong. Fix php_binary , or remove it to let the server find PHP. photo uploads are off: no PHP command line binary found for the image worker (set 'php_binary' ...) The server could not find a command-line PHP. Install the CLI package, or set php_binary . photo uploads are off: the image worker cannot run PHP GD with JPEG, PNG and WebP support ... GD is missing from the command-line PHP, or lacks a format. Install php8.5-gd for the CLI. Check with the gd_info command in What the server needs . photo uploads are off: widgets.photos.sandbox is 'user' but the framephoto setup does not work ... Something in the dedicated user setup is missing or broken. Run the checks in that section. Re-run the setup script. Read frame photos: framephoto setup does not work in the PHP error log. photo uploads are off: the bubblewrap sandbox is required ... but cannot run here bwrap is missing or blocked. Install bubblewrap . On Ubuntu 24.04, use 'sandbox' => 'user' . See When Ubuntu 24.04 blocks it . NOTE (photos): widgets.photos.sandbox is 'none' ... You chose no sandbox. Nothing, if you meant it. NOTE (photos): the image worker runs without the bubblewrap sandbox (bwrap is missing or cannot create namespaces here) ... 'sandbox' => 'auto' fell back. Install bubblewrap , switch to user , or set 'none' to silence it. HEIC (iPhone) photos are refused: heif-dec is not installed (apt install libheif-examples libheif-plugin-libde265) No HEIC converter. Everything else still works. Install the two packages. HEIC (iPhone) photos are refused: heif-dec ran but could not decode the self-test photo ... heif-dec exists but failed. Install libheif-plugin-libde265 . Check that heif-dec works inside the sandbox. libheif X is below the security floor ... The libheif library is older than 1.17.6. Update it. A distribution may fix it under the old number, so check your security updates. libwebp library X is below the security floor ... libwebp is older than 1.3.2 (shared object 7.1.8). Update it. WARNING (photos): the host check failed: ... The check itself crashed. Read the message and the PHP error log. The checks are cached. A failed sandbox check is remembered for 10 minutes and a passed one for an hour. The admin's upload check is remembered for an hour. After a fix, delete var/photos/.sandbox-state , var/photos/.sandbox-state-user and var/photos/.probe-ok to test again now. Other lines in the PHP error log that help: frame photos: worker failed exit=... stderr=... . The worker crashed, was killed, or printed something unexpected. frame photos: image self-test failed code=... . frame photos: heif-dec failed ... . frame photos: ingest ... result=... . One line per upload.","url":"https://calevans.com/picture-frame/docs/photos/index.html#troubleshooting","tags":"","category":""},{"id":165,"title":"Related","pageTitle":"Photos","text":"Widgets Install the frame server Use the admin Security Troubleshooting and recovery Next: Update the kiosk .","url":"https://calevans.com/picture-frame/docs/photos/index.html#related","tags":"","category":""},{"id":166,"title":"Troubleshooting and recovery","pageTitle":"Troubleshooting and recovery","text":"Use this page when something is not working. Each entry starts with what you see, says why it happens, and then lists what to do. The most common problems come first in each group. Find your symptom: Server and admin Uploads Photos Calendar, weather, Home Assistant and Cards The frame ADB Recovery Gotchas Most problems leave a line in the PHP error log. Look there first. On many servers that is the Apache error log. Lines that start frame: , frame admin: or frame photos: come from this system.","url":"https://calevans.com/picture-frame/docs/troubleshooting/index.html","tags":"","category":""},{"id":167,"title":"Every request answers 503 maintenance","pageTitle":"Troubleshooting and recovery","text":"You see: The admin or a frame gets {\"error\":\"maintenance\",\"code\":\"maintenance\"} with HTTP 503 and a Retry-After: 30 header. The log has frame: frames.db is at schema N, code expects M . Why: You deployed new code, and the database has not been brought up to date. What to do: Run the migration as the web user: sudo -u www-data php /srv/frame/app/bin/migrate.php Check that it ends with schema at . Run it again after every update of app/ . Frames and the admin recover on their own once the schema matches.","url":"https://calevans.com/picture-frame/docs/troubleshooting/index.html#every-request-answers-503-maintenance","tags":"","category":""},{"id":168,"title":"Every request answers 500 on a new install","pageTitle":"Troubleshooting and recovery","text":"You see: HTTP 500 with {\"error\":\"internal error\",\"code\":\"internal\"} before you have run any command. Why: The database does not exist yet. What to do: Run the migration as above. Create your admin login next. See Install the frame server .","url":"https://calevans.com/picture-frame/docs/troubleshooting/index.html#every-request-answers-500-on-a-new-install","tags":"","category":""},{"id":169,"title":"The server answers 500 \"server not configured\"","pageTitle":"Troubleshooting and recovery","text":"You see: HTTP 500 with {\"error\":\"server not configured\",\"code\":\"not_configured\"} . Why: config.php is missing, unreadable, or has a bad value. The log line says which, after frame: config error: . What to do: Run the check as the web user and read the message: sudo -u www-data php -r 'require \"/srv/frame/app/bootstrap.php\"; echo \"ok\\n\";' Message Fix ...config.php is missing or unreadable Copy config.example.php to config.php next to app/ . Make it readable by the web user (group www-data , mode 0640). unknown key: ... Remove or fix the key. See the configuration reference . frames_url is required ... Set it, ending in / . owner_name is required ... Set a short name: at most 40 characters, with no < , > , & or quotes. calendar_hosts: each entry must be a lowercase host name Use lowercase host names only, as a list. client_ip_header needs trusted_proxies ... Set trusted_proxies too, or remove the header. kiosk_release_pubkey must be a PEM EC public key (needs the openssl extension) Install php-openssl support, or fix the key. It must be an EC P-256 public key in PEM form. widgets.photos: unknown option ... Remove the option. See Photos: limits and config keys .","url":"https://calevans.com/picture-frame/docs/troubleshooting/index.html#the-server-answers-500-server-not-configured","tags":"","category":""},{"id":170,"title":"The admin answers 500","pageTitle":"Troubleshooting and recovery","text":"You see: https://frames.example.com/frames/admin/ shows HTTP 500, either as plain Apache or as the not_configured JSON. Why: One of two things. frames_url does not start with https:// . The admin refuses to run and logs frame admin: refusing to run: frames_url must be https . Apache does not allow the .htaccess files to work. The Apache error log says a directive \"not allowed here\". What to do: Set frames_url to an https:// address. Check the AllowOverride line in your virtual host includes all four classes: AuthConfig FileInfo Indexes Options . See Install the frame server .","url":"https://calevans.com/picture-frame/docs/troubleshooting/index.html#the-admin-answers-500","tags":"","category":""},{"id":171,"title":"The login page says \"The page expired\"","pageTitle":"Troubleshooting and recovery","text":"You see: After you enter your details, the sign-in page shows \"The page expired. Try again.\" The log has frame admin: login rejected origin or login rejected token . Why: The sign-in form posts only when the request's origin matches the page, and the form's token matches its cookie. One of these failed: The browser sent Origin: null . This happens when a response header Referrer-Policy: no-referrer is set. The admin sends Referrer-Policy: same-origin itself, but a header added by Apache or a proxy for the whole site can replace it. A proxy or CDN changes the Host header, so it no longer matches the Origin . You opened the page by another name than the host in frames_url , such as an IP address or www. . The sign-in page sends you to the frames_url host if the names differ. The form was open for more than 15 minutes, or the browser blocks cookies for the site. The form's token is a cookie that lasts 15 minutes. The site is not on HTTPS. The admin's cookies start with __Host- , so a browser stores them only over HTTPS. What to do: Open the admin at exactly the address in frames_url , over HTTPS. Reload the sign-in page and try again. Look at the response headers (browser developer tools, Network tab). If Referrer-Policy says no-referrer , change your server or proxy to leave the header alone for /frames/admin/ , or to use same-origin . If a proxy sits in front, make it pass the original Host header to Apache.","url":"https://calevans.com/picture-frame/docs/troubleshooting/index.html#the-login-page-says-the-page-expired","tags":"","category":""},{"id":172,"title":"Sign-in failed","pageTitle":"Troubleshooting and recovery","text":"You see: \"Sign-in failed. Check your details and try again.\" Why: The user name, the password or the code is wrong. The message is the same for all three on purpose. A reused code also fails: each code works once. What to do: Check the user name. Capital letters and surrounding spaces do not matter. If two-step sign-in is on, wait for the next code and enter it. Check your server's clock. Codes depend on it. Run NTP. If you cannot get in, reset from the shell: user.php passwd yourname , or user.php totp-disable yourname . See Use the admin .","url":"https://calevans.com/picture-frame/docs/troubleshooting/index.html#sign-in-failed","tags":"","category":""},{"id":173,"title":"Too many attempts","pageTitle":"Troubleshooting and recovery","text":"You see: \"Too many attempts. Try again later.\" Why: A lockout is active: 10 failed sign-ins from your address in 15 minutes, or 20 for the user name in an hour. A correct password is refused while the lockout lasts. What to do: Wait for the window to pass. Behind a proxy, make sure client_ip_header and trusted_proxies are set, or all visitors share one address.","url":"https://calevans.com/picture-frame/docs/troubleshooting/index.html#too-many-attempts","tags":"","category":""},{"id":174,"title":"The admin shows \"Signed out\"","pageTitle":"Troubleshooting and recovery","text":"You see: A box that says \"Your session has ended. Sign in again to continue.\" Why: You were idle for 30 minutes, 12 hours passed since you signed in, or your password or two-step setting changed. What to do: Select Sign in . Unsaved edits on that page are lost.","url":"https://calevans.com/picture-frame/docs/troubleshooting/index.html#the-admin-shows-signed-out","tags":"","category":""},{"id":175,"title":"Changes I make do not reach the frame","pageTitle":"Troubleshooting and recovery","text":"You see: You saved a setting, and the frame still shows the old thing. What to do: Wait a minute or two. Frames pick up changes on their next check-in. Check that the frame is Online on Frames . Use Screen and Refresh to see what the frame shows now. Check the page shows no \"Unsaved changes\" bar at the bottom.","url":"https://calevans.com/picture-frame/docs/troubleshooting/index.html#changes-i-make-do-not-reach-the-frame","tags":"","category":""},{"id":176,"title":"An upload fails with 413","pageTitle":"Troubleshooting and recovery","text":"You see: An upload fails with \"Too large\", or the response is HTTP 413 \"Request Entity Too Large\". Why: A request is bigger than a limit. There are four places a limit can live: the app, the .htaccess files, PHP, and anything in front of Apache. Upload Where the limit is Value Photo in the admin public/admin/.htaccess and upload_bytes 30 MiB Photo from a drop link public/.htaccess and upload_bytes 30 MiB Card cover or stamp public/admin/.htaccess 4 MiB Kiosk release public/admin/.htaccess 16 MiB Anything else The default LimitRequestBody 16 KiB in the admin, 64 KiB elsewhere What to do: Check post_max_size and upload_max_filesize are at least 31M (see PHP settings ). Restart PHP-FPM or Apache after a change. If you copied the .htaccess rules into the virtual host, copy the blocks too. They match on %{THE_REQUEST} , not REQUEST_URI , because Apache evaluates the request-size limit on an internal subrequest where REQUEST_URI is the front controller. A rule written against REQUEST_URI never matches, and the small default limit applies. If a proxy or CDN sits in front, check its upload limit too (for nginx, client_max_body_size ). If you raised upload_bytes , raise LimitRequestBody in both .htaccess exceptions to match.","url":"https://calevans.com/picture-frame/docs/troubleshooting/index.html#an-upload-fails-with-413","tags":"","category":""},{"id":177,"title":"Photo uploads are off","pageTitle":"Troubleshooting and recovery","text":"You see: A red banner in the album: \"Photo uploads are off. The server's image decoder isn't working, so new photos can't be added.\" Uploads stop with \"Photo processing is unavailable on the server\". Why: The photo library's self-test failed. The cause is on the server, in the decoder or the sandbox. What to do: Run the migration as the web user and read the WARNING (photos) lines: sudo -u www-data php /srv/frame/app/bin/migrate.php Photos: troubleshooting explains each line. On Ubuntu 24.04 the usual cause is that bwrap is blocked. Switch to 'sandbox' => 'user' . Frames keep showing photos already stored.","url":"https://calevans.com/picture-frame/docs/troubleshooting/index.html#photo-uploads-are-off","tags":"","category":""},{"id":178,"title":"iPhone photos are refused","pageTitle":"Troubleshooting and recovery","text":"You see: \"iPhone HEIC photos aren't supported on this server yet\". What to do: Install libheif-examples and libheif-plugin-libde265 , then run the migration to check. See Photos: troubleshooting .","url":"https://calevans.com/picture-frame/docs/troubleshooting/index.html#iphone-photos-are-refused","tags":"","category":""},{"id":179,"title":"\"The server is out of space\" or \"This album is full\"","pageTitle":"Troubleshooting and recovery","text":"Why: The library reached library_bytes , the disk has less than min_free_bytes free, or the album reached album_photos . What to do: Delete photos you no longer need, make room on the disk, or raise the limit in config.php . See Photos: limits and config keys .","url":"https://calevans.com/picture-frame/docs/troubleshooting/index.html#the-server-is-out-of-space-or-this-album-is-full","tags":"","category":""},{"id":180,"title":"A new photo does not show on the frame","pageTitle":"Troubleshooting and recovery","text":"Why: The frame shows a daily set, picked once a day at the frame's pick time. A photo added after the pick appears in the next day's set. A photo waiting for approval never reaches a frame. What to do: Open the frame's Photos section. The contact sheet says when the set was picked and when the next pick is. Check the photo is approved, not under Waiting for approval . See How a frame picks its photos .","url":"https://calevans.com/picture-frame/docs/troubleshooting/index.html#a-new-photo-does-not-show-on-the-frame","tags":"","category":""},{"id":181,"title":"The Nextcloud album shows \"Not fetched yet\" or an error","pageTitle":"Troubleshooting and recovery","text":"You see: Under Album link : \"Not fetched yet\", or \"Error: ...\". What to do: Check the cron job runs. Run it by hand as the cron user: php /srv/frame/app/fetch/fetch.php It prints nothing when all is well. cache/cache.db should exist. Check the Nextcloud host is in photo_hosts in config.php . If it is not, the admin refuses to save the link with \"album_url must be a Nextcloud Photos public album link\". Check the link looks like https://cloud.example.org/apps/photos/public/ . Check your server can reach the Nextcloud host, and that the album is shared with a public link.","url":"https://calevans.com/picture-frame/docs/troubleshooting/index.html#the-nextcloud-album-shows-not-fetched-yet-or-an-error","tags":"","category":""},{"id":182,"title":"The admin refuses my Nextcloud link","pageTitle":"Troubleshooting and recovery","text":"You see: \"album_url must be a Nextcloud Photos public album link\". Why: The link's host is not in photo_hosts , or the address is not a public album link. What to do: Add the host in lowercase to photo_hosts and use the album's public link.","url":"https://calevans.com/picture-frame/docs/troubleshooting/index.html#the-admin-refuses-my-nextcloud-link","tags":"","category":""},{"id":183,"title":"A calendar shows Error","pageTitle":"Troubleshooting and recovery","text":"You see: In Library , the calendar's status is Error , with a message. What to do: Check the calendar's host is in calendar_hosts , in lowercase. The admin refuses to save a calendar whose host is not listed (\"host not allowed\"). Check the link is HTTPS with no port, and that it returns an iCal file. Nextcloud's /apps/calendar/p/ and /remote.php/dav/public-calendars/ forms are handled for you. Check the fetcher runs. Run it by hand as in the entry above.","url":"https://calevans.com/picture-frame/docs/troubleshooting/index.html#a-calendar-shows-error","tags":"","category":""},{"id":184,"title":"The calendar widget shows nothing","pageTitle":"Troubleshooting and recovery","text":"Why: A calendar with nothing ticked shows no events. There is no \"show all\". What to do: Open the frame's Calendar section, tick the calendars, and save.","url":"https://calevans.com/picture-frame/docs/troubleshooting/index.html#the-calendar-widget-shows-nothing","tags":"","category":""},{"id":185,"title":"Weather is missing or empty","pageTitle":"Troubleshooting and recovery","text":"What to do: Check the location is in the US. The National Weather Service has no data elsewhere. Check the frame's Weather widget is on and has a Location chosen. Check the fetcher runs. Weather refreshes about every 10 to 30 minutes. If you entered Stations , check each is a valid four-character ID, or clear the field to use the nearest three.","url":"https://calevans.com/picture-frame/docs/troubleshooting/index.html#weather-is-missing-or-empty","tags":"","category":""},{"id":186,"title":"Home Assistant shows nothing or asks me to sign in","pageTitle":"Troubleshooting and recovery","text":"What to do: Check the address. http works only for private addresses ( 10.x , 172.16-31.x , 192.168.x ) and .local names. Use https for anything else. The address has no path. Check the token is saved. The admin shows Token set . Changing the address removes the token, so enter it again. Without a token, Home Assistant must trust the frame's address. See Widgets: Home Assistant . The Dashboard list fills in after the frame reports its dashboards. Until then pick the default.","url":"https://calevans.com/picture-frame/docs/troubleshooting/index.html#home-assistant-shows-nothing-or-asks-me-to-sign-in","tags":"","category":""},{"id":187,"title":"A relative says their link is not working","pageTitle":"Troubleshooting and recovery","text":"You see: \"This link isn't working anymore. Ask for a new one.\" Photo drop links also say when a link has expired or been turned off. Why: The link was replaced ( New link ), revoked, or has expired. A drop link lasts 90 days by default. What to do: Open the sender link or drop link in the admin. Extend an expired drop link, Restore a revoked drop link, or make a New link and send it again.","url":"https://calevans.com/picture-frame/docs/troubleshooting/index.html#a-relative-says-their-link-is-not-working","tags":"","category":""},{"id":188,"title":"A card sender sees \"mailbox is full\"","pageTitle":"Troubleshooting and recovery","text":"Why: The frame already holds 30 unopened cards, or the sender has 10 unopened ones. What to do: Wait until someone opens cards on the frame, or delete unopened cards from the sender in the Cards section.","url":"https://calevans.com/picture-frame/docs/troubleshooting/index.html#a-card-sender-sees-mailbox-is-full","tags":"","category":""},{"id":189,"title":"The frame never shows a pairing code","pageTitle":"Troubleshooting and recovery","text":"You see: The frame shows a \"Can't reach ...\" screen, or \"Setting the clock...\", or no pairing code. What to do: Check the frame is on Wi-Fi. Hold the top-left corner for 10 seconds, enter the PIN, and open Wi-Fi . Check the frame can reach your server. The \"Can't reach ...\" screen shows the network name, address and frame ID. Check the kiosk was built with the right FRAME_SERVER_URL . It must match frames_url on the server, over HTTPS. If the site uses a Let's Encrypt certificate, check you installed the ISRG Root X1 certificate on the frame. Without it Android 6 cannot load the page. See Provisioning, step 4 . If the screen says \"Setting the clock...\", the clock is wrong. See the next entry.","url":"https://calevans.com/picture-frame/docs/troubleshooting/index.html#the-frame-never-shows-a-pairing-code","tags":"","category":""},{"id":190,"title":"The pairing code is rejected","pageTitle":"Troubleshooting and recovery","text":"You see: \"That code was wrong or has expired.\" Why: The code was mistyped, it is older than 24 hours, or you entered five wrong codes in 10 minutes. What to do: Read the code on the frame again (it can change), wait a few minutes if you hit the limit, and try again.","url":"https://calevans.com/picture-frame/docs/troubleshooting/index.html#the-pairing-code-is-rejected","tags":"","category":""},{"id":191,"title":"The frame's clock is wrong (it says 1969)","pageTitle":"Troubleshooting and recovery","text":"Why: The frame has no battery-backed clock. After a power cut it starts in 1969 until it reaches a time server. What to do: Check you ran scripts/provision.sh time and installed the boot script. The boot script restores the last saved time. Check the NTP_SERVER is reachable from the frame's network.","url":"https://calevans.com/picture-frame/docs/troubleshooting/index.html#the-frames-clock-is-wrong-it-says-1969","tags":"","category":""},{"id":192,"title":"The frame goes offline or has a weak signal","pageTitle":"Troubleshooting and recovery","text":"You see: Offline or a Weak Wi-Fi badge on Frames . What to do: Move the frame or the access point. The badge shows below -75 dBm. Check the frame's Details for the network and signal. Reserve the frame's address in your DHCP server. The boot script holds its MAC address fixed.","url":"https://calevans.com/picture-frame/docs/troubleshooting/index.html#the-frame-goes-offline-or-has-a-weak-signal","tags":"","category":""},{"id":193,"title":"The Dim button only makes the screen dark","pageTitle":"Troubleshooting and recovery","text":"Why: The boot script did not hand the backlight to the kiosk. Dim then only lowers brightness. What to do: Check the boot script is installed and has run. Look for lcdbl -> uid N in adb logcat -d -s frame-fixmac . If you uninstalled and reinstalled the kiosk, reboot the frame. See Provisioning, step 9 .","url":"https://calevans.com/picture-frame/docs/troubleshooting/index.html#the-dim-button-only-makes-the-screen-dark","tags":"","category":""},{"id":194,"title":"The Wi-Fi picker shows no networks","pageTitle":"Troubleshooting and recovery","text":"Why: Android 6 hides scan results when location is off. What to do: The kiosk normally turns location on. If it did not: adb shell settings put secure location_providers_allowed +network","url":"https://calevans.com/picture-frame/docs/troubleshooting/index.html#the-wi-fi-picker-shows-no-networks","tags":"","category":""},{"id":195,"title":"The frame did not take an update","pageTitle":"Troubleshooting and recovery","text":"See Update the kiosk: failure states .","url":"https://calevans.com/picture-frame/docs/troubleshooting/index.html#the-frame-did-not-take-an-update","tags":"","category":""},{"id":196,"title":"adb devices shows nothing","pageTitle":"Troubleshooting and recovery","text":"adb devices What to do: On WSL, attach the frame from PowerShell: usbipd list , then usbipd attach --wsl --busid . A running frame shows as 1f3a:1001 . A frame in FEL mode shows as 1f3a:efe8 .","url":"https://calevans.com/picture-frame/docs/troubleshooting/index.html#adb-devices-shows-nothing","tags":"","category":""},{"id":197,"title":"adb says the device is offline","pageTitle":"Troubleshooting and recovery","text":"adb Why: After adb reboot , an old network session is stale. What to do: Run adb disconnect , then adb connect 192.0.2.50:5555 again.","url":"https://calevans.com/picture-frame/docs/troubleshooting/index.html#adb-says-the-device-is-offline","tags":"","category":""},{"id":198,"title":"I cannot connect over the network","pageTitle":"Troubleshooting and recovery","text":"Why: The boot script limits ADB over Wi-Fi to the addresses in ADB_ALLOW . If one entry is not a valid IPv4 address or range, the script allows nobody over Wi-Fi (it logs bad ADB_ALLOW entry ). Wi-Fi ADB is also off on IPv6 when a list is set. What to do: Connect over USB. USB ADB is never limited. Fix ADB_ALLOW in .env . Include your computer's address. Run scripts/provision.sh boot-script again, and reboot.","url":"https://calevans.com/picture-frame/docs/troubleshooting/index.html#i-cannot-connect-over-the-network","tags":"","category":""},{"id":199,"title":"Several devices are connected","pageTitle":"Troubleshooting and recovery","text":"Add -s to adb and to scripts/provision.sh . Use the address ( 192.0.2.50:5555 ) for a network device.","url":"https://calevans.com/picture-frame/docs/troubleshooting/index.html#several-devices-are-connected","tags":"","category":""},{"id":200,"title":"The frame does not boot","pageTitle":"Troubleshooting and recovery","text":"You see: The frame stays on a black screen, or on the boot logo, and never reaches the kiosk or the stock app. What to do, in this order: Power-cycle it. Unplug the USB-C power, wait, and plug it in. Boot Android with the microSD card out. The FEL card makes RESET enter FEL mode. Take the card out and press RESET. See Unlock: first boot . If Android starts but the kiosk is wrong, connect with ADB (USB works even when Wi-Fi is limited) and fix it: Reinstall the kiosk: adb install -r kiosk/build/frame-kiosk.apk . Undo the boot script: restore the frame-fixmac.sh.v backup and remove /system/etc/frame.conf . Restore a .bak of a system file you changed, for example build.prop.bak . If Android does not start, put the frame in FEL mode and talk to its storage: Put the FEL microSD card in and press RESET. usbipd list shows 1f3a:efe8 . Run scripts/boot-ums.sh in WSL. To undo the ADB patch only, run patch-sector.ps1 -Restore in PowerShell. To put the whole storage back, write backups/emmc-full.img to the disk. No script does this for you. It is the reverse of backup-emmc.ps1 , and needs a raw disk write from an Administrator PowerShell. Double-check the disk number: this overwrites the whole disk. The backup from the unlock is what makes step 4 possible. Keep it.","url":"https://calevans.com/picture-frame/docs/troubleshooting/index.html#the-frame-does-not-boot","tags":"","category":""},{"id":201,"title":"I lost the PIN","pageTitle":"Troubleshooting and recovery","text":"You see: The maintenance panel does not accept the PIN. What to do: In the admin, open the frame, then Security . Enter a new PIN and select Set PIN , or select Reset to factory PIN to go back to the KIOSK_PIN from the build. The frame picks it up on its next check-in. The frame must reach your server to get a new PIN. If it is offline, get it back onto a network it knows first, then set the PIN in the admin. A rebuilt kiosk with a new KIOSK_PIN changes only the factory PIN. It applies when the frame has no custom PIN. A custom PIN stays on the frame, through adb install -r , until you change or reset it in the admin. After five wrong PINs the pad locks for 5 minutes, then 30 minutes, 2 hours and 8 hours for each further five. A reboot restarts a lock, so do not use it to try again.","url":"https://calevans.com/picture-frame/docs/troubleshooting/index.html#i-lost-the-pin","tags":"","category":""},{"id":202,"title":"I lost the APK keystore or the release key","pageTitle":"Troubleshooting and recovery","text":"Lost the release key. Frames keep running. You cannot send them self-updates any more, because they check the old public key. Make a new release key. See Provisioning, step 5 . Build a kiosk with the new RELEASE_PUBKEY , signed with the same keystore . Install it on every frame with adb install -r . After that, self-updates work again. Lost the APK keystore. Android refuses an update signed with another key, even over ADB. On every frame you must: Undo device owner . Uninstall the kiosk: adb shell pm uninstall com.calevans.frame . Make a new keystore and release key, and build the kiosk. Run Provisioning, step 7 again and claim the frame again. Back up both keys somewhere private so this does not happen. See Update the kiosk .","url":"https://calevans.com/picture-frame/docs/troubleshooting/index.html#i-lost-the-apk-keystore-or-the-release-key","tags":"","category":""},{"id":203,"title":"A frame shows as Revoked","pageTitle":"Troubleshooting and recovery","text":"Why: Someone revoked the frame in the admin, which stops it working at once. What to do: Open the frame, select More , then Restore . It asks for your password. If you revoked it because it was lost or stolen, leave it revoked.","url":"https://calevans.com/picture-frame/docs/troubleshooting/index.html#a-frame-shows-as-revoked","tags":"","category":""},{"id":204,"title":"I cannot sign in and need a new password or code","pageTitle":"Troubleshooting and recovery","text":"What to do: From a shell on the server, as the web user: sudo -u www-data php /srv/frame/app/bin/user.php passwd yourname sudo -u www-data php /srv/frame/app/bin/user.php totp-disable yourname Both sign the user out of every browser. See Use the admin .","url":"https://calevans.com/picture-frame/docs/troubleshooting/index.html#i-cannot-sign-in-and-need-a-new-password-or-code","tags":"","category":""},{"id":205,"title":"I need to restore the server","pageTitle":"Troubleshooting and recovery","text":"Install the server as in Install the frame server . Put back config.php , and the contents of var/ from your backup: frames.db , photos/ , notes/ and kiosk/ . Run the migration as the web user. Frames reconnect on their own. If you restored an older frames.db , a frame claimed after that backup shows up as unclaimed. Claim it again. See Back up the server .","url":"https://calevans.com/picture-frame/docs/troubleshooting/index.html#i-need-to-restore-the-server","tags":"","category":""},{"id":206,"title":"Gotchas","pageTitle":"Troubleshooting and recovery","text":"Small things that cost time: Use adb exec-out , not adb shell , to read binary files or compare bytes. shell turns \\n into \\r\\n . The frame's sed -i mangles replacement text with & . Rebuild the file from its .bak plus echo >> instead. Do not run grep -r / on the frame. It hangs in /proc . After adb reboot , run adb disconnect and adb connect again. The old session shows \"device offline\". adb exec-out screencap -p > shot.png shows what the kiosk is displaying. Keep a record of each change you make to a frame, with its undo. Never attach 1f3a:1010 (U-Boot's disk) with usbipd, and cancel every \"format this disk\" prompt in Windows. See Unlock, step 5 . Do not run scripts/provision.sh steps out of order. Install the boot script after the kiosk, because it hands the backlight to the kiosk's user ID. The .env reader is strict. A line ending in a carriage return, or an unknown key, stops every script that reads it.","url":"https://calevans.com/picture-frame/docs/troubleshooting/index.html#gotchas","tags":"","category":""},{"id":207,"title":"Related","pageTitle":"Troubleshooting and recovery","text":"Install the frame server Unlock your PF1007L Build the kiosk and set up a frame Photos Update the kiosk Back to: Start here .","url":"https://calevans.com/picture-frame/docs/troubleshooting/index.html#related","tags":"","category":""},{"id":208,"title":"Security","pageTitle":"Security","text":"This page explains how the Picture Frame System defends itself: who and what it expects to be attacked by, every control that matters, and why each one exists. It is for people who run a server, review the code, or want to report a problem. If you only want to install the system, start with the server install guide and come back here when you want to know why it asks for what it asks for. When you finish this page you will know what a leaked link, a hostile photo, a stolen password, a compromised server and a stolen frame can and cannot do, and which parts of the design you must not loosen.","url":"https://calevans.com/picture-frame/docs/security/index.html","tags":"","category":""},{"id":209,"title":"Report a vulnerability","pageTitle":"Security","text":"Open a confidential issue on the project's GitLab: Go to gitlab.com/calevans/picture-frame-system/-/issues/new . Give the issue a short, neutral title. Do not put the vulnerability in the title. Select the This issue is confidential checkbox before you submit. In the description, say what you found, how to reproduce it, which version or commit you tested, and what an attacker gains. Please do not post details in a public issue, a merge request or a public chat. This is a volunteer project and offers no response-time guarantee, but a confidential report is read and answered as soon as a maintainer can. Only the current default branch ( master ) is supported. Fixes are not back-ported.","url":"https://calevans.com/picture-frame/docs/security/index.html#report-a-vulnerability","tags":"","category":""},{"id":210,"title":"How the system is split","pageTitle":"Security","text":"Everything below follows from four trust boundaries. Browser and sender to server. Everything arrives over HTTPS. The admin needs a login. Senders hold a secret in their link and can only write. Frame to server. A frame proves itself with a 256-bit key. A frame can read its own data and nothing else. Web to worker. Photos from strangers are decoded in a separate, resource-limited, optionally sandboxed process. The web process never decodes an upload itself. Server to device. The server can offer a kiosk update. The device decides whether to install it.","url":"https://calevans.com/picture-frame/docs/security/index.html#how-the-system-is-split","tags":"","category":""},{"id":211,"title":"Where each secret lives","pageTitle":"Security","text":"Secret Created by Stored Who can read it Admin password Command line frames.db , as an Argon2id hash The web user Two-step sign-in (TOTP) secret Command line frames.db , as plain base32 text The web user, and anyone who can read frames.db Admin session Login var/sessions/ (directory mode 0700) The web user Trusted-device signing key First successful login var/device.key (mode 0600) The web user Frame key The kiosk, on first run On the device: app-private storage. On the server: only its SHA-256 hash Root on the device; the server holds no usable key Pairing code The server frames.db until claimed (24 hours) The web user Drop link and card link secrets The server Shown once; only a SHA-256 hash is stored The person you gave the link to Calendar addresses and Nextcloud album link The admin frames.db ; never returned by an admin API call The web user Home Assistant token The admin frames.db as plain text inside the widget settings; write-only in the admin The web user; the kiosk's native code through its authenticated request Kiosk PIN The admin frames.db , as a salted PBKDF2 hash The web user; the kiosk APK signing key You Your keystore, outside the repository You Release signing key You Offline. Never on the server You config.php holds no secrets. The release public key may appear in it.","url":"https://calevans.com/picture-frame/docs/security/index.html#where-each-secret-lives","tags":"","category":""},{"id":212,"title":"Threat model","pageTitle":"Security","text":"Threat What the attacker has What stops them What they can still do A drop link leaks The URL of one album's upload page The link only accepts uploads. Photos wait in an approval queue. Rate limits, quotas, expiry, revoke and rotate Fill the pending queue up to its caps; you reject the photos A card link leaks The URL of one sender page Per-sender and per-address send limits; revoke and rotate; the sender sees only their own cards Send cards, up to the limits, until you revoke the link. Cards reach the frame without approval A hostile image is uploaded A crafted JPEG, PNG, WebP or HEIC Magic-byte check, size caps before decoding, a separate worker with resource limits, a sandbox, output rebuilt and checked A decoder bug would run inside the sandbox with no network and no access to your data (if the sandbox is on) The admin password is stolen The password, not the second factor Two-step sign-in, rate limits, session limits Nothing, if two-step sign-in is on. If it is off, they are the admin: re-entering the password does not help against someone who has it The server is compromised Code execution as the web user, or write access to frames.db The device checks every update itself, against two independent keys that never touch the server Read all server data, change settings, show content on frames. Not: install code you did not sign A frame is stolen or its ADB is reached Root on one frame Frame keys are per frame; revoke ends access at once Impersonate that one frame, read what it can read, including its Home Assistant token Someone on the frame's LAN reaches ADB A network path to port 5555 An address allow-list in the boot script, applied by firewall rules Anything, if their address is allowed or the list is turned off Script runs on the frames web origin A script injected into a page No inline script, script-src 'self' , no innerHTML , the frame cookie is HttpOnly , secrets travel only in a header See below Someone sniffs the LAN A position on the frame's network HTTPS to the server The one plain-http exception: Home Assistant on a private address","url":"https://calevans.com/picture-frame/docs/security/index.html#threat-model","tags":"","category":""},{"id":213,"title":"What a script on the frames origin can do","pageTitle":"Security","text":"The frames pages, the admin and the public pages share one origin ( https:///frames/ ). That is deliberate: it keeps the install to one virtual host. It also means a cross-site-scripting hole would be serious, so the code goes to some length to prevent one: Every page sends default-src 'none' with script-src 'self' and style-src 'self' . No page allows unsafe-inline or unsafe-eval . Tests fail if a widget fragment contains style= , an on…= handler or a