Repository navigation
Releases
Free Family Planner v0.7.1 — one session cookie, and an honest sign-out
A hosted display could sign in and still get "not signed in" from every API call behind the page, with the calendar panel wrongly blaming the server-held Google connection. The cause was the session cookie: it was issued with the path of whichever script answered, so a browser ended up holding two cookies of the same name, one for the planner and one for its api/ folder. When the session expired and someone signed in again, only the first was renewed; browsers send the more specific one first, PHP keeps the first, and every API call presented the dead ID.
- One cookie for the whole app. Its path is the planner's own folder, derived from where the app sits under the web root, so rewrites and routers can't change it.
- A stale duplicate is resolved on the spot. If two arrive, the app-root one wins and the stray is expired, so the very first request after a re-login succeeds and the browser is tidied up.
- A lost sign-in is named and handled. When the planner's own server answers 401, the calendar panel says "Signed out of the planner" rather than anything about Google, and the page goes to the login page once, within seconds, and never loops.
If you are on v0.7.0 and the planner opens but shows nothing, this is why: upgrade, reload, sign in once.
Free Family Planner v0.7.0 — the Google connection that stays connected
A display that kept freezing every hour and asking for Google again turned out to be running the in-browser Google flow even though its server held a perfectly good connection. This release makes sure that cannot happen again.
The server-held Google connection now wins
At start-up the page asks its own server whether it holds a Google connection, and uses it whatever the config says. The in-browser flow needs a person at the screen to approve a new token roughly every hour, and on a tablet Google's window opens as a new tab laid over the planner — which is what an hourly freeze looks like. A server connection never needs anyone.
The browser's copy of the config can no longer outrank the server's
When a save to the server fails, the wizard keeps a copy in the browser so nothing is lost. That copy used to override the server's config forever, and a later wizard save would write the stale mixture back to the server. Now both sides stamp savedAt: the newer one wins, a tie goes to the server, and a losing copy is deleted so it cannot creep back.
In-browser Google is calmer
If you do use the in-browser flow, it renews its token automatically at most once per page load and never on a timer. When that one attempt fails, the calendar panel asks for a sign-in and waits.
You can see which mode a display is in
The published state now carries a runtime record: build, live Google mode, where the config came from, and whether a stale browser copy was dropped. ffp state | jq .runtime
Free Family Planner v0.6.1 — recovery that actually recovers
A real wall display ran for 34 hours and its own telemetry showed what went wrong: the clock was still ticking, but the weather and calendar had been silent for 20 hours, and the nightly reload had written its reason while the page carried straight on — location.reload() did nothing at all.
- Reloading escalates and is verified. reload → replace → href → open, and if the page is still running 90 seconds later it says so in the health record. The old code set a flag before reloading, so one ignored reload disabled recovery permanently.
- A feed silent for two hours triggers recovery. Previously only a stalled clock did, which meant a display could sit there showing yesterday's weather for a day. That is the freeze people actually see.
- Waking from sleep pulls everything fresh instead of waiting out the 10- and 15-minute intervals.
- A screen wake lock is held where the browser allows it, since a dozing tablet stops fetching.
- Health is read when the snapshot is published, so
ffp state | jq .healthis never stale or empty.
And a limit stated plainly: if the browser's renderer hangs, the page's own code stops with it and nothing inside can help. For an unattended display, pair this with a kiosk browser watching from outside — the four Fully Kiosk settings that cover it are in docs/kiosk/android-tablet.md.
Free Family Planner v0.6.0 — the display stops asking to sign in
Two faults were making a wall display useless after an hour or two. Both are fixed.
Google is now connected on the server
An in-browser OAuth flow is the wrong model for a display nobody stands at: access tokens last about an hour and Google's silent in-page renewal simply does not answer on some tablets, so the display ends up parked on a sign-in screen.
The server now holds the OAuth client secret and a refresh token and mints access tokens on demand. The page asks its own server for calendar data and never talks to Google. You connect once, in ⚙ Setup → Calendars → On the server: paste the client ID and secret, press Connect, approve at Google, done. Reloads, reboots and nightly refreshes no longer cost you a sign-in, and it works from any address rather than only localhost or https.
The in-browser flow is still there if you prefer it. Walkthrough, including the Testing vs Published seven-day refresh-token trap: docs/google-calendar.md.
The planner's own login stopped expiring
A hosted display was being signed out every half hour even with a seven-day cookie. Distribution PHP expires sessions after 24 minutes, Debian sweeps the session folder on a timer, and session.lazy_write means an idle-but-alive display never refreshes its session file — so the server threw the session away while the cookie was still valid. Sessions now live in the planner's own private folder with a matching lifetime, touched on every request.
Also
api/google.phpon both servers, documented in docs/api.md;ffpreaches it with a bearer token.- Fixed a latent crash on any body-less POST to the local server.
deploy.shno longer skips tracked files underincludes/.
Free Family Planner v0.5.2 — the token renewal, actually wired in
Use this instead of v0.5.1. That release carried only the gcal.js half of the fix: the renewal existed but nothing called it, so the calendar still stopped updating after about an hour.
Now in place and verified in a browser against a stubbed Google:
- the token is renewed silently before any calendar load that needs it, and by a keep-alive on its own schedule;
- a mid-flight 401 retries once quietly — only a failed silent renewal falls back to the sign-in prompt;
- the watchdog's list heartbeat flag is declared (a quiet list no longer looks dead, and the error path no longer throws);
- health is published with the first snapshot rather than a minute later.
ffp state | jq .health
Free Family Planner v0.5.1 — the calendar no longer stops after an hour
Found with v0.5.0's own health telemetry: on a display up for 8.8 hours, the calendar had not refreshed for 7.8 of them.
Google access tokens expire after about an hour. The expiry was reported as Session expired — sign in again, and from that moment every refresh skipped Google — so the wall sat on stale events until somebody reloaded the page. On a wall display nobody is there to tap sign in.
- The token's expiry is tracked and renewed silently before any load that needs it, plus a keep-alive on its own schedule.
- A 401 mid-flight retries once quietly; only a failed silent renewal falls back to the sign-in prompt.
- Watchdog fix: Firestore only calls back on change, so a quiet shopping list looked dead. List heartbeats now tick while the subscription is healthy and stop only on a real error.
ffp state | jq .health shows the heartbeats.
Superseded by v0.5.2. This release shipped only half the fix — the renewal was present but never called. Use v0.5.2.
Free Family Planner v0.5.0 — screen care and a watchdog
For a display that is on every hour of every day.
Screensaver
After an idle stretch the panels give way to a clock, the next event, the temperature and the electricity price, drifting slowly around a dark screen. Styles: drifting, bouncing (corner to corner), starfield, or plain black. Any touch brings the planner straight back. Set the style and the idle time in ☰ Display → Screen care.
Burn-in care
Pixel shift nudges the whole layout a couple of pixels every few minutes, so panel edges, the clock and the status bar never sit on the same pixels for weeks. On by default; it works alongside the existing night dim.
Watchdog
Wall displays run one page for months, and browsers eventually get slow or wedge.
- Heartbeats on the clock, calendar, weather and lists. A stale feed is flagged; a genuinely wedged page reloads itself.
- A sleeping device is told apart from a wedged one by whether the watchdog's own timer ran on schedule, so a screen-off nap never triggers a reload.
- Reloads are capped at three per half hour — a reload loop is worse than a freeze, so it stops and keeps the evidence instead.
- The bundled WeatherStar app is recycled every six hours, and the page refreshes once nightly in a quiet hour (both configurable).
- Uptime, heartbeats, memory, recent errors and the reason for the last reload ride along in
/api/state:ffp state | jq .health.
If the browser hangs hard rather than the page, no in-page watchdog can help — pair this with a kiosk browser that reloads on its own schedule.
Free Family Planner v0.4.1 — login setup, tokens, demo feed
- First run on a hosted install opens Create your login — no more hand-editing a PHP file.
- ⚙ Setup → Access: change the username/password, generate or remove an API token (for
ffp, scripts, agents) and a hub read token (for Home Assistant's REST sensor). Local installs manage the API token and say plainly that a LAN install has no login page. /api/v1/accesson both servers;ffp access,ffp access token,ffp access set-login.- Demo calendar feed at
demo/family-demo.icson every install — 27 fictional family events (soccer, piano, scouts, dentist, camping…) for showcasing without a real calendar. Add it as an ICS feed in the wizard.
Tested end to end on both servers.
Free Family Planner v0.4.0 — API and CLI
Free Family Planner v0.4.0 — API and CLI
Everything the setup wizard does is now an HTTP API, so the planner can be set up and driven from a terminal, a script, or an agent.
/api/v1 on both servers
Same routes on the local server (tools/serve.py, Docker, desktop) and the hosted PHP install:
- config — read, patch or replace the site config
- tiles — list, add, replace, remove House tiles
- hub — connect Home Assistant or Home-IO, test it, list entities and states, call actions (toggle, lock, open, take a picture), read calendars, read/write the hub's shopping to-do list
- lists, meals, chores, events — the self-hosted data store
- state, power — what the wall shows, and the electricity prices
Auth: open on the LAN for local installs, or a bearer token (data/api-token locally, FP_API_TOKEN hosted), or the site login. GET /api/v1 lists the routes; docs/api.md has the details.
ffp, the command-line client
Python 3, standard library only:
ffp hub set --type homeassistant --url http://homeassistant.local:8123 --token <HA token>
ffp hub entities --domain light
ffp tiles add light.kitchen --label Kitchen --control
ffp list shopping add "Milk"
ffp meals set Tuesday Tacos
ffp statePoint it once with ffp --url … --token … save-config, or ffp login <user> for a hosted install.
Tested on both servers against a real Home Assistant.
Free Family Planner v0.3.1
Free Family Planner v0.3.1
Polish from a night on a real wall display with Blink cameras.
- Command tab is the house only: the House panel and the Electricity panel. Everything else stays on FAMILY (add anything back per screen in ☰ Display).
- Camera tiles show the picture's age and the camera's motion state (Blink: "motion off", MOTION in red, battery warnings). Tap a camera tile to ask it for a fresh picture; the server then tells Home Assistant to re-read the camera so the still lands in seconds instead of waiting for Blink's five-minute poll. Verified on real Blink cameras.
- Tiles keep their size in a sparse House panel instead of stretching.
- ☰ Display → House → Tiles… jumps straight to the wizard's Home hub step; the tile picker has a ↻ Refresh from hub button for devices added while it's open.
- Family tab layout restored to the original.
Fixes since v0.3.0 also include: wide status-bar content can no longer push the layout past the right edge; the wall never runs mixed cached modules after a deploy.