From 542cb803a86d25b7e5235fdc727feb2b14abd47d Mon Sep 17 00:00:00 2001 From: Chuck <33324927+ChuckBuilds@users.noreply.github.com> Date: Wed, 23 Sep 2026 16:35:18 -0400 Subject: [PATCH] docs(starlark): say what happens when the device location can't be used A blank app Location only renders at the device's city when one is set and the Open-Meteo lookup finds it. With no city, no match, or the geocoder unreachable (retried after 30 minutes), the app gets no location and keeps its author's default. The guide, the config page hint, CONFIG_REFERENCE and the CHANGELOG entry now say so. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 4 +++- docs/CONFIG_REFERENCE.md | 2 +- docs/STARLARK_APPS_GUIDE.md | 7 ++++--- web_interface/templates/v3/partials/starlark_config.html | 2 +- 4 files changed, 9 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d7534016..c3e81cca 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -28,7 +28,9 @@ accepts both, but the store flags the old spelling as deprecated - `src.device_location` — a blank `Location` field on a Starlark (Tidbyt) app now renders at the device's City / State / Country (geocoded once via Open-Meteo and cached) instead of the app author's hard-coded default, - usually San Francisco. A location saved on the app still wins. Clearing an + usually San Francisco. A location saved on the app still wins. With no + device city set, or when the lookup fails or finds no match, the app keeps + its own default (a failed lookup is retried after 30 minutes). Clearing an app's location in the web UI now actually clears it; the save used to drop the blank field, so the old value stayed. diff --git a/docs/CONFIG_REFERENCE.md b/docs/CONFIG_REFERENCE.md index b5333ee7..705b353b 100644 --- a/docs/CONFIG_REFERENCE.md +++ b/docs/CONFIG_REFERENCE.md @@ -18,7 +18,7 @@ tooling against it. | `web_display_autostart` | bool, `true` | Whether the web interface service starts with the system | `scripts/utils/start_web_conditionally.py` | | `timezone` | string, `"America/New_York"` | IANA timezone for schedules and displays | `ConfigManager.get_timezone()` | | `target_fps` | int, `100` | Legacy "Scroll Frame Rate". Core scrolling no longer reads it: scroll frames are presented at `display.hardware.limit_refresh_rate_hz` divided by each scroll's frame hold, and speed comes from each plugin's scroll settings. Still exposed to plugins via `BasePlugin.global_config` | `src/plugin_system/base_plugin.py` | -| `location` | object | `city` / `state` / `country`. Supplies the **default** for a plugin's own `location_city` / `location_state` / `location_country` setting, so weather, radar and friends follow this device without being configured twice. A value saved on the plugin itself still overrides it. Starlark (Tidbyt) apps get the same treatment: a `Location` field left blank on the app renders at this city (geocoded once via Open-Meteo, coordinates cached permanently) instead of the app author's default, which is usually San Francisco. | `SchemaManager.apply_device_location()`, then plugins via merged config; `src/device_location.py` for Starlark apps | +| `location` | object | `city` / `state` / `country`. Supplies the **default** for a plugin's own `location_city` / `location_state` / `location_country` setting, so weather, radar and friends follow this device without being configured twice. A value saved on the plugin itself still overrides it. Starlark (Tidbyt) apps get the same treatment: a `Location` field left blank on the app renders at this city (geocoded once via Open-Meteo, coordinates cached permanently) instead of the app author's default, which is usually San Francisco. If the city can't be looked up (no match, or the geocoder is unreachable; retried after 30 minutes), the app keeps its own default. | `SchemaManager.apply_device_location()`, then plugins via merged config; `src/device_location.py` for Starlark apps | ## `schedule` — display on/off hours diff --git a/docs/STARLARK_APPS_GUIDE.md b/docs/STARLARK_APPS_GUIDE.md index 7c6362e1..efd5b77d 100644 --- a/docs/STARLARK_APPS_GUIDE.md +++ b/docs/STARLARK_APPS_GUIDE.md @@ -139,9 +139,10 @@ Each app may have different configuration options: - **Location** (lat/lng/timezone): For weather, clocks, transit. Left blank, the app renders at this device's location (City / State / Country under - General settings). Without that, most community apps fall back to their - author's hard-coded default, usually San Francisco. Fill it in only to - point one app somewhere else. + General settings). If no city is set there, or the city can't be looked up + (no match, or the geocoder is unreachable -- retried after 30 minutes), the + app gets no location and falls back to its author's hard-coded default, + usually San Francisco. Fill it in only to point one app somewhere else. - **API Keys**: For services like weather, stocks, sports scores - **Display Preferences**: Colors, units, layouts - **Dropdown Options**: Team selections, language, themes diff --git a/web_interface/templates/v3/partials/starlark_config.html b/web_interface/templates/v3/partials/starlark_config.html index 765eaea2..e099ce1a 100644 --- a/web_interface/templates/v3/partials/starlark_config.html +++ b/web_interface/templates/v3/partials/starlark_config.html @@ -221,7 +221,7 @@ data-starlark-location-key="timezone"> -

Leave latitude and longitude blank to use this device's location (City / State / Country in General settings).

+

Leave latitude and longitude blank to use this device's location (City / State / Country in General settings). If no city is set there, or it can't be looked up, the app uses its own default.

{% if field_desc %}

{{ field_desc }}

{% endif %}