Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions HANDOFF.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ It started on 2026-10-13 as "WinterMiles" (an icTrainer alternative for riding G
| **Herne Hill Velodrome** | Built-in track. The route is in `crates/core/src/velodrome.rs`; the banked track, its paint and the buildings are in `world/venue.rs`. Tested in code, and I've checked a live preview in demo mode on both renderers, each way round (`VP_SMOKE_ROUTE=herne-hill` or `herne-hill-clockwise`). Nobody has ridden it with a trainer yet. |
| **Laps on loop routes** | Lap engine, bests, segments and renderers unit-tested in `crates/core`; smoke-run across the line on Linux with three.js, not yet with the native renderer (macOS). Group standings don't show who is a lap up. |
| **Strava** (OAuth, upload, segments, activities as ghosts) | Never run against the live API. Users must create their own API key (open source can't ship a secret). Scope is `read,activity:read_all,activity:write`. |
| **Dreeve** (API key, upload, rides as ghosts, rides imported as routes) | Request shapes and error mapping are tested against an in-process fake server (`connectors/dreeve.rs` tests). Connecting, listing rides, fetching a track and finding the rides that fit a route were run against a real Dreeve v5.8.2 with about 190 rides on 2026-11-10 (`live_dreeve_lists_rides_and_tracks`, ignored by default, takes `DREEVE_URL`, `DREEVE_API_KEY` and optionally `DREEVE_ROUTE_RIDE`). The upload was tested by hand against a real instance. |
| **Windows and Linux** | Built and packaged by CI on every push (and Arch's package is installed in a container and its libraries checked), but **never run by a person**. |
| **Native renderer** (macOS, opt-in) | wgpu/Metal in an NSView under a transparent webview. Matches three.js in screenshots; HUD-over-native never checked in a real window; no clean release-build performance comparison. |
| **Dense woods and tree sprites** | Checked in both renderers with the smoke harness, and their cost measured only on Apple silicon (about 0.6 M triangles a frame on a wooded climb). Not tried on weaker graphics (Windows/Linux integrated GPUs). |
Expand Down Expand Up @@ -65,7 +66,8 @@ src-tauri/ The app (Tauri 2)
diag.rs Diagnostics log + reports; issues.rs: GitHub new-issue links; snapshot.rs: window PNGs (macOS)
connectors/ Services a ride is uploaded to, and whose past rides can be raced as ghosts:
mod.rs (Connector trait, registry, descriptor types the settings card is built from),
strava.rs (OAuth, upload, recent rides, segments).
strava.rs (OAuth, upload, recent rides, segments),
dreeve.rs (API key, upload, recent rides, ride GPX for route import; a self-hosted Dreeve).
docs/ADDING_A_CONNECTOR.md explains adding one.
geo, photos, smart, group, library, terrain, secrets, store
web/ React + three.js (Vite). ui/ screens, world/ the 3D scene (scene.ts, terrain.ts, trees.ts (tree models, sprite atlas), rider.ts,
Expand Down Expand Up @@ -159,7 +161,7 @@ CI also builds every push to `main`; installers can be downloaded from the run's
- **Laps are `distance` on the loop plus `ridden` for totals.** `RideEngine` keeps `distance` as the position on the loop, in `[0, route.total]`, and adds `lap` (from 1) and `ridden` (metres across all laps). Everything meaning "where on the road" uses `distance`; everything meaning "how far ridden" (FIT, summary, progress, goal) uses `ridden`. Without laps `ridden == distance`, so ordinary rides are unchanged by construction. The choice is only accepted when the route is a loop (`Route.closed`, offered to the page by `route_is_loop`) and is kept on the ride as `laps`. Agreed with the maintainer (#67): ghosts off on lap rides, climbs and segments timed on each lap and kept fastest, and a lap ride never sets the route's best time.
- **Commits are under the maintainer's name only.**

- **Connectors are a trait plus a registry** (`src-tauri/src/connectors/`), not a Strava module with ifs, because Dreeve (self-hosted, API key, no activity page) is the next target and differs from Strava in how it links, what an upload returns and what else it offers. The page draws each service's settings card from the connector's own description, so a new service is one Rust file. Listing past rides (for ghosts) and finding segments along a route are optional parts of the trait whose defaults say the service can't, because services offer different subsets: Strava has both, Dreeve's public API has rides but no segments. `SegmentSource::Strava` became `Remote` plus a `connector` field on the segment; stored segments that still say "strava" are read as Remote from Strava.
- **Connectors are a trait plus a registry** (`src-tauri/src/connectors/`), not a Strava module with ifs, because Dreeve (self-hosted, API key, no activity page) differs from Strava in how it links, what an upload returns and what else it offers. The page draws each service's settings card from the connector's own description, so a new service is one Rust file. Listing past rides (for ghosts) and finding segments along a route are optional parts of the trait whose defaults say the service can't, because services offer different subsets: Strava has both, Dreeve's public API has rides but no segments. Two more optional parts both end in a GPX file but start from different things: `lists_routes` (`saved_routes`, `route_gpx`) lists routes the rider *planned or starred* and feeds Find a route (Strava); `imports_routes` (`ride_gpx`) turns a ride the rider *has ridden* into a route from the routes page (Dreeve). Dreeve has no saved routes, so it doesn't set `lists_routes`. `SegmentSource::Strava` became `Remote` plus a `connector` field on the segment; stored segments that still say "strava" are read as Remote from Strava.

## 10. Known traps

Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,11 +22,11 @@ Free and open source ([GPLv3](LICENSE)) for **Windows, macOS and Linux**. Writte
- **Fitness tracking.** Power curve (5 s to 1 h), an FTP estimate you can apply in one click, power zones on the HUD, and a training-load chart of fitness, fatigue and form.
- **Sensors.** Power meters, heart-rate straps, speed and cadence sensors over Bluetooth and ANT+. When several devices report the same metric the most direct one wins (crank power meter over trainer estimate, strap over relayed HR). Basic trainers with only a speed sensor can use estimated power.
- **Handlebar controllers.** Buttons that speak [OpenBikeControl](https://openbikecontrol.org), an open protocol, shift virtual gears, change the ERG target or workout intensity, skip a workout step, pause and switch camera without letting go of the bars. See [Handlebar controllers](#handlebar-controllers-openbikecontrol).
- **Gamification.** Race the ghost of your best time on each route, chase pace riders at fixed W/kg, and get timed on every auto-detected climb (categorised 4 → HC) and on the Strava segments along the route, with a live "ahead of / behind your best" gap. Race other people's rides as ghosts (GPX, FIT or from your Strava). A season goal (1,000 km by spring by default), week and day streaks, XP, levels and 23 badges.
- **Gamification.** Race the ghost of your best time on each route, chase pace riders at fixed W/kg, and get timed on every auto-detected climb (categorised 4 → HC) and on the Strava segments along the route, with a live "ahead of / behind your best" gap. Race other people's rides as ghosts (GPX, FIT, or from your Strava or Dreeve). A season goal (1,000 km by spring by default), week and day streaks, XP, levels and 23 badges.
- **Group rides.** Ride a route together with friends: share a room code, everyone's rider appears in everyone's world. Goes through a tiny relay server anyone can run (`crates/relay`).
- **Living world.** Village and town signs, summit boards named after the place at the top, and roadside cafés, fountains, bike shops and viewpoints from OpenStreetMap. Dawn, day, evening, dusk or night (with a lamp on the bike), and clear, cloudy, rain, fog or snow — or the weather at the real place right now. Optional street-level photos of the road from Mapillary (bring your own free token).
- **Fan and lights.** A fan that speeds up with your speed, power or heart rate, and a light coloured by power zone, through Home Assistant, a Shelly or Tasmota plug, or any webhook.
- **Recording and sharing.** Every ride is saved as a standard `.FIT` file (GPS, power, heart rate, cadence, laps, normalised power) and can be uploaded to Strava as a Virtual Ride in one click or automatically. Set a second folder under **Settings → Ride files** (iCloud Drive or Dropbox, say) and each ride is copied there too.
- **Recording and sharing.** Every ride is saved as a standard `.FIT` file (GPS, power, heart rate, cadence, laps, normalised power) and can be uploaded in one click or automatically: to Strava as a Virtual Ride, or to your own [Dreeve](https://github.com/dreeveapp/dreeve) server. Set a second folder under **Settings → Ride files** (iCloud Drive or Dropbox, say) and each ride is copied there too.
- **Demo rider.** A simulated rider and trainer so you can try everything with no hardware.

### On the road
Expand Down
31 changes: 26 additions & 5 deletions docs/ADDING_A_CONNECTOR.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Adding a connector

A *connector* is a service a finished ride can be sent to. Strava is one; Dreeve
is next. Each is one Rust file in `src-tauri/src/connectors/`, registered in one
A *connector* is a service a finished ride can be sent to. Strava (OAuth) and
Dreeve (API key) are the two there are. Each is one Rust file in `src-tauri/src/connectors/`, registered in one
place. The page (settings card, upload buttons, auto-upload toggle, the record of
where a ride went) is generic and needs no change for a new service.

Expand All @@ -11,10 +11,12 @@ where a ride went) is generic and needs no change for a new service.
|---|---|
| `src-tauri/src/connectors/mod.rs` | The `Connector` trait, the descriptor types the page draws from, the `ALL` registry, `Ctx` (credential storage + HTTP client) |
| `src-tauri/src/connectors/<id>.rs` | One file per service: a unit struct implementing `Connector` |
| `src-tauri/src/commands.rs`, *Connectors* section | Generic commands routed by connector id: `connectors_list`, `connector_status`, `connector_configure`, `connector_connect`, `connector_disconnect`, `connector_upload`, `connector_rides`, `ghost_import_connector`, `segments_fetch` |
| `src-tauri/src/commands.rs`, *Connectors* section | Generic commands routed by connector id: `connectors_list`, `connector_status`, `connector_configure`, `connector_connect`, `connector_disconnect`, `connector_upload`, `connector_rides`, `ghost_import_connector`, `segments_fetch`; for the optional route features `connector_routes`, `connector_route` (saved routes) and `connector_ride_list`, `route_import_connector` (ride as route) |
| `crates/core/src/types.rs` | `UploadRecord` (what a connector returns, kept per ride under `RideSummary.uploads[id]`), `Settings.auto_upload` (ids to send every ride to) |
| `web/src/ui/Settings.tsx` `ConnectorCard` | Builds the card from `ConnectorInfo`: setup steps, one input per field, connect/disconnect, the auto-upload toggle |
| `web/src/ui/Summary.tsx` `UploadButtons` | One button per connected connector on the summary and history screens |
| `web/src/ui/Explore.tsx` | "Your <name> routes" in Find a route, for connectors with `lists_routes` |
| `web/src/ui/Home.tsx`, `web/src/ui/RemoteImport.tsx` | "Import from <name>…" on the routes page and its dialog, for connectors with `imports_routes` |
| `web/src/ui/RideSetup.tsx` | "From <name>…" ghost import and "Find <name> segments" for every connected connector that offers them |

## Steps
Expand Down Expand Up @@ -100,6 +102,7 @@ where a ride went) is generic and needs no change for a new service.
}
```

`dreeve.rs` is this shape, with tests against a fake HTTP server to copy.
`AuthKind::OAuth` connectors (see `strava.rs`) get `open_browser` to show the
consent page and listen on a loopback port for the redirect. The page shows
"Connect to X" / "Waiting for X in your browser…" for OAuth and "Save and
Expand All @@ -115,7 +118,9 @@ where a ride went) is generic and needs no change for a new service.
That is the only place the app enumerates connectors.

3. **Optional CSS.** Upload buttons get the classes `upload <id>`; add a
`button.<id>` rule in `web/src/styles.css` for a branded colour (Strava has one).
`button.<id>` rule in `web/src/styles.css` for a branded colour: define
`--<id>` next to `--strava` and `--dreeve` in `:root` and use it for the
background and border (Strava and Dreeve have one each).

## Rules of the road

Expand Down Expand Up @@ -143,7 +148,23 @@ where a ride went) is generic and needs no change for a new service.
the listing's summary polyline: `connectors::find_rides` uses it to mark the
rides that ride the chosen route from its start, and pages back until a few
do (at most five pages). The ride setup then shows "From <name>…" with the
fitting rides first. The defaults say the service can't list rides.
fitting rides first. The defaults say the service can't list rides. Set each
ride's `sport` to the service's sport type in Strava's vocabulary ("Ride",
"GravelRide", …) so the rider can filter by bike.
- **Saved routes are optional.** Override `lists_routes` to return `true` and
implement `saved_routes` (the routes the rider planned or starred, starred
first) and `route_gpx` (one of them as GPX, by the id `saved_routes` gave;
keep ids as text). Find a route then shows "Your <name> routes". Strava does
this; a service that only holds finished rides does not.
- **Importing a ride as a route is optional** and builds on listing rides.
Override `imports_routes` to return `true` and implement `ride_gpx`, which
returns one ride as GPX text with elevation. The routes page then shows
"Import from <name>…": a dialog listing every ride (`connectors::list_rides`,
up to twenty pages) with search, a bike filter and a distance range.
Don't confuse the two: `lists_routes` offers routes the rider *planned*
(Find a route); `imports_routes` turns a ride the rider *has ridden* into a
route (the routes page). Both end in a GPX file in the library. Dreeve sets
only `imports_routes`, Strava only `lists_routes`.
- **Finding segments is optional too.** Override `finds_segments` to return
`true` and implement `segments_near`, which gets `[south, west, north, east]`
boxes along the route and returns each segment's shape as `(lat, lon)` points
Expand Down
4 changes: 2 additions & 2 deletions docs/wiki/Architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ src-tauri/ The app (Tauri 2)
mapdata Downloading and caching map data (vector tiles, Overpass)
diag The diagnostics log and reports
group, smart Group-ride client; fan and light control
connectors/ Services rides upload to (one file per service, Strava today)
connectors/ Services rides upload to (one file per service: Strava, Dreeve)
geo place search and route planning
web/ React screens and the three.js world
```
Expand All @@ -35,7 +35,7 @@ web/ React screens and the three.js world
1. **Start:** the route is built (resampled every few metres, smoothed, climbs found). Map data for the route is loaded from the cache or downloaded: vector tiles for scenery, Overpass for building detail and the route's road tags (surface, width, lanes, trail grades). The `World` combines it: a height field pinned to the road, the scene (forests, water, other roads), structures, the route road and barriers.
2. **Loop (50 Hz, Rust):** sensor readings are merged (most direct source wins), the physics advances the rider, rivals and ghosts move, and once a second the trainer gets a command (gradient or ERG target) and the diagnostics log gets a line. State goes to the page 20 times a second.
3. **Drawing:** the page asks for meshes in compact binary form (terrain chunks streamed around the rider with their trees, the road ribbon, structures, barriers, the tree models) and draws them with three.js; trees beyond about 200 m become camera-facing sprites rendered from the same models — or the native renderer draws the same meshes with Metal beneath a transparent page that shows only the HUD.
4. **End:** the ride is saved as FIT, personal bests, XP and badges are updated, and it can be uploaded to any connected service (Strava today).
4. **End:** the ride is saved as FIT, personal bests, XP and badges are updated, and it can be uploaded to any connected service (Strava, Dreeve).

## Design choices

Expand Down
19 changes: 19 additions & 0 deletions docs/wiki/Dreeve.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# Dreeve

[Dreeve](https://github.com/dreeveapp/dreeve) (formerly *Statistics for Strava*) is a self-hosted dashboard for your sports data. VeloPopuli can send every ride's `.FIT` file straight to your own instance.

1. In Dreeve's admin panel open **Settings → Security → API access** and generate a key (it looks like `drv_…`).
2. Set it as `DREEVE_API_KEY` in Dreeve's `.env` and recreate the containers. Dreeve must run with `IMPORT_MODE=files`.
3. In VeloPopuli → **Settings → Dreeve**, enter your instance's address and the key and press **Save and test**. The test tells you if the key is wrong or uploads are switched off.

The address must start with `https://`: VeloPopuli refuses plain `http://` so your key isn't sent unencrypted. Only `localhost` and `127.0.0.1` are allowed without it. If your Dreeve runs on your home network over plain http, put a reverse proxy with a certificate in front of it.

Then:

- Rides upload with one click on the summary or history screen, or automatically (toggle on the Dreeve card).
- Dreeve queues the file and imports it within a few minutes; the button shows what the server said. There is no page to open, so look in Dreeve's activity list.
- Dreeve reads everything from the FIT file (power, heart rate, cadence, the route), so nothing else is sent.
- **Your Dreeve rides** with a GPS track can be raced as ghosts: *From Dreeve…* when setting up a ride.
- **Ride one of them again** as a route: *Import from Dreeve…* on the routes page lists your rides, searchable by name or date and filtered by bike and distance. This needs Dreeve 5.4 or later, which exports a ride as GPX.

The key is kept in the system keychain (macOS, Windows) or a file only you can read (Linux).
1 change: 1 addition & 0 deletions docs/wiki/Home.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ VeloPopuli turns any GPX route into a 3D world built from OpenStreetMap and open
- [[Virtual gears]] — shift with keys or a remote instead of your bike's gears (optional)
- [[Progress and goals]] — power curve, FTP, training load, streaks, badges and the season goal
- [[Strava]] — connect, upload, segments and friends' rides as ghosts
- [[Dreeve]] — upload rides to your own Dreeve server
- [[Group rides and self-hosting]] — ride together; run your own relay
- [[Fan and lights]] — Home Assistant, Shelly, Tasmota and webhooks

Expand Down
2 changes: 1 addition & 1 deletion docs/wiki/Riding.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ Not yet: laps in the FIT file, ending the ride on the workout instead of the lap

- **Pace riders** hold a steady W/kg to chase or drop (set them in Settings).
- **Your ghost** — your best ride on the route.
- **Other people's rides** as ghosts — from a GPX or FIT file, or from your Strava.
- **Other people's rides** as ghosts — from a GPX or FIT file, or from your Strava or Dreeve.
- **Climbs** are detected and categorised (4 → HC) and timed; **Strava segments** along the route are timed too.

## Time of day and weather
Expand Down
Loading
Loading