Skip to content

Device sync: send a trip of up to 32 days as day routes and a trip object #3711

Closed

Description

@timohueser

Status: done

Part of #3652 (step 3). Read the epic's section "The bike computer" first; this issue builds it for plans of up to 32 riding days (one part). Parts (33 to 64 days), and the rule for days that the rider removed to make room for part 2, come in #3713.

Depends on #3709 (a line with a gap must not go) and #3710 (the 3 m step).

TL;DR

Goal: The web planner sends a plan of 2 to 32 riding days to the bike computer as one route per riding day plus one trip object, as the phone does, and keeps it right when the plan or the device changes.
Problem: The web planner sends a trip as one route with the nights as waypoints (builder/web/src/lib/device-sync/route.ts:25-41), so the device's "next day", "day done" and "Trip to go" do not work for web trips, and a long trip does not fit in one route file.
Decision: Day routes cut at the day ends of the stored plan, a TypeScript trip object writer, a new form of the stored state sent, and one ordered sync that reads the card first, removes before it counts room, and resumes after a cut. A trip that the rider deleted on the device reads as not on the device, as a deleted route does today.
Systems: web-planner, library
Contracts: the browser state sent (SentRoute, builder/web/src/lib/library/records.ts:145); specs/ble-interface.md §7.7 is used, not changed.
Size: M (2 systems, a stored browser state, about 700 lines)

What goes

  • A plan of 1 riding day: one route, as today (routeObcr, with its stops as waypoints).
  • A plan of 2 to 32 riding days: one day route for each riding day, then one trip object. A rest day has no route.

Day ends. From the stored plan only: planView(trip, line).days (editor.ts:269) with no proposals: pinned nights (kind: 'night' points), moved day ends (splits), else the even day end. The proposed night towns live only in the page (PlannerApp.svelte:272-274) and are not used. So at a night that is still a suggestion, the device cuts at the even day end.

A day route (dayRoutes(plan, line) in route.ts, new): for each riding day, the line from day.from to day.to (route progress), with end points interpolated on their segment (height interpolated linearly, the surface of the segment). A day that starts with a transfer leg (a train or bus after the night before, trainAfter, editor.ts:572) starts at the end of the transfer, as the phone cuts (TripLine.swift:113-114): the end is the distance of the transfer leg's end point in view.stops (the stop whose point has leg: 'transfer'). A transfer inside a day stays as a straight segment. Waypoints: dayStops(trip, line, day) (editor.ts:407), whose km count from day.from; subtract the transfer length (the start of the day route minus day.from) so that they count from the start of the day route; at most 32. Name: "Day k ‹place›", k = the position of the riding day (1 to 32, the number the device shows), place = the label of the pinned night point of that day; with no pinned night and for the last day, "Day k". At most 48 bytes UTF-8, cut on a character boundary, never inside "Day k". Encoding: lineToObcr as routeObcr does now. CRC: Crc32.of(bytes). The put's display name of a day route is its route name (displayName(name, 'Route'), as today); step 4 compares it.

The trip object (tripObject(...) in builder/web/src/lib/device-sync/trip.ts, new, about 30 lines), the v3 layout of §7.7 as write_trip writes it (firmware/obc-route/src/trip.rs:168-199), little-endian. Header of 64 bytes, all bytes 0 first: offset 0 version 3 (u8); 1 reserved 0; 2–3 day count (u16); 4 name length in bytes (u8, at most 48, the name cut on a character boundary); 5–52 the UTF-8 name, zero-padded; 53 reserved 0; 54–55 start date (u16, days since 1970-01-01, 0 = none); 56–63 key (u64). Then 16 bytes for each day: 0–7 route (u64 object id), 8–11 join_m (u32), 12–15 leave_m (u32). Signature: tripObject(key: bigint, name: string, startDate: number, days: { route: bigint; joinM: number; leaveM: number }[]): Uint8Array. The sync passes whole days: joinM 0, leaveM 0xFFFFFFFF. Key: FNV-1a 64 (offset basis 0xcbf29ce484222325, prime 0x100000001b3) over the UTF-8 bytes of the string "‹plan id›|‹id of route point 1›|‹id of route point 2›|1" (orderedRoutePoints), 0 becomes 1. It stays while the first two points keep their ids (a moved start keeps its id); any reversal (also of a loop) or a new point right after the start makes a new key, and the device then starts the progress empty (§7.7). Name: the plan name (planTitle when it has none); the put's display name is the same name. Start date: days since 1970-01-01 of the start date, or 0. The trip object holds no rest days, so on the bike computer the planned dates after a rest day are one day early until the rider rides (the device dates day k as start date + k, obc-app/src/trip.rs:384-389).

Stored state

SentRoute in records.ts becomes:

{ key: string; card: string; days: string[]; trip: string | null }

card is the store id; days[i] is the object id (decimal string) of the route of riding day i + 1; a one-day plan has one entry in days and trip null. trip is the object id of the trip object. key is the sentKey of the plan when everything is on the card, else the empty string. Each id is written right after its put or removal finishes. An entry of another card counts as no entry. isSent checks the new form; a stored value of the old form fails and reads as empty (store.ts:419-422): the routes it named stay on the device as single routes.

One sync of a plan in waiting

In syncDevice (builder/web/src/lib/device-sync/sync.ts), for each plan in waiting, in this order:

  1. Use the card listing that the sync reads first. An id of the entry that the listing does not hold is gone.
  2. A gone object counts as no object: it is made again.
  3. Make the day routes and their CRCs (above). With a gap leg in the line (Planner: route long plans two requests at a time, and keep the trip when one point or leg fails #3709): stop, as Planner: route long plans two requests at a time, and keep the trip when one point or leg fails #3709 does.
  4. Adopt copies of lost puts: a route or trip object on the card with the same length, CRC and display name, in no entry, takes its place in this entry (today's rule of sync.ts:135-136, now before the room count and also for the trip object).
  5. Remove what the plan no longer has: the trip object when the plan now has one riding day; then the day routes of days D + 1 and later. "Not found" counts as removed.
  6. Room: one menu route for each day with no object, one trip when the trip has no object; a replace or a skip needs none. Free menu routes = 64 − the routes on the card after step 5 (the device's own built day and directions count) − the routes made in this sync; free trips = 16 − the trips likewise. When it does not fit: nothing of this plan goes, and problem gets "“‹name›” waits: the bike computer has room for ‹n› more routes, it needs ‹m›. Remove ridden or unused routes on the bike computer."
  7. Puts: a day route whose length and CRC match its object on the card is skipped; a day with an object is replaced in place (objectId, expectedRevision); else created. Then the trip object, skipped when length and CRC match, else replaced or created, with the ids of the days.
  8. When all is on the card: key = sentKey(plan), and the plan leaves waiting.

A put or removal that the device refuses (for example a route that an active journey holds, specs/ride-archive-metadata.md:84) stops this plan with the device's sentence; the plan waits, the other plans go. Keep the check of sync.ts:150 (a plan deleted during its upload goes into leaving) after each put.

leaving (sync.ts:105-116): remove the trip object, then all day routes, then the entry. "Not found" counts as removed.

Lost objects at the end of a sync (sync.ts:157-161): an entry with any gone object (the trip, a day route, or the only route) is dropped, as today. The Routes page then shows the plan as not on the device, and "Send to device" works again; nothing is sent again by itself. A trip deleted on the device removes the trip and all its routes (firmware/obc-app/src/screen/trip_delete.rs). When the rider sends again, step 4 adopts the routes still on the card by their content, so only the missing ones go.

taken (sync.ts:134): every object of every other entry.

Readers: pages/routes/state.ts:19, pages/Device.svelte:100 and pages/Area.svelte:94 test copy.card === card in place of copy.device.startsWith(card). Device.svelte:82 (more = device.routes − held.sent.length) counts the route objects of the entries on this card (their days), not the plans.

The sync report (SyncReport, sync.ts:26-39): sent counts plans sent as one route, a new trips counts plans sent as a trip (each once, however many day routes moved). The Device page (Device.svelte:77-81) says "1 route sent" and "1 trip sent". library/store.ts:255 needs no change. library/backup.ts:46: a state value that fails its check is dropped, not a reason to refuse the backup, so an old backup still loads.

Cases to walk in the tests

All in builder/web/src/lib/device-sync/sync.test.ts, which already runs the real store through the flat-device double (test-support/flat-device):

  • A 10-day plan gives one trip of 10 days that the store lists, with the 10 route ids in order.
  • A second sync of the unchanged plan sends nothing (no put).
  • With nights 4 and 5 pinned, a changed stop in day 5 replaces one route and the trip, nothing else.
  • No room (the card holds 60 routes): nothing goes; the sentence.
  • A cut after 5 puts (the double throws a link error): the next sync sends only the rest, with no second copy.
  • 10 days to 1 day: the trip is removed, then days 2 to 10, then day 1's object is replaced by the one route. 1 day to 10 days: that object becomes day 1, the rest and the trip are created.
  • A plan in leaving removes its trip and all its days.
  • A day after a train starts after the train.
  • A trip deleted on the device (the test removes the trip and its routes from the store): after the sync the entry is gone and the plan is not on the device; a new send sends the trip again. One day route removed on the device: the entry is dropped; a new send adopts the other days by content and creates only the missing one.
  • The report: a 10-day plan gives trips 1 and sent 0.
  • trip.test.ts (new): tripObject(0x0123456789ABCDEFn, 'Alpen Traverse', 20360, ‹the 3 days of specs/vectors/manifest.json›) equals specs/vectors/trip-v3.bin byte for byte (112 bytes); and the key of a known string, checked once by hand.

These tests seed or check sent in the old form and change to the new: src/lib/library/store.test.ts:86, src/pages/routes/state.test.ts:8 and :22, src/lib/device-sync/sync.test.ts:130-192 ({device, key}), tests/browser/planner/device.test.js:66, routes.test.js:35, route-rows.test.js:78 and :310.

Limits

  • The trip object holds no rest days: on the bike computer, the dates after a rest day are one day early until the rider rides.

Docs

docs/design/web-planner.md, the device sync list (items 1, 5 and 6, about lines 176-182): a plan of several days goes as day routes and a trip object; sent names all its objects; what a removal on the device means. Public docs (docs/content/software/trips.md): one sentence that a web trip reaches the bike computer as a trip, in its own docs: commit; then python3 docs/build_docs.py --check-links.

Checks

In builder/web: npx vitest run src/lib/device-sync src/lib/library/store.test.ts src/lib/library/backup.test.ts src/pages/routes/state.test.ts, npm run check. Browser tests: only the three changed files: in builder/web/tests/browser, npm run test:planner -- planner/device.test.js planner/routes.test.js planner/route-rows.test.js.

Done when

  • The checks pass.
  • The owner pins all nights of a 10-day plan, sends it from the web planner, and looks at the trip menu of his bike computer: pass when one trip with 10 days shows and "next day" opens day 1; fail when 10 loose routes or one long route show. He rides or marks day 1 done, changes a stop in day 5 in the planner, sends again: pass when day 1 is still done and the Device page says "1 trip sent" while only day 5 changed on the bike computer; fail when all days went again or day 1 lost its progress. He deletes the trip on the bike computer and syncs: pass when the planner shows the plan as not on the device and "Send to device" works again.

Public docs: one sentence in trips.md (own commit).

Activity

  1. timohueser commented on Nov 20, 2026

    @timohueser
    OwnerAuthor

    The owner decided: #3727 merges now on the review and the simulated-device proof; he tests everything on the real bike computer later ("Merge now, we'll test everything with the computer later"). His check stays open: the six steps and the carried-over climb check of #3710 are in the owner brief of this pull request.


    Generated by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions