tess1o/geopulse v2.1.0

Release v2.1.0

on GitHub

GeoPulse 2.1.0 is about the timeline. It can now explain why each stay, trip and data gap looks the way it does. It follows your local days when you travel across time zones, and it detects stays and trips more accurately when GPS data is sparse or noisy. Around that, this release adds bulk editing of GPS points, drag and drop imports with notifications, a reworked debug export for bug reports, and 22 new MCP tools.

Upgrading is safe and needs no changes to your compose file, Helm values or nginx configuration. Set the new version, pull, and restart. After the upgrade, GeoPulse regenerates every user's timeline once in the background, so your history gets the explanations and the detection improvements too. Manual trip and stay corrections are kept. If you customized the stay speed threshold with an environment variable, see Upgrading: it is now in km/h.

Contents

• Highlights
• More accurate stays and trips
• Other changes
• Upgrading · API changes
• New configuration · Changed configuration · Removed configuration
• Fixes
• Under the hood

Highlights

Why does the timeline look like this?

Every stay, trip and data gap now has a Why this stay? (or Why this trip?, Why a data gap?) entry in its card menu. It opens a dialog that shows:

• The event's GPS points on a map, with a few points before and after it, the stay radius and the saved place.
• How it was decided, step by step. For example: "Starts where you stopped moving: 3 points slower than 9 km/h for 2 min", "Counted as a stay from 08:42: by then you had been within 50 m of this place for 7 min" or "Ended at 17:05, when you were 180 m from the centre, more than the 50 m stay radius". Select a step to see the points it is based on.
• Points left out, for example because they were less accurate than your accuracy threshold.
• Points that were never stored: the filters of your GPS sources (accuracy, speed, duplicates) that may have dropped points before they reached the timeline.

The trip classification dialog links to it with Why does this trip start and end here?, so you can see both why a trip is a car trip and why it starts and ends where it does.

The explanation is recorded when the timeline is generated. Timelines generated before 2.1.0 get it when GeoPulse regenerates them after the upgrade; see Upgrading.

Local days when you travel

GeoPulse 2.0.0 added the Local time at each place setting, which shows times in the local time where you were. In 2.1.0 the Timeline page follows local days as well: a day ends at local midnight wherever you are, not at midnight in your profile timezone.

• Stays are dated in their own time zone.
• Trips and data gaps are dated by the local clock at each end, as their cards show them. A trip spans two days only when it passes midnight on the departure or arrival clock, so an overnight flight across the date line stays on its departure day.
• The map, the GPS path, weather, photos and notes for a day cover the same local day as the timeline.

With the default Profile timezone setting, nothing changes.

Edit several GPS points at once

On the GPS Data page, editing a point no longer applies the change and regenerates the timeline right away. Instead:

• The row shows the new values and is marked as changed, and a banner counts the changes that are not applied yet.
• Apply Changes saves them together and regenerates the timeline once, from the earliest edited point. Revert All, or the revert button on a row, discards them.
• Leaving the page with unapplied changes asks for confirmation first.

The timeline regeneration and the coverage rebuild now run in the background. The coverage rebuild only runs when a point actually moved.

Data Export / Import

• Drag and drop a file onto the import area, or click to select it. Files of the wrong type are rejected with a message that lists the supported extensions.
• You can leave the page while an export or import runs. GeoPulse sends a notification when your export is ready to download (with its size and how long it stays available) or when your import has finished or failed. The notification opens the right tab.
• Recent exports are listed with their status, size, the time they stay available until, and whether you already downloaded them.

Debug export for bug reports

The debug export (Help & Support → Export Debug Data) was reworked so that a reported timeline problem can be reproduced exactly:

• Describe the problem and when it happened. The text is included in the export, so it is clear what to look at.
• Include your current timeline, so it can be compared with the timeline regenerated from the export.
• The export also includes your manual timeline corrections, the anonymized places your stays were matched to, your GPS source filter settings and the state of your timeline (when it was last built, and whether a rebuild was pending).
• Privacy: all coordinates move east or west by the same random offset; latitude is never changed, so distances, speeds and shapes stay exact. Place names are replaced by placeholders such as "Location 1". Device names and GPS telemetry are not included, and the offset is not stored in the export.

The debug import regenerates the timeline and shows a report: which stays, trips and data gaps match what the user saw, which differ, which are missing or new, why each server created them as it did, and warnings that explain common differences, such as GPS points received after the user's timeline was last built.

22 new MCP tools

The MCP server grew from 10 to 32 read-only tools, and the AI Assistant uses the same tools:

All tools only read data and are marked read-only, so MCP clients can run them without asking for confirmation. searchPhotos needs the Immich integration and returns photo metadata only, getWeather needs weather enabled on the server, and getCoverageSummary needs coverage enabled for the user. See the MCP documentation.

More accurate stays and trips

GeoPulse regenerates every timeline once after the upgrade, so these improvements apply to your history as well; see Upgrading.

• Stops recorded with only a few points. Some trackers send almost nothing while you are stopped, and the few points they send can report a driving speed. A stop is now recognized when the next point arrives much later and only a short distance away (#632).
• Favorite areas keep a stay together. Points farther from the stay's centre than the stay radius no longer end the stay when they are in the same favorite area, so a campus or a large park stays one stay.
• Speeds ignore short bursts of bad readings. The maximum speed of a trip must now be held for at least 30 seconds, and the average speed is weighted by how long each reading lasted. A few bad readings in quick succession, common when a tracker wakes up and the GPS fix is still settling, barely affect the average and cannot set the maximum speed on their own. The trip classification dialog explains both values.
• Boat trips. GPS points less accurate than your accuracy threshold no longer count as water evidence. Before, network fixes far off the real track could hide that a trip was on water (#631).
• Flights. In Timeline Preferences → Trip Classification → Flight:
  • Minimum Distance: trips shorter than this are never classified as flights. This prevents short trips with a GPS jump from becoming flights. The default 0 keeps the current behavior.
  • Minimum Peak Speed can now be set as low as 150 km/h, for light aircraft. It was 400 km/h.
  • Altitude-based Detection (off by default): also classifies a trip as a flight when it stays well above its start and end points for a quarter of its time and climbs or descends quickly. This is meant for gliders, balloons and light aircraft that fly too slowly for the speed rules (#621). It needs GPS altitude in at least half of the trip's points. Known limitations: flights that land far below their take-off point, such as paragliding from a mountain into a valley, are not detected, and a ski day or a cable-car loop recorded as one trip may be detected as a flight.

Other changes

• The stay speed threshold is now a real km/h value. It was shown in km/h but compared with GPS speeds in m/s, so a stored value of 2.5 meant 9 km/h. Saved settings are converted on upgrade, and so are settings in GeoPulse exports from older versions, so stays are detected exactly as before. The default now reads 9 km/h, the same threshold as before.
• The Minimum Accuracy Ratio stay setting was removed. It never took effect: the accuracy filter had already removed every point it would have counted. Saved values are removed on upgrade.
• Translations. Adding a language is now one command: make i18n-add LOCALE=de NAME=Deutsch INTL=de-DE creates the catalog as a draft and registers the language with the backend. make i18n-status shows the coverage of each language, and make i18n-missing LOCALE=de lists every string still to translate, with its English text. Draft languages are visible only in development builds until they are marked ready. See frontend/src/locales/README.md if you want to help translate GeoPulse.

Upgrading

Docker Compose and Unraid: set GEOPULSE_VERSION=2.1.0 in .env, then run:

docker compose pull
docker compose up -d

On Unraid, Community Apps installations update as usual from the Unraid web UI.

Kubernetes (Helm): upgrade to the 2.1.0 chart as usual. No values changes are needed.

Manual installation and Proxmox LXC: replace the backend and frontend files as usual. No nginx changes are needed.

After the upgrade:

• If you set GEOPULSE_TIMELINE_STAYPOINT_VELOCITY_THRESHOLD: it is now in km/h. Multiply your value by 3.6, for example 2.5 becomes 9.0. Users' own settings are converted automatically; only the server default comes from this variable.
• If you set GEOPULSE_TIMELINE_STAYPOINT_MIN_ACCURACY_RATIO: remove it. It is ignored.
• Timelines are regenerated automatically. On the first start, GeoPulse queues a one-time regeneration of the full timeline of every user with GPS data, and each user gets a Timeline refresh scheduled notification. Manual trip and stay corrections are kept.
  • Users are processed in the background, two at a time by default, so on servers with many users or years of data it can take a while. Administrators can follow the progress in Administration → Timeline Regeneration, and can change the pace with GEOPULSE_TIMELINE_REGENERATION_CAMPAIGN_MAX_CONCURRENT_TASKS and GEOPULSE_TIMELINE_REGENERATION_CAMPAIGN_INTERVAL.
  • Until a user's turn comes, new GPS points are added to their timeline when it is regenerated.
  • If the timeline regeneration from 2.0.0 was still in progress, this one replaces it, so no timeline is regenerated twice.

API changes

For scripts and integrations using the REST API:

• PUT /api/v1/gps/points/{pointId} now returns { point, timelineJobId, timelineRegenerationScheduled, coverageRebuildScheduled } instead of the point itself. The timeline regeneration runs in the background instead of during the request.
• New PUT /api/v1/gps/points/bulk applies up to 1000 point edits in one transaction and schedules one timeline regeneration.
• In timeline preferences, staypointVelocityThreshold is now in km/h, and staypointMinAccuracyRatio was removed.
• Endpoints that start a timeline regeneration (timeline preferences, favorites) return the ID of the job that is already running when there is one. The regeneration then runs right after that job.
• The GeoPulse export format is now version 1.2: the stay speed threshold in user preferences is in km/h, and timeline rows include their explanations. Older exports still import, with the threshold converted.

New configuration

These are server defaults; each user can change them in Timeline Preferences.

Changed configuration

Removed configuration

Fixes

• AI Assistant and MCP: relative dates such as "yesterday", and date ranges, now use your profile timezone instead of the server's.
• Timeline settings: saving no longer shows an error when the timeline regeneration cannot start right away. The change is saved, and the timeline updates in the background.

Under the hood

• The PMD static analysis is now a blocking CI check, and the code was cleaned up to pass it, for example with locale-independent text comparisons, HTTP clients that are always closed, and error causes that are kept.
• New integration tests replay real days from bug reports through the timeline engine, and new end-to-end tests cover admin user management, API tokens, timeline preferences and GPS point editing.