Picture Frame System

Get started

Start here: build your own Picture Frame

On this page

This is the documentation for the Picture Frame System. It is for people who own a PF1007L Wi-Fi photo frame, are comfortable in a terminal, and can run a small Linux server. When you finish the first-time path below, you have a frame on your wall that shows your photos, the weather and your calendar, talks only to your server, and updates itself.

Nothing here needs a cloud account or a subscription. The server is PHP 8.5 and SQLite.

What you are building

Three pieces, set up once:

  • The frame, unlocked so you can put your own software on it.
  • The server, a PHP and SQLite site on Apache that the frame talks to. You use its admin page to choose what each frame shows.
  • The kiosk app, built by you, that turns the frame into a locked-down dashboard.
flowchart LR
    F["Frame<br/>kiosk app"]
    S["Your server<br/>PHP 8.5 + SQLite"]
    A["You<br/>desktop admin"]
    R["Relatives<br/>phone links"]
    X["Photo, weather and<br/>calendar sources"]
    A -- "HTTPS login" --> S
    R -- "private links" --> S
    F -- "frame API key" --> S
    S -- "one cron job" --> X

Frames and phones only talk to your server. Your server only talks to the sources you list.

The first-time path

Follow these pages in order. The server and the unlock are independent, so you can do them in either order. Provisioning needs both.

flowchart LR
    H["1. Check the hardware<br/>and what you need"] --> U["2. Unlock the frame<br/>root ADB + backup"]
    H --> S["3. Install the server<br/>Apache, PHP, SQLite"]
    U --> P["4. Build and provision<br/>the kiosk"]
    S --> P
    P --> C["5. Claim the frame<br/>six-digit code"]
    C --> W["6. Choose widgets<br/>and photos"]
    W --> K["7. Keep it updated<br/>from the admin"]
Step Page What you have when you finish
1 Hardware and requirements You know whether your frame is supported and what to gather.
2 Unlock your PF1007L A verified backup of the frame's storage, and root ADB.
3 Install the frame server and Use the admin A running server, a database, an admin login, optional two-step sign-in, and a tour of the admin.
4 Build the kiosk and set up a frame The kiosk installed, locked in, and showing a pairing code.
5 Claim the frame The frame claimed in the admin.
6 Widgets and Photos Clock, Weather, Calendar, Photos, Home Assistant and Cards on the screen.
7 Update the kiosk A way to send new kiosk versions to a frame that is far away.

Plan on an afternoon for the unlock. Most of that is waiting for the backup to be written and checked, which takes about 90 minutes.

Every page

Page Kind Read it when
Hardware and requirements Reference You are deciding whether to start.
Unlock your PF1007L Guide You are ready to back up and root the frame.
Install the frame server Guide and reference You are setting up or updating the server.
Use the admin Guide and reference You are creating logins or learning the admin screens.
Build the kiosk and set up a frame Guide and reference The frame is unlocked and the server is running.
Widgets Reference You are setting up what a frame shows.
Photos Guide and explanation You are choosing how photos reach a frame.
Update the kiosk Guide and explanation You are sending a new kiosk version to a frame.
Troubleshooting and recovery Troubleshooting Something is not working.
A guide for the family Guide You want something to print for the person with the frame, or for relatives who send cards and photos.
Security Explanation You want to know how the system protects your frames and data.
Developer documentation Developer docs You want to change the code or write a widget.

Find a page by goal

I want to... Go to
Check my frame is a PF1007L Hardware and requirements
Back up the frame before touching it Unlock: back up the storage
Install the server on Apache Install the frame server
Create an admin login Use the admin
Turn on two-step sign-in Use the admin
Build the kiosk app Provisioning: build the kiosk
Claim a frame Provisioning: claim the frame
Show a Nextcloud album Photos: method 1
Upload my own photos Photos: method 2
Let relatives send photos Photos: method 3
Let relatives send cards Widgets: Cards
Show Home Assistant Widgets: Home Assistant
Send a new kiosk version Update the kiosk
Fix "maintenance" after a deploy Troubleshooting
Recover a frame that will not boot Troubleshooting
Give a frame to someone Provisioning: give a frame away

How these pages write commands

  • WSL means a shell in your Linux distribution on Windows. PowerShell means an Administrator PowerShell. Server means a shell on the machine that runs Apache.
  • <repo> is the folder that holds this repository.
  • Examples use https://frames.example.com/frames/ for your server, 192.0.2.x for network addresses, and /srv/frame for the install folder. Replace them with your own.
  • Steps you must not skip are marked Warning. Details that are easy to miss are marked Note.

Before you start

Only modify hardware you own. Rooting a frame can brick it. The unlock guide makes you back up the whole storage and check the backup before it writes anything, and it is worth reading all of Unlock your PF1007L before you start.

The repository is MIT-licensed, except the uboot/ folder, which is GPL-2.0-or-later. See the license section of the project README.

Next: Hardware and requirements.

View this page on GitLab