USER_GUIDE.md

User guide

The Quick start covers installation. This guide explains each control and the optional GPS reference trace.

First drive

1. Park on a road represented in the map. Choose the map on the first card under Map (Kyiv, Lviv region or a corridor map; also in Settings, only while no drive is running), then tap your current road. Taps farther than 70 metres from a selectable road are rejected with a note on the card.
2. Hold the green marker briefly, then drag to adjust it along that road. Connected roads become available at junctions. Tap a different road to relocate the starting point.
3. Use Flip so the arrow points forward along the car (the card shows the compass direction it faces). On one-way roads only the mapped driving direction is offered. Press Set as start. Tap point B or search for it. The app calculates up to three legal offline routes: the fastest by road-class speed, the shortest, and distinct alternatives no more than 50% slower that share under 75% of their length with routes already offered. If no legal route leaves in the chosen direction, the card says so; go back and flip the arrow. Choose a route (others are drawn grey), then Start drive. You must follow the blue route: there is no automatic rerouting. Pausing retains the route; while paused and resumable, you can pick another offered route or Change route from here to plan new options from the paused estimate to the same point B. Start over clears A, B and the route.
4. Search (the bar at the top) finds villages, towns, districts, streets and fuel stations of the loaded map offline, in Ukrainian or Latin letters with one-typo tolerance (Slavske, Тухолька, "шевченка славсько"). Over the satellite view, which is Apple's map, it lists Apple Maps suggestions (addresses and businesses; online, only the typed text is sent) above the offline results. While choosing A or B, a result places the point on the nearest road within 400 m; otherwise it only moves the map. When neither finds the place, Find it in Google Maps opens Google Maps (the app, or the website) with the same search. Find the exact spot there, then either tap Share → GPSLess, which opens GPSLess with the place as the point being chosen, or copy its link or coordinates and tap Paste in GPSLess search. Typing or pasting a link or coordinates into the search bar works too. Google Maps, Apple Maps and OpenStreetMap links, geo: links and coordinates such as 50.4501, 30.5234 or 50°27'00"N 30°31'24"E are read on the phone; a short link (maps.app.goo.gl) is opened online once to find the place it points to, and only that link is sent. A place outside the loaded map is refused with a note.
5. Secure the phone in portrait with the top edge up and screen facing straight back along the car, not angled sideways toward the driver. A backward tilt is allowed; laying the phone flat is not supported. Use a rigid mount: speed is measured from road vibration reaching the phone. Set the Wheelbase (front-to-rear axle distance from your car's specifications) in the start sheet or Settings → Car. Speed and distance scale with it; the default is 2.70 m. With Refine from route turns on (the default), the app then measures it while you drive a locked route.
6. Press Start drive. The sheet lists three checks: parked where the arrow is, phone upright in a rigid mount, hands off for four seconds. Optionally enable Use GPS tracing under Testing to save reference data, granting When In Use location permission and Precise Location for useful measurements. Press Start drive and remain still while the card says Hold still, then drive forward. The screen stays awake while tracking, and you can switch to another app, pull down Notification Center or lock the screen: with Location allowed (asked once when the start sheet opens) the drive keeps running in the background under the blue location indicator. That coarse location session only keeps the app awake; its fixes are discarded. Without Location permission, leaving the app pauses tracking. The tracking card shows the speed, the typical position error (±, also the circle on the map: on test drives the car was inside it about four fifths of the time; the engine keeps a wider bound for matching turns), turn fixes (turns matched to the route) and speed fixes (road-bump speed measurements that corrected the inertial speed by 5 km/h or more, each announced briefly).
7. Press Pause before handling the phone. If the car moved while paused, stop and Set position again. Car stayed here · resume is offered only when the road match remains sufficiently unambiguous; it retains the previous uncertainty.
8. If stopped speed is visibly wrong, remain stopped and untouched for two seconds, then press Stopped. This supplies an explicit zero-speed observation and, when the preceding readings are settled, recalibrates gravity and all three gyro offsets. Old engine residual biases are cleared when this input reference changes. This does not correct position. Record the displayed speed before pressing it when assessing a field test.
9. After the drive, open Settings → Recorded drives → Export all test data. Send the files to your Mac with AirDrop or save them to a folder. Nothing is uploaded automatically. Reaching the estimated route end stops tracking and requests a new starting point; this is not an independently verified arrival.

Settings (gear button) holds the map, the car's wheelbase, GPS tracing, recorded drives, Sensor details (live speed, acceleration, turn rate and position diagnostics) and the app version with the OpenStreetMap attribution.

Use a passenger for observations and controls during test drives. A successful build does not establish driving accuracy. This is an experimental tracker, and the displayed speed and uncertainty radius are model estimates, not verified accuracy claims.

Optional GPS reference tracing

Use GPS tracing is off on a new install and its preference persists. It collects only during an active calibration/tracking segment, including while the drive continues in the background. Pause, reset, interruption and replay stop collection. A new collection uses a new location-manager instance; stale callbacks from previous instances are discarded, and the recording queue checks the original drive UUID before writing any reference row. Denied permission or unavailable GPS does not block inertial tracking. The live trace status distinguishes permission failure, waiting for a fix and reported low accuracy.

The most recent fix in each Core Location callback is recorded at most once per second, using receipt uptime to bound storage even if the wall clock changes. gps-reference rows share the drive's existing compressed file, sequence numbers and export controls. They retain fractional Unix acquisition/receipt timestamps, callback uptime, inferred acquisition uptime, fix age, coordinate, altitude, position/speed/course accuracy, reduced-accuracy authorization and software/accessory source flags. Negative unavailable values remain negative; non-finite values become absent and receive quality flags. Stale, cached, out-of-order, future, imprecise and simulated observations are retained with labels rather than silently converted into truth. Collection/permission/error events and observed delivery gaps are separate gps-trace-event rows. The endpoint events also retain the last fix times so a missing tail is visible.

GPS is reference data only: neither live motion processing, road matching, speed/stop calculations nor replay consumes these records. Tracing does not calibrate the engine automatically. Core Location is an iOS location solution, not a raw satellite measurement, and reported accuracy does not prove immunity to interference or spoofing. Later analysis must screen the reference and use separate drives for calibration and validation. Inferred acquisition uptime uses the receipt clock pair; wall_clock_changed flags identify a discontinuity requiring care during alignment.

Long journeys

The bundled maps cover Kyiv and the Lviv region. For a drive across several oblasts, build a corridor map on your Mac (see Technical notes, "Offline data") and install the app again: it appears under Map next to the bundled maps. Plan the whole route on it before leaving.

• Stops: after a fuel stop, Car stayed here · resume is offered while the estimate is still precise; otherwise set the position again. Search finds fuel stations by name or brand (for example OKKO or WOG) as well as towns and streets.
• Long straight roads without turns let the uncertainty grow; it shrinks again at the next matched turn or junction. Position uncertain appears once the typical error passes 45 m. Tracking continues up to 10 km of uncertainty.
• Keep the phone charging: tracking keeps the screen on and records about 1.8 MB per minute.
• Speed cameras are drawn in red with their limit.