Widgets

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.

Turn widgets on and off

1. Select Frames, then the frame.
2. Open Widgets in the rail on the left.
3. Switch each widget On or Off.
4. 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.

Where widgets appear on the frame

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:

Changes you save reach the frame within a minute or two. The frame polls the server about every 20 seconds.

Clock

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.

Weather

Shows current conditions, the next 24 hours, and the next 7 days from the US National Weather Service (api.weather.gov).

Set it up

1. In the admin, select Library, then Add location under Locations.
2. Enter a Name, a Latitude and a Longitude. Leave Stations empty at first.
3. Select Add location.
4. Open the frame, then Widgets, switch Weather on, and select Save.
5. Open the Weather section and pick the Location. If you have no location yet, select New location there.
6. 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.

How it refreshes

The fetcher downloads from the National Weather Service. It needs the cron job from Install the frame server.

The admin refuses to delete a location that a frame's Weather widget uses.

Calendar

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.

Set it up

1. 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.
2. In the admin, select Library, then Add calendar under Calendars.
3. Enter a Name and the calendar's Share URL. Add a Color like #6cb6ff if you want a colored dot.
4. Select Add calendar.
5. Open the frame, then Widgets, switch Calendar on, and select Save.
6. 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/<token>
• https://cloud.example.org/remote.php/dav/public-calendars/<token>

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.

Photos

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:

All of it is explained in Photos.

Home Assistant

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.

What you need

• 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.

Set it up

1. In Home Assistant, create a dedicated user for the frame that is not an administrator.
2. 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.
3. In the admin, open the frame, then Widgets, switch Home Assistant on, and select Save.
4. Open the Home Assistant section.
5. Enter the Home Assistant address: the address only, no path, for example http://homeassistant.local:8123.
6. Paste the token into Access token. The admin never shows it again. It shows Token set, and you can replace or remove it.
7. Select Save.
8. 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.

Address rules

Sign-in options

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.

Both options keep the frame limited to one place: the kiosk allows navigation only to the Home Assistant address you saved.

Cards

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.

Set it up

1. Open Card designs and upload covers and stamps. See Card designs.
2. Open the frame, then Widgets, switch Cards on, and select Save.
3. Open the Cards section.
4. Under Sender links, select New sender link.
5. Enter the sender's Name, which is printed on every card their link sends, then select Create link.
6. Select Copy link and send it to that person. It looks like https://frames.example.com/frames/notes/<43 characters>.

What the relative sees

Opening the link shows a page for sending a card to the frame's recipient ("Cards for Grandma"). They:

1. Pick a cover. The covers are grouped by category.
2. Write a message of up to 400 characters and 8 lines.
3. Sign it, by drawing with a finger or by typing a name of up to 40 characters.
4. 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.

What shows on the frame

• 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.

Settings per frame

In the frame's Cards section, under Settings:

Sender links

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.

Cards sent

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.

Privacy

• 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.

Limits

Card designs

Card designs in the top bar holds the art for every frame's cards.

Covers are the card fronts.

1. Select Upload covers.
2. Choose images. JPEG, PNG or WebP, up to 4 MB, 400 to 4096 pixels on each side.
3. Choose a Category for each cover.
4. 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.

1. Select Upload stamps.
2. Choose images. JPEG, PNG or WebP, up to 4 MB, 100 to 4096 pixels on each side.
3. 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.

How widgets are built

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.

Related

• 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.